hamzacakmakk/design-system-generator

デザインシステムジェネレーター

製品を一貫させるための最小限のシステムを構築します。デザインシステムとは、大きな値の集合ではなく、一連の決定です。よく名前付けられた少数のトークンは、誰も使わない網羅的なスケールよりも優れています。

frontend-design スキルがインストールされている場合、frontend-design/references/tokens.md には、コントラストチェック済みの完全なスターターセットが含まれています。そこから始めて適応させてください。

1. 入力

• 現在存在するもの（現在のCSS、Tailwind設定、テーマファイル、コンポーネントライブラリ、ブランド資産）を読み取ります。 実際に使用されている値（色、フォントサイズ、スペーシング、角丸）と、それぞれの出現頻度を棚卸しします。
• プロダクトのトーン、プラットフォーム（Web、iOS、Android）、密度、およびダークモードとハイコントラストモードが必要かどうかを明確にします（または推測して明記します）。

2. アーキテクチャ：3つのレイヤー

1. プリミティブトークン: 生の値とニュートラルな名前。--gray-50 ... --gray-950、--blue-600、--space-4、--radius-md。コンポーネントで直接使用されることはありません。
2. セマンティックトークン: 用途ベースのエイリアス。--bg、--surface、--surface-sunken、--border、--border-strong、--text、--text-muted、--text-subtle、--accent、--accent-fg、--accent-subtle、--focus-ring、--success、--warning、--danger、--info（+ -subtle バリアント）。テーマはこれらを切り替えます。
3. コンポーネントトークン（必要な場合のみ）: --button-height-md、--input-border、--card-padding。コンポーネントを個別にテーマ設定する必要がある場合に追加します。

命名規則: category-role-variant-state（--text-muted、--accent-hover）。セマンティックトークンに色名を含めないでください（--blue ではなく --accent）。

3. 決定すべき事項

• スペーシング: 4px ベース。スケール: 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128。 （Fluent 2 と Material はどちらも 4px をベースにしており、Tailwind のデフォルトスケールも 4px ベースです。）
• タイポグラフィ: 1～2ファミリー。モジュラースケール（高密度: 1.2、プロダクト: 1.25、編集系: 1.333+）。サイズではなく役割（display、title、heading、body、label、caption、code）。役割ごとの行間。display サイズにのみ fluid clamp()。
• 色: 10～12段階のニュートラルランプ（意図的に暖色または寒色寄りに選択）、1つのアクセントランプ、4つのセマンティック色相。ランプは OKLCH で生成し、知覚的に均等な段差にします。
• 角丸: 1つのファミリー（sharp、soft、round）と 3～4段階に加えて full。
• エレベーション: 最大3レベル（raised、floating、overlay）。2層のニュートラルシャドウ。ダークモードでは、強いシャドウよりも明るいサーフェスを優先します。
• モーション: 3つの持続時間（fast ~140ms、base ~220ms、slow ~320ms）、3つのイージング（out、in、in-out）、および reduced-motion ルール。
• レイヤー: 小さな z-index スケール（sticky、dropdown、overlay、dialog、toast、tooltip）。
• ブレークポイント: コンテンツ駆動。一般的なセットは 640、768、1024、1280、1536。

4. テーマとコントラスト

• ライトとダークを一緒に定義します。ダークモード: 背景は黒に近い色（#000 ではない）、テキストはオフホワイト（#fff ではない）、エレベーションには明るいサーフェス、アクセントは明るくやや彩度を下げます。
• prefers-contrast: more バリアントを追加し、境界線と muted テキストを強化します。
• すべてのテキスト/背景のペア を WCAG 2.0 の公式で検証し、コントラスト比を公開します: テキスト 4.5:1、大きなテキストと意味のあるUI（入力境界線、アイコン、フォーカスリング）3:1。ドキュメントに数値を含めます。「AA準拠」と記載する前に、実際に計算してください。

5. 出力物

プロジェクトのスタックに合わせて以下を生成します:

1. tokens.css（CSSカスタムプロパティ、ライト + ダーク + ハイコントラスト）、および/または Tailwind テーママッピング（v4 では @theme、v3 では theme.extend）、および/または tokens.json（パイプライン（Style Dictionary）を使用する場合は W3C Design Tokens Community Group 形式）。
2. 簡潔な DESIGN.md ドキュメント: 原則（3～5行）、コントラスト比を含むトークンテーブル、タイプロール、スペーシング使用ルール、およびコアコンポーネント（button、input、card、dialog、table、toast）の do/don't。
3. オプションで、すべてのトークンとコンポーネントの状態を両方のテーマでレンダリングする単一の styleguide.html / ストーリーページ。システムを視覚的に確認できます。

6. 移行（既存プロダクト）

• 既存の値を最も近いトークンにマッピングします。削除される値とその理由をリストアップします。
• 色、次にスペーシング、タイポグラフィ、最後に角丸とシャドウの順に置き換えます。
• コードベースが大きい場合は、古い名前用の一時的なエイリアスレイヤーを維持します。

チェックリスト

• プリミティブ、セマンティック、および（必要な場合のみ）コンポーネントレイヤーが分離されている。
• コンポーネントはセマンティックトークンのみを参照している。
• ライト、ダーク、およびハイコントラストテーマが存在し、すべてのペアに計算されたコントラスト比がある。
• スペーシングは 4px ベース。角丸ファミリーは1つ。エレベーションレベルは最大3つ。
• タイプロールは display から caption までをカバー。ファミリーは最大2つ、ウェイトは最大3つ。
• モーショントークンには reduced-motion ルールが含まれている。
• ドキュメントでは、各トークンの値だけでなく、いつ使用するかを説明している。