bigpowers 2.42.0 → 2.43.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.42.0",
-  "description": "71 skills — 70 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.43.0",
+  "description": "72 skills — 70 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/extract-design.md

@@ -0,0 +1,131 @@
+---
+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."
+---
+
+
+# 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
+
+```bash
+# 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
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+---
+
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/.pi/skills/extract-design/SKILL.md

@@ -0,0 +1,133 @@
+---
+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
+---
+
+
+# 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
+
+```bash
+# 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
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+---
+
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.43.0](https://github.com/danielvm-git/bigpowers/compare/v2.42.1...v2.43.0) (2026-06-29)
+
+
+### Features
+
+* **skills:** add extract-design skill ([bda7ceb](https://github.com/danielvm-git/bigpowers/commit/bda7ceb113cba610d438dbb95af150b424e674b4))
+
+## [2.42.1](https://github.com/danielvm-git/bigpowers/compare/v2.42.0...v2.42.1) (2026-06-29)
+
+
+### Bug Fixes
+
+* **ci:** update sync-skills workflow to check for SKILL-SEARCH-INDEX_LATEST.md ([37db229](https://github.com/danielvm-git/bigpowers/commit/37db22985cecb83d6ad08ddef3487e730fce8713))
+
 # [2.42.0](https://github.com/danielvm-git/bigpowers/compare/v2.41.0...v2.42.0) (2026-06-29)
 
 

package/SKILL-INDEX.md

@@ -3,8 +3,8 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-29T16:10:24Z
-**Skills:** 71
+**Generated:** 2026-06-29T16:34:20Z
+**Skills:** 72
 
 ---
 

package/extract-design/REFERENCE.md

@@ -0,0 +1,52 @@
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/extract-design/SKILL.md

@@ -0,0 +1,77 @@
+---
+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
+---
+
+# 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
+
+```bash
+# 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
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.

package/extract-design/extract-design.feature

@@ -0,0 +1,23 @@
+Feature: Extract DESIGN.md from HTML prototype
+
+  Scenario: Extract tokens from a styled prototype
+    Given an HTML prototype with 3+ colors, 2+ font sizes, spacing values, and rounded corners
+    When extract-design runs on the prototype
+    Then DESIGN_LATEST.md contains a colors token group with at least 3 entries
+    And DESIGN_LATEST.md contains a typography token group with at least 2 levels
+    And all 8 prose sections are present
+
+  Scenario: Handle dark mode prototypes
+    Given an HTML prototype that responds to prefers-color-scheme: dark
+    When extract-design runs dual-pass extraction
+    Then DESIGN_LATEST.md contains a colors-dark token group
+
+  Scenario: Degrade gracefully on unstyleable HTML
+    Given an HTML file with no computed styles
+    When extract-design runs on the prototype
+    Then DESIGN_LATEST.md is written with a degradation warning
+
+  Scenario: Flag uncertain classifications
+    Given an HTML prototype where one color is used ambiguously
+    When extract-design classifies colors
+    Then the uncertain color's prose rationale contains an AGENT NOTE comment

package/extract-design/scripts/classify-colors.js

@@ -0,0 +1,21 @@
+function norm(c) { if (!c || c === 'transparent' || c === 'rgba(0, 0, 0, 0)') return null; return c.trim(); }
+function lum(c) { const m = c.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); if (!m) return 0.5; const s = v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); return 0.2126 * s(parseInt(m[1]) / 255) + 0.7152 * s(parseInt(m[2]) / 255) + 0.0722 * s(parseInt(m[3]) / 255); }
+function isNeutral(c) { const m = c.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); if (!m) return false; return Math.max(Math.abs(parseInt(m[1]) - parseInt(m[2])), Math.abs(parseInt(m[2]) - parseInt(m[3])), Math.abs(parseInt(m[1]) - parseInt(m[3]))) < 30; }
+
+export function classifyColors(styles, mode = 'light') {
+  const u = []; const colors = {}; const stats = new Map();
+  for (const el of styles) {
+    for (const [prop, usage] of [['backgroundColor','bg'],['color','text'],['borderColor','border']]) {
+      const k = norm(el[prop]); if (!k) continue;
+      const s = stats.get(k) || { usage: new Set(), area: 0, count: 0 }; s.usage.add(usage); if (prop === 'backgroundColor') s.area += (el.width||0)*(el.height||0); s.count++; stats.set(k, s);
+    }
+  }
+  const neutrals = [], accents = [];
+  for (const [c, s] of stats) { if (isNeutral(c)) neutrals.push({ color: c, ...s, luminance: lum(c) }); else accents.push({ color: c, ...s }); }
+  neutrals.sort((a,b) => b.area - a.area); accents.sort((a,b) => b.count - a.count);
+  if (neutrals.length) { colors.surface = neutrals[0].color; colors.background = neutrals[0].color; const txt = [...stats.entries()].filter(([,s]) => s.usage.has('text')).sort((a,b) => b[1].count - a[1].count); if (txt.length) colors['on-surface'] = txt[0][0]; }
+  const containers = neutrals.slice(1); if (containers.length) { const isDark = mode === 'dark'; containers.sort((a,b) => isDark ? b.luminance - a.luminance : a.luminance - b.luminance); const maxC = Math.min(containers.length >= 5 ? 5 : 3, containers.length); const lvls = ['surface-container-lowest','surface-container-low','surface-container','surface-container-high','surface-container-highest']; for (let i = 0; i < maxC; i++) colors[lvls[i]] = containers[i].color; }
+  if (accents.length) { colors.tertiary = accents[0].color; if (accents.length > 1) colors.secondary = accents[1].color; const err = accents.find(a => { const m = a.color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); return m && parseInt(m[1]) > 180 && parseInt(m[2]) < 100 && parseInt(m[3]) < 100; }); if (err) colors.error = err.color; }
+  if (Object.keys(colors).length < 2) u.push('Fewer than 2 colors extracted.');
+  return { colors, uncertain: u };
+}

package/extract-design/scripts/classify-rounded.js

@@ -0,0 +1,10 @@
+function parseR(v) { if (!v || v === '0px' || v === '0') return 0; const m = v.match(/^([\d.]+)(px|rem)$/); return m ? parseFloat(m[1]) * (m[2] === 'rem' ? 16 : 1) : (parseFloat(v) || 0); }
+export function classifyRounded(styles) { const u = []; const r = {}; const cnt = new Map();
+  for (const el of styles) { const px = parseR(el.borderRadius); cnt.set(px, (cnt.get(px) || 0) + 1); }
+  const freq = [...cnt.entries()].filter(([,c]) => c >= 2).map(([px]) => px).sort((a,b) => a - b);
+  if (!freq.length) { r.none = '0px'; return { rounded: r, uncertain: [] }; }
+  r.none = '0px'; const reg = freq.filter(v => v < 9998 && v > 0); const full = freq.find(v => v >= 9998);
+  if (full) r.full = `${full}px`; if (reg.length === 1) r.sm = `${reg[0]}px`;
+  else if (reg.length >= 2) { r.sm = `${reg[0]}px`; r.md = `${reg[1]}px`; } if (reg.length >= 3) r.lg = `${reg[2]}px`;
+  return { rounded: r, uncertain: u };
+}

package/extract-design/scripts/classify-spacing.js

@@ -0,0 +1,14 @@
+function toPx(v) { if (!v) return 0; const m = v.match(/^([\d.]+)(px|rem|em)$/); if (!m) return 0; return parseFloat(m[1]) * (m[2] === 'rem' || m[2] === 'em' ? 16 : 1); }
+function tGcd(nums, tol = 0.5) { if (!nums.length) return null; let r = nums[0]; for (let i = 1; i < nums.length; i++) { let a = Math.abs(r), b = Math.abs(nums[i]); while (b > tol) { const t = b; b = a % b; a = t; } r = a; } return r; }
+function collect(css, counts) { if (!css) return; for (const p of css.split(/\s+/)) { const v = toPx(p); if (v > 0) counts.set(v, (counts.get(v) || 0) + 1); } }
+
+export function classifySpacing(styles) { const u = []; const s = {}; const counts = new Map();
+  for (const el of styles) { collect(el.padding, counts); collect(el.margin, counts); if (el.gap) collect(el.gap, counts); }
+  const freq = new Map(); for (const [v, c] of counts) { if (c >= 3) freq.set(v, c); }
+  if (freq.size < 3) u.push('Fewer than 3 spacing values.');
+  const nums = [...freq.keys()].map(toPx).filter(v => v > 0); const g = tGcd(nums, 0.5);
+  if (!g || g < 2) { const sorted = [...freq.entries()].sort((a,b) => b[1] - a[1]); s.unit = sorted.length ? `${toPx(sorted[0][0])}px` : '8px'; return { spacing: s, uncertain: u }; }
+  s.unit = `${g}px`; const half = g / 2; if (nums.filter(v => Math.abs(v - half) < 0.5).length >= 3) s.half = `${half}px`;
+  s.sm = `${g * 2}px`; s.md = `${g * 4}px`; s.lg = `${g * 8}px`; if (nums.some(v => v >= g * 16)) s.xl = `${g * 16}px`;
+  return { spacing: s, uncertain: u };
+}

package/extract-design/scripts/classify-typography.js

@@ -0,0 +1,9 @@
+function px(v) { if (!v) return 0; const n = parseFloat(v); return isNaN(n) ? 0 : n; }
+export function classifyTypography(styles) { const u = []; const t = {}; const txt = styles.filter(s => s.text && s.text.length > 0 && s.fontSize); const clusters = new Map();
+  for (const el of txt) { const s = Math.round(px(el.fontSize)); if (!s) continue; if (!clusters.has(s)) clusters.set(s, { fontFamily: el.fontFamily, fontWeight: el.fontWeight, lineHeight: el.lineHeight, letterSpacing: el.letterSpacing, tag: el.tag, count: 0 }); clusters.get(s).count++; }
+  const sorted = [...clusters.entries()].sort((a,b) => b[0] - a[0]); if (!sorted.length) { u.push('No typography detected.'); return { typography: {}, uncertain: u }; }
+  let di = 0, hi = 0, bi = 0;
+  for (const [sz, cl] of sorted) { const hd = /^h[1-6]$/.test(cl.tag) || sz >= 32; let n; if (sz >= 64 && di === 0) { n = 'display-lg'; di++; } else if (hd && sz >= 40) { n = hi === 0 ? 'headline-lg' : 'headline-md'; hi++; } else if (hd && sz >= 28) { n = hi <= 1 ? 'headline-md' : 'headline-sm'; hi++; } else if (hd) { n = 'title-lg'; } else if (sz <= 18 && bi === 0) { n = 'body-lg'; bi++; } else if (sz <= 18) { n = 'body-md'; bi++; } else if (sz <= 14) { n = 'label-md'; } else { n = 'body-sm'; }
+    t[n] = { fontFamily: cl.fontFamily, fontSize: `${sz}px`, fontWeight: String(cl.fontWeight || '400') }; if (cl.lineHeight && cl.lineHeight !== 'normal') t[n].lineHeight = cl.lineHeight; if (cl.letterSpacing && cl.letterSpacing !== 'normal' && cl.letterSpacing !== '0px') t[n].letterSpacing = cl.letterSpacing; }
+  return { typography: t, uncertain: u };
+}