design.md
A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/google-labs-code/design.md with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/google-labs-code/design.md'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/google-labs-code--design-md)HTML
<a href="/listings/google-labs-code--design-md"><img src="/api/listings/google-labs-code--design-md/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Validate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.
npx @google/design.md lint DESIGN.md
{
"findings": [
{
"severity": "warning",
"path": "components.button-primary",
"message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
}
],
"summary": { "errors": 0, "warnings": 1, "infos": 1 }
}Compare two versions of a design system to detect token-level and prose regressions:
npx @google/design.md diff DESIGN.md DESIGN-v2.md
{
"tokens": {
"colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
"typography": { "added": [], "removed": [], "modified": [] },
"rounded": { "added": [], "removed": [], "modified": [] },
"spacing": { "added": [], "removed": [], "modified": [] },
"components": { "added": [], "removed": [], "modified": [] }
},
"findings": {
"before": { "errors": 0, "warnings": 1, "infos": 1 },
"after": { "errors": 0, "warnings": 1, "infos": 1 },
"delta": { "errors": 0, "warnings": 0 }
},
"regression": false
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 394 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # DESIGN.md
- A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
- ## The Format
- A DESIGN.md file combines machine-readable design tokens (YAML front matter or interleaved YAML code blocks) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them *why* those values exist and how to apply them.
- ```md
- ---
- name: Heritage
- colors:
- primary: "#1A1C1E"
- secondary: "#6C7278"
- tertiary: "#B8422E"
- neutral: "#F7F5F2"
- typography:
- h1:
- fontFamily: Public Sans
- fontSize: 3rem
- body-md:
- fontFamily: Public Sans
- fontSize: 1rem
- label-caps:
- fontFamily: Space Grotesk
- fontSize: 0.75rem
- rounded:
- sm: 4px
- md: 8px
- spacing:
- sm: 8px
- md: 16px
- ---
- ## Overview
- Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
- premium matte finish — a high-end broadsheet or contemporary gallery.
- ## Colors
- The palette is rooted in high-contrast neutrals and a single accent color.
- - **Primary (#1A1C1E):** Deep ink for headlines and core text.
- - **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- - **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- - **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.
- ```
- An agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.
- ## Getting Started
- Validate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.
- ```bash
- npx @google/design.md lint DESIGN.md
- ```
- ```json
- {
- "findings": [
- {
- "severity": "warning",
- "path": "components.button-primary",
- "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
- }
- ],
- "summary": { "errors": 0, "warnings": 1, "infos": 1 }
- }
- ```
- Compare two versions of a design system to detect token-level and prose regressions:
- ```bash
- npx @google/design.md diff DESIGN.md DESIGN-v2.md
- ```
- ```json
- {
- "tokens": {
- "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
- "typography": { "added": [], "removed": [], "modified": [] },
- "rounded": { "added": [], "removed": [], "modified": [] },
- "spacing": { "added": [], "removed": [], "modified": [] },
- "components": { "added": [], "removed": [], "modified": [] }
- },
- "findings": {
- "before": { "errors": 0, "warnings": 1, "infos": 1 },
- "after": { "errors": 0, "warnings": 1, "infos": 1 },
- "delta": { "errors": 0, "warnings": 0 }
- },
- "regression": false
- }
- ```
- ## The Specification
- The full DESIGN.md spec lives at [`docs/spec.md`](docs/spec.md). What follows is a condensed reference.
- ### File Structure
- A DESIGN.md file has two layers:
- 1. **YAML Design tokens** — Machine-readable design tokens, delimited by `---` fences at the top of the file or interleaved as fenced ` ```yaml ` code blocks within each `##` section.
- 2. **Markdown body** — Human-readable design rationale organized into `##` sections.
- The tokens are the normative values. The prose provides context for how to apply them.
- ### Token Schema
- ```yaml
- version: <string> # optional, current: "alpha"
- name: <string>
- description: <string> # optional
- omitted: <string[] | OmittedSection[]> # optional, list of sections to intentionally omit
- colors:
- <token-name>: <Color>
- <group-name>: # optional nested group
- <token-name>: <Color>
- typography:
- <token-name>: <Typography>
- <group-name>: # optional nested group
- <token-name>: <Typography>
- rounded:
- <scale-level>: <Dimension>
- <group-name>: # optional nested group
- <scale-level>: <Dimension>
- spacing:
- <scale-level>: <Dimension | number>
- <group-name>: # optional nested group
- <scale-level>: <Dimension | number>
- motion:
- <token-name>: <Motion>
- components:
- <component-name>:
- <token-name>: <string | token reference>
- ```
- ### Token Types
- | Type | Format | Example |
- |:-----|:-------|:--------|
- | Color | Any CSS color (hex, `rgb()`, `oklch()`, named, etc.) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
- | Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
- | Duration | number + `ms` | `100ms`, `250ms` |
- | Token Reference | `{path.to.token}` | `{colors.primary}`, `{colors.light.surface}`, `{typography.sm.headline-lg}` |
- | Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | See example above |
- | Motion | object with `duration`, `delay`, `timingFunction` | `duration: 100ms`, `timingFunction: ease-out` |
- ### Section Order
- Sections use `##` headings. They can be omitted, but those present must appear in this order:
- | # | Section | Aliases |
- |:--|:--------|:--------|
- | 1 | Overview | Brand & Style |
- | 2 | Colors | |
- | 3 | Typography | |
- | 4 | Layout | Layout & Spacing |
- | 5 | Elevation & Depth | Elevation |
- | 6 | Shapes | |
- | 7 | Motion & Micro-interaction | Motion & Micro-interactions, Motion |
- | 8 | Voice & Content Strategy | |
- | 9 | Components | |
- | 10 | Do's and Don'ts | |
- ### Component Tokens
- Components map a name to a group of sub-token properties:
- ```yaml
- components:
- button-primary:
- backgroundColor: "{colors.tertiary}"
- textColor: "{colors.on-tertiary}"
- rounded: "{rounded.sm}"
- padding: 12px
- button-primary-hover:
- backgroundColor: "{colors.tertiary-container}"
- ```
- Valid component properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`.
- Variants (hover, active, pressed) are expressed as separate component entries with a related key name.
- The components section may use external references (`@<path>[#<fragment>]` in inline code spans) to point to further elaboration of the component kit, such as component templates in HTML or component source code in JSX:
- ```markdown
- ## Components
- - **Buttons** → `@components/button.html` — `button-primary`, `button-secondary`, `button-tertiary`, `button-icon`
- - **Cards** → `@components/card.html` — `card-elevated`, `card-outlined`
- ```
- ### Consumer Behavior for Unknown Content
- | Scenario | Behavior |
- |:---------|:---------|
- | Unknown section heading | Preserve; do not error |
- | Unknown color token name | Accept if value is valid |
- | Unknown typography token name | Accept as valid typography |
- | Unknown motion token name | Accept as valid motion |
- | Grouped token sub-map | Flatten to dot-separated token path |
- | Flat and grouped token name collision | Error; reject the conflicting token |
- | Unknown component property | Accept with warning |
- | External `@`-reference in prose | Preserve; resolve referenced file on demand |
- | External `@`-reference fragment for unsupported file type | Ignore fragment and use whole file; do not treat as broken |
- | Duplicate section heading | Error; reject the file |
- | Duplicate top-level YAML key | Error; reject the file |
- ## CLI Reference
- ### Installation
- ```bash
- npm install @google/design.md
- ```
- On **Windows**, quote the package name if your shell treats `@` specially (PowerShell, some terminals):
- ```bash
- npm install "@google/design.md"
- ```
- Or run directly (always resolves from the public npm registry):
- ```bash
- npx @google/design.md lint DESIGN.md
- ```
- On **Windows/PowerShell**, this direct form can produce no output (or open
- `DESIGN.md` in your Markdown editor) because the `.md` suffix in the `design.md`
- bin name collides with the Windows Markdown file association during command
- resolution. Run the dot-free `designmd` alias instead — point `npx` at the
- package with `-p`, then invoke `designmd`:
- ```bash
- npx -p @google/design.md designmd lint DESIGN.md
- ```
- The `designmd` shim resolves to the same entrypoint and works identically across
- all platforms.
- #### `npm error ENOVERSIONS` (“No versions available for @google/design.md”)
- The CLI is published as [`@google/design.md` on npm](https://www.npmjs.com/package/@google/design.md). `ENOVERSIONS` almost always means npm is not querying the public registry (custom `registry=` in `.npmrc`, a corporate mirror that has not synced this package, or a misconfigured `@google:registry` for the `@google` scope).
- Check your effective registry:
- ```bash
- npm config get registry
- ```
- For a normal install from the internet it should be `https://registry.npmjs.org/`. After fixing config, retry with `npm cache clean --force` if a stale 404 was cached.
- All commands accept a file path or `-` for stdin. Output defaults to JSON.
- > **Windows tip**: when invoking the CLI directly from a `package.json` script
- > (rather than through `npx`), use the `designmd` alias instead of `design.md`.
- > The `.md` suffix in the original bin name confuses Windows command resolution
- > with the file association for Markdown files. The `designmd` shim resolves to
- > the same entrypoint and works identically across all platforms.
- >
- > ```jsonc
- > // package.json
- > {
- > "scripts": {
- > "design:lint": "designmd lint DESIGN.md"
- > }
- > }
- > ```
- ### `lint`
- Validate a DESIGN.md file for structural correctness.
- ```bash
- npx @google/design.md lint DESIGN.md
- npx @google/design.md lint --format json DESIGN.md
- cat DESIGN.md | npx @google/design.md lint -
- ```
- | Option | Type | Default | Description |
- |:-------|:-----|:--------|:------------|
- | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
- | `--format` | `json` | `json` | Output format |
- Exit code `1` if errors are found, `0` otherwise.
- ### `diff`
- Compare two DESIGN.md files and report token-level changes.
- ```bash
- npx @google/design.md diff DESIGN.md DESIGN-v2.md
- ```
- | Option | Type | Default | Description |
- |:-------|:-----|:--------|:------------|
- | `before` | positional | required | Path to the "before" DESIGN.md |
- | `after` | positional | required | Path to the "after" DESIGN.md |
- | `--format` | `json` | `json` | Output format |
- Exit code `1` if regressions are detected (more errors or warnings in the "after" file).
- ### `export`
- Export DESIGN.md tokens to other formats.
- ```bash
- npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
- npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
- npx @google/design.md export --format dtcg DESIGN.md > tokens.json
- ```
- | Option | Type | Default | Description |
- |:-------|:-----|:--------|:------------|
- | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
- | `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | required | Output format |
- | Format | Output | Description |
- |:-------|:-------|:------------|
- | `json-tailwind` | JSON | Tailwind v3 `theme.extend` config object |
- | `css-tailwind` | CSS | Tailwind v4 `@theme { ... }` block with CSS custom properties |
- | `tailwind` | JSON | Alias for `json-tailwind` |
- | `dtcg` | JSON | W3C Design Tokens Format Module |
- Exit code `0` on a successful export (regardless of any lint findings in the source — run `lint` to gate on those), `1` on an invalid `--format` or an emitter error, and `2` if the input file cannot be read.
- ### `spec`
- Output the DESIGN.md format specification (useful for injecting spec context into agent prompts).
- ```bash
- npx @google/design.md spec
- npx @google/design.md spec --rules
- npx @google/design.md spec --rules-only --format json
- ```
- | Option | Type | Default | Description |
- |:-------|:-----|:--------|:------------|
- | `--rules` | boolean | `false` | Append the active linting rules table |
- | `--rules-only` | boolean | `false` | Output only the linting rules table |
- | `--format` | `markdown` \| `json` | `markdown` | Output format |
- ## Linting Rules
- The linter runs eleven rules against a parsed DESIGN.md. Each rule produces findings at a fixed severity level.
- | Rule | Severity | What it checks |
- |:-----|:---------|:---------------|
- | `broken-ref` | error | Unresolved token references (`{colors.primary}`), unknown component sub-tokens, and broken or out-of-bounds external `@`-references |
- | `missing-primary` | warning | Colors are defined but no `primary` color exists — agents will auto-generate one |
- | `contrast-ratio` | warning | Component `backgroundColor`/`textColor` pairs below WCAG AA minimum (4.5:1) |
- | `orphaned-tokens` | warning | Color tokens defined but never referenced by any component |
- | `token-summary` | info | Summary of how many tokens are defined in each section |
- | `missing-sections` | info | Optional sections (spacing, rounded) absent when other tokens exist |
- | `missing-typography` | warning | Colors are defined but no typography tokens exist — agents will use default fonts |
- | `section-order` | warning | Sections appear out of the canonical order defined by the spec |
- | `unknown-key` | warning | A top-level YAML key looks like a typo of a known schema key (e.g. `colours:` → `colors:`); custom extension keys stay silent |
- | `token-like-ignored` | warning | An unknown top-level key has token-like values (e.g. hex colors, font families, dimensions) suggesting it was dropped or misspelled |
- | `omitted-rules` | info | Validates the `omitted` configuration mapping for unknown or redundant sections |
- ### Programmatic API
- The linter is also available as a library:
- ```typescript
- import { lint } from '@google/design.md/linter';
- const report = lint(markdownString);
- console.log(report.findings); // Finding[]
- console.log(report.summary); // { errors, warnings, info }
- console.log(report.designSystem); // Parsed DesignSystemState
- ```
- ## Design Token Interoperability
- DESIGN.md tokens are inspired by the [W3C Design Token Format](https://www.designtokens.org/). The `export` command converts tokens to other formats:
- - **Tailwind v3 config (JSON)** — `npx @google/design.md export --format json-tailwind DESIGN.md` — emits a `theme.extend` JSON object for `tailwind.config.js`. `--format tailwind` is a backwards-compatible alias.
- - **Tailwind v4 theme (CSS)** — `npx @google/design.md export --format css-tailwind DESIGN.md` — emits a CSS `@theme { ... }` block using Tailwind v4's CSS-variable token namespaces (`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`).
- - **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`
- ## Status
- The DESIGN.md format is at version `alpha`. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures.
- ## Disclaimer
- This project is not eligible for the [Google Open Source Software Vulnerability
- Rewards Program](https://bughunters.google.com/open-source-security).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.