web-design-system

Web デザインシステム

プロダクトの一貫性を高める、最小限のシステムを構築します。装飾的な値を大量にそろえるより、コンポーネントが利用できるセマンティックな契約を優先します。

モードを選択する

• 抽出：プロダクトの見た目に一貫性はあるものの、文書化されていない場合に選択します。
• 調整：複数のパターンが競合している場合に選択します。
• 作成：新しいプロダクトに確立された UI 言語がない場合に選択します。
• 拡張：機能に、システムにない状態やコンポーネントが必要な場合に選択します。

ワークフロー

1. フレームワーク、CSS の方針、テーマファイル、プリミティブ、コンポーネントライブラリ、アイコンセット、代表的な画面を確認します。
2. 繰り返し使われている値やパターンを洗い出します。意図的な違いと、意図せず生じたずれを区別します。
3. コードを変更する前に、生の値をセマンティックな役割に対応付けます。例：blue-600 -> action-primary。「すべての青を置き換える」ではありません。
4. 最小限のトークン階層を定義します。
   • 基礎：色、文字、間隔、角丸、境界線、シャドウ、モーション
   • セマンティックトークン：背景、サーフェス、テキスト、境界線、アクション、フォーカス、ステータス
   • コンポーネントトークン：コンポーネントに本当に必要な場合に限る
5. コンポーネントの構造、バリエーション、サイズ、状態の動作を仕様化します。見た目だけでなく、コンテンツの制約も含めます。
6. デバイス固有の重複を新たに作らず、レスポンシブ動作と密度のルールを定義します。
7. アクセシビリティのデフォルトを定めます。セマンティック要素、名前、ラベル、可視フォーカス、キーボード操作、コントラスト、エラー、ターゲットサイズ、モーションの軽減を含めます。
8. 既存のスタイル機構の中で実装します。並行するトークンシステムは避けます。
9. 代表的なコンポーネントまたは画面を1つ移行し、安全であれば置き換えられた値を削除します。
10. ライト／ダークテーマ、主要な状態、狭い／広いレイアウト、および少なくとも1つの現実的なコンテンツ負荷テストケースを検証します。

システムのルール

• トークンには現在の見た目ではなく、目的に基づいた名前を付けます。
• プリミティブへの直接指定手段は残しつつ、正しい方法をより簡単にします。
• すべての領域をカードに押し込まないでください。
• ステータスを色だけで表現しないでください。
• コンポーネント API は小さく保ち、バリエーションを増やしすぎるより、組み合わせを優先します。
• ユーザビリティ、アクセシビリティ、保守性に問題がない限り、確立されたパターンを維持します。
• 将来のコントリビューターが同じ不整合を再び作りかねない箇所では、判断の内容を文書化します。

成果物の要件

以下を提示します。

1. モードと監査 - 既存のもの、競合しているもの、未対応のもの。
2. トークンマップ - 既存の値 -> セマンティックな役割 -> 実装場所。
3. コンポーネントの契約 - 構造、バリエーション、状態、コンテンツの制限、レスポンシブ動作。
4. 移行範囲 - コード変更が求められている場合、実際のコンポーネントを少なくとも1つ含めます。
5. 検証の証跡 - テーマ、状態、ビューポート、および検証した例外。

参考資料

トークンやコンポーネントの状態を定義または監査する際は、references/token-checklist.md を確認してください。