DESIGN.md

Name: DESIGN.md
Availability: InStock
Author: Google Labs

Free Verified 129 lines By Google Labs Content Marketing Copywriting CRO Design

Description

A portable design system spec for AI coding agents, from Google Labs. Combines YAML front matter (machine-readable tokens: colors, typography, spacing, components) with markdown prose (rationale, do’s and don’ts). Includes a CLI to lint, diff, and export DESIGN.md files to Tailwind config or DTCG tokens.json — so you can brief Claude Code, Cursor, and other agents on brand style once and have it stick across every UI generation.

Stack & Dependencies

Claude Code Node.js @google/design.md CLI

Related Skills

Frequently Asked Questions

What technologies does DESIGN.md require?

This skill works with Claude Code, Node.js, and @google/design.md CLI. Make sure these are available in your project before using the skill with Claude Code.

How detailed is the DESIGN.md skill?

DESIGN.md contains 129 lines of structured instructions. It provides detailed guidance including specific implementation patterns, not just surface-level tips.

Is DESIGN.md free to use?

Yes u2014 DESIGN.md is free. Install it directly with one command (`npx mkt-skills install design-md`) or download the SKILL.md file and drop it into your `~/.claude/skills/` directory. No account, no sign-up, no license fee.

Download SKILL.md GitHub

---
name: design-md
description: Author, validate, and consume DESIGN.md files — a plain-text spec (YAML front matter + markdown prose) that describes a design system to coding agents. Use when the user asks to create/update a design system, brief an agent on brand style, generate a DESIGN.md, lint/diff/export design tokens, or when a project has a DESIGN.md at its root that should drive UI decisions. Based on google-labs-code/design.md.
user-invocable: true
disable-model-invocation: false
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# DESIGN.md

A format specification from Google Labs for describing a visual identity to coding agents. A `DESIGN.md` file combines machine-readable tokens (YAML front matter) with human-readable rationale (markdown prose). Tokens give exact values; prose tells agents *why* and *how* to apply them.

Full spec: `spec.md` in this skill folder (source: https://github.com/google-labs-code/design.md).

## When to use

- User asks to create, update, or review a `DESIGN.md` file.
- User wants to brief an agent on brand/visual style in a portable, persistent way.
- Project has a `DESIGN.md` at its root — read it before generating UI and treat its tokens as normative.
- User wants to lint, diff, or export design tokens (to Tailwind, DTCG tokens.json).

## CLI (run via npx — no install needed)

```bash
npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
npx @google/design.md spec                  # print the spec (good for prompt injection)
npx @google/design.md spec --rules          # spec + linting rules
```

All commands accept `-` for stdin. `lint` exits 1 on errors; `diff` exits 1 on regressions.

Prefer `sfw npx ...` per the global install rule.

## File shape

```md
---
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: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview
...prose...

## Colors
...prose with hex values in bold headings...

## Typography
...prose naming each level's role...
```

## Authoring rules

- **Front matter** is between two `---` fences at the top. Tokens are the source of truth.
- **Colors**: hex only, sRGB, `#` prefix. Define at least `primary`. Common names: `primary`, `secondary`, `tertiary`, `neutral`.
- **Typography**: object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`. Unitless `lineHeight` is a multiplier (recommended).
- **Dimensions**: number + unit (`px`, `em`, `rem`). Spacing values may also be bare numbers.
- **Token references**: `{path.to.token}` — must resolve to a primitive (e.g. `{colors.primary}`). In `components`, composite refs like `{typography.label-md}` are allowed.
- **Components**: map `<name>` to `{ backgroundColor, textColor, typography, rounded, padding, size, height, width }`. Variants (hover, active, pressed) are separate entries with related names: `button-primary-hover`.
- **Sections** (omit as needed, but keep this order):
  1. Overview (aka Brand & Style)
  2. Colors
  3. Typography
  4. Layout (aka Layout & Spacing)
  5. Elevation & Depth
  6. Shapes
  7. Components
  8. Do's and Don'ts
- **Duplicate section headings are errors**; unknown sections/tokens are preserved with warnings.

## Lint rules (what to watch for)

| Rule | Severity |
|---|---|
| `broken-ref` (unresolved `{...}`) | error |
| `missing-primary` | warning |
| `contrast-ratio` (<4.5:1 WCAG AA) | warning |
| `orphaned-tokens` (defined, never referenced) | warning |
| `missing-typography` | warning |
| `section-order` | warning |
| `token-summary`, `missing-sections` | info |

Always run `npx @google/design.md lint` after authoring or editing.

## Consuming a DESIGN.md (when building UI)

1. Read the front matter first — tokens are normative.
2. Read the prose for intent and "why" — it resolves ambiguity the tokens don't cover.
3. Map tokens to the target stack (Tailwind config, CSS vars, Figma variables). Use `export` for mechanical conversions.
4. If a rule isn't explicit, lean on the Overview section's stated personality.

## Workflow shortcuts

- **Create new**: draft front matter → fill prose sections → `lint` → iterate.
- **Brief an agent mid-task**: run `npx @google/design.md spec` and paste into the prompt, alongside the project's `DESIGN.md`.
- **Detect regressions in CI**: `npx @google/design.md diff main-DESIGN.md branch-DESIGN.md` (non-zero exit fails the build).

Description

Stack & Dependencies

Related Skills

Clear Writing

Make Pages Interactive

They Ask You Answer

Technical Writer

Frequently Asked Questions

AI Marketing Skills Newsletter