ポモドーロタイマープロジェクトの README.md - Amplifier（AI駆動開発ツール）で生成

pomodoro-timer-README.md

Pomodoro Timer

シンプルで効果的なポモドーロテクニック実装。集中力を維持し、生産性を向上させるための時間管理ツールです。

特徴

• 25分作業 + 5分休憩 - クラシックなポモドーロサイクル
• 視覚的モード区別 - 作業・短休憩・長休憩を色とアイコンで明確に表示
• セッション記録 - すべての作業セッションを自動保存
• 統計表示 - 今日の集中時間、完了ポモドーロ数、連続日数を追跡
• OS通知 - セッション完了時にデスクトップ通知
• アクセシビリティ対応 - WCAG AA準拠、キーボード操作完全対応
• ローカルデータ保存 - プライバシー重視、クラウド不要

インストール

前提条件

• Python 3.11以上
• uv（パッケージマネージャー）

セットアップ

# リポジトリをクローン
git clone <repository-url>
cd pomodoro-timer

# 依存関係をインストール
uv sync

使い方

アプリケーションの起動

uv run streamlit run app.py

ブラウザが自動的に開き、タイマーインターフェースが表示されます。

基本操作

1. 開始: 「Start」ボタンをクリックまたはSpaceキーを押す
2. 一時停止: タイマー実行中に「Pause」ボタンまたはSpaceキー
3. 停止: 「Stop」ボタンまたはEscキー
4. 休憩開始: Bキーで手動で休憩を開始
5. 統計表示: Sキーで統計ビューに切り替え

キーボードショートカット

キー	操作
Space	タイマーの開始/一時停止
Esc	タイマーの停止とリセット
B	休憩の手動開始
S	統計表示の切り替え

タイマーサイクル

1. 作業セッション (🍅) - 25分間の集中作業（深い緑のグラデーション）
2. 短い休憩 (☕) - 5分間の休憩（明るい青のグラデーション）
3. 長い休憩 (🌴) - 4ポモドーロごとに15分間の休憩（温かいオレンジのグラデーション）

視覚的モード区別

各モードは以下の3つの要素で明確に区別されます：

• 色: モードごとの専用グラデーション背景

  • 作業モード: 深い緑 (#2E7D32 → #388E3C) - 集中と成長
  • 短休憩: 明るい青 (#0288D1 → #03A9F4) - リフレッシュと落ち着き
  • 長休憩: 温かいオレンジ (#F57C00 → #FB8C00) - 回復と温かさ
  • 一時停止: 琥珀色 (#FFA726 → #FFB74D) - 待機状態

• アイコン: 各モード専用の絵文字（🍅/☕/🌴）

• プログレスバー: モードに応じた色のプログレスバー

この設計はWCAG AA基準（4.5:1コントラスト比）に準拠し、色覚特性に関わらず識別可能です。

設定

デフォルト設定は以下の通りです:

work_duration: 1500秒（25分）
short_break: 300秒（5分）
long_break: 900秒（15分）
pomodoros_until_long_break: 4
sound_enabled: True
notification_enabled: True

設定を変更するには、UIの設定パネルを使用します。

データ保存

セッションデータはdata/sessions.jsonにローカル保存されます。各セッションには以下の情報が含まれます:

• セッションID
• タイプ（作業/休憩）
• 開始時刻と終了時刻
• 完了状態
• 継続時間

統計

以下の統計が表示されます:

• 今日の集中時間 - 本日完了した作業セッションの合計時間
• 完了ポモドーロ数 - 本日完了した25分セッションの数
• 連続日数 - 少なくとも1ポモドーロを完了した連続日数
• 週間概要 - 過去7日間の日別ポモドーロ数

トラブルシューティング

通知が表示されない

Windows:

• システム設定で通知が有効になっているか確認
• Pythonアプリに通知権限があるか確認

macOS:

• システム環境設定 > 通知でPythonの通知を許可

Linux:

• libnotifyがインストールされているか確認
• 通知デーモンが実行中か確認

タイマーが不正確

タイマーはシステムクロックに基づいており、ドリフトを防ぐように設計されています。それでも問題がある場合:

1. システムの時刻設定を確認
2. 他のCPU負荷の高いプロセスを終了
3. アプリケーションを再起動

データファイルが見つからない

初回起動時にdata/ディレクトリとsessions.jsonが自動作成されます。手動で作成する必要はありません。

開発

テストの実行

# すべてのテストを実行
uv run pytest

# カバレッジ付き
uv run pytest --cov=pomodoro --cov-report=html

# 特定のテストファイル
uv run pytest tests/test_timer.py -v

コード品質チェック

# リント、フォーマット、型チェック
make check

# 個別実行
uv run ruff check .
uv run pyright

プロジェクト構造

pomodoro-timer/
├── pomodoro/              # コアモジュール
│   ├── models.py          # データモデル
│   ├── timer.py           # タイマーロジック
│   ├── storage.py         # データ永続化
│   ├── stats.py           # 統計計算
│   ├── notifications.py   # 通知システム
│   └── ui/                # UIコンポーネント
│       ├── timer_display.py   # タイマー表示
│       └── stats_display.py   # 統計表示
├── app.py                 # メインアプリケーション
├── tests/                 # テストスイート
│   ├── test_models.py
│   ├── test_storage.py
│   ├── test_timer.py
│   └── test_stats.py
├── data/                  # セッションデータ（gitignored）
└── docs/                  # 追加ドキュメント
    ├── DESIGN.md
    ├── IMPLEMENTATION_PLAN.md
    └── TEST_REPORT.md

詳細なアーキテクチャ情報はDESIGN.mdを参照してください。

アクセシビリティ

このアプリケーションは以下のアクセシビリティ機能を提供します:

• WCAG AA準拠 - すべてのモードで4.5:1以上のコントラスト比を実現
• トリプル識別システム - 色 + アイコン + テキストラベルで各モードを識別
• 色覚多様性対応 - 色だけに依存しない情報伝達
• キーボードナビゲーション - マウスなしで完全操作可能
• スクリーンリーダー対応 - 意味のあるHTML構造とARIAラベル
• 大きなタッチターゲット - Streamlitデフォルトの44px以上のボタンサイズ

デザイン品質評価

UIデザインは9つの次元で評価されています（詳細はdocs/TEST_REPORT.md参照）：

• 総合評価: 9.3/10
• Body（操作性）: 10/10 - Streamlit標準UIによる優れた操作性
• Space（空間）: 9/10 - 適切な余白とグルーピング
• Proportion（比率）: 9/10 - バランスの取れた要素配置
• Typography（文字）: 9/10 - 明確な階層構造
• Color（色彩）: 10/10 - モード別の感情的適切性
• Style（スタイル）: 9/10 - クリーンで機能的
• Motion（動き）: 8/10 - スムーズな遷移
• Voice（声）: 9/10 - フレンドリーで明確
• Texture（質感）: 9/10 - グラデーションによる深み

ライセンス

このプロジェクトは学習目的のAmplifierチュートリアルプロジェクトです。

貢献

問題や提案がある場合は、Issueを作成してください。

関連ドキュメント

• DESIGN.md - アーキテクチャと設計決定
• AGENTS.md - AI開発ガイドライン
• 親プロジェクトAGENTS.md - 全体的な開発原則