体系的な設計システムの構築
brandスキルはアイデンティティを、frontend-designスキルは画面の見た目を決定します。このスキルは、その見た目を拡張可能な形で構造化する方法を提供します。3層のトークンアーキテクチャと唯一の情報源、すべての状態をカバーするコンポーネント仕様、そして生の値が再び紛れ込むのを防ぐチェック機能を備えています。深く掘り下げたい場合は、以下のリファレンスを参照してください。
| トピック | リファレンス |
|---|---|
| 層構造、命名規則、ダークモード、DTCG JSON、フラットトークンからの移行 | references/token-architecture.md |
| ボタン/入力/カード/バッジ/アラート/ダイアログ/テーブルのバリエーション、サイズ、状態マトリクス | references/component-specs.md |
| 状態の優先順位、フォーカスリング、エラー/ローディングパターン、状態別ARIA | references/states-and-variants.md |
アーキテクチャの概要
/* PRIMITIVE — 生の値、意味なし。ほとんど変更しない。 */
--blue-600: oklch(55% 0.2 264);
/* SEMANTIC — 目的。テーマの継ぎ目: ライト/ダーク/ブランドの上書きはこの層のみ。 */
--color-primary: var(--blue-600);
/* COMPONENT — コンポーネントごとの調整、セマンティックトークンを参照。 */
--button-bg: var(--color-primary);
コンポーネントはコンポーネントトークンまたはセマンティックトークンのみを使用します。プミティブやリテラルは決して使用しません。テーマ（ダーク、ハイコントラスト、セカンドブランド）はセマンティックトークンを再設定するだけで、他の層は変更しません。
唯一の情報源。 リポジトリがW3C Design Tokens Community Group (DTCG) JSONとしてトークンを管理している場合（2025年10月に最初の安定版に達した形式）、それらのファイルが情報源となります。トークンは$valueと$typeを持ち、エイリアスは{color.blue.600}のように記述され、ビルドツール（Style Dictionaryまたは同等のもの）がCSS変数、Tailwindテーマ、ネイティブ値を生成します。JSONを編集して再生成し、生成された出力を手動で編集しないでください。リポジトリにCSSカスタムプロパティしかない場合は、それらが情報源です。第二の情報源を導入しないでください。
手順
- 既存のものを読む。
search_loreを使用して設計システムのADRを見つけ、トークンファイル（*.tokens.json、tokens/、theme.ts、:rootブロック、Tailwind設定）、出力を生成するビルドコマンド、および関連する2つのコンポーネントを特定します。既存のシステムをそのイディオムで拡張し、競合するものを決して追加しないでください。 - 追加する前に監査する。 コンポーネントスタイル内のリテラルをカウントします（以下のコマンド）。見つけたリークは、既存のトークンに置き換えるか、新しいトークンの正当化に使用します。
- 新しいトークンを適切な層に配置する。 真に新しい生の値に対してのみプミティブを使用、新しい目的に対してセマンティック（
--color-surface-raised、--space-section）、1つのコンポーネントが他と異なる必要がある場合のみコンポーネントトークン。名前は外観ではなく目的を表す（--color-dangerであって--color-redではない）。カラーのプミティブはoklch（ハウスイディオム）、タイプはclamp()による流動的スケール、スペーシングは1つの基本単位（4pxまたは8px）に基づく。 - セマンティックな継ぎ目でテーマを設定する。 ダークモードやその他のテーマは、1つのブロック（リポジトリに応じて
[data-theme="dark"]、.dark、または@media (prefers-color-scheme: dark)）でセマンティックトークンを上書きし、color-schemeを設定してネイティブコントロールやスクロールバーも追従させます。プミティブやコンポーネントトークンを上書きするテーマは、継ぎ目の位置が間違っていることを意味します。 - テーマごとのコントラストを検証する。 実際に使用されているすべての前景/背景セマンティックペア（表面のテキスト、プライマリ上のテキスト、表面上の境界、表面上のフォーカスインジケータ）について、各テーマでWCAGコントラスト比を計算します。本文テキストは4.5:1、大きなテキスト、UI境界、フォーカスインジケータは3:1。
oklchの明度はWCAG比ではありません。計算してください（スクリプト、リポジトリのチェッカー、またはテストを使用）。テーブルを記録します。 - コンポーネントを完全に仕様化する。 バリエーション、サイズ（明示的な高さ、パディング、フォントトークン）、および状態マトリクス（デフォルト、ホバー、フォーカス可視、アクティブ、無効、ローディング、エラー、さらに該当する場合は選択/チェック）を、各状態が公開するARIAとともに定義します。複数が適用される場合の優先順位: disabled > loading > error > active > focus > hover > default。フォーカスは常に可視（
--color-ringによる:focus-visibleリング、決してoutline: noneだけではない）。詳細はリファレンスを参照。 - 新製品のシステムを推奨する場合: 製品自体から推論し、キットから始めない — (a) パターンと密度（マーケティング、データ密集型ダッシュボード、トランザクショナルフロー）、(b) 方向性（
brandに従う）、(c) パレットの姿勢（成功/警告/危険/情報を含むセマンティックロール; ダークモードはユーザーが必要な場合のみ）、(d) アクセシビリティとパフォーマンス目標を事前に明示。短い根拠とトークンおよびコンポーネントのスキャフォールドを出力し、視覚的な実行はfrontend-designに委ねます。 - 検証と証跡。 リポジトリがトークン出力をビルドする場合は再生成し、差分が意図したものだけであることを確認。リンター、型チェック、テストを実行。リークチェックを実行。リポジトリのコンポーネントテストやスクリーンショットテストが存在する場合は、変更したコンポーネントをすべてのテーマでレンダリング。
record-evidenceスキルを使用してACごとの証跡を記録（リーク数 before/after、コントラストテーブル）、その後終了します。
リークチェック
変更されたコンポーネントとスタイルファイルで実行（トークンファイル自体は除外）:
- 生の色:
grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components - 生のタイプサイズ:
grep -rEn 'font-size:\s*[0-9.]+px' src/components - コンポーネントから参照されるプミティブ:
grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components - トークンが存在するのにTailwindの任意値を使用:
grep -rEn '\[(#|[0-9]+px)' src/components
パスとプミティブ名はリポジトリに合わせて調整してください。差分内の新しいマッチは、その行がトークン定義自体でない限り、ビルダーが修正すべき欠陥です。レビュアーは、ACやテーマのコントラストを壊すもの以外を(任意)としてリストします。
完了条件
コンポーネントに新しいリテラルやプミティブ参照がない。すべてのテーマがセマンティックトークンのみを上書きする。コントラストテーブルがすべてのテーマで合格する。修正された各コンポーネントの状態マトリクスが可視フォーカス付きで実装されている。生成された出力が情報源と一致する。
ロアのキャプチャ
リポジトリのトークンアーキテクチャ — 層の分割、命名規則、ダークモードの継ぎ目、「コンポーネントでプミティブを参照してはならない」ルールなど — は、次のエージェントが作業を始める前に必要とする正確な事実です。 そのような事実はロアです。以下の方法でキャプチャしてください: あなたのブリーフ（CLAUDE.factory.md、ステップ11「メモリへの貢献」）のロアキャプチャプロトコルに従い、作業の終了時にMemory MCPのsuggest_loreを1回呼び出します。再利用可能な規約、落とし穴、決定、境界のみを含め、チケットごとの些事は含めないでください。