# DESIGN.md Desk

> Paste a DESIGN.md written to Google's open DESIGN.md format (spec version alpha) and work it in one
> sitting: the official @google/design.md 0.4.0 linter runs in the browser, with a WCAG contrast
> table for every component and byte-identical CSS, Tailwind and DTCG exports, free; then a paid run
> reviews what a coding agent would get wrong, or returns a repaired file that the browser re-lints
> and diffs against the original before the author takes it.

Site: https://design-md-desk.skillsafe.ai/
API tutorial: https://design-md-desk.skillsafe.ai/api.html
Token panel: https://design-md-desk.skillsafe.ai/tokens.html (noindex)
Independent tool: not made, affiliated with or endorsed by Google.

## What it is for

One work object: a DESIGN.md file - YAML front matter with the normative tokens (`colors`,
`typography`, `rounded`, `spacing`, `components`) and Markdown sections that explain them (Overview,
Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts). One user - a
design engineer or a developer who hands this file to coding agents - checks it, reviews it, repairs
it and re-checks it in the same sitting.

## The free lane (no account, nothing uploaded)

- The official linter, `@google/design.md` 0.4.0, built for the browser from the unmodified source at
  the 0.4.0 tag. Checked against the published CLI on 410 files (Google's three examples, a starter,
  six edge cases and 400 mutated variants): lint report, diff and all four exports identical in 2,868 of 2,868
  comparisons.
- Its rules: broken-ref (error), contrast-ratio (warning, text vs background below WCAG AA 4.5:1),
  missing-primary, missing-typography, orphaned-tokens, section-order, unknown-key (misspelled schema
  keys), token-like-ignored (token maps exports will drop), unknown-omission, plus token-summary and
  missing-sections (info). A file the linter cannot parse is reported with the parser's own message.
- Four checks of this page's own, labelled as such: a hex colour in the prose that is no token, a
  `{group.token}` reference in the prose that resolves to nothing, a core colour role (primary,
  secondary, tertiary, neutral) the prose never names, a component the prose never names.
- A contrast table for every component whose backgroundColor and textColor both resolve.
- Exports, byte-identical to `npx @google/design.md export`: css-vars (CSS custom properties, optional
  prefix), css-tailwind (Tailwind v4 @theme), json-tailwind (Tailwind v3 theme.extend JSON), dtcg (W3C
  Design Tokens). The lint report JSON is what `npx @google/design.md lint` prints.
- The official section fixer (canonical order, unknown sections after), undoable.
- A baseline for the edit loop: the version you loaded (or mark) is kept, and every re-lint lists the
  findings and page checks that went away, the new ones, and the tokens changed (the CLI's own diff).
- Each finding's path jumps to that key in the file; each export can be previewed and copied.
- A front matter the linter cannot read (tabs, bad indentation, no YAML) is called out, and the empty
  exports it would produce are refused.

## The paid lanes (task field)

- `review`: verdict (blocked, needs_work, ready), an answer to every finding and check (fix, accept,
  dispute), prose that disagrees with the tokens, gaps an agent will hit, the mistakes a coding agent
  would make from the file, and 3-7 priority fixes.
- `repair`: the complete repaired DESIGN.md, every change listed against the finding it answers, and
  open questions for values only the author can choose. The browser re-lints the repair with the
  official linter, diffs it with the CLI's own diff, and flags remaining errors, regressions, findings
  still reported, tokens removed or changed without a word, and new colour values not put to the author.
- A review hands itself to the repair lane with one button; a repair goes back into the editor with
  one button and the lint re-runs.

## Contract

Input (every field a string): task, design_md, facts (a JSON string: summary, findings F1..,
checks P1.., tokens, contrast, sections, hint, clipped), title, context, question, review (repair).
Output: one JSON object - lane, verdict, headline, finding_responses, then prose_vs_tokens, gaps,
agent_readiness, priority_fixes (review) or changes, design_md, open_questions (repair), and next_steps.
The model is told never to compute a contrast ratio; the page checks every ratio it quotes.

## Limits

Contrast covers component text on component background only, not borders, focus rings or text on
images. The model's judgement is not a design review by a person. Nothing is written to a repository.

## Sources

- Derived from the agent skill @nousresearch/design-md (Hermes Agent):
  https://skillsafe.ai/skill/@nousresearch/design-md
- DESIGN.md format and linter: https://github.com/google-labs-code/design.md (Apache-2.0,
  Copyright 2026 Google LLC); npm @google/design.md 0.4.0. Notice: https://design-md-desk.skillsafe.ai/NOTICE.txt
- WCAG 2 contrast ratio and the 4.5:1 AA minimum for normal text: https://www.w3.org/TR/WCAG22/#contrast-minimum