ui-craft

UI Craft

横断的なスキルです。 このスキルは、ライブラリ固有のスキル（spartan-ng-developer、primeng-developer、ng-zorro-developer、angular-material-developer）のいずれかに、ベースとなる angular-developer と組み合わせて使用します。このスキルでは、優れた UI とはどのようなものか、なぜ優れているのかを学びます。ライブラリ固有のスキルでは、どのコンポーネントを使うべきかを学びます。ユーザーが洗練された UI を求めている場合は、両方を読み込みます。

このスキルを適用するタイミング

ユーザーが次のように言った場合は、積極的に適用します。

• 「見た目をもっと良く／すっきり／洗練させて」
• 「なんだかありきたり」／「テンプレートみたい」
• 「ダッシュボードを改善して」／「このページを再設計して」
• 「なぜ素人っぽく見えるのか」
• 具体的な話題：「階層」「間隔」「タイポグラフィ」「カラーパレット」「影」「空の状態」「ツールチップ」「ホバー状態」「読み込み状態」

また、次のような状況を見かけた場合は、依頼がなくても先回りして適用します。

• ダッシュボードやデータ量の多い画面を構築している
• すべての文字がグレーで、配置に統一感がなく、控えめな表示とアクティブな表示の区別もないテーブル
• フォームのラベルと値のウェイトや色が同じ
• 色だけを識別手段として使い、アイコン、テキスト、形状による補助がない
• ホバー時にしか使えず、操作できることを示す手がかりがないアクション
• 非同期の画面に空の状態や読み込み状態がまったくない

素人っぽいダッシュボードを見分ける3つのポイント

意図を持たずに作られた UI だとすぐにわかるパターンです。それぞれ単なるルールではなく、ひとつの分野であるため、個別のリファレンスファイルを用意しています。

1. UI はデータに基づいて作ります。 その逆ではありません。形状、密度、配置、色、グラフとテーブルのどちらを選ぶかは、すべて表示するデータに応じて決めます。デフォルトのテーブルテンプレートを使うのではありません。data-driven-ui.md を参照してください。

2. 段階的に情報を開示します。 ほとんどのアクション、コントロール、メタデータは、常に画面に表示しておく必要はありません。ホバー、ポップオーバー、シート、コンテキストメニューの背後に隠し、操作できることを明確に示します。「明示性のスペクトラム」は、常に表示されるグローバルアクションから、ホバー時に表示される行アクション、右クリックで表示されるパワーユーザー向けアクションまで広がります。progressive-disclosure.md を参照してください。

3. UI は見えない部分にこそあります。 アイコンのみのボタンに付けるツールチップ、クリック可能な領域に設けるホバー時の手がかり、空の状態、読み込み状態、エラー状態、右クリックメニュー、キーボードショートカット、保存時のトースト通知。こうした隠れた要素が、実際の UI の大部分を占めます。hidden-ui.md を参照してください。

Refactoring UI の原則

Adam Wathan と Steve Schoger による書籍 Refactoring UI では、レイアウトがしっくりくる理由を説明するための語彙を学べます。各章に対応するリファレンスを用意しています。

• 階層、すべての要素が同じ重要度ではありません。目立たせるには、それ以外を控えめにします。ラベルの使用は最終手段です。視覚的な階層と文書の階層を分けて考えます。hierarchy.md を参照してください。
• 間隔、まずは余白を多めに取り、そこからサイズのシステムを作ります。画面を埋めるためだけに要素を詰め込まないでください。曖昧な間隔は避けます。spacing.md を参照してください。
• タイポグラフィ、文字サイズのスケールを定めます。行の長さ（45～75ch）に注意します。行の高さはフォントサイズに比例させます。中央揃えではなく、ベースラインを揃えます。typography.md を参照してください。
• 色、HEX ではなく HSL または OKLCH を使います。色相ごとに9段階のシェードシステムを定義します。明度を上げすぎて彩度を損なわないようにします。グレーは必ずしも無彩色である必要はありません。色だけを識別手段にしないでください。color.md を参照してください。
• 奥行き、光源を模倣します。影で高さを表現します。2つの要素からなる影（近接＋環境）を使います。フラットなデザインでも、重なりや明暗のコントラストで奥行きを表現できます。depth.md を参照してください。
• 仕上げの工夫、デフォルトの見た目を強化します。アクセントとなる境界線を加えます。空の背景に装飾を加えます。空の状態を省略しないでください。境界線を減らし、明暗のコントラストを強めます。finishing.md を参照してください。

ダッシュボード固有のパターン

ダッシュボード、テーブル、KPI 表示領域、またはデータ量の多いビューを構築または改善する場合は、dashboard-patterns.md もお読みください。次の内容を扱っています。

• KPI カードのパターン（ラベル、値、増減、スパークライン）
• テーブルの仕上げ（列挙値にはチップを使用、数値は右揃え、長いテキストは省略、非アクティブな行は控えめに表示、ヘッダーを固定、ホバー時のアクションを非表示）
• フィルターバーの慣例（トグルグループ、コンボボックス、日付範囲、「ビューとして保存」）
• サイドバーナビゲーションの密度
• テーブルではなくチャートを使うタイミング（データに意味のある X 軸がある場合はいつでも）

ライブラリスキルとの連携

4 つのライブラリスキルでは、どの Helm / Aura / NG-ZORRO / Material コンポーネントを使うかを説明します。このスキルでは、見た目をどう整えるかを説明します。連携ファイルでは、どのデザイントークンをオーバーライドするか、どの密度モードを選ぶか、また標準設定のままでは適切でない一般的な項目を含め、各原則を 4 つのライブラリに対応付けています。library-bridge.md をお読みください。

作業原則

1. 生成する前に批評する。 ユーザーが既存のコードを持っている場合は、それを読んでから、リファクタリングの前に具体的な問題点（色付き背景上のグレーのラベル、省略表示なし、状態の控えめな表示なし）を指摘してください。問題点に名前を付けることは、ユーザーの学びにもつながります。

2. 重要な変更では変更前後を示す。 余白、階層、または色を変更する場合は、変更の「理由」を 1 行で説明し、変更の意図が分からなくならないようにしてください。「レビュー担当者列を 152px から 96px に縮小し、アバターが余白のある状態で浮いて見えるのではなく、行の右側のパディングにぴったり揃うようにしました。」

3. Tailwind を優先し、デザイントークンを意識する。 4 つのライブラリスキルはいずれも Tailwind と組み合わせて使えます。個別の仕上げにはユーティリティクラスを使いますが、ダークモードやテーマ設定をそのまま利用できるよう、テーマトークン（text-muted-foreground、border-border、bg-card）を優先してください。16 進数カラーを直接指定してはいけません。

4. 密度は選択するものであり、デフォルトではありません。 コンポーネントライブラリの標準密度は、通常、ダッシュボードには間隔が広すぎます。ライブラリの密度トークンを使って詰めてください（Material：density-3、Spartan：より小さな size バリアント、PrimeNG：--p-form-field-padding、ZORRO：nzSize="small"）。library-bridge.md を参照してください。

5. 理由なく新しいコンポーネントを追加しない。 Helm／PrimeNG／NG-ZORRO／Material のコンポーネントで対応できる場合は、それを使ってください。カスタムコンポーネントには、独自のバグが入り込む可能性があります。

6. 空、読み込み中、エラーの各状態は必須です。 非同期の表示領域には、必ずこの 3 つすべてを用意してください。ライブラリの Skeleton／Empty／Alert プリミティブを使用します。

7. アクセシビリティも技術の一部です。 フォーカスリング、アイコンのみのボタンの ARIA ラベル、キーボードショートカット、コントラスト比に配慮してください。各ライブラリスキルの accessibility.md では具体的な方法を説明していますが、その「意図」はここにあります。