ai-design-dot-md

Create / Extract DESIGN.md

DESIGN.md = YAML design tokens (machine-readable) + 8 ordered markdown sections (human-readable rationale). Two modes: extract from existing source code, create from design intent.

MANDATORY READ before any token work (Phase 3+): references/design-md-spec.md — Do NOT load during Phases 1 and 2.

---

Phase 1 — Detect Mode

Extract — frontend source exists. Signals: package.json, tailwind.config.js, CSS/SCSS files, component directories with repeated styles.

Create — no extractable source. User provides brand brief, palette, adjectives, or aesthetic description.

Ambiguous → ask: "Extract design tokens from existing source code, or create from a design brief?"

If an existing DESIGN.md is present → ask: "Update existing file or replace it?"

Exit criterion: mode is unambiguous and any existing file decision is made.

---

Phase 2 — Gather Inputs

Extract mode

Scan in order:

1. package.json → detect framework (Svelte, React, Vue, Angular, Tailwind)
2. Framework config (tailwind.config.js, svelte.config.js, theme files)
3. Global CSS/SCSS → custom properties, font-face declarations, spacing scales
4. Component files → repeated class patterns, inline styles, token usage frequency

Consolidate near-duplicate colors (within ~10% perceptual distance). Use semantic keys in YAML (primary, secondary, accent) for cross-referencing. Use descriptive names ("Warm Amber") only in prose sections and as YAML value comments — never as token keys.

If no extractable tokens are found (minified CSS, no custom properties, framework-agnostic markup) → switch to Create mode and inform the user: "No design tokens found in source — I'll create DESIGN.md from a design brief instead."

Create mode

Elicit: brand name, 2–3 personality adjectives, primary color or hex, secondary/accent colors, preferred typeface (or "system" if unspecified), corner style (sharp / soft / pill), density (compact / comfortable / spacious).