---
name: design-md
description: Create, edit, validate, compare, export, and apply Google Labs DESIGN.md files for AI-readable design systems. Use when the user asks to create or use DESIGN.md, convert brand/UI guidance into DESIGN.md, derive design rules from an existing app or screenshots, keep frontend implementation aligned with design tokens and prose, validate DESIGN.md with the @google/design.md CLI, or export DESIGN.md tokens to Tailwind, CSS, JSON, or DTCG formats.
---

# DESIGN.md

Use this skill to make `DESIGN.md` a durable source of truth for a product's visual identity. A `DESIGN.md` combines exact machine-readable tokens in YAML front matter with human-readable design rationale in Markdown.

## Core Workflow

1. Locate and read any existing `DESIGN.md` before UI work. Treat it as design context for implementation, review, and refactoring.
2. If creating one, gather concrete inputs first: existing CSS/Tailwind/theme files, component styles, screenshots, brand notes, typography choices, accessibility constraints, and target audience.
3. Write exact tokens in YAML front matter and explain intent in prose. Tokens provide values; prose explains how to apply them.
4. Validate with the official CLI whenever Node/npm is available. Fix errors before considering the file ready.
5. Apply tokens and prose to implementation, then update `DESIGN.md` if the code intentionally changes the design system.

Read `references/design-md-reference.md` when creating, editing, validating, exporting, or applying a `DESIGN.md`.

Use `assets/DESIGN.md.template` as a starting point for new files when the repo has no existing `DESIGN.md`.

## Creating DESIGN.md

Prefer a specific design reference over vague adjectives. For example, "enterprise observability console with dense tables and quiet operational controls" is more useful than "modern, clean, premium." Include intentional negative constraints only when they prevent likely drift.

Structure the file as:

```markdown
---
version: alpha
name: Product Design System
colors:
  primary: "#1A1C1E"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
---

## Overview
...
```

Use canonical `##` sections in this order when relevant: `Overview`, `Colors`, `Typography`, `Layout`, `Elevation & Depth`, `Shapes`, `Components`, `Do's and Don'ts`. Preserve custom sections when editing existing files.

Include token groups that the implementation can actually use:

- `colors`: CSS color strings such as hex, rgb(), hsl(), oklch(), named colors, or transparent.
- `typography`: objects with font family, size, weight, line height, letter spacing, and optional feature/variation settings.
- `rounded`: radius scale values such as `4px`, `8px`, or `9999px`.
- `spacing`: spacing scale values such as `4px`, `8px`, `1rem`, or domain-specific numeric values.
- `components`: common component style tokens and state variants using literal values or references like `{colors.primary}`.

## Applying DESIGN.md

When building UI from an existing `DESIGN.md`:

1. Parse the YAML tokens first for exact values.
2. Read the prose for personality, density, hierarchy, interaction emphasis, and constraints.
3. Map tokens into the local styling system: CSS variables, Tailwind theme, component props, design-token JSON, or framework-specific theme configuration.
4. Use the design's named roles, not arbitrary nearby values. Do not invent new colors, radii, shadows, or type styles unless the task requires extending the system.
5. Keep visual decisions consistent across new screens and components. When a required pattern is absent, extend the `DESIGN.md` deliberately and validate it.

## CLI

Use the official package for checks and conversion:

```powershell
npx -p @google/design.md designmd lint DESIGN.md
npx -p @google/design.md designmd diff DESIGN.md DESIGN-v2.md
npx -p @google/design.md designmd export --format css-tailwind DESIGN.md > theme.css
npx -p @google/design.md designmd export --format json-tailwind DESIGN.md > tailwind.theme.json
npx -p @google/design.md designmd export --format dtcg DESIGN.md > tokens.json
```

On macOS/Linux, `npx @google/design.md ...` is also acceptable. On Windows/PowerShell, prefer the `designmd` alias via `npx -p @google/design.md designmd ...` because the `.md` executable name can collide with Markdown file associations.

If CLI access is unavailable, manually check:

- Front matter starts and ends with exact `---` fences.
- Token references resolve to existing YAML paths.
- Component text/background color pairs meet WCAG AA contrast for normal text when possible.
- Present sections follow canonical order.
- No duplicate section headings exist.

## Editing Rules

Preserve unknown sections and custom token keys unless the user asks to remove them. Unknown content is allowed by the format and often contains project-specific design context.

Reject or repair duplicate canonical sections, broken token references, obvious misspelled top-level keys, and invalid YAML.

Use `diff` when comparing versions. Treat added errors or warnings as a regression unless the user explicitly accepts the change.

## Sources

Primary reference: https://github.com/google-labs-code/design.md

Official spec: https://github.com/google-labs-code/design.md/blob/main/docs/spec.md
