Skip to content
helixui

DESIGN.md — DNA-first design statements

DESIGN.md is an open Apache-2.0 spec from Google Labs, released alongside Stitch in April 2026. One markdown file at your repo root with a YAML frontmatter that carries design tokens — read by Stitch, Cursor, Claude Code, Lovable, v0, Bolt, and any AI agent that knows the format.

helixui follows the canonical schema and treats it as a deterministic projection of the 8-gene helixui DNA. Author your design system in 5 lines of DNA; helixui produces the full canonical document.

The DNA-first authoring path

Instead of hand-authoring 100+ token entries, write the genome:

---
version: alpha
name: Aurora
description: AI notebook for researchers.
extensions:
  helixui:
    basePreset: wildtype       # one of: wildtype | studio | botanic | solstice | noir
    mutations:
      - { gene: accent, value: violet }
      - { gene: density, value: compact }
      - { gene: lightness, value: dark }
---


## Overview
Aurora is …

Run helixui-prompt design DESIGN.md. The parser:

  1. Reads the canonical fields (none here — that’s fine).
  2. Resolves basePreset + mutations into an effective DNA.
  3. Auto-expands every missing canonical block (colors, typography, rounded, spacing, components) by running express(dna).
  4. Returns a fully-populated DESIGN.md object with expanded: true.

Tools that don’t know helixui’s DNA shorthand can call helixui-prompt express DESIGN.md to get the long form.

How DNA maps onto canonical tokens

GeneWhat it multiplies / picksCanonical block it drives
accentOKLCH hue (and chromaMax per hue)colors.brand-50 … brand-900
chromaglobal chroma multiplier (0.55 / 1.0 / 1.3)every brand stop’s saturation
lightnesslight / dark / autosemantic alias resolution ({colors.primary} → which stop)
radiusfactor on base (0.35 / 0.7 / 1.0 / 1.4 / 2.2)rounded.sm/md/lg/xl
densityfactor on base (0.78 / 1.0 / 1.25)spacing.1 … spacing.24
typographyfamily stack + scale (1.0 / 1.05 / 0.98)typography.*.fontFamily + .fontSize
surfaceflat / elevated / glassyshadow tokens (body section)
motionsubtle / standard / livelyduration tokens (body section)

accent: violet swaps every brand stop to violet OKLCH. density: compact shrinks every spacing token by 22%. radius: rounded makes `md` 11.20px instead of 8px. The math is deterministic and lossless.

Named presets

Run helixui-prompt presets for the full list. As of this version:

Presetaccentdensityradiustypographymood
wildtypebluecomfortablestandardsansThe default — calm, blue, comfortable.
studiocyancompactsubtlegroteskCompact, sharp, mono-feel for code-heavy interfaces.
botanicgreenspaciousroundedroundedSoft, warm, organic — for content-first surfaces.
solsticeorangecomfortableroundedsansWarm, vibrant accent for marketing or playful apps.
noircrimsoncompactsharpgroteskDark, sharp, crimson — for tools you live in.

CLI reference

Terminal window
# scaffold a project DESIGN.md (DNA-first body, hand-tunable)
npx helixui-prompt init-design [DESIGN.md] --preset=wildtype --name="My App"


# express DNA into a complete canonical DESIGN.md
npx helixui-prompt express DESIGN.md --preset=noir --gene=accent --to=violet


# apply additional mutations to an existing DESIGN.md
npx helixui-prompt mutate DESIGN.md --gene=density --to=spacious > new-DESIGN.md


# parse + validate (canonical + helixui extensions, with consistency check)
npx helixui-prompt design DESIGN.md --pretty


# show DNA-vs-canonical disagreements (where the file overrides DNA)
npx helixui-prompt diff DESIGN.md --pretty


# list named presets
npx helixui-prompt presets

Auto-expansion

If your DESIGN.md has DNA but is missing canonical blocks, the parser fills them in:

extensions:
  helixui:
    basePreset: noir   # accent=crimson, lightness=dark, density=compact, radius=sharp, …

The result has colors.brand-500: oklch(56% 0.16 18) (crimson), spacing.4: 12.48px (compact), rounded.md: 2.80px (sharp) — all derived. You can override individual values; the consistency check warns when an override drifts from the DNA.

Consistency checking

When both DNA and canonical blocks are present, helixui-prompt compares the semantic aliases:

colors:
  primary: "#ff0000"          # ← hand-authored override
extensions:
  helixui:
    basePreset: wildtype       # implies primary = {colors.brand-500} (blue)
warning: DNA disagreement at colors.primary: file has "#ff0000", DNA implies "{colors.brand-500}"

This is a warning, not an error — overrides are sometimes intentional (a brand demands an exact hex). Use helixui-prompt diff to see all disagreements at once.

Programmatic API

import {
  expressDesignMd,    // DNA shorthand → full canonical markdown
  parseDesignMd,      // canonical + extensions → normalized object
  resolveDna,         // basePreset + mutations → effective DNA
  expressForDesignMd, // effective DNA → canonical token blocks (object)
  DNA_PRESETS,        // named presets
} from '@helixui/prompt';


const md = expressDesignMd({
  name: 'Aurora',
  basePreset: 'wildtype',
  mutations: [{ gene: 'accent', value: 'violet' }],
});


const parsed = await parseDesignMd(md);
// parsed.colors['brand-500']  → 'oklch(56% 0.20 280)'  (violet hue)
// parsed.effectiveDna.accent  → 'violet'
// parsed.expanded             → false  (canonical blocks were authored, not expanded)

Why DNA-first

Hand-authoring tokens for every project means rebuilding what helixui already knows. The 8 genes compress the design space into ~10⁴ unique combinations, every one of which is internally consistent (a compact density auto-shrinks every spacing token; a dark lightness auto-swaps every alias). DESIGN.md gives you the canonical, tool-portable surface; DNA gives you the compression of that surface to its meaningful axes.

A 5-line DESIGN.md becomes a 100-line canonical document on demand. Editing one gene re-derives the whole frontmatter consistently. Tools that read canonical-only see a normal DESIGN.md; helixui-aware tools see the genome.

References