dashboard-build

前提条件

dashboard-design スキルの Phase 1 仕様ファイルが必要です：spec/1_information_architecture.md、spec/2_interaction_ux.md、spec/3_visual_design.md。これらが存在しない場合は、まず Phase 1 を実行するか、仕様ファイルなしで進めるかをユーザーに確認してください。

ガイドライン

• データを十分に理解するため、特にカスタムチャートを作成する場合や特定のセレクターを使用する場合は、組み込みのツールを使ってください。
• ユーザーが例を求めた場合は、サンプルアプリをそのままコピーして実行してください。独自のデータを追加したり、サンプルを変更したりしないでください。
• 以下で説明するスクリプトを初めて実行する際は、依存関係のインストールに時間がかかることがあります。軽率な操作をする前に、時間を考慮してください。
• すべての手順を完了した後、ダッシュボードを反復して改善する際は、以下の重要な点、特に仕様への準拠と更新、ターミナルの扱いを忘れないでください。すべての仕様を常に最新の状態に保ち、反復のたびにターミナルの出力がクリーンかどうかを必ず確認してください。
• このスキルのすべてのスクリプトと、作成する app.py は、uv run <script_name>.py または uv run app.py で実行してください。これにより、正しい依存関係とバージョンが使用されます。
• 絶対に、ダッシュボードアプリの実行中のターミナルでは、sleep、echo、その他のコマンドを含め、いかなるコマンドも入力しないでください。isBackground=true で起動した場合も同様です。これを行うと、ダッシュボードのプロセスが終了します。ダッシュボードの起動には時間がかかります。辛抱強く待ち、実行を妨げないでください。
• ステップ 2（テスト）は重要です。省略しないでください。利用可能な場合は Playwright MCP を使用し、そうでない場合は環境で利用できるブラウザー自動化ツールを使用してください。

仕様ファイル：判断内容の記録

重要：各ステップでは、判断の根拠を記録し、共同作業を可能にし、今後のセッションで作業を再開できるように、spec/ ディレクトリに仕様ファイルを作成します。プロジェクトのルートに spec/ ディレクトリがまだない場合は作成してください。

ステップ 1：ダッシュボードの構築

1. 必ずサンプルアプリをコピーしてから変更してください。これにより、エラーを減らせます。
2. スキーマ取得スクリプトを実行して、Vizro モデルを調べてください。必要なすべてのモデルについて、必ず実行してください。モデルについて把握していると決めつけないでください。次のようにスクリプトを実行します：uv run ./scripts/get_model_json_schema.py <model_name> <model_name2> ...。ここで <model_name> はスキーマを取得するモデル名です（各モデルの完全な JSON スキーマが標準出力に表示されます）。概要スクリプトを次のように実行すると、利用可能なモデルの一覧を確認できます：uv run ./scripts/get_overview_vizro_models.py（利用可能なすべてのモデル名と1行の説明が標準出力に表示されます）。
3. コピーしたサンプルアプリを変更して、ダッシュボードの設定を構築してください。重要：通常の Plotly Express チャートだけでは単純すぎて不十分なことがよくあります。その場合は、カスタムチャートガイドを参照して、より複雑なチャートを作成してください。これらは Python アプリの正しいセクションに追加する必要があります。ダッシュボードアプリの Graph モデルからカスタムチャート関数を呼び出してください。
4. uv run <your_dashboard_app>.py でダッシュボードアプリを実行してください。重要：このコマンドの実行後、そのターミナルではほかのコマンドを実行しないでください。ダッシュボードの起動には時間がかかります（場合によっては 10〜30 秒）。
5. エラーがないか確認するため、ターミナルを必ず確認してください。ただし、sleep などのコマンドを入力してはいけません。発生した警告はすべて、特にエラーは必ず修正してください。ダッシュボードが実行中であることを確認してから、ユーザーに知らせてください。ダッシュボードを起動した後は、そのターミナルでいかなるコマンドも実行しないでください。
6. 反復して改善する際、デバッグモードを使用しているため、ダッシュボードを終了する必要はありません。ファイルを保存すると自動的に再読み込みされます。問題が発生していないか、ターミナルを定期的に確認してください。問題が発生した場合は、ダッシュボードを再起動する必要があります。

最適化とよくあるエラー

• 色：Plotly チャートと KPI カードでは、コードに色を追加しないでください。Vizro テンプレートのデフォルトが自動的に適用されます。チャートの色を追加するのは、spec/3_visual_design.md に ## Colors セクションが明示されている場合のみです。AG Grid のセルスタイル（条件付き書式、ヒートマップ）には、from vizro.themes import palettes, colors を使用してください。16 進数値を独自に作成してはいけません。selecting-vizro-charts スキルを参照してください。
• データの読み込み：データの更新（データベース、API）が必要なダッシュボードや、パフォーマンスを最適化するダッシュボードについては、静的データと動的データ、キャッシュ、ベストプラクティスに関する データ管理ガイド を参照してください。
• KPI カード：Figure モデル内の組み込み kpi_card／kpi_card_reference のみを使用してください。カスタムチャートとして作り直してはいけません（動的テキストを除く）。selecting-vizro-charts スキルを参照してください。
• テーブル：figure=dash_ag_grid(...) を指定した vm.AgGrid のみを使用してください。vm.Table／Dash DataTable の使用や、Plotly でテーブルを模倣することは禁止です。2 つの標準パターンと Dash-AG-Grid／JS-AG-Grid のナレッジマッピングについては、example_ag_grid.py を参照してください。
• インタラクション／アクション：クロスフィルター、クロスハイライト、ドリルスルー、データエクスポートを行う場合は、wiring-vizro-actions スキルを読み込み、spec/2_interaction_ux.md の ## Interactions セクションに従ってください。

必須の出力：spec/4_implementation.md

assets/4_implementation.md からテンプレートをコピーして、プロジェクトのルートに spec/4_implementation.md を作成し、プレースホルダーに内容を記入してから、ステップ 2 に進む前に保存してください。

検証チェックリスト

ステップ 2 に進む前に、spec ファイルに照らして確認してください。

• spec が存在する場合、spec/1_information_architecture.md、spec/2_interaction_ux.md、spec/3_visual_design.md のすべての仕様が実装されている
• ダッシュボードアプリのターミナル出力を読み、エラーや警告がないか確認している。また、アプリの起動後にターミナルへコマンドを入力していない
• 仕様からの逸脱があれば、spec/4_implementation.md に記録している

ステップ 2：テスト

このステップは、バグのないダッシュボードを作成するうえで重要です。省略しないでください。

以下のテストを実施する際に問題が見つかった場合は、ステップ 1 に戻って修正してから、ここに戻ってください。

自動コード検証

よくある問題を検出するため、アプリの app.py に対して次の検証スクリプトを実行してください。

1. 色の検証：uv run ./scripts/validate_colors.py . — Vizro のテーマ設定を迂回するハードコードされた色（color_discrete_map、16 進コード、plot_bgcolor）がないか確認します。FAIL があれば修正してください。ユーザーがカスタムカラーを明示的に求めた場合は、--custom-colors-requested を追加して app.py の色チェックをスキップしてください。
2. 集計の検証：uv run ./scripts/validate_aggregation.py . — 棒グラフ／折れ線グラフが、@capture("graph") を使った事前集計済みデータを使用しているかを確認します。インラインの px.bar／px.line に明細データを直接渡してはいけません。FAIL があれば修正してください。

ブラウザテスト

コードレビューだけでは見つからないエラーを発見するため、実行中のダッシュボードを操作します。（1）起動時のコンソールエラー、（2）ページ移動時のコールバックエラー、（3）アクションの実行時に発生するコールバックの 500 エラーを確認します。これらは、インタラクティブなソースをユーザーが実際にクリックしたときにのみ表面化し、ページの読み込み時には発生しません。

1. 利用可能なブラウザー自動化ツールを確認します。

   Playwright MCP ツールを利用できますか？ → 直接使用して、ページに移動し、クリックし、コンソールを確認します。Playwright MCP がありませんか？ → Python パッケージをインストールしてから、テストスクリプトを作成します。uv pip install playwright && uv run playwright install --with-deps chromium を実行します。--with-deps フラグは Chromium に必要な OS ライブラリをインストールします。通常のインストールでは起動時に共有ライブラリ不足のエラーが発生する、軽量 Linux ベースイメージ（Docker、CI ランナー、devcontainer）で必須です。macOS／Windows でも安全に使用できます。Chromium がすでにディスク上にある場合は、インストールを省略します。ダウンロードサイズは約 170 MB です。

2. アプローチ — エラーはまとめて確認し、ひとつずつループしないでください。 すべてのページを巡回し、すべてのアクションを1 回のパスで実行して、エラー（コンソール、ネットワークの 500、コールバックの失敗、ダッシュボードのプロセス出力にあるサーバーのトレースバック）をひとつのリストにまとめます。その後、すべてのエラーを一括で修正し、ダッシュボードを1 回だけ再起動してから、再度巡回します。避けるべきなのは、エラーをひとつ発見 → 修正 → 再起動 → 次のエラーを発見 → 修正 → 再起動、という流れです。再起動のたびに約 30〜60 秒かかるため、ダッシュボードを完全にクリーンにする前に時間切れになります。

3. 選択したツールを使い、1 回の巡回で次のチェックを実行します。

   • ダッシュボードの URL（例：http://localhost:8050）に移動します。
   • すべてのページを開き、ブラウザーコンソールにエラーがないか確認します。最初のエラーで止めず、記録して先に進みます。
   • app.py に actions=（クロスフィルター、クロスハイライト、ドリルスルー、エクスポート）が含まれている場合は、同じ巡回ですべて実行します。 アプリ内で actions= を grep し、一致する項目ごとに対応するソース（散布図の点、棒、AgGrid の行、エクスポート用の Button など）をクリックします。それぞれについて、次の内容を記録します。
     • ブラウザーコンソールに Callback error updating ... メッセージが表示されたか
     • _dash-update-component でネットワーク 500 応答があったか
     • アクションで意図した効果が実際に発生したか（show_in_url=True の場合は URL が更新されたか、対象のフィルターが変わったか、ハイライトが適用されたか、ファイルがダウンロードされたかなど）
   • ダッシュボードのプロセス出力（app.py を起動したターミナル）にサーバー側のトレースバックがないかも確認します。ブラウザーには汎用的なコールバックエラーしか表示されない場合、トレースバックから根本原因を特定できます。
   • 収集した失敗をグループ化し、すべて一括で修正してから再起動し、この巡回を再実行します。新しいエラーが見つかった場合にのみ繰り返します。

高度なテストの流れ

1. 各ページのスクリーンショットを撮り、仕様、特にワイヤーフレームと比較します
2. 相違点を記録します

確認すべき重要な項目：

• 折れ線グラフは読みやすく、集計不足で見づらくなっていないこと
• グラフがレイアウトの影響で読みにくくなったり、押しつぶされたりしていないこと

必須の出力：spec/5_test_report.md

assets/5_test_report.md のテンプレートをプロジェクトルートの spec/5_test_report.md にコピーし、プレースホルダーを埋めて保存すると、プロジェクトは完了です。

完了条件

• 検証スクリプト（validate_colors.py、validate_aggregation.py）がどちらも PASS する
• ダッシュボードがエラーなく起動し、コンソールエラーがなく、ページ移動時にコールバックエラーが発生しない
• app.py 内のすべての actions= をブラウザーでクリックし、コールバックの 500 エラーなく、意図した効果が発生する
• ユーザーが要件の充足を確認する
• この Phase 2 の仕様ファイルがすべて spec/ ディレクトリに保存されている

参考ファイル

参考資料	読み込むタイミング
selecting-vizro-charts スキル	色、KPI カード、カスタムチャート、Plotly の規約
writing-vizro-yaml スキル	YAML の構文、コンポーネントのパターン、data_manager、注意点
wiring-vizro-actions スキル	クロスフィルター、クロスハイライト、ドリルスルー、エクスポート
data_management.md	静的データと動的データ、キャッシュ、データベース、API
custom_charts_guide.md	カスタム @capture("graph") チャートの実装
example_app.py	ダッシュボード実装の開始用テンプレート
example_ag_grid.py	標準的な AG Grid のパターン — vm.AgGrid を記述する前に必ず読む
validate_colors.py	app.py のハードコードされた色を自動チェック
validate_aggregation.py	棒グラフ／折れ線グラフで事前集計が行われているかの自動チェック