--- # This frontmatter is the canonical Google DESIGN.md spec (Apache-2.0, alpha). # Every token block below is *derived* from helixui's `wildtype` DNA via the # 8-gene express() function. Edit the DNA in `extensions.helixui` and regenerate # (`pnpm build:design-md` or `node scripts/build-helixui-design-md.mjs`); the # canonical blocks update consistently. version: alpha name: helixui description: "An AI-friendly React design system. Tokens are JSON in W3C DTCG; every component is one self-describing spec.md; static manifests ship with every build so an LLM can answer \"what tokens exist?\" or \"how do I use Button?\" from a single fetch." # === DERIVED FROM extensions.helixui.basePreset (wildtype) ===================== # accent=blue chroma=standard radius=standard density=comfortable # typography=sans surface=elevated motion=standard lightness=auto colors: brand-50: "oklch(96% 0.045 234)" brand-100: "oklch(93% 0.0788 234)" brand-200: "oklch(87% 0.1125 234)" brand-300: "oklch(78% 0.1462 234)" brand-400: "oklch(67% 0.1744 234)" brand-500: "oklch(56% 0.18 234)" brand-600: "oklch(47% 0.1744 234)" brand-700: "oklch(38% 0.1462 234)" brand-800: "oklch(28% 0.1125 234)" brand-900: "oklch(18% 0.0788 234)" neutral-50: "#f8fafc" neutral-100: "#f1f5f9" neutral-200: "#e2e8f0" neutral-300: "#cbd5e1" neutral-400: "#94a3b8" neutral-500: "#64748b" neutral-600: "#475569" neutral-700: "#334155" neutral-800: "#1e293b" neutral-900: "#0f172a" danger-50: "#fef2f2" danger-500: "#ef4444" danger-600: "#dc2626" danger-700: "#b91c1c" success-50: "#f0fdf4" success-500: "#22c55e" success-600: "#16a34a" success-700: "#15803d" warning-50: "#fffbeb" warning-500: "#f59e0b" warning-600: "#d97706" warning-700: "#b45309" primary: "{colors.brand-500}" secondary: "{colors.neutral-700}" tertiary: "{colors.brand-600}" background: "{colors.neutral-50}" surface: "#ffffff" text: "{colors.neutral-900}" muted: "{colors.neutral-500}" border: "{colors.neutral-200}" danger: "{colors.danger-500}" success: "{colors.success-500}" warning: "{colors.warning-500}" typography: display: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 36.00px, fontWeight: 700, lineHeight: 1.2 } h1: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 30.00px, fontWeight: 700, lineHeight: 1.2 } h2: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 24.00px, fontWeight: 600, lineHeight: 1.2 } h3: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 20.00px, fontWeight: 600, lineHeight: 1.2 } body-lg: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 18.00px, fontWeight: 400, lineHeight: 1.5 } body: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 16.00px, fontWeight: 400, lineHeight: 1.5 } body-sm: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 14.00px, fontWeight: 400, lineHeight: 1.5 } caption: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 12.00px, fontWeight: 500, lineHeight: 1.5 } button: { fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif", fontSize: 14.00px, fontWeight: 600, lineHeight: 1.2 } mono: { fontFamily: "ui-monospace, SFMono-Regular, 'Berkeley Mono', Menlo, Consolas, monospace", fontSize: 14.00px, fontWeight: 400, lineHeight: 1.5 } rounded: none: 0px full: 9999px sm: 4.00px md: 8.00px lg: 12.00px xl: 16.00px spacing: "0": 0px "1": 4.00px "2": 8.00px "3": 12.00px "4": 16.00px "5": 20.00px "6": 24.00px "8": 32.00px "10": 40.00px "12": 48.00px "16": 64.00px "20": 80.00px "24": 96.00px components: Button: { backgroundColor: "{colors.primary}", textColor: "#ffffff", typography: "{typography.button}", rounded: "{rounded.md}", padding: "12.00px 16.00px", height: 36px } IconButton: { backgroundColor: transparent, textColor: "{colors.text}", rounded: "{rounded.md}", size: 36px } Card: { backgroundColor: "{colors.surface}", textColor: "{colors.text}", rounded: "{rounded.lg}", padding: 20.00px } Dialog: { backgroundColor: "{colors.surface}", textColor: "{colors.text}", rounded: "{rounded.xl}", padding: 24.00px } Sheet: { backgroundColor: "{colors.surface}", rounded: "{rounded.xl}" } TextInput: { backgroundColor: "{colors.surface}", textColor: "{colors.text}", rounded: "{rounded.md}", padding: "8.00px 12.00px", height: 36px } Badge: { backgroundColor: "{colors.brand-50}", textColor: "{colors.brand-700}", typography: "{typography.caption}", rounded: "{rounded.full}", padding: "4.00px 8.00px" } # === HELIXUI EXTENSIONS — ignored by canonical-only parsers =================== extensions: helixui: package: "@helixui/core" designSystemKind: design-system flavorVersion: 1 generated: schema: helixui.design-md/v1 buildId: 444df7f at: 2026-06-18T04:22:54.839Z themes: [light, dark] mediums: [web, mobile-web] aiFriendly: true # The DNA shorthand. helixui-aware tools resolve this back into the # canonical token blocks above (which they then know are deterministic). basePreset: wildtype dna: accent: blue chroma: standard lightness: auto radius: standard density: comfortable typography: sans surface: elevated motion: standard mutations: [] 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 --- # helixui — design statement > An AI-friendly React design system. The system itself is shaped so an AI does not need a skill to use it correctly. This file follows the [DESIGN.md format from Google Labs](https://github.com/google-labs-code/design.md) (Apache-2.0, currently `alpha`). Any AI tool that reads `DESIGN.md` — Stitch, Cursor, Claude Code, Lovable, v0, Bolt — can understand helixui from this one file. **The frontmatter is DNA-first.** Every token block (`colors`, `typography`, `rounded`, `spacing`, `components`) is *derived* from the 8-gene helixui DNA expressed in `extensions.helixui` — not hand-authored. Change one gene, the whole frontmatter changes consistently. If you only read one file: read this one, then `/components.md`, then `/tokens-manifest.json`. That is enough to use helixui. ## Overview helixui is shaped around three design choices: 1. **Tokens are JSON, with descriptions.** `packages/tokens/tokens/*.json` is the source. Every token has `$value`, `$type`, `$description`. The build emits CSS, TS types, **and** a flat manifest at `/tokens-manifest.json`. 2. **Every component documents itself in one file.** `packages/core/src/components//spec.md` is the single source of truth — props, slots, tokens, accessibility, anatomy, layout, visual, composition graph, prompt examples. 3. **DNA compresses the design space into 8 genes.** Accent (hue), chroma (saturation), lightness (light/dark), radius (multiplier), density (multiplier), typography (family + scale), surface (shadow style), motion (duration). `express(dna)` produces this DESIGN.md frontmatter deterministically. Any tool that knows the DNA shorthand can re-derive the full canonical document on demand. There is no AST extractor and no runtime injection. To document a new component, you write that one file. To re-derive this DESIGN.md from DNA: `node scripts/build-helixui-design-md.mjs`. ## Colors The brand ramp is generated in **OKLCH** from `accent.hue` and `chroma.multiplier`. helixui's wildtype is `accent=blue` (hue 234) at `chroma=standard` (multiplier 1.0), so `brand-500` resolves to `oklch(56% 0.18 234)` — the perceptually-uniform equivalent of `#3b82f6`. Other ramps (`neutral`, `danger`, `success`, `warning`) are static — they don't shift with the DNA. Semantic aliases (`primary`, `text`, `background`, …) resolve via `{colors.}` references. Light vs dark themes pick different ramp stops: - **light**: `primary → brand-500`, `text → neutral-900`, `background → neutral-50`. - **dark**: `primary → brand-400` (lighter for contrast), `text → neutral-50`, `background → neutral-900`. Switching the DNA `accent` gene changes the brand hue family without touching the semantic structure. `accent: violet` makes `{colors.primary}` violet everywhere; nothing else moves. ## Typography `typography.family` (8 alleles: sans / grotesk / rounded / serif / mono) picks the family stack; `typography.scale` multiplies the font-size scale (1.0 default, 1.05 for serif, 0.98 for mono). The wildtype is `sans` at scale 1.0. Nine typography tokens cover everything: `display` / `h1` / `h2` / `h3` / `body-lg` / `body` / `body-sm` / `caption` / `button` / `mono`. Rules: - Headings always use `lineHeight: 1.2` (tight). - Body always uses `lineHeight: 1.5` (normal). - `button` uses size 14px / weight 600 / line-height 1.2 — distinct from `body-sm`. ## Layout Spacing is a 13-step scale (`0`, `1`, `2`, `3`, `4`, `5`, `6`, `8`, `10`, `12`, `16`, `20`, `24`) where the index is the canonical name and the resolved value is `index × 4px × density.spacing`. The wildtype `density=comfortable` (×1.0) gives `{spacing.4} = 16px`. The DNA `density` gene multiplies the entire scale — `compact` (×0.78) makes `{spacing.4} = 12.48px`, `spacious` (×1.25) makes it `20px`. Component layouts adapt automatically because they reference token indices, not pixels. `` resolves to whatever `{spacing.4}` currently is. ## Elevation & Depth Three shadow tokens — `sm` (cards on a page), `md` (popovers / dropdowns), `lg` (modals / sheets / FAB) — driven by the DNA `surface` gene: - `flat` — borders only, no shadows. - `elevated` (wildtype) — soft layered RGBA shadows. - `glassy` — shadow + thin top highlight, designed for use with `backdrop-blur` on overlays. Borders carry the rest of the depth: `border` (1px subtle) for separation, `border-strong` for emphasis, `border-focus` (2px brand) for `:focus-visible` only. ## Shapes Six radius tokens (`none`, `sm`, `md`, `lg`, `xl`, `full`). The DNA `radius` gene multiplies the four base values (sm 4, md 8, lg 12, xl 16): | Allele | factor | md resolves to | |--------|--------|----------------| | sharp | 0.35 | 2.80px | | subtle | 0.7 | 5.60px | | standard (wildtype) | 1.0 | 8.00px | | rounded | 1.4 | 11.20px | | extreme | 2.2 | 17.60px | Per-component conventions: - `sm` — Badge, chip, hairline indicator. - `md` — Button, IconButton, TextInput, Select, NumberField, Checkbox, RadioCard, Tabs, SegmentedControl, Tooltip. - `lg` — Card, ChatComposer, ToolCall, Callout, Banner, ChatMessage bubble, CodeBlock. - `xl` — Dialog, Sheet, ActionSheet, BottomNav (top corners), CollapsingHeader. - `full` — Avatar, AvatarGroup, FAB, PresenceDot, Switch knob. ## Components The frontmatter `components` block is also DNA-derived — Button's height, padding, and rounded values are computed from `density.spacing` and `radius.factor`. helixui-aware tools should fetch `/components-manifest.json` for the full surface (90 components across 11 categories: shell, navigation, layout, primitive, surface, overlay, form, feedback, data, media, chat). ## Do's and Don'ts **Do** - **Edit the DNA** in `extensions.helixui` and re-run `build-helixui-design-md`. The canonical blocks regenerate consistently. - Use semantic aliases (`{colors.primary}`) over ramp stops (`{colors.brand-500}`). Themes only swap the alias. - Use `Button` for actions, `Link` for navigation — even if they look the same. - Provide `aria-label` on icon-only controls. - Honor `prefers-reduced-motion`. helixui components already do; don't override. **Don't** - Don't hand-edit canonical token blocks to drift from the DNA. `helixui-prompt design --strict` warns; CI rejects. - Don't reference literal hex / px in component CSS — add a token if one is missing. - Don't put `onClick` on `Card` — wrap or render an `` / `