# DESIGN.md Reference

Use this reference after the `design-md` skill triggers. It is a compact working guide based on the Google Labs DESIGN.md alpha specification.

## Purpose

`DESIGN.md` is a plain-text design-system file for coding agents. It has two layers:

- YAML front matter for machine-readable design tokens.
- Markdown prose for design rationale, usage guidance, and constraints.

Tokens are the exact values. Prose explains the design intent and tells the agent how to apply the values.

## File Shape

```markdown
---
version: alpha
name: Product Name
description: Optional one-line summary
colors:
  primary: "#1A1C1E"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 4px
spacing:
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview
...
```

The front matter block must be at the top of the file and delimited by lines containing exactly `---`.

## Token Schema

Top-level token groups:

- `version`: optional, current alpha value is `alpha`.
- `name`: design-system name.
- `description`: optional short summary.
- `colors`: map of color token names to CSS color strings.
- `typography`: map of type role names to typography objects.
- `rounded`: map of radius scale names to dimensions.
- `spacing`: map of spacing names to dimensions or numbers.
- `components`: map of component/state names to component property tokens.

Common color token names: `primary`, `secondary`, `tertiary`, `neutral`, `surface`, `on-surface`, `error`, `on-primary`.

Common typography token names: `headline-display`, `headline-lg`, `headline-md`, `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`.

Common rounded token names: `none`, `sm`, `md`, `lg`, `xl`, `full`.

## Token Types

Color values may be any valid CSS color string. Hex `#RRGGBB` is the safest default for broad tooling support.

Dimensions are numbers with `px`, `em`, or `rem` units. Use unitless `lineHeight` only when intended as a multiplier.

Typography objects may contain:

- `fontFamily`
- `fontSize`
- `fontWeight`
- `lineHeight`
- `letterSpacing`
- `fontFeature`
- `fontVariation`

Token references use `{path.to.token}`. Most references should point to primitive values, such as `{colors.primary}`. Component tokens may reference composite typography objects, such as `{typography.label-md}`.

## Section Order

Use `##` headings. Sections are optional, but present canonical sections should appear in this order:

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

An optional `#` title may appear before the sections. It is not parsed as a design section.

## Section Guidance

`Overview`: describe the product, audience, density, personality, and emotional target. Use specific visual references. Avoid generic adjective lists.

`Colors`: define roles, not just hex values. Explain where each color appears and where it must not appear.

`Typography`: define hierarchy, font families, weights, scale, line heights, casing, data/label treatments, and reading-density decisions.

`Layout`: define grid, max widths, spacing rhythm, density, page gutters, container behavior, and responsive expectations.

`Elevation & Depth`: define whether hierarchy comes from shadows, borders, tonal layers, contrast, surface color, or no elevation.

`Shapes`: define radius, border geometry, sharp/soft language, and where exceptions are allowed.

`Components`: define buttons, inputs, cards, tables, lists, chips, tabs, dialogs, tooltips, and state variants that matter to the product.

`Do's and Don'ts`: include practical guardrails. Keep them intentional; if the list gets long, strengthen the overview and component guidance.

## Components

Known component property tokens:

- `backgroundColor`
- `textColor`
- `typography`
- `rounded`
- `padding`
- `size`
- `height`
- `width`

Represent states and variants as related component keys:

```yaml
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-hover}"
```

Unknown component properties are allowed but should produce a warning during review.

## Consumer Behavior

Preserve unknown section headings. Preserve unknown valid token names. Accept unknown component properties with review warnings. Reject duplicate section headings. Fix broken references.

## Official CLI

Install or run directly:

```bash
npm install @google/design.md
npx @google/design.md lint DESIGN.md
```

Windows/PowerShell reliable form:

```powershell
npx -p @google/design.md designmd lint DESIGN.md
```

Useful commands:

```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 json-tailwind DESIGN.md > tailwind.theme.json
npx -p @google/design.md designmd export --format css-tailwind DESIGN.md > theme.css
npx -p @google/design.md designmd export --format dtcg DESIGN.md > tokens.json
npx -p @google/design.md designmd spec --rules
```

`lint` exits nonzero when errors are present. `diff` exits nonzero when the later file has regressions, such as more errors or warnings.

## Authoring Checklist

- Use a concrete visual reference in `Overview`.
- Include exact values for reusable colors, typography, spacing, radii, and core components.
- Explain scarcity rules for accents, shadows, display type, decorative elements, and motion.
- Use token references for component values instead of duplicating literals.
- Keep prose actionable for future UI generation.
- Validate with the CLI and fix structural errors.

## Applying Checklist

- Read `DESIGN.md` before editing UI.
- Bind exact tokens to CSS variables, Tailwind theme entries, framework theme objects, or component constants.
- Use prose for unstated choices such as density, hierarchy, affordance strength, and restraint.
- Avoid introducing style drift. Add new tokens only when the task expands the design system.
- Re-run lint after editing `DESIGN.md`.

## Source Links

- Repository: https://github.com/google-labs-code/design.md
- Specification: https://github.com/google-labs-code/design.md/blob/main/docs/spec.md
- Philosophy: https://github.com/google-labs-code/design.md/blob/main/PHILOSOPHY.md
