homeassistant-dashboard-designer

Home Assistant ダッシュボードデザイナー

ダッシュボードはシステムとして設計します。予測可能な構造、再利用可能なテンプレート、最小限のばらつきを目指します。Stitch はあくまで参考にとどめ、安全な Lovelace YAML に変換します。

主な入力：自然言語（デフォルト）

自然言語で指示できます。このスキルは、デザインシステムを適用し、利用可能な場合は Home Assistant MCP を使ってエンティティやサービスを検証しながら、構造化された意図（ダッシュボードの目的、ビュー名、エンティティのマッピング、制約）を内部で推測する必要があります。

自然言語に含めると役立つ最低限の情報：

• 変更内容（追加／削除／リファクタリング）と、その理由（目的）。
• 変更する場所：config/dashboards/** 以下の正確なビュー／部分ファイルのパス。
• デスクトップ／モバイルの列数、グラフの時間範囲の希望、「変更しない」テンプレート／セクションなど、考慮してほしい制約。

上記に不足がある場合は、的を絞った確認質問をしてください（「意図ブロック」全体を要求しないでください）。

自然言語による依頼の例：

• 「config/dashboards/infrastructure/views/06_mariadb.yaml を、ほかの Infrastructure ビューで使われている button-card 優先のシステムに合わせてリファクタリングしてください。エンティティはそのままにし、新しいテンプレートは追加せず、デスクトップは4列／モバイルは2列にしてください。」

任意の入力：構造化された意図（使用可能、必須ではありません）

ユーザーが構造化された意図を提示した場合は受け入れてください。必須にはしないでください。

dashboard_type: infra  # infra|home|energy|environment
view_name: "Infrastructure Overview"
target_paths:
  dashboard_yaml: "config/dashboards/infrastructure/dashboard.yaml"
  view_yaml: "config/dashboards/infrastructure/views/07_docker_containers.yaml"
entities:
  - name: "Proxmox01"
    cpu: "sensor.proxmox01_cpu"
    memory: "sensor.proxmox01_mem"
constraints:
  desktop_columns: 4
  mobile_columns: 2
notes:
  - "Preserve existing templates; minimize diff."

既存のビューを更新する場合、文脈から明らかでなければ次の点を確認してください：

• 正とするビューのファイル（単一のビュー辞書）はどれですか？
• 「変更しない」領域やテンプレートはありますか？
• 維持が必要な既存のフォールバックカードはありますか？

出力要件（常に満たす）

• 有効な Lovelace ビューを1つ（単一のビュー辞書）
• 決定的な順序（カード／セクションの順序を固定）
• セクションコメント（簡潔で一貫性のあるもの）
• カードごとのスタイルのばらつきゼロ（個別スタイルを使わず、テンプレート／スニペットを使用）
• フォールバックの使用には明確な理由を付ける（フォールバックカードの近くに YAML コメントを記載）

カード優先度モデル

まず Tier 1 を試してください。Tier 1 では要件を安全に実現できない場合に限り、Tier 2 を使用してください。

Tier 1（優先）：

• custom:button-card（構造＋タイル＋ヘッダー＋コンテナー）
• card-mod（共有／グローバルな仕上げのみ。共有スニペットは可）
• custom:flex-horseshoe-card（単一指標の放射状テレメトリー）
• custom:mini-graph-card（単一指標のトレンド）

Tier 2（フォールバック。コメントで理由を明記）：

• entities、markdown、history-graph、conditional
• iframe（最終手段）

レイアウトルール（厳守）

• 使用可能なレイアウトコンテナー：grid、vertical-stack
• 入れ子の最大深度：2（例：grid -> vertical-stack -> カード）
• グリッドのセル内に horizontal-stack を配置しないでください（列を増やすか、vertical-stack を使用してください）
• 自由配置は禁止
• card-mod にレイアウトのロジックを埋め込まないでください
• type: sections ビューで高密度のタイル一覧を表示する場合、外側のパネルは全幅（column_span: 4）にし、内側のタイルグリッドは custom:layout-card でレスポンシブにしてください（ユーザーから別の指示がない限り、デスクトップは 4 列／モバイルは 2 列）。
• type: sections ビューでは、上部のチップ／バッジ直下にある最初のセクションを、全幅のコンテナー（column_span: 4）にしてください。さらに、細い列に余白が生じないよう、単一のラッパーカードにも grid_options.columns: full を設定してください。
• 削除や移動の後は上方向に詰めてください。ユーザーが明示的に余白を求めた場合を除き、空きスペース、空のプレースホルダー、意図的にまばらな行を残さないでください。

注：リポジトリ／ビューで Home Assistant の type: sections を使用している場合は、sections をトップレベルの構造として扱い、各セクション内にも同じコンテナールールを適用してください（セクションに含めるのは grid／vertical-stack カードとその子要素だけです）。

デザインシステムのルール（実装の規律）

Button Card（主要なレンダラー）

• 構造上の基本要素として custom:button-card を使用してください。
• テンプレートは必須です。カードごとの styles: のインライン指定は避け、スタイルは一元管理されたテンプレート／スニペット内に記述してください。
• ロジックには変数またはテンプレート JS を使用してください（カードごとにロジックを重複させないでください）。

card-mod（スタイル制約レイヤー）

• 共有／グローバルな仕上げにのみ使用できます。
  • パディングの正規化
  • 角丸の調整
  • 影の抑制
  • タイポグラフィの統一
• エンティティ固有のスタイル設定は禁止です
• カードごとのビジュアル実験は禁止です

Flex Horseshoe Card

• 1 枚のカードにつき、主要な指標は 1 つにします。
• 色のしきい値を明示します。
• 単位を混在させないでください。

Mini Graph Card

• グラフごとに指標は 1 つにします。
• ダッシュボード内で時間範囲を統一します。
• 凡例は最小限にします（必要な場合のみ）。

テンプレートアーキテクチャ（必須）

• ビューではテンプレートのみを参照します（custom:button-card の場合、すべてのインスタンスで template: を指定する必要があります）。
• テンプレートでは変数を受け取り、ビューから変数を渡します。
• 明示的な指示がない限り、新しいテンプレートを作成しないでください。

リポジトリの実態を確認してください（重要）：

• リポジトリにすでに確立されたテンプレートがある場合（たとえば、Infrastructure の bearstone_*）、既存のものを使用してください。
• 仕様で「必須」とされるテンプレートカテゴリが存在しない場合は、最も近い既存のテンプレートに対応付けて不足点を明示するか、テンプレートの追加について明示的な許可を求めてください。

Stitch MCP（インスピレーションのみ）

Stitch は次の点を学ぶ目的にのみ使用してください。

• 視覚的な階層構造（ヘッダー、グループ化、密度）
• 余白のリズム（パディング／間隔）
• グループ化のパターン（パネル、セクション）

Stitch の出力を実装コードとして扱わないでください。

Stitch へのプロンプトには、次の制約をそのまま含めてください。

Grid-only layout. No absolute positioning. No JS frameworks. No custom HTML/CSS outside card-mod.
Card types limited to: custom:button-card, card-mod, custom:flex-horseshoe-card, custom:mini-graph-card, and HA core fallback cards only if unavoidable.
Max layout nesting depth: 2. No horizontal-stack inside grid cells.

Stitch への引き継ぎ（任意・簡易連携）

ユーザーがビジュアルのアイデア出し、レイアウトの検討、またはバリエーションを明示的に求めた場合にのみ使用してください。

• Stitch の使用が必要な場合：
  • ユーザーが、再デザインのインスピレーション、バリエーション、または複数のビジュアル案を求めている。
• Stitch の使用を省略する場合：
  • ユーザーがダッシュボードの直接的なリファクタリング／更新を求めており、アイデア出しが不要である。
• 前提条件：
  • Stitch は階層構造／余白／グループ化のアイデア出しにのみ使用します。
  • Stitch の出力を実装コードとしてコピーしてはいけません。
  • 最終的な実装も、このスキルで許可されたすべてのカード／レイアウトのルールに従う必要があります。

引き継ぎ成果物（要約のみ、コードのエクスポートなし）：

stitch_intent:
  layout_pattern: "<grid and grouping pattern to translate>"
  section_hierarchy: "<header/panel/section ordering>"
  density_target: "<compact|balanced|spacious>"
  cards_to_translate:
    - "<visual card concept mapped to allowed Lovelace card types>"

翻訳要件：

• stitch_intent を、許可された Lovelace の構造のみ（grid、vertical-stack、Tier 1 カードを優先）に変換します。
• サポートされていない Stitch の概念は、準拠したカード／コンテナに再対応付けします。Tier 2 が必要な場合は、フォールバックの選択理由をその場で説明してください。

Stitch が利用できない場合のフォールバック動作：

• このスキルのデザインシステムとルールに従い、手動でアイデア出しを続けます。
• 制限モードであることを明確に伝えてください（「Stitch が利用できないため、手動で階層構造／密度を計画します」）。
• Stitch が利用できないことを理由に、ダッシュボードの作業を中断しないでください。

ワークフロー（この順番で実行）

1. このリポジトリでは直接更新モードを使用します：
   • 本番用 YAML を直接編集します（このスキルのワークフローでは、ダッシュボードのステージング用コピーは作成しません）。
   • 差分を最小限に抑え、HA の再起動／再読み込み前に検証して、ロールバックの安全性を確保します。
2. 編集前に、対象のダッシュボード／ビュー／部分テンプレート／テンプレートと、インクルード対象を読みます：
   • 正確なソースビュー／部分テンプレート／テンプレートのファイルを確認します。
   • 参照されている !include のファイル／ディレクトリが存在し、対象範囲内であることを確認します。
3. ユーザーのリクエストと既存のダッシュボードのコンテキストから意図を判断します：infra（NOC）、home、energy、または environment。1 つのビューにつき、意図は 1 つにします。
4. 編集前にエンティティとサービスを検証します：
   • ライブのエンティティ／サービス検証には Home Assistant MCP を優先的に使用します（利用可能な場合は必須）。
   • YAML を記述する前に、作業メモに MCP での検証手順を記録します。
   • MCP を利用できない場合は、エンティティ ID とサービスをユーザーに確認します（推測しないでください）。
5. 制約に従ってレイアウトを作成します：トップレベルの grid と、必要に応じた vertical-stack グループを使用します。
   • Stitch を使用する場合は、まず stitch_intent を要約し、この手順への参考情報として扱います。
   • 削除後は、カード／セクションを上に詰めて、空白を埋め、不要な行を減らします。
6. まず Tier 1 カードを使用して実装します。既存のテンプレートを再利用し、その場限りのスタイルは避けます。
7. フォールバックカードが必要な場合は、Tier 1 では要件を満たせない理由を説明するインラインコメントを追加します。
8. 次の順番で検証します：
   • pwsh -NoProfile -File tools/validate_dashboards.ps1 を実行します。
   • pwsh -NoProfile -File tools/ha_ui_smoke.ps1 を実行します。
   • 利用可能な場合は、Home Assistant の設定検証（ha core check または homeassistant --script check_config）を実行します。
   • このスキルの scripts/validate_lovelace_view.py を、変更した各ビューのファイルに対して実行します。
9. 失敗時の対応：
   • 要件を満たせない場合：違反するルールを示し、準拠する代替案を提案します。
   • 検証に失敗した場合：停止し、エラー出力を提示して、修正済み YAML を提案します。無効な設定を適用したままにしないでください。

フローの例：

• ユーザーが再設計のアイデアを求めた場合 → 必須制約に従って Stitch でアイデアを出す → stitch_intent を要約する → Lovelace で安全に使用できる YAML に変換する → 検証を実行する。

参考資料

• 制約の全容とリポジトリ固有のマッピングに関する注意事項が必要な場合は、references/dashboard_rules.md を読みます。

Home Assistant MCP による検証（利用可能な場合は必須）

Lovelace YAML を記述する前に、次の項目を確認します：

• すべての entity:（および変数を介して参照されるエンティティ）が存在すること。
• 呼び出す予定のサービスがすべて存在し、ペイロードの形式が正しいこと（特に service_data）。

Home Assistant MCP が有効な場合は、次の用途に使用します：

• エンティティを一覧表示して確認する（sensor.foo_bar と sensor.foobar のような入力ミスを防ぎます）。
• ダッシュボードカードの参照先が実在するエンティティと一致することを確認する。
• YAML の変更をコミットする前に、サービス名とフィールドを検証する。

MCP が有効でない、または接続できない場合は、停止して、不足しているエンティティ／サービス ID をユーザーに確認します。作り出さないでください。