databricks-app-design

データアプリの設計

Databricks のデータアプリや AI アプリを、内容が明確に伝わり、実際の AppKit コードに落とし込める形で作成します。このスキルは、2 つの知識体系を統合し、実装に結び付けます。

• 構成 — 何を表示し、どこまで抽象化し、どう配置するか → references/dashboard-patterns.md
• 表記法 — 比較可能なものは比較しやすく見せること、誠実な尺度、シナリオのマーク → references/ibcs-notation.md
• 実装 — 使用する AppKit コンポーネント、フック、トークンの詳細 → references/appkit-cheatsheet.md

パッケージスクリプトとプロジェクト固有の CLI ツールについては、親スキルのパッケージマネージャー選択方法とコマンドプレースホルダーを使用してください。

実際のコンポーネントを示さない設計上の助言は不完全です。必ずコンポーネント計画まで提示してください。

使用する場合／使用しない場合

• 使用する場合：カスタムコードの Databricks App（AppKit／React）のデータ画面。概要／KPI ページ、レポート、メトリクス／オントロジーページ、差異分析、チャート、テーブル、Genie／自然言語データサーフェスの設計またはレビュー。
• 使用しない場合：マネージド AI/BI（Lakeview）ダッシュボードの作成（→ databricks-aibi-dashboards）、一般的なフロントエンド（フォーム、認証、設定、マーケティング）、またはスキャフォールディング／ビルド／デプロイ（→ databricks-apps）。「ダッシュボードを作成して」「ダッシュボードを構築して」という単純な依頼（アプリ／AppKit／React／カスタムコードの指定がない場合）は、マネージド AI/BI（Lakeview）ダッシュボードを意味します → このスキルではなく databricks-aibi-dashboards を使用してください。「フォームを追加して」「これをデプロイして」「Lakeview／AI-BI ダッシュボードを構築して」という依頼では、このスキルを適用しないでください。
• 関係性：databricks-apps はアプリをビルド／実行し、このスキルはデータ画面の見た目と、それを実現するプリミティブを決定します。

ワークフロー

1. 条件を整理する — 対象ユーザー、判断／質問、更新頻度、デバイス、主要タスクを 1 文でまとめます。
2. ジャンルを選ぶ — dashboard-patterns.md から最も近いもの（静的／分析／マガジン／インフォグラフィック／リポジトリ／埋め込みミニ）を選び、明示します。
3. 構成する — コンテンツと構成パターン（データの抽象化、メタ情報、レイアウト、インタラクション、色）を選びます。何を要約し、隠し、ページ分割し、またはインタラクティブにするのか、その理由とともにトレードオフを明示します。
4. 表記法を適用する — 該当する ibcs-notation.md のルールを適用します。タイトルでのメッセージ表現、シナリオのマーク（実績／PY／計画／予測）、誠実な尺度、意味に基づく色を確認します。チャート用語に競合がある場合は、IBCS を優先してください（同ファイルの競合に関する注記を参照）。
5. コンポーネントに結び付ける — すべての要素を、実際に @databricks/appkit／@databricks/appkit-ui からエクスポートされているプリミティブに対応付けます（appkit-cheatsheet.md を参照）。AppKit にないコンポーネントを挙げてはいけません。KPI／トレンド／分布用の既成カードはありません。表記法のルールに従い、プリミティブを組み合わせて作成してください。ハードコードした 16 進数ではなく、colorPalette と意味トークンを使用します。useAnalyticsQuery／queryKey と sql.* パラメーターを使ってデータをバインドします。
6. 各状態に対応する — すべてのデータビューで、読み込み中／空／エラー／一部表示に対応します（チェックリストを参照）。
7. レビューする — 両方の参照ファイルにあるチェックリストを実行します。レビューでは、理解度または整合性に最も影響する問題を最初に挙げ、該当するコンポーネント／ファイルを示します。

必須の状態とデータの現実性（データアプリでは必須）

• 読み込み中 → Skeleton、空 → 次に取るべき有用なアクションを含む Empty、エラー → インラインメッセージを表示し、空のパネルにはしない、一部表示／古いデータ → 利用できる情報を表示し、鮮度に関する注記を添えます。
• すべての KPI に単位＋期間＋比較対象＋鮮度／ソースを表示します（メトリクス定義に合わせ、出所のない数値は表示しないでください）。
• 大規模なテーブルには、巨大な結果セットに対するクライアント側の処理ではなく、サーバー側のページネーション／ソート／フィルターを使用します。
• 実行時間の長いクエリには、楽観的な読み込み表示とタイムアウト／エラー時の UX を用意します。

AI / Genie の画面（「AI」の部分）

適用条件： このセクションは、アプリに Genie／チャット／自然言語／「データに質問する」画面がある場合にのみ適用されます。会話形式の入力がないダッシュボード／KPI／レポート専用アプリでは、このセクションと references/genie-ai-trust.md は全体をスキップしてください。 該当する場合は、5 項目すべてを実装してください（コードは references/genie-ai-trust.md にあります）。 Genie／チャット／NL の回答が信頼できるのは、ユーザーがその回答の生成方法と実行ユーザーを確認できる場合のみです。「GenieChat とスピナーを使う」だけでは不十分です。Genie／チャット画面では、必ず次の 5 項目すべてを実装してください（リファレンスのスニペットをそのまま使用してください）。

1. ID — /api/whoami ルート（実際の x-forwarded-email／x-forwarded-user ヘッダーを使用）と、Badge によるサインイン中のユーザー表示。OBO を主張できるのは user_api_scopes: [dashboards.genie] が設定されている場合のみです。それ以外の場合は、クエリがアプリのサービスプリンシパルとして実行されることを明記してください。
2. 生成された SQL — attachments[].query を確認可能な「Generated SQL」Card に表示し、回答の計算方法を決して隠さないでください。
3. ストリーミング／ステータス — useGenieChat().status（streaming／error）を反映し、固まったスピナーを表示しないでください。
4. 免責事項 — 各回答に、常時表示される「AI-generated — verify」という注記を付けてください。
5. ガバナンスと状態 — genie() のスペース設定、実行時の ID に関する正確な注記（ユーザーのスコープが設定されている場合は OBO、それ以外はサービスプリンシパル）、および空／エラー／曖昧な入力への対応（Empty、Alert）。

出力形式

デザイン提案：

## Direction
[Genre, audience, primary task, design intent.]
## Pattern & notation choices
- Composition: [data info, meta info, layout, interaction, color]
- Notation: [message, scenario marks, scales, semantic color]
## Component plan        ← the part that makes it buildable
- [element] → [AppKit component] (queryKey/props), [token/palette], states handled
## Tradeoffs & risks
[What's summarized/hidden/paginated/interactive; overload, scale, a11y, maintenance risks.]

批評： 理解や整合性に関する最も重大な問題から述べ、該当するコンポーネント／ファイルを示したうえで、影響度順に指摘事項を列挙します。それぞれに、具体的な修正内容（変更するコンポーネント／トークン／状態）を記載します。

アンチパターン

• コンポーネント計画のないデザインメモを作成する。
• トークン／パレットを明示せずに「セマンティックカラーを使う」とだけ述べる。
• AppKit がエクスポートしていないコンポーネント（例：組み込みの KpiCard）を挙げる。代わりに、公開されているプリミティブから複合コンポーネントを構成してください。
• タスクに不要なインタラクション、ページ、情報密度を追加する（モック優先のアプリの過剰設計）。
• ローディング／空／エラー状態や、鮮度／ソースのない KPI を見落とす。