DESIGN.md 仕様

DESIGN.md ファイルには 2 つのレイヤーがあります。YAML front matter には、エージェントが一貫性を保つために使う正確な値、すなわち機械可読なデザイントークンが含まれます。markdown 本文は、## セクションに整理された、人間が読めるデザインの根拠を提供します。文章では、体系的なトークン名（例：primary）に対応する説明的なカラー名（例：「Midnight Forest Green」）を使ってもかまいません。規範となる値はトークンであり、文章はそれらをどのように適用するかの文脈を提供します。

この仕様は処方箋ではなく土台です。エージェント、ツール、チームが依拠できる共通の基盤を提供しつつ、ドメイン固有のニーズに合わせてフォーマットを拡張する自由を保ちます。

デザイントークン

DESIGN.md は、ファイルの先頭に YAML front matter としてデザイントークンを埋め込みます。front matter ブロックは、--- のみを含む行で始まり、--- のみを含む行で終わる必要があります。この区切り文字の間にある YAML コンテンツは、以下で定義するスキーマに従います。

トークンシステムは W3C Design Token Format に着想を得ています。トークンは tokens.json、Figma 変数、Tailwind テーマ設定との間で簡単に相互変換できます。

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
---

スキーマ

version: <string>          # optional, current version: "alpha"
name: <string>
description: <string>      # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

<scale-level> プレースホルダーは、サイズまたは余白のスケールにおける名前付きレベルを表します。一般的なレベル名には xs、sm、md、lg、xl、full があります。説明的な文字列キーであれば、どのようなものでも有効です。

トークンの種類

種類	フォーマット	例
カラー	# + hex コード（sRGB）	"#1A1C1E"
ディメンション	数値 + 単位（px、em、rem）	48px, -0.02em
トークン参照	{path.to.token}	{colors.primary}
タイポグラフィ	複合オブジェクト	以下のプロパティを参照

タイポグラフィのプロパティ

プロパティ	型	説明
fontFamily	string	フォントファミリー名
fontSize	Dimension	フォントサイズ
fontWeight	number	数値のウェイト（例：400、700）。YAML では、裸の数値と引用符付き文字列は同等です
lineHeight	Dimension	number
letterSpacing	Dimension	字間の調整
fontFeature	string	font-feature-settings を設定します
fontVariation	string	font-variation-settings を設定します

トークン参照

トークン参照は波括弧で囲まれ、YAML ツリー内の別の値へのオブジェクトパスを含みます。ほとんどのトークングループでは、参照はグループではなくプリミティブ値（例：{colors.primary-60}）を指す必要があります。components セクション内では、複合値（例：{typography.label-md}）への参照が許可されます。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"

セクション

すべての DESIGN.md は同じ構造に従います。プロジェクトに関係のないセクションは省略できますが、存在するセクションは以下に示す順序で並べる必要があります。すべてのセクションは ## 見出しを使用します。文書タイトル用に任意の # 見出しを置いてもかまいませんが、セクションとして解析されません。

セクション構造は意図的に開かれています。標準セクションは共通の語彙を提供し、デザインシステムはそれらに加えてドメイン固有のセクションを自由に追加できます。

セクションの順序

#	セクション	別名
1	概要	ブランドとスタイル
2	カラー
3	タイポグラフィ
4	レイアウト	レイアウトと余白
5	エレベーションと奥行き	エレベーション
6	シェイプ
7	コンポーネント
8	すべきことと避けること

概要

「Brand & Style」とも呼ばれます。プロダクトの見た目と印象を包括的に説明するセクションです。ブランドのパーソナリティ、ターゲットオーディエンス、UI が呼び起こすべき感情的な反応を定義します。特定のルールやトークンが定義されていない場合の基盤となる文脈として機能します。

## Overview
A calm, professional interface for a healthcare scheduling platform.
Accessibility-first design with high contrast and generous touch targets.

カラー

デザインシステムのカラーパレットを定義します。少なくとも primary パレットを定義する必要があります。追加のパレットには自由に名前を付けられます。一般的な慣例は primary、secondary、tertiary、neutral です。

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** The sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.

デザイントークン： トークン名を hex 値にマッピングする map<string, Color> です。

colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"

タイポグラフィ

タイポグラフィのレベルを定義します。ほとんどのデザインシステムには 9〜15 のレベルがあり、それぞれに意味的な役割（見出し、本文、ラベル）とサイズのバリエーション（小、中、大）があります。

## Typography

- **Headlines:** Public Sans Semi-Bold for an institutional voice.
- **Body:** Public Sans Regular at 16px for long-form readability.
- **Labels:** Space Grotesk for technical data and metadata.

デザイントークン： トークン名をタイポグラフィプロパティにマッピングする map<string, Typography> です。

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em

レイアウト

「Layout & Spacing」とも呼ばれます。レイアウトと余白の戦略（グリッドモデル、余白スケール、コンテインメントの原則）を説明します。

## Layout

The layout follows a Fluid Grid model for mobile and a Fixed-Max-Width
Grid for desktop (max 1200px). A strict 8px spacing scale is used.

デザイントークン： 余白スケールの識別子をディメンションまたは単位なしの数値（例：列数や比率）にマッピングする map<string, Dimension | number> です。

spacing:
  base: 16px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px

エレベーションと奥行き

「Elevation」とも呼ばれます。視覚的な階層がどのように伝えられるかを説明します。影を使うデザインでは影のプロパティを定義します。フラットなデザインでは、代替手段（ボーダー、色調レイヤー、カラーコントラスト）を説明します。

## Elevation & Depth

Depth is achieved through tonal layers rather than heavy shadows.
Background uses a soft off-white; primary content sits on pure white cards.

シェイプ

視覚要素の形（コーナー半径、エッジの処理、全体的な形状言語）を説明します。

## Shapes

All interactive elements use a minimal 4px corner radius.
Modern enough to feel current, rigid enough to feel engineered.

デザイントークン： スケールレベルをコーナー半径にマッピングする map<string, Dimension> です。

rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px

コンポーネント

コンポーネントを構成する基本要素のスタイルガイドです。仕様では一般的なコンポーネントの種類（ボタン、チップ、リスト、入力欄、チェックボックス、ラジオボタン、ツールチップ）を定義していますが、デザインシステムはドメインに関連する追加コンポーネントを定義することが推奨されます。

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill, secondary uses outline
- **Inputs**: 1px border, surface-variant background, 12px padding
- **Cards**: No elevation, 1px outline border, 12px corner radius

デザイントークン： コンポーネント識別子をサブトークンプロパティのグループにマッピングする map<string, map<string, string>> です。トークンの値は、リテラル値または既に定義されたトークンへの参照にできます。

バリアント。 コンポーネントは、異なる UI 状態（hover、active、pressed）のバリアントを持てます。バリアントは、関連するキー名を持つ別個のコンポーネントエントリとして定義します。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

コンポーネントプロパティトークン

プロパティ	型
backgroundColor	Color
textColor	Color
typography	Typography
rounded	Dimension
padding	Dimension
size	Dimension
height	Dimension
width	Dimension

すべきことと避けること

実践的なガイドラインとよくある落とし穴です。生成時のガードレールとして機能します。

## Do's and Don'ts

- Do use the primary color only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

未知のコンテンツに対する利用側の動作

この仕様は拡張できるように設計されています。利用側がこの仕様で定義されていないコンテンツに遭遇した場合：

シナリオ	動作	例
未知のセクション見出し	保持する。エラーにしない	## Iconography
未知のカラートークン名	値が有効であれば受け入れる	surface-container-high: '#ede7dd'
未知のタイポグラフィトークン名	有効なタイポグラフィとして受け入れる	telemetry-data
未知の余白値	受け入れる。有効なディメンションでない場合は文字列として保存	grid-columns: '5'
未知のコンポーネントプロパティ	警告付きで受け入れる	borderColor
重複したセクション見出し	エラー。ファイルを拒否する	## Colors 見出しが 2 つ

推奨トークン名

次の名前は、さまざまなデザインシステムでよく使われています。必須ではありませんが、一貫性のための指針として提供されています。

カラー： primary、secondary、tertiary、neutral、surface、on-surface、error

タイポグラフィ： headline-display、headline-lg、headline-md、body-lg、body-md、body-sm、label-lg、label-md、label-sm

角丸： none、sm、md、lg、xl、full