taste-design-system

taste-design-system

デザインシステムは意思決定の一覧です。このスキルでは、その一覧を作成し、構造化し、信頼性を保つ方法をエージェントに伝えます。

1. トークンアーキテクチャ（3階層、2階層にはしない）

1. プリミティブトークン — 生の値です：--color-ink-900、--space-4、--radius-md。値以外の意味は持ちません。
2. セマンティックトークン — 値ではなく意味を表します：--color-surface、--color-text-muted、--color-border、--space-inset-lg。プロダクトが使用するのはセマンティックトークンのみです。
3. コンポーネントトークン — コンポーネントごとのエイリアスです：--button-bg-primary、--button-radius、--input-border-width。コンポーネントがプリミティブを直接参照することはありません。

ルール：コンポーネント → セマンティック → プリミティブ → 値。いずれかの階層を飛ばすと、システムが分岐します。

2. トークン形式（自由形式ではなくDTCG）

トークンはフラットなキーのマップ（または、スタックが対応している場合はW3C DTCG JSON）として記述します：

--color-ink-900: #101014;
--color-ink-700: #3B3B40;
--color-accent: #E8540B;
--space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px;
--radius-sm: 2px; --radius-md: 6px; --radius-lg: 12px;
--font-display: 'Archivo', sans-serif; --font-body: 'Inter', sans-serif; --font-mono: 'JetBrains Mono', monospace;

命名規則：kebab-case、名詞を先にし、スケールを最後にします（--space-4、--color-ink-900、--radius-md）。名前に意図を含めること（「fancy-purple」など）は避け、コンポーネント内で16進数の色を直接使わないでください。

3. インベントリ（構築前に監査する）

何かを構築する前に、インベントリを作成します：

1. 色 — コードベース内の16進数をすべて列挙します。トークンセットに含まれない値があれば記録します（独自の色が15色を超える場合、システムに問題があります）。
2. スペーシング — 4px（または8px）スケールにないマージンやパディングを記録します。
3. タイポグラフィ — 使用中のフォントサイズとウェイトの種類を数えます。1ページに5サイズを超える場合、階層がありません。
4. 角丸／エレベーション／ボーダー — 値をすべて収集し、2～4個のトークンにまとめます。
5. コンポーネント — コンポーネントをすべて列挙します。同じ役割を担うバリアントが3つを超えるコンポーネントや、生の値を使ってスタイルを定義しているコンポーネントがあれば記録します。

出力：トークンマップ、違反の件数一覧、修正順序（プリミティブ、セマンティックマッピング、コンポーネントの整理の順）。監査と同じ工程でシステムをリファクタリングしてはいけません。監査、報告、その後に変更を行います。

4. スケール（固定の基準）

• スペーシング： 4/8/12/16/24/32/48/64/96。4px未満のギャップは、極細のボーダーに限ります。意図的な光学的調整として記録されている場合を除き、5、7、10、14pxは使用しないでください。
• タイポグラフィスケール（流動的）： 12/14/16/18/24/32/48/64。レスポンシブにする箇所ではclamp()を使って描画します。
• カラースケール： OKLCHで50→950の9～11段階（知覚的に均等）、ニュートラルと少なくとも1つのアクセントファミリーを用意します。ダークモードでは、新しい色を追加するのではなく、セマンティックマッピングを変更します。
• エレベーション： 最大3段階です。フラット（シャドウなし）、レイズド（控えめ、ぼかし ≥ 16px、不透明度 ≤ 0.15）、フローティング（ぼかし ≥ 40px、不透明度 ≤ 0.2）。それ以外はすべて不具合です。

5. コンポーネントの構成（すべてのコンポーネントに含めるもの）

1. 役割は1つ、名前も1つです。説明に「および」が含まれるコンポーネントは分割します。
2. 完全な状態マトリクス：デフォルト、ホバー、アクティブ／押下、フォーカス可視、無効、読み込み中、エラー。実現できない状態がある場合は、その理由を記載します。
3. サイズバリアントは必要な場合に限ります（sm/md/lg）。状態の代わりに色のバリアントを使ってはいけません。
4. レスポンシブ時の動作と、変更が発生するブレークポイント。
5. コード内でのトークン参照。コンポーネントのスタイルに生の値は一切使いません。

6. ドキュメントとガバナンス

• コンポーネントごとに1ページ用意します。目的、構成図（コードコメントとして記載）、状態マトリクス、使用ルール、使用例と避けるべき例、アクセシビリティに関する注記を記載します。
• 変更プロセス：トークンの変更は追加方式にします（新しいトークンを追加 → 古いトークンを非推奨にする → 1リリースサイクル後に削除）。トークンの値を予告なく変更してはいけません。
• オーナーシップ：トークンファイルを管理するのは1人（または1つのスキル）です。コンポーネントに関する意思決定は、その管理者を通じて行います。
• 導入指標（四半期ごとに測定）： セマンティックトークンを使用する画面の割合、生の色に関する違反件数、スケール外のスペーシング値の件数、状態が文書化されているコンポーネントの割合。重要なのは、違反件数が減少傾向にあることです。

7. チェックリスト（次の場合はシステムを不合格にする）

• コンポーネントがプリミティブを直接参照している。
• UI で、トークンセットに含まれていない 16 進数カラーコードを使用している。
• ドキュメントに記載された例外なく、スペーシングの値がスケールから外れている。
• コンポーネントに無効状態またはフォーカス可視状態がない。
• 使用しているエレベーションのレベルが 3 を超えている。
• トークン名に意味と値の両方が含まれている（セマンティックな名前ではなく、"dark-purple" など）。
• 異なる API を持ちながら、同じ役割を果たすコンポーネントが 2 つ存在する。

トークンは、デザインシステムの記憶です。システムが記憶できなければ、同じことを繰り返します。ページも同じです。