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
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 a format/spec route. Awesome Design MD is the reference corpus of real-company design files. Sigil Token Architecture is Kevin's local design-token architecture.
Kevin stack fit
This belongs in the generated design.md and design-systems.md packs. It strengthens the current Sigil/Reticle thesis: agents should not infer visual identity from vibes when the project can give them an explicit token file 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 |
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-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