Design Md

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

IO_CONTRACT

• input: request: str, context: dict — 用户请求描述、上下文信息
• output: result: dict — 技能执行结果（结构因技能而异）

对应原则：P2（机械原子暴露输入输出规范）

DESIGN.md Skill

DESIGN.md is Google's open spec (Apache-2.0, google-labs-code/design.md) for describing a visual identity to coding agents. One file combines:

• YAML front matter — machine-readable design tokens (normative values)
• Markdown body — human-readable rationale, organized into canonical sections

Tokens give exact values. Prose tells agents why those values exist and how to apply them. The CLI (npx @google/design.md) lints structure + WCAG contrast, diffs versions for regressions, and exports to Tailwind or W3C DTCG JSON.

When to use this skill

• User asks for a DESIGN.md file, design tokens, or a design system spec
• User wants consistent UI/brand across multiple projects or tools
• User pastes an existing DESIGN.md and asks to lint, diff, export, or extend it
• User asks to port a style guide into a format agents can consume
• User wants contrast / WCAG accessibility validation on their color palette

For purely visual inspiration or layout examples, use popular-web-designs instead. For process and taste when designing a one-off HTML artifact from scratch (prototype, deck, landing page, component lab), use claude-design. This skill is for the formal spec file itself.

File anatomy

---
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...

Token types

Component property whitelist: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants (hover, active, pressed) are separate component entries with related key names (button-primary-hover), not nested.

Canonical section order

Sections are optional, but present ones MUST appear in this order. Duplicate headings reject the file.

1. Overview (alias: Brand & Style)
2. Colors
3. Typography
4. Layout (alias: Layout & Spacing)
5. Elevation & Depth (alias: Elevation)
6. Shapes
7. Components
8. Do's and Don'ts

Unknown sections are preserved, not errored. Unknown token names are accepted if the value type is valid. Unknown component properties produce a warning.

Workflow: authoring a new DESIGN.md

1. Ask the user (or infer) the brand tone, accent color, and typography direction. If they provided a site, image, or vibe, translate it to the token shape above.
2. Write DESIGN.md in their project root using write_file. Always include name: and colors:; other sections optional but encouraged.
3. Use token references ({colors.primary}) in the components: section instead of re-typing hex values. Keeps the palette single-source.
4. Lint it (see below). Fix any broken references or WCAG failures before returning.
5. If the user has an existing project, also write Tailwind or DTCG exports next to the file (tailwind.theme.json, tokens.json).

Workflow: lint / diff / export

The CLI is @google/design.md (Node). Use npx — no global install needed.

# 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 theme JSON
npx -y @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

# 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

All commands accept - for stdin. lint returns exit 1 on errors. Use the --format json flag and parse the output if you need to report findings structurally.

Lint rule reference (what the 7 rules catch)

• broken-ref (error) — {colors.missing} points at a non-existent token
• duplicate-section (error) — same ## Heading appears twice
• invalid-color, invalid-dimension, invalid-typography (error)
• wcag-contrast (warning/info) — component textColor vs backgroundColor ratio against WCAG AA (4.5:1) and AAA (7:1)
• unknown-component-property (warning) — outside the whitelist above

When the user cares about accessibility, call this out explicitly in your summary — WCAG findings are the most load-bearing reason to use the CLI.

Pitfalls

-

-

Verification

-

-

• Don't nest component variants. button-primary.hover is wrong; button-primary-hover as a sibling key is right.
• Hex colors must be quoted strings. YAML will otherwise choke on # or truncate values like #1A1C1E oddly.
• Negative dimensions need quotes too. letterSpacing: -0.02em parses as a YAML flow — write letterSpacing: "-0.02em".
• Section order is enforced. If the user gives you prose in a random order, reorder it to match the canonical list before saving.
• version: alpha is the current spec version (as of Apr 2026). The spec is marked alpha — watch for breaking changes.
• Token references resolve by dotted path. {colors.primary} works; {primary} does not.

Spec source of truth

• Repo: https://github.com/google-labs-code/design.md (Apache-2.0)
• CLI: @google/design.md on npm
• License of generated DESIGN.md files: whatever the user's project uses; the spec itself is Apache-2.0.

验证清单 · VERIFICATION

• frontmatter 含必需的 name: 与 colors:，正文 ## 章节按 Overview→Colors→Typography→Layout→Elevation→Shapes→Components→Do's/Don'ts 顺序且无重复标题
• 所有颜色为带引号 hex 字符串、负维度（如 -0.02em）加引号，YAML 解析不报错
• components: 中样式用 {token.path} 引用而非硬编码值；hover/active 等变体为同级键（button-primary-hover）而非嵌套属性
• npx -y @google/design.md lint DESIGN.md 退出码为 0，无 broken-ref / invalid-* 错误；WCAG 对比度结果已在汇报中说明
• 如需导出，export --format tailwind / dtcg 生成的 JSON 可被解析且 token 值与源文件一致

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Design Md

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [DESI-001] 当需要定义组件样式时 → 使用 {token.path} 引用而非硬编码值，确保设计令牌单一数据源
• [DESI-002] 当定义组件交互状态（如 hover/active）时 → 创建独立的同级组件键（如 button-primary-hover）而非嵌套属性
• [DESI-003] 当编写 YAML 中的颜色或负数维度值时 → 必须使用引号包裹字符串（如 "#1A1C1E", "-0.02em"）以防止解析错误
• [DESI-004] 当组织 DESIGN.md 文档结构时 → 严格遵循 Overview 到 Do's and Don'ts 的规范章节顺序，禁止重复标题
• [DESI-005] 当完成 DESIGN.md 编写后 → 必须执行 npx @google/design.md lint 验证结构完整性及 WCAG 对比度合规性
• [DESI-006] 当用户需要跨项目一致性或代码集成时 → 使用 CLI 导出 Tailwind 或 W3C DTCG JSON 格式以对接现有开发工作流