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

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

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 for extraction algorithms and heuristics.