design-md

DESIGN.md

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

• YAML front matter — machine-readable design tokens (normative values Archie publishes, Nova implements)
• Markdown body — human-readable rationale organised into canonical sections

This skill lives in the engineering plugin because DESIGN.md is the design contract between Archie (who authors it as a frontend artefact) and Nova (who implements UI against it). It belongs alongside frontend/pages.md and frontend/flows.md in docs/architecture/frontend/DESIGN.md.

---

When to use this skill

• Authoring a new design system for a project from scratch
• Archie needs to publish a DESIGN.md as part of docs/architecture/frontend/
• Nova needs to lint or validate a DESIGN.md before implementing components
• Exporting tokens to Tailwind or W3C DTCG JSON for build tooling
• Running WCAG contrast validation on a colour palette

---

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. No serif except for pull-quotes...

## Components

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

---

Token types

Type	Format	Example
Color	# + hex (sRGB), quoted	"#1A1C1E"
Dimension	number + unit (px, em, rem)	48px, "-0.02em"
Token reference	{path.to.token}	{colors.primary}
Typography	object: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation	see above

Component property whitelist: backgroundColor, textColor, typography, rounded, padding, size, height, width.

Variants (hover, active, pressed) are separate sibling entries — button-primary-hover, never nested inside button-primary.

---

Canonical section order

Sections are optional. 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. Unknown token names are accepted if the value type is valid. Unknown component properties produce a warning.

---

Workflow: authoring (Archie's perspective)

When Archie is producing a DESIGN.md as a frontend artefact, follow this sequence:

1. Collect brand inputs — ask for (or infer from) brand tone, primary accent colour, type direction, and any existing brand assets.
2. Write docs/architecture/frontend/DESIGN.md with at minimum name:, version: alpha, and colors:. Add typography, spacing, and components as needed.
3. Use token references ({colors.primary}) in the components: section — never repeat hex values inline.
4. Lint it — fix all errors before publishing to Nova.
5. Note WCAG findings — failing contrast pairs must be flagged to Archie for palette adjustment before Nova builds against the spec.

---

Workflow: implementing (Nova's perspective)

When Nova receives a DESIGN.md from Archie:

1. Lint first — do not implement against a spec with errors.
2. Map tokens to the project's design system:
   • Export to Tailwind theme JSON → merge into tailwind.config.ts
   • Or export to W3C DTCG JSON → import into the token pipeline
3. Never hardcode values that are represented in DESIGN.md — always reference via the exported token variable.
4. Check WCAG warnings — raise any failing pairs with Archie before shipping.

---

CLI reference

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 docs/architecture/frontend/DESIGN.md

# Compare two versions — 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 JSON
npx -y @google/design.md export --format dtcg DESIGN.md > tokens.json

# Print the spec rules (useful when authoring)
npx -y @google/design.md spec --rules-only --format json

Lint rules

Rule	Severity	What it catches
broken-ref	error	{colors.missing} points at a non-existent token
duplicate-section	error	Same ## Heading appears twice
invalid-color	error	Malformed hex or unquoted # value
invalid-dimension	error	Missing unit, or unquoted negative dimension
invalid-typography	error	Missing required field in a type object
wcag-contrast	warning	textColor vs backgroundColor below AA (4.5:1) or AAA (7:1)
unknown-component-property	warning	Property outside the whitelist

---

Pitfalls

• Don't nest variants. button-primary.hover is wrong; button-primary-hover as a sibling key is correct.
• Hex colors must be quoted strings. "#1A1C1E" — unquoted YAML will truncate or error.
• Negative dimensions need quotes. letterSpacing: "-0.02em" not letterSpacing: -0.02em.
• Section order is enforced. Reorder prose to match the canonical list before saving.
• version: alpha is the current spec version (as of mid-2026). Watch for breaking changes.
• Token references resolve by dotted path. {colors.primary} ✓, {primary} ✗.
• WCAG failures are not blocking by default — the CLI exits 0 on warnings. Treat contrast failures as blocking before shipping.

---

Crew integration

Role	Use
Archie	Authors docs/architecture/frontend/DESIGN.md as part of the frontend artefact set. Published before Nova starts component work.
Nova	Lints on receipt, exports tokens into the build pipeline, builds all components against the spec. Never hardcodes values present in DESIGN.md.
Sherlock	Phase-boundary check: verify that Nova's component implementations reference exported token variables, not hardcoded hex values.

---

References

• Spec: https://stitch.withgoogle.com/docs/design-md/specification
• Repo: https://github.com/google-labs-code/design.md (Apache-2.0)
• CLI: @google/design.md on npm
• Stitch MCP: @google/stitch-cli mcp — create_ui / generate_code consume DESIGN.md context