DESIGN.md
Google Labs Code format specification and CLI for describing a visual identity to coding agents as one persistent, lintable Markdown file.
What it is
google-labs-code/design.md formalizes DESIGN.md as a two-layer file: YAML frontmatter for machine-readable tokens and Markdown body sections for human-readable design rationale. The README describes colors, typography, rounded, spacing, and component token schemas, plus a required section order for overview, colors, typography, layout, elevation/depth, shapes, components, and do/don't guidance. Source: GitHub README, 2026-06-26
The CLI can lint, diff, export, and print the spec. Export targets include Tailwind v3 JSON, Tailwind v4 CSS @theme, and W3C Design Tokens Community Group tokens JSON. Source: GitHub README, 2026-06-26
Current source authority: google-labs-code/design.md is Apache-2.0 at
9bf8eae67128b6cc55ad9bf86665767deb4c11cd, with 15 detected tests, one
workflow, and four skill files. The companion Apache-2.0
google-labs-code/stitch-skills source is at 535b0889 with 15 skills. These
are active source and extraction procedures, not evidence that a hosted import
perfectly preserves a project's components, behavior, or design intent.
Source: commit-pinned repository receipts, 2026-08-12
Routing
Use DESIGN.md when an agent needs a persistent visual identity file for a project:
- bootstrapping a new app with a reusable design identity
- porting a brand/style into coding-agent instructions
- diffing token changes before and after a redesign
- exporting design tokens to Tailwind or DTCG-style JSON
- giving non-design agents a compact visual source of truth
For Kevin's system, DESIGN.md is the format/spec route,
Awesome Design MD is a reference corpus, and Sigil Token Architecture
is the local token architecture. The project-owned DESIGN.md, components,
CSS, and rendered states remain authoritative over any catalog, imported
playground, generated proposal, or inferred style.
Kevin stack fit
Expose this through the design-system and frontend workflow routes whenever an agent needs project visual authority. Agents should not infer identity from vibes when the project can provide an explicit token file, structural grammar, component source, and prose constraints.
Reticle fit
Reticle is the local stress test for DESIGN.md: normal tokens are not enough. The file must also encode structural grammar so agents can reproduce the aesthetic across projects.
A Reticle-flavored DESIGN.md should include these prose sections in addition to color/type/spacing tokens:
| Section | Purpose |
|---|---|
Grammar |
Defines structural visibility, line ownership, and the "one visual structure, one owner" invariant. |
Layout |
Names content max width, rail offset, gutter width, section rhythm, and full-width separator behavior. |
Line Topology |
States which primitive owns page rails, section spacers, frame borders, table seams, chart grids, and internal rules. |
Hatching |
Defines diagonal pitch, angle, opacity, and allowed use cases. |
Components |
Lists ReticlePageGrid, ReticleSection, ReticleSpacer, ReticleFrame, ReticleHatch, ReticleLabel, controls, charts, and states. |
Do / Do not |
Blocks double borders, nested cards, hardcoded colors, random radius, and decorative hatching. |
This makes Reticle Design System portable: an agent can read one markdown file and recreate page rails, full-width two-line spacers, diagonal margin hatch, square controls, and shared-border tables without having seen the original app. Source: Reticle Design System, 2026-07-01
Category Map
DESIGN.md now has a small ecosystem:
| Layer | Examples | Use |
|---|---|---|
| Spec | Google Labs Code design.md |
Canonical syntax, lint, diff, export |
| Reference corpus | Awesome Design MD, getdesign.md, Refero Styles | Study real visual systems and extract constraints |
| Hosted agent surface | Google Stitch, Open Design, Aura, Neuform, Hyperbrowser, TypeUI | Productized design-to-agent workflows |
| Local generator | Frontend and Design Skills and project DESIGN.md files |
Kevin-owned visual identity and tokens |
| Import/playground | v0 Design Systems, Google Stitch skills | Inspect components, props, tokens, providers, usage patterns, and proposed outputs; save only after conflict, behavior, accessibility, and source-diff review |
The May 2026 "9 tools" bookmark is useful because it proves the handoff is no longer one repo. The Voxyz/Refero artifact makes the corpus layer visible: search, style filters, tabs, product cards, and 2,000+ AI-readable systems are now packaged as a browsing surface for agents and humans. The right local rule stays boring: keep Kevin's actual identity in a versioned project DESIGN.md, then use catalogs only as references. Source: X/@tranmautritam, 2026-05-12; Source: X/@Voxyz_ai, 2026-06-20; Source: Refero Styles, 2026-07-03
First-Party Examples
Vercel's live https://vercel.com/design.md is a high-signal first-party example of the format in production. It exposes Geist as version: alpha, points the light theme at /design.md and the dark theme at /design.dark.md, and publishes machine-readable color and typography tokens including semantic colors, gray ramps, accent ramps, alpha variants, and P3 oklch() fallbacks. The durable lesson: design-system owners are starting to publish agent-readable token docs directly at stable product URLs. Source: X/@rauchg, 2026-06-18; Source: Vercel design.md, 2026-07-04; Source: Vercel design.dark.md, 2026-07-04
Timeline
- 2026-08-12 | Refreshed the Google spec and Stitch sources and made the
authority order explicit: project
DESIGN.md, components, CSS, and rendered behavior outrank catalogs and generated imports. v0/Stitch playgrounds are preview surfaces; promotion requires conflict handling, behavior, accessibility, and exact source-diff review. Source: X2070187562577391731through2070187598635823126, X2077844277800157503; Google repositories at9bf8eaeand535b088 - 2026-07-04 | Deep-reviewed Guillermo Rauch's
vercel.com/design.mdbookmark. Added Vercel's live Geist light/darkdesign.mdfiles as first-party evidence that agent-readable design-token documents are being published at stable product URLs. Source: X/@rauchg, 2026-06-18; Source: Vercel design.md, 2026-07-04 - 2026-07-03 | Added the Voxyz/Refero Styles artifact as proof that
DESIGN.mdnow has a browsable reference-corpus surface, not only a spec and a handful of tools. Source: X/@Voxyz_ai, 2026-06-20; Refero Styles, 2026-07-03 - 2026-07-01 | Added Reticle as the local
DESIGN.mdstress test: the markdown file must encode line topology, spacer bands, diagonal hatching, and component ownership, not only colors and type. Source: Reticle Design System - 2026-06-30 | Added the
DESIGN.mdcategory map from the deep-reviewed Refero/Open Design/GetDesign/Aura/Neuform/Hyperbrowser/TypeUI bookmark. Source: X/@tranmautritam, 2026-05-12; Refero Styles, 2026-06-30 - 2026-06-26 | Promoted from Kevin's GitHub stars harvest. GitHub API reported 21,061 stars, TypeScript, Apache-2.0, and homepage
stitch.withgoogle.com/docs/design-md/specification. Source:raw/github/google-labs-code_design.md-repo-2026-06-26.json; GitHub API, 2026-06-26