/extract-design

name: extract-design
description: "Extract a Google DESIGN.md file from an HTML prototype (claude.ai/design or any styled page) using Puppeteer, producing machine-readable tokens and AI-generated prose. Use when the user has an HTML prototype and wants a DESIGN.md to anchor their project's visual identity, or when seed-conventions has just scaffolded a new project."
model: sonnet
effort: standard

Extract DESIGN.md from HTML

> **HARD GATE** — Do NOT write DESIGN.md without Puppeteer dual-pass extraction. Tokens from static HTML (Cheerio, regex, string scanning) are invalid — they miss cascade, custom properties, and Tailwind resolution. > > **HARD GATE** — Do NOT claim certainty where evidence is thin. Low-confidence color roles, component classifications, and prose assertions MUST be flagged with `<!-- AGENT NOTE: uncertain — validate during grill-me. Evidence: [what was observed] -->`. > > **HARD GATE** — Do NOT ship DESIGN.md without running `npx @google/design.md lint`. Unvalidated output is unverified output. If lint is unavailable (offline), flag prominently in terminal and in DESIGN.md prose.

Quick Start

# First run — extract from HTML prototype
node extract-design/scripts/extract.js --source ./prototype.html

# From a published URL
node extract-design/scripts/extract.js --source https://my-prototype.example.com

# With a custom name
node extract-design/scripts/extract.js --source ./proto.html --name "My Design System"

# Update — re-extract from new HTML, diff against existing
node extract-design/scripts/extract.js --source ./proto-v2.html

# Lint-only — validate existing DESIGN.md without re-extraction
node extract-design/scripts/extract.js --lint-only

Flow

1. **Launch Puppeteer** — dual-pass (light + dark) with retry + timeout. CI flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`. 2. **Collect styles** — `page.evaluate()` collects computed styles from every element. Returns raw JSON to Node.js. Browser = sensor; Node = brain. 3. **Classify tokens** — modular pipeline: colors (Material 3 roles), typography (scale detection), spacing (tolerance GCD), rounded (clustering), components (visual signature + pseudo-state variants). 4. **Generate prose** — AI heuristics produce all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with agent notes. 5. **Write + validate** — serialize to `specs/tech-architecture/DESIGN_LATEST.md`, run `npx @google/design.md lint`, report to terminal. 6. **Handoff** — writes `handoff.next_skill: grill-me` to `specs/state.yaml` with uncertain decisions context.

Inputs

| Parameter | Required | Description | |-----------|----------|-------------| | `--source <file\|url>` | First run: yes. Update: optional | HTML prototype path or URL | | `--name <string>` | No | Design system name (defaults to `<title>` or directory name) | | `--lint-only` | No | Validate existing DESIGN.md without re-extraction |

Output

• `specs/tech-architecture/DESIGN_LATEST.md` — replaces `DESIGN_PLAN_LATEST.md` as the canonical design artifact
• Terminal summary: token counts, component count, lint result, uncertain decisions
• Structured JSON log to stderr: extraction events, timing, counts
• `specs/state.yaml` → `handoff.next_skill: grill-me` with context

Error Tiers

| Tier | Condition | Response | |------|-----------|----------| | Fatal | No Chrome, page load timeout after retries | Exit non-zero, suggest fixes | | Degraded | Zero colors, zero typography, SPA shell | Write DESIGN.md with degradation warning | | Warned | Lint errors, uncertain decisions | Write DESIGN.md, flag in terminal, hand off to grill-me |

Dependencies

• **Puppeteer** (Chrome binary) — wrapped behind `BrowserExtractor` interface for testability
• **`@google/design.md`** (soft, via `npx`) — wrapped behind `DesignValidator` interface. Warns and skips if offline.

verify

node extract-design/tests/test-extraction.js

See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.