design-md

DESIGN.md スキル

DESIGN.md は、コーディングエージェントにビジュアルアイデンティティを説明するための Google のオープン仕様（Apache-2.0、google-labs-code/design.md）です。1つのファイルに次の内容をまとめます。

• YAML フロントマター — 機械可読なデザイントークン（規範値）
• Markdown 本文 — 正式なセクションに沿って整理された、人が読める根拠

トークンは正確な値を示します。文章では、それらの値がなぜ存在するのか、どのように適用するのかをエージェントに伝えます。CLI（npx @google/design.md）は、構造と WCAG コントラストを検証し、バージョン間の差分からリグレッションを検出して、Tailwind または W3C DTCG JSON にエクスポートします。

このスキルを使う場合

• ユーザーが DESIGN.md ファイル、デザイントークン、またはデザインシステムの仕様を求めている
• 複数のプロジェクトやツールで一貫した UI／ブランドを実現したい
• ユーザーが既存の DESIGN.md を貼り付け、検証、差分確認、エクスポート、または拡張を求めている
• エージェントが利用できる形式にスタイルガイドを変換したい
• カラーパレットのコントラスト／WCAG アクセシビリティ検証を求めている

純粋に視覚的なインスピレーションやレイアウト例が必要な場合は、代わりに popular-web-designs を使ってください。プロトタイプ、デック、ランディングページ、コンポーネントラボなど、単発の HTML 成果物をゼロからデザインする際の プロセスとセンス については、claude-design を使ってください。このスキルの対象は、正式な仕様ファイル そのものです。

ファイルの構成

---
version: alpha
name: Heritage
description: Architectural minimalism meets journalistic gravitas.
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary}"
---

## Overview

Architectural Minimalism meets Journalistic Gravitas...

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

## Typography

Public Sans for everything except small all-caps labels...

## Components

`button-primary` is the only high-emphasis action on a page...

トークンの種類

種類	形式	例
色	任意の CSS 色（hex、rgb()、oklch()、名前付き）	"#1A1C1E"、"oklch(62% 0.18 250)"
寸法	数値 + 単位（px、em、rem）	48px、-0.02em
トークン参照	{path.to.token}	{colors.primary}
タイポグラフィ	fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation を持つオブジェクト	上記を参照

コンポーネントプロパティの許可リスト：backgroundColor、textColor、typography、 rounded、padding、size、height、width。バリアント（hover、active、 pressed）は、入れ子にするのではなく、関連するキー名（button-primary-hover）を持つ 個別のコンポーネントエントリ として定義します。

正式なセクションの順序

セクションは任意ですが、記載する場合は次の順序にしてください。リンターは、順序が異なるセクション（section-order、warning）と見出しの重複を検出します。仕様に準拠する利用側では重複が拒否されるため、ファイルを返す前に両方を修正してください。

1. Overview（別名：Brand & Style）
2. Colors
3. Typography
4. Layout（別名：Layout & Spacing）
5. Elevation & Depth（別名：Elevation）
6. Shapes
7. Components
8. Do's and Don'ts

不明なセクションはエラーにならず、そのまま保持されます。不明なトークン名も、値の型が有効であれば受け付けられます。不明なコンポーネントプロパティは警告になります。

ワークフロー：新しい DESIGN.md の作成

1. ユーザーに確認する（または推測する）：ブランドのトーン、アクセントカラー、タイポグラフィの方向性を確認してください。サイト、画像、または雰囲気の参考が提示されている場合は、上記のトークン形式に変換してください。
2. write_file を使って、プロジェクトのルートに DESIGN.md を作成します。必ず name: と colors: を含めてください。その他のセクションは任意ですが、推奨されます。
3. components: セクションでは、16進数の値を再入力する代わりに、トークン参照（{colors.primary}）を 使用してください。これにより、パレットを一元管理できます。
4. リンターで検証します（下記を参照）。ファイルを返す前に、参照切れや WCAG 違反を修正してください。
5. ユーザーに既存のプロジェクトがある場合は、ファイルと並べて Tailwind または DTCG のエクスポートも作成してください（tailwind.theme.json、tokens.json）。

ワークフロー：検証／差分確認／エクスポート

CLI は @google/design.md（Node）です。npx を使えば、グローバルインストールは不要です。

# Validate structure + token references + WCAG contrast
npx -y @google/design.md lint DESIGN.md

# Compare two versions, fail on regression (exit 1 = regression)
npx -y @google/design.md diff DESIGN.md DESIGN-v2.md

# Export to Tailwind v3 theme JSON (`tailwind` is a back-compat alias)
npx -y @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Export to a Tailwind v4 CSS @theme block (--color-*, --text-*, --radius-*, ...)
npx -y @google/design.md export --format css-tailwind DESIGN.md > theme.css

# Export to W3C DTCG (Design Tokens Format Module) JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json

# Print the spec itself — useful when injecting into an agent prompt
npx -y @google/design.md spec --rules-only --format json

すべてのコマンドで、標準入力には - を指定できます。lint はエラーがある場合に終了コード 1 を返します（警告のみの場合は終了コード 0）。export はソースにリンターの指摘事項があっても、エクスポートに成功すれば終了コード 0 を返します。指摘事項を終了条件として確認するには、別途 lint を実行してください。デフォルトの出力は JSON です。指摘事項を構造化して報告する必要がある場合は、JSON を解析してください。

Windows では、design.md という実行ファイル名が .md ファイルの関連付けと競合し、何も起きない（無言のまま処理が終了する）か、ファイルがエディターで開くことがあります。ドットを含まない別名を使ってください：npx -y -p @google/design.md designmd lint DESIGN.md。

Lint ルールのリファレンス（9 つのルール、CLI 0.3.0 時点）

• broken-ref（エラー） — {colors.missing} が存在しないトークンを参照しています
• contrast-ratio（警告） — コンポーネントの textColor と backgroundColor のコントラスト比が WCAG AA の基準（4.5:1）を下回っています
• missing-primary（警告） — 色は定義されていますが、primary トークンがありません
• missing-typography（警告） — 色は定義されていますが、タイポグラフィのトークンがありません
• orphaned-tokens（警告） — コンポーネントから一度も参照されていないカラー・トークンがあります
• section-order（警告） — セクションの順序が標準の順序と異なります
• unknown-key（警告） — スキーマのキーのタイプミスと思われるトップレベルの YAML キー（colours: → colors:）。カスタム拡張キーは通知されません
• token-summary、missing-sections（情報） — 件数と存在しない任意のセクション

ユーザーがアクセシビリティを重視している場合は、要約で明示的に触れてください。WCAG に関する検出結果は CLI を使う最も重要な理由です。

注意点

• コンポーネントのバリアントを入れ子にしないでください。 button-primary.hover は誤りです。兄弟キーとしての button-primary-hover が正しい形式です。
• 16 進数カラーは引用符で囲んだ文字列にする必要があります。 そうしないと YAML が # でエラーになったり、#1A1C1E のような値が予期せず切り詰められたりします。
• 負の値を持つ寸法も引用符で囲む必要があります。 letterSpacing: -0.02em は YAML のフローとして解析されます。letterSpacing: "-0.02em" と記述してください。
• リンターが警告するだけでも、セクションの順序は重要です。 ユーザーからランダムな順序の文章が渡された場合は、保存前に標準のリストに従って並べ替えてください。仕様に準拠したコンシューマーはこの順序を前提としています。
• タイポグラフィのサブプロパティのタイプミスは通知されずに無視されます。 CLI 0.3.0 時点では、fontwight: のようなタイプミスがあっても検出結果は出ず、その値はエクスポートから消えます。スキーマと照らし合わせてサブプロパティ名を再確認してください（fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation）。
• version: alpha は現在の仕様バージョンです（2026 年 7 月、CLI 0.3.0 時点）。仕様はアルファ版として示されているため、破壊的変更に注意してください。
• トークン参照はドット区切りのパスで解決されます。 {colors.primary} は機能しますが、{primary} は機能しません。

仕様の一次情報源

• リポジトリ：https://github.com/google-labs-code/design.md（Apache-2.0）
• CLI：npm の @google/design.md
• 生成される DESIGN.md ファイルのライセンス：ユーザーのプロジェクトで使用されているライセンス。仕様自体は Apache-2.0 です。