# DESIGN.md — helixui flavor on top of the canonical Google spec `DESIGN.md` is an **open Apache-2.0 specification from Google Labs** ([`google-labs-code/design.md`](https://github.com/google-labs-code/design.md), released 2026-04-23 alongside Stitch). One markdown file at your repo root, with a YAML frontmatter that carries design tokens and a markdown body that explains design rationale. AI coding agents — Stitch, Cursor, Claude Code, Lovable, v0, Bolt — all read it. The spec is currently `version: alpha` and under active development. This document tracks the canonical schema as of May 2026 and describes the **helixui flavor**: the optional `extensions.helixui` namespace that lets helixui-aware tools get more structured information without breaking compatibility with tools that don't know helixui. > **TL;DR.** Write a normal canonical DESIGN.md. If you're using helixui, add an `extensions.helixui:` block under the frontmatter. Generic tools see the canonical part; `helixui-prompt` sees both. --- ## 1. The canonical Google schema Source of truth: . Reproduced here for offline reference; if it conflicts with the upstream, upstream wins. ### File location One `DESIGN.md` per project, at the **repo root**. Same level as `README.md`, `CLAUDE.md`, `AGENTS.md`. Some practitioners also drop a per-package `DESIGN.md` in monorepos; the root one is canonical and others inherit. ### Frontmatter ```yaml --- version: alpha # optional; current spec version name: # required description: # optional colors: : typography: : fontFamily: fontSize: fontWeight: lineHeight: letterSpacing: fontFeature: # OpenType feature settings fontVariation: # OpenType variation settings rounded: : spacing: : components: : backgroundColor: textColor: typography: rounded: padding: size: height: width: --- ``` ### Token types | Type | Shape | Example | |------|-------|---------| | **Color** | `#` + sRGB hex | `"#1A1C1E"` | | **Dimension** | number + unit (`px` / `em` / `rem`) | `48px`, `1.5rem` | | **TokenRef** | `{path.to.token}` | `{colors.primary}`, `{spacing.md}`, `{typography.body}` | Token references are resolved at parse time. Cycles are an error. Forward references are allowed. ### Body sections (canonical order) ``` ## Overview ## Colors ## Typography ## Layout ## Elevation & Depth ## Shapes ## Components ## Do's and Don'ts ``` Aliases the upstream spec accepts: `Brand & Style` ≡ `Overview`, `Layout & Spacing` ≡ `Layout`, `Elevation` ≡ `Elevation & Depth`. HelixUI-flavored parsers accept those too. ### Status > "The DESIGN.md format is at version `alpha`. The spec, token schema, and CLI are under active development." Treat field names as load-bearing; treat the *exact* set of valid keys as in motion. A forgiving parser (ignore unknown fields, warn but don't fail) is the right posture. --- ## 2. helixui extensions helixui is a design *system*, not a single product. To stay compatible with the canonical spec, every helixui-specific addition lives under one namespaced key: ```yaml extensions: helixui: package: "@helixui/core" designSystemKind: design-system | app | site | docs | extension | mobile themes: [light, dark] mediums: [web, mobile-web, mobile-native, desktop, tv] aiFriendly: true dna: accent: blue|violet|cyan|green|lime|orange|pink|crimson|gold chroma: muted|standard|vibrant lightness: light|dark|auto radius: sharp|subtle|standard|rounded|extreme density: compact|comfortable|spacious typography: sans|grotesk|rounded|serif|mono surface: flat|elevated|glassy motion: subtle|standard|lively manifests: tokens: /tokens-manifest.json components: /components-manifest.json llms_index: /llms.txt llms_full: /llms-full.txt artifacts: perComponent: /components/.md consolidated: /components.md spec: componentFormat: ./packages/core/src/components/SPEC_FORMAT.md promptDsl: ./packages/prompt/SPEC_DSL.md designMdFlavor: ./DESIGN_MD_FORMAT.md componentPrefs: # in *project* DESIGN.md, not helixui's own use: [Button, IconButton, Card, Dialog, Sidebar, AppShell] avoid: [Carousel] defaults: Button: { variant: solid, tone: brand } ``` Why a namespace and not `x_helixui_*` or top-level keys? - **Top-level** would collide with future canonical fields. Risky given the spec is alpha. - **`x_*` prefix** is a JSON-Schema convention for unknown extensions; `extensions.` is more idiomatic for YAML and matches what other ecosystems (OpenAPI, Docker Compose) do. - **Discoverable**: `extensions.helixui` is the obvious place for a tool to look. ### What each helixui-extension key adds | Key | Why it exists | |-----|---------------| | `dna.*` | helixui has 8 independent "genes" that re-skin the system without touching tokens. Apps tune the genome here; helixui-aware codegen reads it. Falls back to wildtype if absent. | | `manifests.*` | URLs of the static AI artifacts helixui builds. `helixui-prompt` and other agents fetch these for a structured view of the system. | | `componentPrefs.use` | Components the AI is encouraged to emit. | | `componentPrefs.avoid` | Components the AI must not emit. | | `componentPrefs.defaults..` | Default prop value to bake into every emitted JSX of ``. | | `package`, `designSystemKind` | Self-describing metadata — is this a system, an app, etc. | A canonical-only parser sees only `name`, `description`, `colors`, `typography`, `rounded`, `spacing`, `components`. The `extensions.helixui` block is **silently ignored** — that's the whole point. --- ## 3. Two flavors of DESIGN.md you'll write ### a) For helixui itself `/DESIGN.md` at the repo root of the design system. Frontmatter declares the system's tokens in canonical Google shape; `extensions.helixui.designSystemKind: design-system` flags it. Body uses the 8 canonical sections. ### b) For an app that uses helixui `/DESIGN.md` at the repo root of the consuming product. Frontmatter declares **the product's** tokens — its brand color, its typography overrides, its component customizations. `extensions.helixui.designSystemKind: app` flags it. `extensions.helixui.componentPrefs.use` lists which helixui components the app uses; `defaults` overrides per-prop defaults. The product DESIGN.md *can* — but doesn't have to — re-declare every helixui token. The minimal product DESIGN.md is: ```yaml --- version: alpha name: Aurora description: AI-powered notebook for researchers. colors: primary: "#7c3aed" # brand override; everything else inherits helixui extensions: helixui: designSystemKind: app dna: accent: violet lightness: dark density: compact manifests: components: https://helixui.example.com/components-manifest.json --- ## Overview Aurora is … ## Voice & tone # extra section — non-canonical but allowed … ``` Use `helixui-prompt init-design` to scaffold this with sensible defaults. --- ## 4. Tooling ```bash npx helixui-prompt init-design [DESIGN.md] [--flags] # scaffold npx helixui-prompt design DESIGN.md [--strict] [--pretty] # validate + JSON ``` Validation rules: | Rule | Source of truth | |------|------------------| | Frontmatter parses as YAML | YAML 1.2 | | `name` present | canonical spec | | `colors`, `typography`, `rounded`, `spacing`, `components` shape | canonical spec | | Token references (`{path.to.token}`) resolve | canonical spec | | Section names match canonical (or alias) | canonical spec | | `extensions.helixui.dna.*` values valid | `packages/dna/src/alleles.ts` | | `extensions.helixui.componentPrefs.*` reference real components | `/components-manifest.json` | | Component-customize props exist on the component | `/components-manifest.json` | Unknown keys in `extensions.helixui.*` warn, don't error. Unknown body sections (`## Voice & tone`, `## Layout patterns`) are accepted — the canonical spec doesn't forbid extra sections. --- ## 5. Compatibility matrix | Tool | Reads canonical | Reads `extensions.helixui` | Notes | |------|------------------|--------------------------|-------| | **Stitch** (Google) | ✅ everything | — | The originating tool. | | **helixui-prompt** | ✅ everything | ✅ everything | Validates against helixui manifests. | | **Claude Code** | ✅ frontmatter + body | partial (sees as text) | Reads as supplied design context. | | **Cursor** | ✅ frontmatter + body | partial | Same; treats the file as docs context. | | **Vercel v0** | ✅ colors / typography / spacing | — | Looks for canonical token blocks. | | **Lovable** | ✅ colors / typography / components | — | Reads `## Brand`, `## Voice & tone`. | | **Bolt** | ✅ frontmatter | — | Token-focused. | | **awesome-design-md catalog** | ✅ everything | — | 100+ public DESIGN.md files for reference. | The format is designed so unknown fields are *ignored*, not rejected. helixui's `extensions.helixui` block is invisible to every tool except helixui-aware ones. --- ## 6. Versioning The frontmatter `version: alpha` matches the upstream Google spec version. When upstream advances to `beta` / `1.0`, helixui will track within one minor version. helixui's flavor tracks its own version under `extensions.helixui.flavorVersion` (default `1`). Breaking changes to the helixui extension shape bump that. --- ## 7. References - Spec & repo: (Apache-2.0) - Stitch (Google's first-party tool): - Catalog of community DESIGN.md files: , , - helixui's own DESIGN.md: [`/DESIGN.md`](./DESIGN.md) - helixui prompt DSL (separate but complementary): [`./packages/prompt/SPEC_DSL.md`](./packages/prompt/SPEC_DSL.md) - helixui component spec format: [`./packages/core/src/components/SPEC_FORMAT.md`](./packages/core/src/components/SPEC_FORMAT.md)