Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/google-labs-code--design-md/badge.svg)](/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

i

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.

  1. # DESIGN.md
  2. A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
  3. ## The Format
  4. 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.
  5. ```md
  6. ---
  7. name: Heritage
  8. colors:
  9. primary: "#1A1C1E"
  10. secondary: "#6C7278"
  11. tertiary: "#B8422E"
  12. neutral: "#F7F5F2"
  13. typography:
  14. h1:
  15. fontFamily: Public Sans
  16. fontSize: 3rem
  17. body-md:
  18. fontFamily: Public Sans
  19. fontSize: 1rem
  20. label-caps:
  21. fontFamily: Space Grotesk
  22. fontSize: 0.75rem
  23. rounded:
  24. sm: 4px
  25. md: 8px
  26. spacing:
  27. sm: 8px
  28. md: 16px
  29. ---
  30. ## Overview
  31. Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
  32. premium matte finish — a high-end broadsheet or contemporary gallery.
  33. ## Colors
  34. The palette is rooted in high-contrast neutrals and a single accent color.
  35. - **Primary (#1A1C1E):** Deep ink for headlines and core text.
  36. - **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
  37. - **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
  38. - **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.
  39. ```
  40. 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.
  41. ## Getting Started
  42. 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.
  43. ```bash
  44. npx @google/design.md lint DESIGN.md
  45. ```
  46. ```json
  47. {
  48. "findings": [
  49. {
  50. "severity": "warning",
  51. "path": "components.button-primary",
  52. "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
  53. }
  54. ],
  55. "summary": { "errors": 0, "warnings": 1, "infos": 1 }
  56. }
  57. ```
  58. Compare two versions of a design system to detect token-level and prose regressions:
  59. ```bash
  60. npx @google/design.md diff DESIGN.md DESIGN-v2.md
  61. ```
  62. ```json
  63. {
  64. "tokens": {
  65. "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
  66. "typography": { "added": [], "removed": [], "modified": [] },
  67. "rounded": { "added": [], "removed": [], "modified": [] },
  68. "spacing": { "added": [], "removed": [], "modified": [] },
  69. "components": { "added": [], "removed": [], "modified": [] }
  70. },
  71. "findings": {
  72. "before": { "errors": 0, "warnings": 1, "infos": 1 },
  73. "after": { "errors": 0, "warnings": 1, "infos": 1 },
  74. "delta": { "errors": 0, "warnings": 0 }
  75. },
  76. "regression": false
  77. }
  78. ```
  79. ## The Specification
  80. The full DESIGN.md spec lives at [`docs/spec.md`](docs/spec.md). What follows is a condensed reference.
  81. ### File Structure
  82. A DESIGN.md file has two layers:
  83. 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.
  84. 2. **Markdown body** — Human-readable design rationale organized into `##` sections.
  85. The tokens are the normative values. The prose provides context for how to apply them.
  86. ### Token Schema
  87. ```yaml
  88. version: <string> # optional, current: "alpha"
  89. name: <string>
  90. description: <string> # optional
  91. omitted: <string[] | OmittedSection[]> # optional, list of sections to intentionally omit
  92. colors:
  93. <token-name>: <Color>
  94. <group-name>: # optional nested group
  95. <token-name>: <Color>
  96. typography:
  97. <token-name>: <Typography>
  98. <group-name>: # optional nested group
  99. <token-name>: <Typography>
  100. rounded:
  101. <scale-level>: <Dimension>
  102. <group-name>: # optional nested group
  103. <scale-level>: <Dimension>
  104. spacing:
  105. <scale-level>: <Dimension | number>
  106. <group-name>: # optional nested group
  107. <scale-level>: <Dimension | number>
  108. motion:
  109. <token-name>: <Motion>
  110. components:
  111. <component-name>:
  112. <token-name>: <string | token reference>
  113. ```
  114. ### Token Types
  115. | Type | Format | Example |
  116. |:-----|:-------|:--------|
  117. | Color | Any CSS color (hex, `rgb()`, `oklch()`, named, etc.) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
  118. | Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
  119. | Duration | number + `ms` | `100ms`, `250ms` |
  120. | Token Reference | `{path.to.token}` | `{colors.primary}`, `{colors.light.surface}`, `{typography.sm.headline-lg}` |
  121. | Typography | object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` | See example above |
  122. | Motion | object with `duration`, `delay`, `timingFunction` | `duration: 100ms`, `timingFunction: ease-out` |
  123. ### Section Order
  124. Sections use `##` headings. They can be omitted, but those present must appear in this order:
  125. | # | Section | Aliases |
  126. |:--|:--------|:--------|
  127. | 1 | Overview | Brand & Style |
  128. | 2 | Colors | |
  129. | 3 | Typography | |
  130. | 4 | Layout | Layout & Spacing |
  131. | 5 | Elevation & Depth | Elevation |
  132. | 6 | Shapes | |
  133. | 7 | Motion & Micro-interaction | Motion & Micro-interactions, Motion |
  134. | 8 | Voice & Content Strategy | |
  135. | 9 | Components | |
  136. | 10 | Do's and Don'ts | |
  137. ### Component Tokens
  138. Components map a name to a group of sub-token properties:
  139. ```yaml
  140. components:
  141. button-primary:
  142. backgroundColor: "{colors.tertiary}"
  143. textColor: "{colors.on-tertiary}"
  144. rounded: "{rounded.sm}"
  145. padding: 12px
  146. button-primary-hover:
  147. backgroundColor: "{colors.tertiary-container}"
  148. ```
  149. Valid component properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`.
  150. Variants (hover, active, pressed) are expressed as separate component entries with a related key name.
  151. 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:
  152. ```markdown
  153. ## Components
  154. - **Buttons** → `@components/button.html` — `button-primary`, `button-secondary`, `button-tertiary`, `button-icon`
  155. - **Cards** → `@components/card.html` — `card-elevated`, `card-outlined`
  156. ```
  157. ### Consumer Behavior for Unknown Content
  158. | Scenario | Behavior |
  159. |:---------|:---------|
  160. | Unknown section heading | Preserve; do not error |
  161. | Unknown color token name | Accept if value is valid |
  162. | Unknown typography token name | Accept as valid typography |
  163. | Unknown motion token name | Accept as valid motion |
  164. | Grouped token sub-map | Flatten to dot-separated token path |
  165. | Flat and grouped token name collision | Error; reject the conflicting token |
  166. | Unknown component property | Accept with warning |
  167. | External `@`-reference in prose | Preserve; resolve referenced file on demand |
  168. | External `@`-reference fragment for unsupported file type | Ignore fragment and use whole file; do not treat as broken |
  169. | Duplicate section heading | Error; reject the file |
  170. | Duplicate top-level YAML key | Error; reject the file |
  171. ## CLI Reference
  172. ### Installation
  173. ```bash
  174. npm install @google/design.md
  175. ```
  176. On **Windows**, quote the package name if your shell treats `@` specially (PowerShell, some terminals):
  177. ```bash
  178. npm install "@google/design.md"
  179. ```
  180. Or run directly (always resolves from the public npm registry):
  181. ```bash
  182. npx @google/design.md lint DESIGN.md
  183. ```
  184. On **Windows/PowerShell**, this direct form can produce no output (or open
  185. `DESIGN.md` in your Markdown editor) because the `.md` suffix in the `design.md`
  186. bin name collides with the Windows Markdown file association during command
  187. resolution. Run the dot-free `designmd` alias instead — point `npx` at the
  188. package with `-p`, then invoke `designmd`:
  189. ```bash
  190. npx -p @google/design.md designmd lint DESIGN.md
  191. ```
  192. The `designmd` shim resolves to the same entrypoint and works identically across
  193. all platforms.
  194. #### `npm error ENOVERSIONS` (“No versions available for @google/design.md”)
  195. 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).
  196. Check your effective registry:
  197. ```bash
  198. npm config get registry
  199. ```
  200. 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.
  201. All commands accept a file path or `-` for stdin. Output defaults to JSON.
  202. > **Windows tip**: when invoking the CLI directly from a `package.json` script
  203. > (rather than through `npx`), use the `designmd` alias instead of `design.md`.
  204. > The `.md` suffix in the original bin name confuses Windows command resolution
  205. > with the file association for Markdown files. The `designmd` shim resolves to
  206. > the same entrypoint and works identically across all platforms.
  207. >
  208. > ```jsonc
  209. > // package.json
  210. > {
  211. > "scripts": {
  212. > "design:lint": "designmd lint DESIGN.md"
  213. > }
  214. > }
  215. > ```
  216. ### `lint`
  217. Validate a DESIGN.md file for structural correctness.
  218. ```bash
  219. npx @google/design.md lint DESIGN.md
  220. npx @google/design.md lint --format json DESIGN.md
  221. cat DESIGN.md | npx @google/design.md lint -
  222. ```
  223. | Option | Type | Default | Description |
  224. |:-------|:-----|:--------|:------------|
  225. | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
  226. | `--format` | `json` | `json` | Output format |
  227. Exit code `1` if errors are found, `0` otherwise.
  228. ### `diff`
  229. Compare two DESIGN.md files and report token-level changes.
  230. ```bash
  231. npx @google/design.md diff DESIGN.md DESIGN-v2.md
  232. ```
  233. | Option | Type | Default | Description |
  234. |:-------|:-----|:--------|:------------|
  235. | `before` | positional | required | Path to the "before" DESIGN.md |
  236. | `after` | positional | required | Path to the "after" DESIGN.md |
  237. | `--format` | `json` | `json` | Output format |
  238. Exit code `1` if regressions are detected (more errors or warnings in the "after" file).
  239. ### `export`
  240. Export DESIGN.md tokens to other formats.
  241. ```bash
  242. npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
  243. npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
  244. npx @google/design.md export --format dtcg DESIGN.md > tokens.json
  245. ```
  246. | Option | Type | Default | Description |
  247. |:-------|:-----|:--------|:------------|
  248. | `file` | positional | required | Path to DESIGN.md (or `-` for stdin) |
  249. | `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | required | Output format |
  250. | Format | Output | Description |
  251. |:-------|:-------|:------------|
  252. | `json-tailwind` | JSON | Tailwind v3 `theme.extend` config object |
  253. | `css-tailwind` | CSS | Tailwind v4 `@theme { ... }` block with CSS custom properties |
  254. | `tailwind` | JSON | Alias for `json-tailwind` |
  255. | `dtcg` | JSON | W3C Design Tokens Format Module |
  256. 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.
  257. ### `spec`
  258. Output the DESIGN.md format specification (useful for injecting spec context into agent prompts).
  259. ```bash
  260. npx @google/design.md spec
  261. npx @google/design.md spec --rules
  262. npx @google/design.md spec --rules-only --format json
  263. ```
  264. | Option | Type | Default | Description |
  265. |:-------|:-----|:--------|:------------|
  266. | `--rules` | boolean | `false` | Append the active linting rules table |
  267. | `--rules-only` | boolean | `false` | Output only the linting rules table |
  268. | `--format` | `markdown` \| `json` | `markdown` | Output format |
  269. ## Linting Rules
  270. The linter runs eleven rules against a parsed DESIGN.md. Each rule produces findings at a fixed severity level.
  271. | Rule | Severity | What it checks |
  272. |:-----|:---------|:---------------|
  273. | `broken-ref` | error | Unresolved token references (`{colors.primary}`), unknown component sub-tokens, and broken or out-of-bounds external `@`-references |
  274. | `missing-primary` | warning | Colors are defined but no `primary` color exists — agents will auto-generate one |
  275. | `contrast-ratio` | warning | Component `backgroundColor`/`textColor` pairs below WCAG AA minimum (4.5:1) |
  276. | `orphaned-tokens` | warning | Color tokens defined but never referenced by any component |
  277. | `token-summary` | info | Summary of how many tokens are defined in each section |
  278. | `missing-sections` | info | Optional sections (spacing, rounded) absent when other tokens exist |
  279. | `missing-typography` | warning | Colors are defined but no typography tokens exist — agents will use default fonts |
  280. | `section-order` | warning | Sections appear out of the canonical order defined by the spec |
  281. | `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 |
  282. | `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 |
  283. | `omitted-rules` | info | Validates the `omitted` configuration mapping for unknown or redundant sections |
  284. ### Programmatic API
  285. The linter is also available as a library:
  286. ```typescript
  287. import { lint } from '@google/design.md/linter';
  288. const report = lint(markdownString);
  289. console.log(report.findings); // Finding[]
  290. console.log(report.summary); // { errors, warnings, info }
  291. console.log(report.designSystem); // Parsed DesignSystemState
  292. ```
  293. ## Design Token Interoperability
  294. DESIGN.md tokens are inspired by the [W3C Design Token Format](https://www.designtokens.org/). The `export` command converts tokens to other formats:
  295. - **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.
  296. - **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-*`).
  297. - **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) — `npx @google/design.md export --format dtcg DESIGN.md`
  298. ## Status
  299. 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.
  300. ## Disclaimer
  301. This project is not eligible for the [Google Open Source Software Vulnerability
  302. Rewards Program](https://bughunters.google.com/open-source-security).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.