# Design Md

> Create, update, validate, diff, or export DESIGN.md files following the Google Stitch DESIGN.md spec and @google/design.md tooling. Use when the user asks to write/update DESIGN.md, create a design system document, generate design tokens, encode brand/UI guidelines, export a design system, or document UI consistency rules for AI agents. Do NOT use for ordinary UI implementation unless the user asks for DESIGN.md or design-system documentation.

- Skill: `bolasblack/design-md` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add bolasblack/design-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bolasblack/design-md/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: bolasblack (https://skillmd.com/u/bolasblack)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/bolasblack/design-md

---


# DESIGN.md

Create or update a project-root `DESIGN.md` using the DESIGN.md format: preferably YAML front matter for machine-readable design tokens, followed by markdown sections for human-readable design rationale.

## Source of Truth

Read `references/format.md` first. It is the reference index and tells you which detailed files to load for the task.

Use two upstream sources:

1. `google-labs-code/design.md` is authoritative for spec, CLI, linter, export formats, and what `@google/design.md` accepts.
2. Stitch docs explain product/UI behavior and examples. When opening Stitch documentation pages, the actual documentation content may be nested inside two iframe layers; inspect the page's nested iframe tree and open the innermost documentation frame if normal page text is empty.

If these sources conflict, prefer `google-labs-code/design.md` for validation/tooling behavior and Stitch docs for Stitch UI behavior. When creating new files, generate YAML front matter by default; when validating existing files, accept prose-only files if the official tooling accepts them, but recommend adding front matter for precise agent/tool control.

Detailed references:
- `references/overview.md` for the DESIGN.md concept, creation paths, and minimal example.
- `references/specification.md` for YAML front matter, token schema, token references, canonical section order, aliases, and unknown-content behavior.
- `references/usage.md` for Stitch view/edit/export behavior and outside-Stitch workflow.
- `references/cli.md` for `@google/design.md` lint, diff, export, spec, and programmatic API behavior.
- `references/linting-rules.md` for the 8 linter rules and manual validation checklist.

The core rule: tokens are the normative values; prose provides context for how to apply them. Generate the token layer and rationale layer together.

## What This Skill Covers

The current Stitch DESIGN.md docs are split across five pages, all summarized in `references/format.md`:

- **What is DESIGN.md?**: purpose, creation paths, and the two-layer token/prose model.
- **The specification**: YAML front matter schema, token types, token references, canonical sections, aliases, and unknown-content behavior.
- **View, edit, and export**: how Stitch exposes the active design system, project defaults, editable token groups, export behavior, and outside-Stitch workflow.
- **Validate with the CLI**: lint, diff, export, spec, and programmatic API behavior for `@google/design.md`.
- **Linting rules**: the 8 rules agents should satisfy or report: `broken-ref`, `missing-primary`, `contrast-ratio`, `orphaned-tokens`, `missing-typography`, `section-order`, `missing-sections`, and `token-summary`.

## Workflow

### 1. Determine the task

- **Create**: no `DESIGN.md` exists, or the user asks for a new design system.
- **Update**: `DESIGN.md` exists and the user asks for a targeted change.
- **Validate**: the user asks whether a `DESIGN.md` follows the spec.
- **Export or integrate**: the user asks how to use `DESIGN.md` outside Stitch, export tokens, or carry the design system into code.
- **Reconcile**: the user asks to align `DESIGN.md` with current UI, brand assets, screenshots, or code.

### 2. Gather design context

Check, as available:

- Existing `DESIGN.md`
- README/product description
- Theme files, CSS variables, Tailwind config, component library config
- Representative UI components
- Brand URLs, screenshots, logos, or user-provided vibe prompts

If the project has no design context and the user gave no direction, ask for the product type, target platform, and intended look/feel.

### 3. Write the YAML token layer

For new or substantially rebuilt files, `DESIGN.md` should start with YAML front matter delimited by `---` lines. For existing prose-only files, do not mark the file invalid solely because front matter is absent if the official tooling accepts it; recommend adding front matter when precise token control matters.

Use the Stitch token schema:

- `version` optional, current version is `alpha`
- `name` required
- `description` optional
- `colors`
- `typography`
- `rounded`
- `spacing`
- `components`

Use exact values from existing code or brand assets when available. Token references use `{path.to.token}` syntax, for example `{colors.primary}` or `{rounded.md}`.

### 4. Write the markdown rationale layer

Use the canonical section order from the Stitch spec for recognized sections:

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

Sections can be omitted when irrelevant, but keep recognized sections in order. Unknown sections are allowed and should be preserved.

### 5. Update safely

When editing an existing `DESIGN.md`:

- Preserve custom sections and unknown tokens.
- Do not discard user-authored rationale.
- Fix broken token references instead of removing dependent components.
- Keep aliases recognizable: `Brand & Style` for Overview, `Layout & Spacing` for Layout, `Elevation` for Elevation & Depth.
- Avoid introducing duplicate recognized sections.

### 6. Validate

Use the `@google/design.md` CLI only when it is already installed in the project or globally. Do not run plain `npx @google/design.md ...`, because it can install the package implicitly.

If the CLI is unavailable, validate manually using `references/format.md`. If the user wants CLI validation and the package is not installed, first run the dependency-safety workflow and get explicit approval before installing or invoking package-manager commands that may install it.

- YAML front matter parses and has valid token types when present; new files should include it.
- Token references resolve.
- Unknown component sub-token properties are intentional and reported as warnings; prefer recognized properties for interoperability.
- Sections are in canonical order.
- Component text/background color pairs meet WCAG AA 4.5:1.
- Colors include `primary` when colors are defined.
- Typography exists when colors are defined.
- Optional `spacing` and `rounded` sections are present when explicit control matters.

## Examples

### Create from a vibe prompt

**User says:** "Create a DESIGN.md for a playful coffee shop ordering app with warm colors, rounded corners, and a friendly feel."

**Actions:**
1. Inspect existing app/theme files if present.
2. Read `references/overview.md` and `references/specification.md`.
3. Create YAML tokens for colors, typography, rounded, spacing, and core components.
4. Add markdown sections explaining the warm, rounded, friendly design rationale.

### Derive from existing branding

**User says:** "Make a DESIGN.md from our homepage and app components."

**Actions:**
1. Read `references/overview.md` and `references/specification.md`.
2. Read brand colors, fonts, spacing, and component patterns from the site/code.
3. Encode exact values as YAML tokens.
4. Use markdown sections to explain where each token should be applied.

### Validate a file

**User says:** "Check whether this DESIGN.md is valid."

**Actions:**
1. Read `references/cli.md` and `references/linting-rules.md`.
2. Use the CLI only if available without new installation.
3. Otherwise manually check Stitch lint rules from `references/linting-rules.md`.
4. Report errors, warnings, and concrete fixes.

## Version History

- v2.0.0: Rebuilt around the Stitch DESIGN.md overview, specification, CLI, and linting rules.
- v1.0.0: Initial version based on the Stitch DESIGN.md overview.