create-design-md

DESIGN.md の作成

1 つの製品または一貫性のある Web サイトの DESIGN.md を作成します。そのデザインを統一するデザイン言語を記録し、存在するすべての値を網羅する必要はありません。

範囲

• 変更するのは DESIGN.md のみです。製品のソースコード、依存関係、設定、生成ファイルは変更しないでください。
• 以下の DESIGN.md 形式の契約に従ってください。独自のスキーマを作らないでください。
• 見つかったトークンやコンポーネントをすべて文書にコピーしないでください。
• 繰り返し、局所的なスタイル、見た目の好みを製品の意図に置き換えないでください。

1. モードの選択

リポジトリモード

ローカルの製品リポジトリが利用できる場合に使用します。選択した製品のルートに DESIGN.md を作成または更新してください。

リポジトリにデプロイ可能な製品が複数含まれている場合は、ユーザーが指定した製品を選択してください。依頼で製品が指定されておらず、どの製品を対象にするか判断できない場合は、作成前に確認してください。

リポジトリの情報から、規範となる値、トークン名、コンポーネントの所有者、文書化された根拠を特定できます。

URL モード

ユーザーから公開 URL が提供され、対応するソースリポジトリが提供されていない場合に使用します。現在のワークスペースに、再構成した DESIGN.md の草案を作成してください。

URL モードでは、レンダリングされたページをブラウザーで確認する必要があります。デスクトップとモバイルの幅で、DOM、計算済みスタイル、公開されている読み込み済みスタイルシートを調査してください。スクリーンショットは解釈の参考にはできますが、それだけでは正確な値を特定できません。

指定されたページと共通の UI を調査してください。サイト全体を対象とする依頼では、異なるテンプレートを代表する同一オリジンのページを最大 3 ページ確認してください。

URL から特定できるのは、観察可能な視覚的パターンと計算済みの値のみです。内部のトークン名、コンポーネントの所有者、文書化されていない根拠、またはパターンが意図的に標準化されているかどうかは特定できません。

レンダリングされたページを確認できない場合は、スクリーンショットまたはソースファイルを依頼してください。コピー、メタデータ、HTML 構造だけを根拠に DESIGN.md を作成しないでください。

ソースが利用できる場合は、必ずリポジトリモードを選択してください。提供された URL はレンダリング結果の確認には使えますが、リポジトリの情報に代わるものではありません。

共通のエビデンス処理パイプライン

モードによって異なるのはエビデンスの収集方法のみです。記録と出力には、どちらのモードでも同じパイプラインを使用してください。

role → value → source → scope → recurrence → confidence

1. 選択したモードを使ってエビデンスを収集します。
2. 候補ごとに、出典、対象範囲、再現性を記録します。
3. 候補を DESIGN.md のスキーマに合わせて正規化します。
4. 不確かな候補、契約のない局所的な候補、実装に関係しない候補は省略します。
5. フロントマターの形式とエクスポートの互換性を検証します。
6. 正規化したフロントマターの検証に合格してから、Markdown を記述します。

リポジトリまたは URL のエビデンスによって、別のトークンスキーマを導入しないでください。どちらのモードにも、同じフラットなトークン名、マッピング形式のタイポグラフィ、省略ルール、エクスポートの条件が適用されます。

生成したドキュメントは、検証に合格するまで非公開にしてください。lint とエクスポートが成功する前に、DESIGN.md の草案を返したり、表示したり、要約したりしないでください。検証で無効な形式または不足しているエクスポートカテゴリが報告された場合は、フロントマターを書き直して再実行してください。カテゴリを修正できない場合は削除し、省略したことを報告してください。

2. 根拠を確認する

リポジトリモードでは、次の順序で確認します。

1. 既存の DESIGN.md と明示的なリポジトリのガイダンス
2. トークン、テーマ、変数、グローバルスタイル
3. 共有プリミティブとそのバリアント
4. 代表的なルートとレンダリングされる利用箇所
5. 表面ごとのローカルな実装

選択したプロダクトがインポート、参照、継承、またはレンダリングするソースのみを対象にします。選択したプロダクトで使われていない提案、移行、サンプル、生成物、レガシー実装、名前の似たパッケージは除外します。

URL モードでは、次の代表的な要素をサンプリングします。

• 色と表面の役割
• タイポグラフィの役割
• 余白とレイアウト
• 境界線、角丸、エレベーション
• ナビゲーション、ボタン、入力欄、カード、繰り返し使われるコンテンツ構造
• デスクトップとモバイルでの表示

視覚的な推定より、計算済みの値と読み込まれた CSS 宣言を優先します。

URL モードの文章や YAML を作成する前に、サンプリングした各ページとビューポートについて、非公開の根拠台帳を作成します。各候補について、ページ、ビューポート、要素の役割、計算済みのプロパティ／値、該当する読み込み済み CSS 宣言またはカスタムプロパティ（確認できる場合）を記録します。ページが読み込む公開スタイルシートを確認し、カスタムプロパティとメディアクエリのルールも調べます。スタイルシートの値を使用できるのは、レンダリングされた要素に適用されているか、サンプリングしたページ全体で繰り返し確認できる場合に限ります。

次のいずれかを満たす場合に、URL の値を DESIGN.md に記載します。（a）レンダリング時の計算済みの値と、読み込み済みの宣言／カスタムプロパティが一致する。（b）必要なサンプル全体で、同じ役割に同じ計算済みの値が繰り返し現れる。どちらも満たさない場合は、その値を省略します。公開されているカスタムプロパティ名をそのまま記載できるのは、宣言とレンダリングでの使用を直接確認できる場合に限ります。生の値から意味的な別名を作り出してはいけません。

URL モードで主張を記載する前に、次の3つの根拠をすべて確認します。

1. 観察：パターンまたは値が、レンダリングされたページ上で視認できるか、計算によって確認できること。
2. 根拠：測定されていること、または必要なサンプルのページ／ビューポート全体で繰り返し確認できること。
3. 影響：DESIGN.md における具体的な実装上の選択に影響すること。

いずれかの根拠が欠けている場合は、その主張を省略します。視覚的な印象をトークンにしたり、単一の出現をサイト全体のルールにしたり、推測した値を YAML に記載したりしてはいけません。正確な値には、計算済みのスタイルまたは読み込み済みの CSS が必要です。確認できない場合は、値を使わず役割だけを説明するか、省略します。

3. 記載する内容を決める

リポジトリモードでは、プロダクトの特徴を説明する前に、明示されたプロダクトの意図またはデザインの参考資料を確認します。URL モードでは、プロダクトの特徴を推測してはいけません。Overview に記載できるのは、サイトの確認可能な目的と表示のみであり、文書が再構成されたものであることも明記します。

YAML は、適用されるソースで名前が定義された共有トークンと役割のみから作成します。ユーティリティクラス、繰り返し使われるリテラル値、コンポーネントの値をトークンスケールにしてはいけません。

フロントマターの形状はスタイル上の選択ではなく、必須条件として扱います。トークングループの値は、スキーマのフィールドを子要素に持つマッピングでなければなりません。スカラーのタイポグラフィ項目（sans: Geist）、任意のネストされたソースオブジェクト（font-family: { mono: ... }）、CSS 変数名からコピーした角丸キー（radius-sm、radius-md など）は出力しないでください。

トークングループにはシーケンスではなくマッピングを使います。適用されるソースでグループレベルのトークンが1つだけ定義されている場合（例：--radius）は、これを base に正規化します。それ以外の場合は、ソースのトークン名を保持します。

ソースの値を DESIGN.md のスキーマフィールドに対応付けます。ソースオブジェクトのネスト構造ではなく、意味的なトークン名を保持します。たとえば、typography.mono: Geist Mono ではなく typography.mono.fontFamily: Geist Mono と記載します。ソースに --radius しかない場合は、rounded.radius や派生した角丸の段階ではなく、rounded.base: 0.625rem と記載します。

正確な値を記載する前に、アクティブなテーマまたは設定を使ってフレームワークのユーティリティを解決します。

フロントマターを書く前に、リポジトリのエクスポート先を特定します。Tailwind v4 なら css-tailwind、Tailwind v3 なら json-tailwind、それ以外なら dtcg を指定します。トークン名は、そのエクスポート先で有効なものにしてください。 テーマモードをエンコードする前に、インストール済みの DESIGN.md 仕様を確認してください。

npx @google/design.md spec

仕様が themes と default-theme をサポートしている場合は、テーマ対応のトークン構文を使用してください。サポートしていない場合は、各正規セマンティックトークンにデフォルトテーマの値を設定し、代替テーマの値は正確なまま ## Themes テーブルに記載してください。-light と -dark のトークン名を並列して作成したり、代替テーマの値を破棄したり、未リリースの構文を使用したりしないでください。フォールバックの Themes テーブルはドキュメントにすぎません。これによってフロントマターがテーマ対応になると見なさないでください。

リポジトリモードでは、すべての文章によるルールを、明示的なガイダンス、名前付きの共有トークンまたはバリアント、あるいは監査対象の少なくとも2つの画面で使用されている共有オーナーによって裏付ける必要があります。そうでない場合は省略してください。

URLモードでは、すべての文章によるルールを直接観察できる必要があります。サイト全体に適用されるルールは、サンプリングした少なくとも2つのテンプレートで繰り返し確認できなければなりません。そうでない場合は、調査したページに対象を限定してください。再構成した役割ベースの名前を使用し、ドキュメントをドラフトとして明記してください。

URLモードの YAML は意図的に簡素ですが、測定可能な証拠がある場合は空にしないでください。3つの証拠要件を満たす値または役割が少なくとも1つ残る場合は、カテゴリを追加してください。色には計算済みの値または検証済みの公開カスタムプロパティを使用できますが、フラットで、エクスポートに安全な形式にしてください。タイポグラフィには fontFamily、fontSize、lineHeight、fontWeight などの正規フィールドを使用してください。角丸と間隔の値は、計算済みスタイルまたは読み込まれた宣言に基づく必要があります。観察結果を整理するためだけに primary、elevated、display などのエイリアスを作成しないでください。コンポーネントセクションを追加できるのは、同じインタラクションまたは表面処理がサンプリングした少なくとも2つのページで繰り返し確認でき、具体的な実装上の選択に影響する場合に限ります。

URLの再構成によってフロントマターのスキーマが変わることはありません。タイポグラフィのプロパティ名には、次のものだけを使用してください：fontFamily、fontSize、lineHeight、fontWeight、letterSpacing。例：

typography:
  sans:
    fontFamily: Inter Variable
  display:
    fontFamily: Inter Variable
    fontSize: 64px
    lineHeight: 64px
    fontWeight: 510

family、size、weight、mobile-display などの URL 固有のエイリアスや、タイポグラフィスケール内の sans／mono のようなネストされた値は、決して出力しないでください。再構成した役割名は異なっていてもかまいませんが、スキーマのフィールド名は変更できません。

URL出力では、ユーザーが別のターゲットを指定しない限り、互換性エクスポート先として css-tailwind を使用してください。再構成した色の役割を、有効なトークン名にフラット化してください。background.primary や foreground.secondary のようなネストされたキーではなく、background-primary、foreground-secondary、border-muted を使用してください。出力するすべてのトークン名は ^[a-zA-Z0-9][a-zA-Z0-9-]*$ に一致する必要があります。このテストに失敗するキーは拒否し、書き換えてください。

Markdownを書く前に、URLのフロントマターを正規化してください。順序は、証拠を収集し、エクスポート先を選び、証拠を正規スキーマにマッピングし、無効な形状を拒否してから、ドキュメントを記述することです。先に文章を書き、後から YAML を合わせることは決してしないでください。

URLのフロントマターは、次の形状ルールを満たす必要があります。

• colors は、有効なトークン名と値のフラットなマッピングです。
• typography は名前付きスケールのマッピングであり、各スケールは正規フィールドのみを使用するマッピングです。
• rounded と spacing は、有効なトークン名と値のフラットなマッピングです。
• components では正規トークンパスを参照できますが、2つ目のトークンスキーマを導入してはいけません。

正規化によってトークン名、フィールド、スケール、またはセマンティックな関係を創作する必要がある場合、その候補は省略してください。

Overview 以外では、Markdownのすべての文が実装上の選択を変えるものでなければなりません。コンポーネントの一覧、一般的なデザインの助言、YAMLを言い換えるだけの文章は削除してください。

すべてのルールについて、その対象範囲と方向性を維持してください。実装が明示的なガイダンスと矛盾する場合は、ガイダンスを記録し、矛盾は DESIGN.md の外で報告してください。

4. ドキュメントを作成する

最小限の有効なフロントマターから始めます。

---
version: alpha
name: <string>
description: <string>
---

必須なのは name のみです。colors、typography、rounded、spacing、components は、該当する名前付きのシステムまたは契約を統括するソースがすでに定義している場合にのみ追加します。実装値を整理するためのトークン名を作成しないでください。トークン参照には {path.to.token} を使用します。

コピーしたソースのネストではなく、スキーマに沿ったマッピングを使用します。タイポグラフィのスケールには必ず名前を付け、そのプロパティをその下にマッピングします。

typography:
  sans:
    fontFamily: Geist
  mono:
    fontFamily: Geist Mono

ソースで --radius のみが定義されている場合は、rounded.radius ではなく rounded.base と記述します。ユーティリティクラスや繰り返し値から sm、md、lg、xl を導き出さないでください。保存する前に、解析済みのフロントマターを確認し、typography の子要素にスカラー値が含まれている場合、または rounded に統括するソースにないキーが含まれている場合は、自分で不適格と判断してください。

## Overview から始めます。製品の目的と、根拠のあるデザインの方向性のみを記述します。ページ、コンポーネント、トークン、実装を要約しないでください。次の順序から、根拠のあるセクションのみを追加します。

1. Colors
2. Themes
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

フォーマットに存在するという理由だけでセクションを作成しないでください。追加するセクションの順序を入れ替えたり、重複させたりしないでください。標準セクションに収まらない、根拠のあるガイダンスがある場合にのみ、未知のセクションを追加します。

Markdown にはデザインの意図と適用ガイダンスを記述します。代替テーマ値を除き、インストール済みの仕様でモードを表現できない場合の ## Themes テーブルを除いて、トークン一覧、コンポーネント設定、ソース構文、ドキュメント作成手法を Markdown に記述しないでください。

統括するソースが明示的な禁止事項を示している場合にのみ、禁止事項を記載します。

• 正確な規範値は、インストール済みの仕様でモードを表現できない場合の代替テーマ値を除き、YAML フロントマターに記載します。
• 根拠のある理由と適用ガイダンスは Markdown に記載します。
• 既存の DESIGN.md にある採用済みの決定は、ユーザーまたは現在の統括する根拠によって置き換えられない限り保持します。
• ブランドの個性、対象ユーザー、感情的な理由を創作しないでください。
• 引用、監査メモ、不採用候補、矛盾、未解決の質問を DESIGN.md に含めないでください。

保存する前に、以下を削除します。

• 統括するソースですでに名前が定義されていない YAML トークン
• ページ固有の動作を製品全体のルールとして示したもの
• 明示的なガイダンスに反する実装パターン
• 明示されていない禁止事項
• YAML フロントマターまたは代替となる ## Themes テーブル以外にある、正確な実装値
• Markdown 内のコンポーネント設定やドキュメント作成手法
• 最終的な DESIGN.md の内容を変えない文

最後に、何も追加しない最終確認を行います。「徹底する」「洗練された状態を保つ」「適切な判断をする」といった曖昧な助言を削除します。根拠の確認条件、スキーマの制約、またはドキュメントを変える適用ルールのみを残します。

5. 検証

構造の lint を実行します。

npx @google/design.md lint DESIGN.md

次に、上で選択したターゲットを使って互換性エクスポートを 1 回実行します。

npx @google/design.md export --format <format> DESIGN.md

出力を確認します。ターゲットがサポートする、値が設定されたフロントマターの各カテゴリは、対応するトークンカテゴリとして出力される必要があります。コマンドが正常に終了しても、カテゴリが空または存在しない場合はスキーマエラーです。カテゴリが出力されるまで、フロントマターを書き直して検証を再実行します。ただし、ターゲットがそのカテゴリを実際に表現できない場合は除きます。値が設定されたカテゴリがエクスポートから欠落している間は、成功を報告しないでください。lint またはエクスポートが失敗した場合、ドキュメントを返さないでください。エクスポーターの制限に合わせるためだけに、サポートされているデザイン情報を削除しないでください。その制限を報告してください。エクスポートされたファイルを作成または保持しないでください。

css-tailwind では、次の出力ファミリーを確認します。colors → --color-*、typography.<name>.fontFamily → --font-*、typography.<name>.fontSize → --text-*、rounded → --radius-*、spacing → --spacing-*。Typography エントリは名前付きスケールです。fontFamily、fontSize、lineHeight は各スケール内に記述し、font-family のような任意のソース階層の下に記述しないでください。typography に値が設定されているにもかかわらず、エクスポートに --font-* も --text-* も含まれていない場合、そのドキュメントは無効であり、報告する前に書き直す必要があります。

既存のドキュメントを更新する場合は、元の内容を一時的に保持し、次を実行します。

npx @google/design.md diff <previous-file> DESIGN.md

削除された、すでに受け入れられている決定があれば、現在の支配的な根拠またはユーザーが明示的に置き換えない限り、元に戻してください。

6. 報告

次を返します。

• モード、および監査対象の製品または URL
• 作成または更新した DESIGN.md
• 使用した支配的な情報源
• ドキュメントから省略した競合または未サポート領域
• 最終的な lint とエクスポートの結果

URL モードでは、出力に「再構成されたドラフト」と明記してください。