rebrand: Design System Extractor → Design System Automation

- Rename project across all 30+ source files, docs, and configs
- Update DTCG namespace: com.design-system-automation
- Update Gradio app title, heading, and footer
- Update token_schema generator field
- Remove internal docs from repo (CLAUDE.md, PROJECT_CONTEXT.md,
ARCHITECTURE.md, PLAN_W3C_DTCG_UPDATE.md, PART2_COMPONENT_GENERATION.md,
docs/CONTEXT.md, docs/FIGMA_SPECIMEN_IDEAS.md, content/*)
- Remove data files (sample JSON outputs, benchmark cache)
- Add .gitignore rules for internal docs and data files
- Add optimized Medium article v2 (9 min read)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -16,3 +16,17 @@ storage/cache/
 storage/exports/
 __MACOSX/
 .claude/
+
+# Internal project docs (not for public repos)
+CLAUDE.md
+PROJECT_CONTEXT.md
+ARCHITECTURE.md
+PLAN_W3C_DTCG_UPDATE.md
+PART2_COMPONENT_GENERATION.md
+docs/CONTEXT.md
+docs/FIGMA_SPECIMEN_IDEAS.md
+content/
+
+# Data files (sample outputs, caches)
+storage/benchmark_cache.json
+output_json/*.json

ARCHITECTURE.md

@@ -1,466 +0,0 @@
-# Design System Extractor v2 — Complete Architecture
-
-## Overview
-
-A **2-stage pipeline** that extracts, analyzes, and recommends improvements to any website's design system. Combines **deterministic rule-based analysis** (free, fast, reliable) with **4 specialized LLM agents** (context-aware reasoning) — each agent does one thing well.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        STAGE 1: EXTRACTION                       │
-│                        (No LLM — $0.00)                          │
-│                                                                   │
-│  URL → Crawler → Extractor → Normalizer → Semantic Analyzer      │
-│                         ↓                                         │
-│              [HUMAN REVIEW CHECKPOINT]                             │
-│         Accept/reject tokens, Desktop ↔ Mobile toggle             │
-├─────────────────────────────────────────────────────────────────┤
-│                     STAGE 2: ANALYSIS                             │
-│                                                                   │
-│  Layer 1: Rule Engine ──────────────── FREE ($0.00)               │
-│     ├─ WCAG Contrast (AA/AAA)                                     │
-│     ├─ Type Scale Detection                                       │
-│     ├─ Spacing Grid Alignment                                     │
-│     └─ Color Statistics                                           │
-│                                                                   │
-│  Layer 2: Benchmark Research ──────── Semi-Free                   │
-│     └─ Compare to Material 3, Polaris, Atlassian, etc.            │
-│                                                                   │
-│  Layer 3: LLM Agents ─────────────── ~$0.003/run                  │
-│     ├─ AURORA  → Brand color identification                       │
-│     ├─ ATLAS   → Benchmark recommendation                        │
-│     └─ SENTINEL → Best practices validation                      │
-│                                                                   │
-│  Layer 4: HEAD Synthesizer ────────── Final output                │
-│     └─ NEXUS   → Combines everything → User-facing results       │
-│                                                                   │
-│  [GRACEFUL DEGRADATION: Each layer has fallbacks]                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Stage 1: Extraction & Normalization (No LLM)
-
-### 1A. PageDiscoverer (Crawler)
-
-| | |
-|---|---|
-| **File** | `agents/crawler.py` |
-| **Model** | None |
-| **Input** | Base URL |
-| **Output** | List of discovered pages (title, URL, page type) |
-| **How** | Playwright browser crawling + heuristic page type detection |
-| **Why no LLM** | Pure URL discovery — deterministic crawling |
-
-### 1B. TokenExtractor
-
-| | |
-|---|---|
-| **File** | `agents/extractor.py` + `agents/firecrawl_extractor.py` |
-| **Model** | None |
-| **Input** | Confirmed page URLs + Viewport (1440px desktop / 375px mobile) |
-| **Output** | `ExtractedTokens` — colors, typography, spacing, radius, shadows, FG/BG pairs, CSS variables |
-| **How** | 7-source extraction via Playwright |
-| **Why no LLM** | DOM parsing + regex — no reasoning needed |
-
-**7 Extraction Sources:**
-1. DOM computed styles (`getComputedStyle`)
-2. CSS variables (`:root { --color: }`)
-3. SVG colors (fill, stroke)
-4. Inline styles (`style='color:'`)
-5. Stylesheet rules (CSS files)
-6. External CSS files (fetched via Firecrawl)
-7. Page content scan (brute-force token search)
-
-### 1C. TokenNormalizer
-
-| | |
-|---|---|
-| **File** | `agents/normalizer.py` |
-| **Model** | None |
-| **Input** | Raw `ExtractedTokens` |
-| **Output** | `NormalizedTokens` — deduplicated, named, confidence-tagged |
-| **How** | Deduplication (exact hex + Delta-E merge), role inference from frequency, semantic naming |
-| **Why no LLM** | Algorithmic deduplication — pure math |
-
-### 1D. SemanticColorAnalyzer
-
-| | |
-|---|---|
-| **File** | `agents/semantic_analyzer.py` |
-| **Model** | None |
-| **Input** | Extracted colors with usage/frequency data |
-| **Output** | Semantic mapping: `{brand, text, background, border, feedback}` |
-| **How** | Rule-based: buttons → brand, `color` property → text, `background-color` → background, red → error, green → success |
-| **Why no LLM** | CSS property analysis — pattern matching on property names |
-
-### Human Review Checkpoint
-
-After Stage 1, the user sees:
-- Desktop vs Mobile token comparison (side-by-side)
-- Accept/reject individual colors, typography, spacing tokens
-- Viewport toggle to switch views
-- All accepted tokens flow into Stage 2
-
----
-
-## Stage 2: Analysis (Hybrid — Rule Engine + LLM)
-
-### Layer 1: Rule Engine (FREE — No LLM)
-
-**File:** `core/rule_engine.py`
-**Cost:** $0.00
-**Speed:** < 1 second
-
-The rule engine handles everything that can be computed with math. No LLM reasoning needed.
-
-#### What It Calculates:
-
-**1. Typography Analysis (TypeScaleAnalysis)**
-```
-Input:  [11, 12, 14, 16, 18, 22, 24, 32]  (extracted font sizes)
-Output:
-  ├─ Detected Ratio: 1.167
-  ├─ Closest Standard: Minor Third (1.2)
-  ├─ Consistent: No (variance: 0.24)
-  └─ Recommendation: 1.25 (Major Third)
-```
-- Compares to standard ratios: 1.067, 1.125, 1.2, 1.25, 1.333, 1.414, 1.5
-- Calculates variance to determine consistency
-- 100% deterministic math
-
-**2. Color Accessibility (WCAG AA/AAA)**
-```
-Input:  210 colors + 220 FG/BG pairs
-Output:
-  ├─ AA Pass: 143
-  ├─ AA Fail (real pairs): 67
-  └─ Fix suggestions: #06b2c4 → #048391 (4.5:1)
-```
-- WCAG 2.1 contrast ratio formula
-- Tests actual FG/BG pairs found on page (not just color vs white)
-- Algorithmically generates AA-compliant alternatives
-- Pure math — no LLM
-
-**3. Spacing Grid Detection**
-```
-Input:  [3, 8, 10, 16, 20, 24, 32, 40]  (spacing values)
-Output:
-  ├─ Detected Base: 1px (GCD)
-  ├─ Grid Aligned: 0%
-  └─ Recommendation: 8px grid
-```
-- GCD math + alignment percentage calculation
-
-**4. Color Statistics**
-```
-Input:  143 extracted colors
-Output:
-  ├─ Unique: 143
-  ├─ Near-Duplicates: 351
-  ├─ Grays: 68 | Saturated: 69
-  └─ Hue Distribution: {gray: 68, blue: 14, red: 11, ...}
-```
-
-**5. Overall Consistency Score (0–100)**
-```
-Weights:
-  ├─ AA Compliance:        25 pts
-  ├─ Type Scale Consistent: 15 pts
-  ├─ Base Size (≥16px):     15 pts
-  ├─ Spacing Grid Aligned:  15 pts
-  ├─ Color Count (< 20):    10 pts
-  └─ No Near-Duplicates:    10 pts
-```
-
----
-
-### Layer 2: Benchmark Research
-
-**File:** `agents/benchmark_researcher.py`
-**Cost:** Near-free (optional HF LLM for doc extraction, mostly cached)
-
-**Available Benchmarks:**
-| System | Short Name |
-|--------|-----------|
-| Material Design 3 | Material 3 |
-| Apple HIG | Apple |
-| Shopify Polaris | Polaris |
-| Atlassian Design | Atlassian |
-| IBM Carbon | Carbon |
-| Tailwind CSS | Tailwind |
-| Ant Design | Ant |
-| Chakra UI | Chakra |
-
-**Process:**
-1. Check 24-hour cache per benchmark
-2. If expired: Fetch docs via Firecrawl → Extract specs → Cache
-3. Compare user's tokens to each benchmark:
-   - Type ratio diff, base size diff, spacing grid diff
-   - Weighted similarity score
-4. Sort by similarity (closest match first)
-
-**Fallback:** Hardcoded `FALLBACK_BENCHMARKS` dict — no external fetch needed
-
----
-
-### Layer 3: LLM Agents (4 Specialized Agents)
-
-**File:** `agents/llm_agents.py`
-
-Each agent has a single responsibility. They run after the rule engine — they reason about patterns the rule engine can't detect.
-
----
-
-#### Agent 1: AURORA — Brand Color Identifier
-
-| | |
-|---|---|
-| **Persona** | Senior Brand Color Analyst |
-| **Model** | Qwen 72B |
-| **Temperature** | 0.4 (allows creative interpretation) |
-| **Input** | Color tokens with usage counts + semantic CSS analysis |
-| **Output** | `BrandIdentification` |
-
-**Why LLM:** Requires context understanding — "33 button instances using #06b2c4 = likely brand primary." A rule engine can count colors, but can't reason about which one is the *brand* color based on where and how it's used.
-
-**Sample Output:**
-```
-AURORA's Analysis:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Brand Primary:  #06b2c4 (confidence: HIGH)
-  └─ 33 buttons, 12 CTAs, dominant accent
-
-Brand Secondary: #373737 (confidence: HIGH)
-  └─ 89 text elements, consistent dark tone
-
-Palette Strategy: Complementary
-Cohesion Score: 7/10
-  └─ "Clear primary-secondary hierarchy,
-      accent colors well-differentiated"
-
-Self-Evaluation:
-  ├─ Confidence: 8/10
-  ├─ Data Quality: good
-  └─ Flags: []
-```
-
----
-
-#### Agent 2: ATLAS — Benchmark Advisor
-
-| | |
-|---|---|
-| **Persona** | Senior Design System Benchmark Analyst |
-| **Model** | Llama 3.3 70B (128K context) |
-| **Temperature** | 0.25 (analytical, data-driven) |
-| **Input** | User's type ratio, base size, spacing + benchmark comparison data |
-| **Output** | `BenchmarkAdvice` |
-
-**Why LLM:** Requires trade-off reasoning. The closest mathematical match (85%) might not be the best fit if alignment effort is high. ATLAS reasons about effort vs. value — "Polaris is 87% match and your spacing already aligns. Material 3 is 77% but would require restructuring your grid."
-
-**Sample Output:**
-```
-ATLAS's Recommendation:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Recommended: Shopify Polaris (87% match)
-
-Alignment Changes:
-  ├─ Type scale: 1.17 → 1.25 (effort: medium)
-  ├─ Spacing grid: mixed → 4px (effort: high)
-  └─ Base size: 16px → 16px (already aligned!)
-
-Pros:
-  ├─ Closest match to existing system
-  ├─ E-commerce proven at scale
-  └─ Well-documented, community supported
-
-Cons:
-  ├─ Spacing migration is significant effort
-  └─ Type scale shift affects all components
-
-Alternative: Material 3 (77% match)
-  └─ "Stronger mobile patterns, 8px grid"
-```
-
----
-
-#### Agent 3: SENTINEL — Best Practices Validator
-
-| | |
-|---|---|
-| **Persona** | Design System Best Practices Auditor |
-| **Model** | Qwen 72B |
-| **Temperature** | 0.2 (strict, consistent evaluation) |
-| **Input** | Rule Engine results (typography, accessibility, spacing, color stats) |
-| **Output** | `BestPracticesResult` |
-
-**Why LLM:** Requires impact assessment and prioritization. The rule engine says "67 colors fail AA." SENTINEL says "Brand primary failing AA affects 40% of interactive elements — fix this FIRST, it's 5 minutes of work with high impact."
-
-**Sample Output:**
-```
-SENTINEL's Audit:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Overall Score: 68/100
-
-Checks:
-  ├─ ✅ Type Scale Standard (1.25 ratio)
-  ├─ ⚠️ Type Scale Consistency (variance 0.18)
-  ├─ ✅ Base Size Accessible (16px)
-  ├─ ❌ AA Compliance (67 failures)
-  ├─ ⚠️ Spacing Grid (0% aligned)
-  ├─ ⚠️ Color Count (143 unique — too many)
-  └─ ❌ Near-Duplicates (351 pairs)
-
-Priority Fixes:
-  #1 Fix brand color AA compliance
-     Impact: HIGH | Effort: 5 min
-     Action: #06b2c4 → #048391
-
-  #2 Consolidate near-duplicate colors
-     Impact: MEDIUM | Effort: 2 hours
-     Action: Merge 351 near-duplicate pairs
-
-  #3 Align spacing to 8px grid
-     Impact: MEDIUM | Effort: 1 hour
-     Action: Snap values to [8, 16, 24, 32, 40]
-```
-
----
-
-#### Agent 4: NEXUS — HEAD Synthesizer (Final Agent)
-
-| | |
-|---|---|
-| **Persona** | Senior Design System Architect & Synthesizer |
-| **Model** | Llama 3.3 70B (128K context) |
-| **Temperature** | 0.3 (balanced synthesis) |
-| **Input** | ALL Rule Engine results + AURORA + ATLAS + SENTINEL outputs |
-| **Output** | `HeadSynthesis` — the final user-facing result |
-
-**Why LLM:** Synthesis and contradiction resolution. If ATLAS says "close to Polaris" but SENTINEL says "spacing misaligned," NEXUS reconciles: "Align to Polaris type scale now (low effort) but defer spacing migration (high effort)."
-
-**Sample Output:**
-```
-NEXUS Final Synthesis:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Executive Summary:
-"Your design system scores 68/100. Critical issue:
-67 color pairs fail AA compliance. Top action:
-fix brand primary contrast (5 min, high impact)."
-
-Scores:
-  ├─ Overall:       68/100
-  ├─ Accessibility:  45/100
-  ├─ Consistency:    75/100
-  └─ Organization:   70/100
-
-Benchmark Fit:
-  ├─ Closest: Shopify Polaris (87%)
-  └─ Recommendation: Adopt Polaris type scale
-
-Top 3 Actions:
-  1. Fix brand color AA → #06b2c4 → #048391
-     Impact: HIGH | Effort: 5 min
-  2. Align type scale to 1.25
-     Impact: MEDIUM | Effort: 1 hour
-  3. Consolidate 143 → ~20 semantic colors
-     Impact: MEDIUM | Effort: 2 hours
-
-Color Recommendations:
-  ├─ ✅ brand.primary: #06b2c4 → #048391 (AA fix — auto-accept)
-  ├─ ✅ text.secondary: #999999 → #757575 (AA fix — auto-accept)
-  └─ ❌ brand.accent: #FF6B35 → #E65100 (aesthetic — user decides)
-
-Self-Evaluation:
-  ├─ Confidence: 7/10
-  ├─ Data Quality: good
-  └─ Flags: ["high near-duplicate count may indicate extraction noise"]
-```
-
----
-
-## Cost Model
-
-| Component | LLM? | Cost per Run |
-|-----------|-------|-------------|
-| Stage 1 (Crawl + Extract + Normalize) | No | $0.00 |
-| Rule Engine | No | $0.00 |
-| Benchmark Research | Optional | ~$0.0005 |
-| AURORA (Qwen 72B) | Yes | ~$0.0005 |
-| ATLAS (Llama 3.3 70B) | Yes | ~$0.0005 |
-| SENTINEL (Qwen 72B) | Yes | ~$0.0005 |
-| NEXUS (Llama 3.3 70B) | Yes | ~$0.001 |
-| **Total** | | **~$0.003** |
-
-All LLM inference via HuggingFace Inference API (PRO subscription at $9/month includes generous free tier for these models).
-
----
-
-## Graceful Degradation
-
-The system is designed to **always produce output**, even when components fail:
-
-| If This Fails... | Fallback |
-|-------------------|----------|
-| Firecrawl (CSS fetch) | Use DOM-only extraction |
-| Benchmark fetch | Use hardcoded `FALLBACK_BENCHMARKS` |
-| AURORA (brand ID) | Skip brand analysis, use defaults |
-| ATLAS (benchmark advice) | Skip recommendation, show raw comparisons |
-| SENTINEL (practices) | Use rule engine score directly |
-| NEXUS (synthesis) | `create_fallback_synthesis()` from rule engine data |
-| Entire LLM layer | Full rule-engine-only analysis still works |
-
----
-
-## Key Data Structures
-
-```
-ExtractedTokens (Stage 1 raw)
-├─ colors: dict[ColorToken]
-├─ typography: dict[TypographyToken]
-├─ spacing: dict[SpacingToken]
-├─ radius: dict[RadiusToken]
-├─ shadows: dict[ShadowToken]
-├─ fg_bg_pairs: list[dict]      ← for real AA checking
-└─ css_variables: dict[str, str] ← CSS var mappings
-
-NormalizedTokens (Stage 1 clean)
-├─ colors, typography, spacing, radius, shadows (deduplicated)
-├─ font_families: dict[FontFamily]
-├─ detected_spacing_base: int (4 or 8)
-└─ detected_naming_convention: str
-
-RuleEngineResults (Layer 1)
-├─ typography: TypeScaleAnalysis
-├─ accessibility: list[ColorAccessibility]
-├─ spacing: SpacingGridAnalysis
-├─ color_stats: ColorStatistics
-├─ aa_failures: int
-└─ consistency_score: int (0-100)
-
-HeadSynthesis (Final output)
-├─ executive_summary: str
-├─ scores: {overall, accessibility, consistency, organization}
-├─ benchmark_fit: {closest, similarity, recommendation}
-├─ brand_analysis: {primary, secondary, cohesion}
-├─ top_3_actions: [{action, impact, effort, details}]
-├─ color_recommendations: [{role, current, suggested, reason, accept}]
-├─ type_scale_recommendation: dict
-├─ spacing_recommendation: dict
-└─ self_evaluation: {confidence, reasoning, data_quality, flags}
-```
-
----
-
-## Tech Stack
-
-| Component | Technology |
-|-----------|-----------|
-| Frontend | Gradio 4.x |
-| Browser Automation | Playwright (Chromium) |
-| Web Scraping | Firecrawl |
-| LLM Inference | HuggingFace Inference API |
-| Models | Qwen 72B, Llama 3.3 70B |
-| Color Math | Custom WCAG implementation |
-| Deployment | Docker → HuggingFace Spaces |

CLAUDE.md

@@ -1,1468 +0,0 @@
-# Design System Extractor v3.2 — Project Context
-
-## Overview
-
-A multi-agent system that extracts, analyzes, and recommends improvements for design systems from websites. The system operates in two stages:
-
-1. **Stage 1 (Deterministic)**: Extract CSS values → Normalize (colors, radius, shadows, typography, spacing) → Rule Engine analysis → **Rule-Based Color Classification** (free, no LLM)
-2. **Stage 2 (LLM-powered)**: Brand identification (AURORA) → Benchmark comparison (ATLAS) → Best practices (SENTINEL) → Synthesis (NEXUS)
-3. **Export**: W3C DTCG v1 compliant JSON → Figma Plugin (visual spec + styles/variables)
-
----
-
-## CURRENT STATUS: v3.2 (Feb 2026)
-
-### What's Working
-
-| Component | Status | Notes |
-|-----------|--------|-------|
-| CSS Extraction (Playwright) | ✅ Working | Desktop + mobile viewports |
-| Color normalization | ✅ Working | Single numeric shade system (50-900) |
-| Color classification | ✅ Working | `core/color_classifier.py` (815 lines, 100% deterministic) |
-| Radius normalization | ✅ Working | Parse, deduplicate, sort, name (none/sm/md/lg/xl/2xl/full) |
-| Shadow normalization | ✅ Working | Parse, sort by blur, deduplicate, name (xs/sm/md/lg/xl) |
-| Typography normalization | ✅ Working | Desktop/mobile split, weight suffix |
-| Spacing normalization | ✅ Working | GCD-based grid detection, base-8 alignment |
-| Rule engine | ✅ Working | Type scale, WCAG AA, spacing grid, color statistics |
-| LLM agents (ReAct) | ✅ Working | AURORA, ATLAS, SENTINEL, NEXUS with critic/retry |
-| W3C DTCG export | ✅ Working | $value, $type, $description, $extensions |
-| Figma plugin - visual spec | ✅ Working | Separate frames, AA badges, horizontal layout |
-| Figma plugin - styles/variables | ✅ Working | Paint, text, effect styles + variable collections |
-| Shadow interpolation | ✅ Working | Always produces 5 levels (xs→xl), interpolates if fewer extracted |
-
-### Architecture Decisions (v3.2)
-
-#### Naming Authority Chain (RESOLVED)
-The three-naming-system conflict from v2/v3.0 is resolved:
-
-```
-1. Color Classifier (PRIMARY) — deterministic, covers ALL colors
-   └── Rule-based: CSS evidence → category → token name
-   └── 100% reproducible, logged with evidence
-
-2. AURORA LLM (SECONDARY) — semantic role enhancer ONLY
-   └── Can promote "color.blue.500" → "color.brand.primary"
-   └── CANNOT rename palette colors
-   └── Only brand/text/bg/border/feedback roles accepted
-   └── filter_aurora_naming_map() enforces this boundary
-
-3. Normalizer (FALLBACK) — preliminary hue+shade names
-   └── Only used if classifier hasn't run yet
-   └── _generate_preliminary_name() → "color.blue.500"
-```
-
-**app.py `_get_semantic_color_overrides()`** implements this chain:
-- PRIMARY: `state.color_classification.colors` (from color_classifier)
-- SECONDARY: `state.brand_result.naming_map` (from AURORA, filtered to semantic roles only)
-
-**`_generate_color_name_from_hex()`** is DEPRECATED — kept as thin wrapper for edge cases.
-
-#### W3C DTCG v1 Compliance (2025.10 Spec)
-- `$type` values: `color`, `dimension`, `typography`, `shadow`
-- `$value` for all token values
-- `$description` for human-readable descriptions
-- `$extensions` with namespaced metadata: `com.design-system-extractor`
-  - Colors: `{frequency, confidence, category, evidence}`
-  - Radius: `{frequency, fitsBase4, fitsBase8}`
-  - Shadows: `{frequency, rawCSS, blurPx}`
-- Nested structure (not flat)
-- `_flat_key_to_nested()` prevents nesting inside DTCG leaf nodes
-
-#### Deprecated Components
-- `agents/semantic_analyzer.py` — superseded by color_classifier + normalizer._infer_role_hint()
-- `agents/stage2_graph.py` — old LangGraph parallel system, replaced by direct async in app.py
-- `app.py _generate_color_name_from_hex()` — third naming system, now thin wrapper
-
----
-
-## v3.1 FIX: RULE-BASED COLOR NAMING (Feb 2026)
-
-### What Changed
-- **KILLED LLM color naming entirely.** New `core/color_classifier.py` handles all color naming with 100% deterministic rules.
-- **Aggressive deduplication**: Colors within RGB distance < 30 AND same category get merged (e.g., 13 text grays → 3)
-- **Capped categories**: brand (max 3), text (max 3), bg (max 3), border (max 3), feedback (max 4), palette (remaining)
-- **User-selectable naming convention**: semantic, tailwind, or material — chosen BEFORE export
-- **Preview before export**: User sees classification + decision log before committing
-- **Every decision logged**: `[DEDUP]`, `[CLASSIFY]`, `[CAP]`, `[NAME]` with evidence
-
-### How Classification Works (No LLM)
-```
-CSS Evidence → Category:
-  background-color on <button> + saturated + freq>5 → BRAND
-  color on <p>/<span> + low saturation → TEXT
-  background-color on <div>/<body> + neutral → BG
-  border-color + low saturation → BORDER
-  red hue + sat>0.6 + low freq → FEEDBACK (error)
-  everything else → PALETTE (named by hue.shade)
-```
-
-### What AURORA Does Now
-- Provides brand insights, palette strategy, cohesion score
-- naming_map is filtered to semantic roles only (brand/text/bg/border/feedback)
-- LLM reasoning is shown in logs
-- `filter_aurora_naming_map()` in llm_agents.py enforces the boundary
-
-### Files Changed in v3.1
-- `core/color_classifier.py` — NEW: Rule-based classifier with dedup, caps, naming conventions
-- `app.py` — Export functions use classifier instead of LLM naming; convention picker in UI
-- `agents/llm_agents.py` — AURORA prompt updated to advisory-only
-- `CLAUDE.md` — This documentation
-
----
-
-## v3.2 FIX: DTCG COMPLIANCE + NAMING AUTHORITY (Feb 2026)
-
-### What Changed
-1. **W3C DTCG v1 strict compliance**: `_to_dtcg_token()` now supports `$extensions` with namespaced metadata
-2. **Single naming authority resolved**: Color classifier is PRIMARY, AURORA is SECONDARY (semantic roles only)
-3. **`_get_semantic_color_overrides()` rewritten**: Uses classifier as primary, AURORA filtered to role-only names
-4. **`filter_aurora_naming_map()` added**: In llm_agents.py, strips non-semantic names from AURORA output
-5. **`_generate_color_name_from_hex()` deprecated**: Thin wrapper using `categorize_color()` from color_utils
-6. **`semantic_analyzer.py` deprecated**: Marked with deprecation notice, functionality absorbed elsewhere
-
-### Files Changed in v3.2
-- `app.py` — DTCG helpers enhanced, `_get_semantic_color_overrides()` rewritten, hex-name function deprecated
-- `agents/llm_agents.py` — Added `filter_aurora_naming_map()` function
-- `agents/semantic_analyzer.py` — Deprecated with notice
-- `CLAUDE.md` — Updated to current status
-
----
-
-## PREVIOUS STATUS (v3.0 and earlier): BROKEN — RETHINK COMPLETED
-
-### What's Wrong (observed from real site tests)
-
-**Tested sites**: sixflagsqiddiyacity.com, others
-
-#### Problem 1: Color Naming is Inconsistent (CRITICAL)
-Three competing naming systems produce mixed output:
-
-| Source | Convention | Example |
-|--------|-----------|---------|
-| `normalizer.py` (line 266-275) | Word-based: light/dark/base | `color.blue.light` |
-| `app.py _generate_color_name_from_hex()` | Numeric: 50-900 | `color.blue.500` |
-| AURORA LLM agent | Anything it wants | `brand.primary` |
-
-**Result in Figma**: `blue.300`, `blue.dark`, `blue.light`, `blue.base` — ALL IN THE SAME EXPORT. Unusable.
-
-#### Problem 2: Border Radius is Broken (CRITICAL)
-- `md = 1616` (concatenated garbage)
-- `full = 50` (should be 9999px)
-- Nested structures: `radius.full.9999` and `radius.full.100` incorrectly inside `radius.full`
-- Multi-value radii like `"0px 0px 16px 16px"` passed as-is — Figma can't use these
-- **Root cause**: Normalizer doesn't process radius at all (line 94-97 just stores raw values)
-
-#### Problem 3: LLM Agents Are Single-Shot, No Reasoning (CRITICAL)
-- AURORA does one LLM call → returns whatever it returns → no verification
-- SENTINEL does one LLM call → scores and checks not validated against actual data
-- NEXUS does one LLM call → synthesizes without checking if inputs make sense
-- No ReAct/ToT/reflection loop. No self-correction. No critic.
-- Models (Qwen 72B, Llama 3.3 70B via HF Inference) may not follow structured output reliably
-
-#### Problem 4: AURORA Only Names ~10 Colors
-- Prompt says "Suggest Semantic Names for top 10 most-used colors"
-- Remaining 20+ colors keep their normalizer names (word-based)
-- AURORA doesn't see existing names — only receives hex + usage count
-- No cleanup pass exists to unify naming after AURORA
-
-#### Problem 5: Shadow Ordering Wrong
-- xs has blur=25px, sm has blur=30px, md has blur=80px — non-progressive
-- Shadow naming (xs/sm/md/lg/xl) doesn't match actual elevation hierarchy
-- No validation that shadow progression makes physical sense
-
-#### Problem 6: Font Family Detection
-- All fonts showing as "sans-serif" (the fallback) instead of actual font name
-- Extraction gets computed style which resolves to generic family
-
----
-
-## ARCHITECTURE RETHINK PLAN
-
-### Phase 1: Fix Stage 2 (LLM Agents) — ADD AGENTIC REASONING
-
-Current Stage 2 is just 4 single-shot LLM calls. Needs proper agentic framework.
-
-#### Current (Broken):
-```
-Color Data ──→ [Single LLM Call] ──→ Output (hope for the best)
-```
-
-#### Target (With Reasoning):
-```
-Color Data ──→ [THINK] ──→ [ACT] ──→ [OBSERVE] ──→ [REFLECT] ──→ [VERIFY] ──→ Output
-                  │            │           │             │             │
-                  │            │           │             │        Does it pass
-                  │            │           │        Is this       validation?
-                  │            │      Check against  consistent?   If no, loop
-                  │         Generate   real data
-                  │         initial
-                  │         analysis
-                Plan approach
-```
-
-#### Option A: ReAct Framework (Recommended for AURORA + SENTINEL)
-```
-Thought: I need to identify brand colors from 30 extracted colors
-Action: Analyze usage frequency — #005aa3 used 47x in buttons/CTAs
-Observation: #005aa3 is clearly the primary CTA color
-Thought: Now check if secondary color exists — look for headers/nav
-Action: #ff0000 used 23x in headers → likely brand secondary
-Observation: Red + Blue = complementary strategy
-Thought: Now I need to name ALL colors consistently using numeric shades
-Action: Generate full naming map using Tailwind convention (50-900)
-Observation: 28 colors named, all using numeric shades
-Thought: Let me verify — any naming conflicts? Any mixed conventions?
-Action: Self-check naming consistency
-Final Answer: {complete consistent output}
-```
-
-#### Option B: Tree of Thought (For NEXUS synthesis)
-```
-Branch 1: Weight accessibility heavily → overall score 45
-Branch 2: Weight consistency heavily → overall score 68
-Branch 3: Balanced weighting → overall score 55
-Evaluate: Which scoring best reflects reality?
-Select: Branch 3 with adjustments
-```
-
-#### Option C: Critic/Verifier Pattern (For ALL agents)
-```
-Agent Output ──→ [CRITIC LLM] ──→ Pass? ──→ Final Output
-                      │              │
-                      │          No: feedback
-                      │              │
-                      │              ▼
-                      │         [RETRY with feedback]
-                      │
-                 Checks:
-                 - Naming convention consistent?
-                 - Scores match actual data?
-                 - All required fields present?
-                 - Values in valid ranges?
-```
-
-### Proposed New Stage 2 Architecture:
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  STAGE 2: AGENTIC ANALYSIS                                         │
-│                                                                     │
-│  ┌───────────────────────────────────────────────────┐              │
-│  │  STEP 1: AURORA (ReAct, 2-3 reasoning steps)     │              │
-│  │  Think → Identify brand → Name ALL colors         │              │
-│  │  → Self-verify naming consistency                 │              │
-│  │  → Critic check → Retry if needed                 │              │
-│  └───────────────────────────────────────────────────┘              │
-│                          │                                          │
-│  ┌───────────────────────┼───────────────────────────┐              │
-│  │                       │                           │              │
-│  ▼                       ▼                           ▼              │
-│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐              │
-│  │   ATLAS     │   │  SENTINEL   │   │  VALIDATOR   │              │
-│  │  Benchmark  │   │  Best Prac  │   │  (Critic)    │              │
-│  │  (ReAct)    │   │  (ReAct)    │   │  Checks ALL  │              │
-│  │             │   │             │   │  outputs      │              │
-│  └─────────────┘   └─────────────┘   └─────────────┘              │
-│         │                │                 │                        │
-│         └────────────────┼─────────────────┘                        │
-│                          ▼                                          │
-│                  ┌─────────────┐                                    │
-│                  │   NEXUS     │                                    │
-│                  │   (ToT)     │                                    │
-│                  │  + Critic   │                                    │
-│                  └─────────────┘                                    │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### Model Selection Rethink
-
-Current models via HuggingFace Inference API:
-| Agent | Current Model | Problem |
-|-------|--------------|---------|
-| AURORA | Qwen 72B | Doesn't follow structured output reliably |
-| ATLAS | Llama 3.3 70B | Adequate for comparison |
-| SENTINEL | Qwen 72B | Doesn't validate against actual data |
-| NEXUS | Llama 3.3 70B | Single-shot synthesis, no verification |
-
-**Models to evaluate:**
-- **Qwen 2.5 72B Instruct** — Better instruction following than Qwen 72B
-- **Mixtral 8x22B** — Good at structured JSON output
-- **DeepSeek V3** — Strong at reasoning chains
-- **Llama 3.1 405B** — Largest open model, best reasoning (but slow/expensive)
-- **Command R+** — Designed for tool use and structured output
-
-**Key question**: Should we use ONE model for all agents (consistency) or specialized models per task?
-
-### Phase 2: Fix Stage 1 (After Stage 2 is stable)
-
-#### Normalizer Fixes Needed:
-1. **Unify color shade convention** — Pick ONE system (numeric 50-900 recommended)
-2. **Add radius normalization** — Currently just stores raw values
-3. **Handle multi-value radius** — `"0px 0px 16px 16px"` needs decomposition
-4. **Deduplicate radius values** — Multiple entries for same visual radius
-
-#### Rule Engine Fixes Needed:
-1. **Base font size filter** — DONE (>= 10px filter applied)
-2. **Shadow progression validation** — Check blur/offset increase with elevation
-3. **Radius grid alignment** — Check if radii follow base-4/base-8
-
-#### Export Fixes Needed:
-1. **Validation layer before export** — Catch mixed conventions, nested garbage
-2. **Radius structure flattening** — Never nest tokens inside tokens
-3. **Unit consistency** — All radius values must have `px` units
-
----
-
-## FILE STRUCTURE
-
-```
-design-system-extractor-v2-hf-fix/
-├── app.py                    # Main Gradio app, orchestrates everything
-├── CLAUDE.md                 # THIS FILE — project context and plan
-│
-├── agents/
-│   ├── crawler.py            # Page discovery (finds links on site)
-│   ├── extractor.py          # Playwright-based CSS extraction
-│   ├── firecrawl_extractor.py # Firecrawl CSS deep extraction
-│   ├── normalizer.py         # Token deduplication and naming
-│   ├── llm_agents.py         # AURORA, ATLAS, SENTINEL, NEXUS agents
-│   ├── stage2_graph.py       # LangGraph orchestration for Stage 2
-│   ├── advisor.py            # Upgrade advisor
-│   ├── benchmark_researcher.py # Benchmark data collection
-│   └── semantic_analyzer.py  # Semantic CSS analysis
-│
-├── core/
-│   ├── token_schema.py       # Pydantic models for all token types
-│   ├── color_utils.py        # Color parsing, contrast, ramp generation
-│   ├── rule_engine.py        # Deterministic analysis (type scale, WCAG, spacing)
-│   ├── hf_inference.py       # HuggingFace Inference API client
-│   ├── preview_generator.py  # HTML preview generation
-│   ├── validation.py         # Output validation
-│   └── logging.py            # Logging utilities
-│
-├── config/
-│   └── settings.py           # Configuration (viewports, timeouts, thresholds)
-│
-├── tests/
-│   ├── test_stage1_extraction.py  # 82 deterministic tests
-│   ├── test_agent_evals.py        # 27 LLM agent schema/behavior tests
-│   └── test_stage2_pipeline.py    # Pipeline integration tests
-│
-└── output_json/
-    ├── file (16).json             # Latest extraction output (sixflags)
-    └── figma-plugin-extracted/    # Figma plugin source
-        └── figma-design-token-creator 5/
-            └── src/code.js        # Figma plugin main code
-```
-
----
-
-## DATA FLOW (Current vs Target)
-
-### Current Flow (Broken):
-```
-Extraction → Normalizer (word shades) → Rule Engine → LLM (single-shot)
-     ↓              ↓                       ↓              ↓
-  Raw CSS     color.blue.light         Stats only    Unverified output
-  values      color.neutral.dark       No radius     Mixed naming
-              No radius processing     validation    No self-correction
-                    ↓
-              Export (merges 3 naming conventions → chaos)
-```
-
-### Target Flow:
-```
-Extraction → Normalizer (numeric shades, radius too) → Rule Engine
-     ↓              ↓                                      ↓
-  Raw CSS     color.blue.500                          Stats + validation
-  values      color.neutral.200                       Shadow progression
-              radius.md = 8px                         Radius grid check
-                    ↓                                      ↓
-              LLM Agents (ReAct framework)                 │
-                    ↓                                      │
-              AURORA: Think → Act → Observe → Verify       │
-              SENTINEL: Think → Check data → Score         │
-              NEXUS: ToT → Select best synthesis           │
-                    ↓                                      │
-              CRITIC/VALIDATOR ←────────────────────────────┘
-                    ↓                    (validates against Stage 1 data)
-              Pass? → Export
-              Fail? → Retry with feedback
-```
-
----
-
-## WHAT EACH AGENT SHOULD ACTUALLY DO
-
-### AURORA (Brand Identifier) — Needs ReAct
-**Current**: Single-shot, names 10 colors, no verification
-**Target**:
-- Step 1 (Think): Plan approach based on color count and usage patterns
-- Step 2 (Act): Identify brand primary/secondary/accent from usage evidence
-- Step 3 (Observe): Check if identification makes sense (is primary really the most-used CTA color?)
-- Step 4 (Act): Name ALL colors using consistent numeric convention (50-900)
-- Step 5 (Verify): Self-check — are all names consistent? Any mixed conventions?
-- Step 6 (Critic): External validation — does output match schema? Names all `color.{family}.{shade}`?
-
-### SENTINEL (Best Practices) — Needs ReAct + Data Grounding
-**Current**: Single-shot, scores without verifying against actual data
-**Target**:
-- Step 1 (Think): What checks apply given the data?
-- Step 2 (Act): Score each check CITING SPECIFIC DATA from rule engine
-- Step 3 (Observe): Does my score match what the data shows?
-- Step 4 (Verify): If rule engine says 5 AA failures, my AA check MUST be "fail" not "pass"
-- Step 5 (Critic): Cross-check scores against rule engine numbers
-
-### NEXUS (Synthesizer) — Needs ToT
-**Current**: Single-shot synthesis, no evaluation of alternatives
-**Target**:
-- Branch 1: Accessibility-focused scoring (weight AA failures heavily)
-- Branch 2: Consistency-focused scoring (weight naming/grid alignment)
-- Branch 3: Balanced approach
-- Evaluate: Which branch best reflects reality?
-- Critic: Does final score contradict any agent's findings?
-
----
-
-## KNOWN FIXES ALREADY APPLIED
-
-### 1. Base Font Size Detection (FIXED in rule_engine.py)
-Filters out sizes < 10px before detecting base size.
-
-### 2. Garbage Color Names (PARTIALLY FIXED in app.py)
-Detects `firecrawl.N` names and regenerates — but the replacement still creates mixed conventions.
-
-### 3. Visual Spec Error Handling (FIXED in code.js)
-Defensive error handling for undefined errors.
-
----
-
-## IDEAL OUTPUT REFERENCE
-
-What the exported JSON SHOULD look like (for Figma):
-
-```json
-{
-  "color": {
-    "brand": {
-      "primary": { "$type": "color", "$value": "#005aa3" },
-      "secondary": { "$type": "color", "$value": "#ff0000" }
-    },
-    "text": {
-      "primary": { "$type": "color", "$value": "#000000" },
-      "secondary": { "$type": "color", "$value": "#999999" },
-      "muted": { "$type": "color", "$value": "#cccccc" }
-    },
-    "background": {
-      "primary": { "$type": "color", "$value": "#ebedef" },
-      "secondary": { "$type": "color", "$value": "#bfbfbf" }
-    },
-    "blue": {
-      "50": { "$type": "color", "$value": "#b9daff" },
-      "300": { "$type": "color", "$value": "#7fdbff" },
-      "500": { "$type": "color", "$value": "#6f7597" },
-      "800": { "$type": "color", "$value": "#2c3e50" }
-    },
-    "neutral": {
-      "200": { "$type": "color", "$value": "#b2b8bf" },
-      "700": { "$type": "color", "$value": "#333333" }
-    }
-  },
-  "radius": {
-    "none": { "$type": "dimension", "$value": "0px" },
-    "sm": { "$type": "dimension", "$value": "2px" },
-    "md": { "$type": "dimension", "$value": "4px" },
-    "lg": { "$type": "dimension", "$value": "8px" },
-    "xl": { "$type": "dimension", "$value": "16px" },
-    "2xl": { "$type": "dimension", "$value": "24px" },
-    "full": { "$type": "dimension", "$value": "9999px" }
-  }
-}
-```
-
-**Key rules**:
-- Palette colors ALWAYS use numeric shades (50-900)
-- Role colors use semantic names (primary, secondary, muted)
-- Radius is FLAT — never nested, always single px values
-- No mixed conventions in the same category
-
----
-
-## FILES TO UPDATE ON HUGGINGFACE
-
-When making changes, these files need updating:
-1. `app.py` — Main application logic
-2. `core/rule_engine.py` — Deterministic analysis
-3. `agents/llm_agents.py` — LLM agent prompts and reasoning
-4. `agents/normalizer.py` — Token naming and dedup
-5. `agents/extractor.py` — CSS extraction
-6. `output_json/figma-plugin-extracted/figma-design-token-creator 5/src/code.js` — Figma plugin
-
----
-
-## CRITICAL DISCOVERY: TWO COMPETING STAGE 2 ARCHITECTURES
-
-The codebase has **two parallel Stage 2 systems** that partially overlap:
-
-### System A: `llm_agents.py` (4 Specialized Agents)
-```
-AURORA (brand ID) → ATLAS (benchmark) → SENTINEL (best practices) → NEXUS (synthesis)
-```
-- Each agent has a focused prompt + dedicated data class
-- Called from `app.py` directly via `hf_client.complete_async()`
-- Uses `Qwen/Qwen2.5-72B-Instruct` and `Llama-3.3-70B-Instruct`
-- **Problem**: Single-shot calls, no reasoning, no verification
-
-### System B: `stage2_graph.py` (LangGraph Parallel)
-```
-LLM1 (Qwen) ──┐
-               ├──→ HEAD ──→ Final
-LLM2 (Llama) ─┘
-Rule Engine ───┘
-```
-- Two generic "analyst" LLMs run in parallel + rule engine
-- Uses LangGraph `StateGraph` with `asyncio.gather()`
-- HEAD compiler merges results
-- **Problem**: Generic prompts, no specialization, same analysis duplicated
-
-### Decision: Merge into ONE system with ReAct reasoning
-
-Keep System A's **specialized agents** (AURORA, SENTINEL, NEXUS) but add System B's **parallel execution** and **LangGraph state management**. Drop the duplicate generic analysts (LLM1/LLM2).
-
----
-
-## DETAILED AGENTIC ARCHITECTURE FOR STAGE 2
-
-### Design Principles
-1. **ReAct (Reasoning + Acting)**: Each agent THINKS before it acts, OBSERVES the result, REFLECTS on quality
-2. **Critic/Verifier**: A lightweight validation pass after each agent output
-3. **Grounded Reasoning**: LLMs must cite specific data from Stage 1, not hallucinate
-4. **Fail-Safe Defaults**: If LLM fails or produces garbage, fall back to rule-engine defaults
-5. **Single Convention**: ALL naming uses numeric shades (50-900), enforced post-LLM
-
-### New Stage 2 Flow
-
-```
-Stage 1 Output (NormalizedTokens + RuleEngineResults)
-                    │
-                    ▼
-┌──────────────────────────────────────────────────────────────┐
-│  PRE-PROCESSING (Deterministic, no LLM)                      │
-│  • Unify all color names to numeric shades (50-900)          │
-│  • Normalize radius values (flatten, deduplicate)            │
-│  • Validate shadow progression (sort by blur)                │
-│  • Build structured data packets for each agent              │
-└──────────────────────────────────────────────────────────────┘
-                    │
-        ┌───────────┼───────────┐
-        ▼           ▼           ▼
-┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-│   AURORA    │ │   ATLAS     │ │  SENTINEL   │
-│   (ReAct)   │ │  (Single)   │ │  (ReAct)    │
-│   2 steps   │ │   1 step    │ │  2 steps    │
-└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
-       │               │               │
-       ▼               ▼               ▼
-┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-│  CRITIC 1   │ │  (no critic │ │  CRITIC 2   │
-│  Validate   │ │   needed)   │ │  Cross-ref  │
-│  naming     │ │             │ │  with data  │
-└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
-       │               │               │
-       └───────────────┼───────────────┘
-                       ▼
-              ┌─────────────────┐
-              │     NEXUS       │
-              │  (ToT: 2 branches, pick best)  │
-              └────────┬────────┘
-                       ▼
-              ┌─────────────────┐
-              │  POST-VALIDATION│
-              │  (Deterministic)│
-              │  • Names consistent? │
-              │  • Scores in range?  │
-              │  • All fields present?│
-              └─────────────────┘
-```
-
-### AURORA — Brand Identifier (ReAct, 2 LLM Calls)
-
-**Why ReAct**: Brand identification requires reasoning about CONTEXT (why a color is used 47x on buttons) not just statistics. The model needs to think step-by-step.
-
-**Step 1: Identify + Name (Main Call)**
-```
-System: You are AURORA. You will receive color data with usage context.
-
-TASK (do these in order, show your reasoning):
-
-THINK: Look at the color usage data. Which colors appear most in
-       interactive elements (buttons, links, CTAs)?
-ACT:   Identify brand primary, secondary, accent.
-THINK: Now look at ALL colors. Group them by hue family.
-ACT:   Assign EVERY color a name using this EXACT convention:
-       - Role colors: color.{role}.{shade} where role=brand/text/background/border/feedback
-       - Palette colors: color.{hue}.{shade} where hue=red/orange/yellow/green/teal/blue/purple/pink/neutral
-       - Shade MUST be numeric: 50/100/200/300/400/500/600/700/800/900
-       - NEVER use words like "light", "dark", "base" for shades
-OBSERVE: Check your naming. Are ALL names using numeric shades?
-         Any duplicates? Any conflicts?
-
-Output JSON with brand_colors + complete naming_map for ALL colors.
-```
-
-**Step 2: Critic Check (Lightweight Call or Rule-Based)**
-```python
-# Can be done WITHOUT an LLM call — just Python validation:
-def validate_aurora_output(output: dict, input_colors: list[str]) -> tuple[bool, list[str]]:
-    errors = []
-    naming_map = output.get("naming_map", {})
-
-    # Check 1: All input colors have names
-    for hex_val in input_colors:
-        if hex_val not in naming_map:
-            errors.append(f"Missing name for {hex_val}")
-
-    # Check 2: No word-based shades
-    for hex_val, name in naming_map.items():
-        parts = name.split(".")
-        last = parts[-1]
-        if last in ("light", "dark", "base", "muted", "deep"):
-            errors.append(f"Word shade '{last}' in {name} — must be numeric")
-
-    # Check 3: No duplicate names
-    names = list(naming_map.values())
-    dupes = [n for n in names if names.count(n) > 1]
-    if dupes:
-        errors.append(f"Duplicate names: {set(dupes)}")
-
-    return len(errors) == 0, errors
-```
-
-If validation fails → retry ONCE with error feedback appended to prompt. If still fails → fall back to deterministic HSL-based naming (already in `color_utils.py`).
-
-### SENTINEL — Best Practices (ReAct, 2 LLM Calls)
-
-**Why ReAct**: Scoring must be GROUNDED in actual data. The model needs to cite specific numbers, not make up scores.
-
-**Step 1: Score + Prioritize (Main Call)**
-```
-System: You are SENTINEL. You MUST cite specific data for every score.
-
-INPUT DATA (from Rule Engine — these are FACTS, not opinions):
-- AA Pass: 18 of 25 colors (72%)
-- AA Fail: 7 colors (list: #ff0000 3.2:1, #ffdc00 1.8:1, ...)
-- Type Scale Ratio: 1.18 (variance: 0.22)
-- Base Font: 14px
-- Spacing: 8px grid, 85% aligned
-- Shadows: 5 defined, blur progression: 25→30→80→80→90 (non-monotonic)
-- Near-duplicates: 3 pairs
-
-TASK (cite data for EVERY check):
-
-CHECK 1 - AA Compliance:
-  THINK: Rule Engine says 7 of 25 fail. That's 28% failure rate.
-  SCORE: "fail" — cite "7 colors fail AA, including brand primary #ff0000 (3.2:1)"
-
-CHECK 2 - Type Scale:
-  THINK: Ratio 1.18 is not standard (nearest: 1.2 Minor Third). Variance 0.22 > 0.15.
-  SCORE: "warn" — cite "1.18 is close to Minor Third but inconsistent (variance 0.22)"
-
-... (continue for all 8 checks)
-
-THEN calculate overall_score using the weighting:
-  AA: 25pts × (pass%/100) = 25 × 0.72 = 18
-  Type Scale Consistent: ...
-  ... total = sum
-
-Output JSON with checks, overall_score, priority_fixes.
-```
-
-**Step 2: Cross-Reference Critic (Rule-Based)**
-```python
-def validate_sentinel_output(output: dict, rule_engine: RuleEngineResults) -> tuple[bool, list[str]]:
-    errors = []
-    checks = output.get("checks", {})
-
-    # If rule engine found AA failures, sentinel MUST mark aa_compliance as fail/warn
-    aa_failures = len([a for a in rule_engine.accessibility if not a.passes_aa_normal])
-    if aa_failures > 0 and checks.get("aa_compliance", {}).get("status") == "pass":
-        errors.append(f"Sentinel says AA passes but rule engine found {aa_failures} failures")
-
-    # Score must be 0-100
-    score = output.get("overall_score", -1)
-    if not (0 <= score <= 100):
-        errors.append(f"Score {score} out of range")
-
-    # If many failures, score can't be high
-    fail_count = sum(1 for c in checks.values() if isinstance(c, dict) and c.get("status") == "fail")
-    if fail_count >= 3 and score > 70:
-        errors.append(f"Score {score} too high with {fail_count} failures")
-
-    return len(errors) == 0, errors
-```
-
-### ATLAS — Benchmark Advisor (Single Call, No ReAct Needed)
-
-**Why single call**: This agent receives well-structured benchmark comparison data and just needs to pick the best fit. The reasoning is straightforward comparison.
-
-Keep current implementation but improve prompt to:
-1. Explicitly output the top 3 benchmarks ranked
-2. Include specific numeric diffs for each
-3. Cap alignment changes at 4
-
-### NEXUS — HEAD Synthesizer (ToT: 2 Branches)
-
-**Why Tree of Thought**: The synthesizer needs to weigh competing priorities. Should it emphasize accessibility (SENTINEL's input) or brand fidelity (AURORA's input)? ToT lets it explore both and pick the best.
-
-**Branch 1: Accessibility-First Scoring**
-```
-Weight accessibility at 40%, consistency at 30%, organization at 30%.
-If SENTINEL found 7 AA failures → accessibility score tanks → overall score lower.
-Result: overall ~55
-```
-
-**Branch 2: Balanced Scoring**
-```
-Weight accessibility at 30%, consistency at 35%, organization at 35%.
-Same data but organization counts more.
-Result: overall ~65
-```
-
-**Selection**: Pick the branch that:
-1. Doesn't contradict any agent's hard failures (if SENTINEL says AA fails, score CAN'T say accessibility is "good")
-2. Produces actionable top-3 actions (not generic)
-3. Has color recommendations with specific hex values
-
-**Implementation**: This can be done as a SINGLE LLM call with explicit instruction:
-
-```
-TASK: You will synthesize from two perspectives.
-
-PERSPECTIVE A (Accessibility-First): Weight AA compliance heavily.
-Calculate scores with accessibility=40%, consistency=30%, org=30%.
-
-PERSPECTIVE B (Balanced): Equal weights.
-Calculate scores with accessibility=33%, consistency=33%, org=33%.
-
-THEN: Compare both perspectives. Choose the one that:
-1. Better reflects the ACTUAL data (don't ignore failures)
-2. Produces the most actionable top-3 list
-3. Is internally consistent
-
-Output your CHOSEN perspective's scores + explain WHY you chose it.
-```
-
-### Model Selection (Final Decision)
-
-After reviewing all agents' needs:
-
-| Agent | Model | Reasoning |
-|-------|-------|-----------|
-| AURORA | `Qwen/Qwen2.5-72B-Instruct` | Best at structured JSON, good reasoning |
-| ATLAS | `meta-llama/Llama-3.3-70B-Instruct` | 128K context for benchmark data |
-| SENTINEL | `Qwen/Qwen2.5-72B-Instruct` | Methodical, follows rubrics well |
-| NEXUS | `meta-llama/Llama-3.3-70B-Instruct` | Good synthesis, large context |
-
-**Keep current models** — the problem isn't the models, it's the prompting strategy (single-shot vs ReAct) and lack of validation.
-
-### Cost Budget Per Extraction
-
-| Step | LLM Calls | Est. Tokens | Est. Cost |
-|------|-----------|-------------|-----------|
-| AURORA main | 1 | ~2K in, ~1K out | $0.001 |
-| AURORA retry (10% of time) | 0.1 | ~2K in, ~1K out | $0.0001 |
-| ATLAS | 1 | ~1.5K in, ~0.8K out | $0.001 |
-| SENTINEL main | 1 | ~2K in, ~1K out | $0.001 |
-| SENTINEL retry (10% of time) | 0.1 | ~2K in, ~1K out | $0.0001 |
-| NEXUS | 1 | ~3K in, ~1.2K out | $0.002 |
-| **Total** | **~4.2** | **~14K** | **~$0.005** |
-
-Well within HF free tier ($0.10/mo).
-
----
-
-## IMPLEMENTATION PLAN
-
-### Step 1: Consolidate Stage 2 into ONE system
-- Keep `llm_agents.py` as the agent definitions (AURORA, SENTINEL, NEXUS)
-- Use `stage2_graph.py` for orchestration (parallel AURORA+ATLAS+SENTINEL, then NEXUS)
-- Delete the duplicate generic LLM1/LLM2 analyst nodes
-- Single entry point: `run_stage2_analysis()`
-
-### Step 2: Add Pre-Processing Layer
-- Before any LLM call, run deterministic cleanup:
-  - Unify ALL color names to numeric shades (50-900)
-  - Flatten and deduplicate radius values
-  - Sort shadows by blur radius
-  - Build structured data packets for each agent
-
-### Step 3: Rewrite AURORA with ReAct Prompt
-- New prompt: Think → Identify brand → Name ALL colors → Self-verify
-- Add `validate_aurora_output()` rule-based critic
-- Retry once on validation failure
-- Fallback to `_generate_color_name_from_hex()` if LLM fails
-
-### Step 4: Rewrite SENTINEL with Grounded Scoring
-- New prompt: Must cite rule-engine data for every check
-- Add `validate_sentinel_output()` cross-reference critic
-- Ensure scores match actual data (no inflated pass when data says fail)
-
-### Step 5: Rewrite NEXUS with ToT
-- Two-perspective evaluation in single prompt
-- Must choose perspective and explain why
-- Post-validation: scores internally consistent, actions are specific
-
-### Step 6: Add Post-Validation Layer
-- After all agents complete, run deterministic checks:
-  - All color names follow `color.{family}.{shade}` pattern
-  - All scores are in valid ranges
-  - No contradictions between agents
-  - All required fields present
-- If post-validation fails, apply rule-based fixes (not another LLM call)
-
-### Step 7: Fix Normalizer (Stage 1)
-- Unify `_generate_color_name_from_value()` to use numeric shades only
-- Add radius normalization (flatten, single-value, deduplicate)
-- Handle multi-value radius (`"0px 0px 16px 16px"` → individual values or skip)
-
-### Step 8: Fix Export Layer
-- Validation before JSON export
-- Ensure DTCG format (`$type`, `$value`)
-- Flat radius (never nested tokens inside tokens)
-- Consistent units (all px for dimensions)
-
----
-
-## STAGE 1 AUDIT: WHAT IS VALID vs WHAT NEEDS RETHINKING
-
-Stage 1 feeds Stage 2 — if Stage 1 produces garbage, no amount of agentic reasoning in Stage 2 can fix it. Let's audit every rule-based component honestly.
-
-### OVERALL VERDICT: Stage 1 is ~60% correct, 40% broken/missing
-
-The extraction (Playwright CSS scraping) is solid. The normalizer and rule engine have real problems that corrupt data BEFORE any LLM ever sees it.
-
----
-
-### Component 1: Extractor (`agents/extractor.py`) — ✅ MOSTLY VALID
-
-**What it does**: Playwright visits pages, extracts computed CSS styles for every element.
-**What it produces**: `ExtractedTokens` — lists of `ColorToken`, `TypographyToken`, `SpacingToken`, `RadiusToken`, `ShadowToken`.
-
-**What's working**:
-- Color extraction: Gets hex values, usage frequency, CSS property context (background-color, color, border-color), element types (button, h1, p). This is exactly what Stage 2 needs.
-- Typography extraction: Gets font-family, font-size, font-weight, line-height, element context. Solid.
-- Spacing extraction: Gets margin/padding/gap values with px conversion. Solid.
-
-**What's broken**:
-- **Font family**: Returns `"sans-serif"` (the computed fallback) instead of `"Inter"` (the actual font). This is a browser behavior issue — `getComputedStyle()` resolves the font stack to the generic family. **Fix needed**: Use `document.fonts.check()` or extract from CSS `font-family` declarations before resolution.
-- **Radius**: Extracts raw CSS values including multi-value shorthand like `"0px 0px 16px 16px"` and percentage values like `"50%"`. The RadiusToken has `value: str` and `value_px: Optional[int]` but the extractor doesn't parse multi-value or percentage. **Fix needed**: Parse in extractor or normalizer.
-- **Shadows**: Extracts full CSS shadow string but parsing into components (offset_x, offset_y, blur, spread, color) is unreliable. Some shadows have `None` for all parsed fields. **Fix needed**: Better CSS shadow parser.
-
-**Verdict**: Extraction is the least broken part. Font family is the biggest issue but it's a well-known Playwright limitation with known workarounds.
-
----
-
-### Component 2: Normalizer (`agents/normalizer.py`) — ❌ NEEDS MAJOR RETHINK
-
-**What it does**: Takes raw `ExtractedTokens` lists → deduplicates → names → outputs `NormalizedTokens` dicts.
-
-**What's working**:
-- Color deduplication by exact hex: Correct. Merges frequency/contexts.
-- Similar color merging (RGB Euclidean distance < 10): Reasonable threshold, works.
-- Typography dedup by unique `family|size|weight|lineHeight`: Correct.
-- Spacing dedup and base-8 alignment preference: Correct.
-- Confidence scoring by frequency (10+=high, 3-9=medium, 1-2=low): Reasonable.
-
-**What's BROKEN**:
-
-#### Problem 2A: Color Naming — TWO COMPETING FUNCTIONS
-
-```
-_generate_color_name(color, role) → line 236-256
-  Input: color + inferred role (from CSS context keywords)
-  Output: "color.{role}.{shade}" where shade = 50/200/500/700/900
-  Uses: NUMERIC shades based on luminance buckets ✅
-
-_generate_color_name_from_value(color) → line 258-275
-  Input: color (no role found)
-  Output: "color.{category}.{shade}" where shade = light/base/dark
-  Uses: WORD shades ❌ ← THIS IS THE ROOT OF THE NAMING PROBLEM
-```
-
-**The irony**: The first function (with role) already uses numeric shades! But only colors where `_infer_color_role()` finds a keyword match get numeric names. All other colors fall through to the word-based function.
-
-**`_infer_color_role()` (line 220-234)**: Searches color.contexts + color.elements for keywords like "primary", "button", "background". **Problem**: Most extracted colors don't have semantic class names — they come from computed styles on generic elements. A `<div>` with `background-color: #005aa3` has no "primary" keyword anywhere. So MOST colors fall through to word-based naming.
-
-**How often does role inference work?** Rough estimate:
-- Sites with BEM/utility classes (Tailwind, Bootstrap): ~40% of colors get roles
-- Sites with generic/minified classes: ~5-10% of colors get roles
-- Remaining get word-based names → causes mixed convention chaos
-
-**Fix needed**: Remove `_generate_color_name_from_value()` entirely. Make `_generate_color_name()` the only path, and if no role is inferred, use hue-family + numeric shade (which `_generate_color_name_from_hex()` in app.py already does correctly).
-
-#### Problem 2B: Radius — NO PROCESSING AT ALL
-
-```python
-# Line 93-97: Just stores raw values
-radius_dict = {}
-for r in extracted.radius:
-    key = f"radius-{r.value}"   # Raw CSS value as dict key!
-    radius_dict[key] = r
-```
-
-**What this produces**:
-- `"radius-8px"` → ok
-- `"radius-0px 0px 16px 16px"` → garbage key, multi-value
-- `"radius-50%"` → percentage, Figma can't use
-- `"radius-16px"` AND `"radius-1rem"` → duplicates (both = 16px)
-
-**What's missing**:
-1. No value parsing (multi-value → skip or take max)
-2. No unit normalization (%, rem, em → px)
-3. No deduplication by resolved px value
-4. No semantic naming (none/sm/md/lg/xl/full)
-5. No sorting by size
-
-#### Problem 2C: Shadows — NO PROCESSING AT ALL
-
-```python
-# Line 99-102: Hash-based key, no analysis
-shadows_dict = {}
-for s in extracted.shadows:
-    key = f"shadow-{hash(s.value) % 1000}"  # Meaningless key!
-    shadows_dict[key] = s
-```
-
-**What's missing**:
-1. No deduplication by visual similarity
-2. No sorting by elevation (blur radius)
-3. No semantic naming (xs/sm/md/lg/xl)
-4. No validation of shadow progression (blur should increase with elevation level)
-5. No filtering of garbage shadows (blur=0, identical to another, etc.)
-
-#### Problem 2D: Typography Naming — COLLISION RISK
-
-```python
-# Line 310-339: Size-tier names can collide
-"font.{category}.{size_tier}"
-# Two different h2 styles (24px/700 and 24px/400) both become "font.heading.lg"
-```
-
-The dedup key at line 86 is `suggested_name or f"{font_family}-{font_size}"`, so if two styles get the SAME suggested name, the second overwrites the first silently.
-
----
-
-### Component 3: Rule Engine (`core/rule_engine.py`) — ✅ MOSTLY VALID
-
-**What it does**: Deterministic analysis — type scale ratios, WCAG contrast, spacing grid detection, color statistics.
-
-**What's working**:
-- **Type scale analysis**: Detects ratio between consecutive font sizes, identifies closest standard scale, measures consistency (variance). Correctly filters sizes < 10px. ✅
-- **WCAG contrast checking**: Correct `get_relative_luminance()` per WCAG 2.1 spec. Correct 4.5:1 threshold for AA normal text, 3.0:1 for large text. ✅
-- **AA fix suggestions**: `find_aa_compliant_color()` iterates darken/lighten in 1% steps until 4.5:1 is reached. Brute-force but correct. ✅
-- **Spacing grid detection**: GCD-based base detection, alignment % calculation. Correct. ✅
-- **Color statistics**: Near-duplicate detection, hue distribution, gray/saturated counts. Correct. ✅
-- **Consistency score**: Weighted formula combining all checks. Reasonable. ✅
-
-**What's broken/questionable**:
-
-#### Problem 3A: Accessibility Only Tests Against White/Black
-
-```python
-# Line 545-550
-contrast_white = get_contrast_ratio(hex_color, "#ffffff")
-contrast_black = get_contrast_ratio(hex_color, "#000000")
-passes_aa_normal = contrast_white >= 4.5 or contrast_black >= 4.5
-```
-
-This tests every color against pure white AND pure black. If it passes against EITHER, it's marked as passing. But:
-- A brand blue (#005aa3) that passes on white (7.2:1) might be used on a dark navy background (#1a1a2e) where it fails (1.8:1)
-- A light gray (#cccccc) passes on black but is used as text on white (#ffffff) where it fails (1.6:1)
-
-The `fg_bg_pairs` logic (line 577-610) partially addresses this — it checks actual foreground-background combinations from the DOM. **But**: it only adds FAILURES to the results, doesn't correct the per-color assessment above. So a color could show as "passes AA" in the per-color check but "fails AA" in the pair check. **Contradictory data sent to SENTINEL**.
-
-**Fix needed**: Two modes — (1) per-color against white/black for palette overview, (2) per-pair for actual accessibility score. SENTINEL should see BOTH clearly labeled.
-
-#### Problem 3B: No Radius Analysis
-
-The rule engine receives `radius_tokens` (line 1034) but does NOTHING with them. No grid alignment check, no progression validation, no statistics. It's just passed through.
-
-#### Problem 3C: Shadow Analysis Is Minimal
-
-The rule engine receives `shadow_tokens` but only passes them to SENTINEL's prompt as raw strings. No programmatic analysis of:
-- Blur progression (should increase with elevation)
-- Y-offset progression (should increase with elevation)
-- Color consistency (should all use same base color/alpha)
-- Whether shadows form a coherent elevation system
-
-This means SENTINEL gets raw shadow CSS strings and has to evaluate them purely from text — no pre-computed metrics to ground its scoring.
-
----
-
-### Component 4: Semantic Analyzer (`agents/semantic_analyzer.py`) — ⚠️ USEFUL BUT UNDERTRUSTED
-
-**What it does**: Rule-based categorization of colors by CSS property usage. If a color is used in `background-color` on buttons → it's likely brand primary. If used in `color` property on `<p>` → it's likely text color.
-
-**What's working**: The logic is sound — CSS property + element type is a strong signal for color role. This is actually one of the best parts of Stage 1.
-
-**What's broken**: AURORA receives this as `semantic_analysis` parameter but the data is passed as a secondary input, not the primary. AURORA's prompt says "Suggest Semantic Names for top 10 most-used colors" — it ignores the semantic analysis for the OTHER 20 colors. The semantic analyzer's work is wasted for most colors.
-
----
-
-### Component 5: Color Utils (`core/color_utils.py`) — ✅ VALID
-
-**What it does**: Hex/RGB/HSL parsing, contrast calculation, color categorization by hue, color ramp generation.
-
-**What's working**: All the pure color math is correct. `categorize_color()` returns the right hue family. `generate_color_ramp()` produces reasonable 50-900 shade ramps using OKLCH.
-
-**No issues found.** This is the most solid component.
-
----
-
-### Component 6: Export Layer (`app.py` export functions) — ❌ NEEDS RETHINK
-
-Already documented above in the AS-IS flow. The 3-way naming merge is the killer.
-
----
-
-## WHAT STAGE 1 SHOULD ACTUALLY PRODUCE (for Stage 2 to work)
-
-### Current: What Stage 2 receives
-```
-NormalizedTokens:
-  colors: {
-    "color.blue.light": ColorToken(value="#7fdbff", freq=5, contexts=["background"]),
-    "color.blue.dark": ColorToken(value="#2c3e50", freq=12, contexts=["text", "button"]),
-    "color.blue.base": ColorToken(value="#005aa3", freq=47, contexts=["button", "link"]),
-    "color.neutral.dark": ColorToken(value="#333333", freq=89, contexts=["text"]),
-    // ← word-based shades, no consistent convention
-  }
-  radius: {
-    "radius-8px": RadiusToken(value="8px"),
-    "radius-0px 0px 16px 16px": RadiusToken(value="0px 0px 16px 16px"),  // ← garbage
-    "radius-50%": RadiusToken(value="50%"),  // ← Figma can't use
-  }
-  shadows: {
-    "shadow-234": ShadowToken(value="0px 4px 25px rgba(0,0,0,0.1)"),  // ← meaningless key
-    "shadow-891": ShadowToken(value="0px 2px 30px rgba(0,0,0,0.15)"),  // ← unsorted
-  }
-```
-
-### Target: What Stage 2 SHOULD receive
-```
-NormalizedTokens:
-  colors: {
-    "color.blue.300": ColorToken(value="#7fdbff", freq=5, contexts=["background"],
-                                  role="palette", hue="blue", shade=300),
-    "color.blue.800": ColorToken(value="#2c3e50", freq=12, contexts=["text", "button"],
-                                  role="palette", hue="blue", shade=800),
-    "color.blue.500": ColorToken(value="#005aa3", freq=47, contexts=["button", "link"],
-                                  role="brand_candidate", hue="blue", shade=500),
-    "color.neutral.700": ColorToken(value="#333333", freq=89, contexts=["text"],
-                                    role="text_candidate", hue="neutral", shade=700),
-    // ← ALL numeric shades, with role hints for AURORA
-  }
-  radius: {
-    "radius.sm": RadiusToken(value="4px", value_px=4),
-    "radius.md": RadiusToken(value="8px", value_px=8),
-    "radius.xl": RadiusToken(value="16px", value_px=16),
-    "radius.full": RadiusToken(value="9999px", value_px=9999),
-    // ← flat, single-value, deduped, sorted, named
-  }
-  shadows: {
-    "shadow.xs": ShadowToken(value="...", blur_px=4, y_offset_px=2),
-    "shadow.sm": ShadowToken(value="...", blur_px=8, y_offset_px=4),
-    "shadow.md": ShadowToken(value="...", blur_px=16, y_offset_px=8),
-    // ← sorted by elevation, named progressively
-  }
-```
-
-### What changes are needed in Stage 1:
-
-| Component | Current State | What's Wrong | Fix |
-|-----------|--------------|-------------|-----|
-| **Normalizer: color naming** | Two functions, word vs numeric | Mixed conventions | Remove word-based function, use numeric for ALL |
-| **Normalizer: color role hints** | Keyword-based inference (5-40% hit rate) | Most colors get no role | Add `role_hint` field: "brand_candidate", "text_candidate", "bg_candidate" based on CSS property (from semantic analyzer) |
-| **Normalizer: radius** | Raw values stored, no processing | Multi-value, %, no dedup | Parse → single px value → deduplicate → sort → name (none/sm/md/lg/xl/full) |
-| **Normalizer: shadows** | Hash-based keys, no processing | Unsorted, unnamed, no metrics | Parse components → sort by blur → deduplicate → name (xs/sm/md/lg/xl) |
-| **Normalizer: typography** | Collision-prone naming | Same name for different styles | Add weight suffix: `font.heading.lg.700` vs `font.heading.lg.400` |
-| **Rule engine: accessibility** | Tests against white/black only | Doesn't match real usage | Add separate per-pair analysis, label both modes clearly |
-| **Rule engine: radius** | Not analyzed | No grid check, no stats | Add radius grid analysis (base-4/base-8), dedup stats |
-| **Rule engine: shadows** | Not analyzed | No progression check | Add shadow elevation analysis (blur/offset progression) |
-| **Extractor: font family** | Returns fallback generic | Browser resolves to "sans-serif" | Extract from CSS declaration before computed resolution |
-
----
-
-## EXECUTION STATUS (Updated Feb 2026)
-
-### Phases 1-3: COMPLETED
-
-```
-PHASE 1: FIX NORMALIZER ✅ DONE
-  1a. ✅ Unify color naming → numeric shades only (_generate_preliminary_name)
-  1b. ✅ Add radius normalization (parse, deduplicate, sort, name) — normalizer.py:626-778
-  1c. ✅ Add shadow normalization (parse, sort by blur, name) — normalizer.py:784-940
-  1d. ✅ Feed role hints into normalizer — normalizer._infer_role_hint()
-
-PHASE 2: FIX STAGE 2 ✅ DONE
-  2a. ✅ Consolidated — llm_agents.py is primary, stage2_graph.py deprecated
-  2b. ✅ AURORA with ReAct + critic + retry — llm_agents.py:420-470
-  2c. ✅ SENTINEL with grounded scoring + cross-reference critic
-  2d. ✅ NEXUS with ToT (two-perspective evaluation)
-  2e. ✅ Post-validation layer — post_validate_stage2()
-
-PHASE 3: FIX EXPORT ✅ DONE (v3.2)
-  3a. ✅ Color classifier = PRIMARY authority, AURORA = semantic roles only
-  3b. ✅ Radius/shadow export uses normalizer output directly
-  3c. ✅ W3C DTCG v1 compliance with $extensions metadata
-  3d. ✅ filter_aurora_naming_map() enforces role-only boundary
-
-PHASE 4: EXTRACTION IMPROVEMENTS (NOT STARTED)
-  4a. ❌ Font family detection — still returns "sans-serif" fallback
-  4b. ❌ Rule engine: radius grid analysis
-  4c. ❌ Rule engine: shadow elevation analysis
-```
-
-### PHASE 5: COMPONENT GENERATION (NEXT — RESEARCH COMPLETE)
-
-**Full context**: See `PART2_COMPONENT_GENERATION.md` for detailed research, API checks, and architecture.
-
-**Research finding (Feb 2026)**: 30+ tools evaluated. No production tool takes DTCG JSON -> Figma Components. This is a genuine market gap.
-
-**Decision**: Custom Figma Plugin (Option A) — extend existing `code.js` with component generation.
-
-```
-PHASE 5: FIGMA COMPONENT GENERATION
-  5a. Component Definition Schema (JSON defining anatomy + token bindings + variants)
-  5b. Token-to-Component binding engine (resolveTokenValue, bindTokenToVariable)
-  5c. Variable Collection builder (primitives, semantic, spacing, radius, shadow, typography)
-  5d. MVP Components:
-      - Button: 4 variants x 3 sizes x 5 states = 60 variants (2-3 days)
-      - TextInput: 4 states x 2 sizes = 8 variants (1-2 days)
-      - Card: 2 configurations (1 day)
-      - Toast: 4 types success/error/warn/info (1 day)
-      - Checkbox+Radio: ~12 variants (1-2 days)
-  5e. Post-MVP: Toggle (4), Select (multi-state), Modal (3 sizes), Table (template)
-
-  Estimated: ~1400 lines new plugin code, 8-12 days total
-```
-
-**Figma Plugin API confirmed**: createComponent(), combineAsVariants(), setBoundVariable(),
-setBoundVariableForPaint(), addComponentProperty(), setReactionsAsync() — ALL supported.
-
-```
-PHASE 6: ECOSYSTEM INTEGRATION
-  6a. Style Dictionary v4 compatible output (50+ platform formats for free)
-  6b. Tokens Studio compatible JSON import
-  6c. Dembrandt JSON as alternative input source
-  6d. CI/CD GitHub Action for design system regression checks
-
-PHASE 7: MCP INTEGRATION
-  7a. Expose extractor as MCP tool server
-  7b. Claude Desktop: "Extract design system from example.com"
-  7c. Community Figma MCP bridge for push-to-Figma
-```
-
-### Strategic Positioning
-
-**"Lighthouse for Design Systems"** — We are NOT a token management platform (Tokens Studio), NOT a documentation platform (Zeroheight), NOT an extraction tool (Dembrandt). We are the **automated audit + bootstrap tool** that sits upstream of all of those.
-
-**With Phase 5**: We become the ONLY tool that goes from URL -> complete Figma design system WITH components. Fully automated. Nobody else does this end-to-end.
-
-**Unique differentiators no competitor has:**
-- Type scale ratio detection + standard scale matching
-- Spacing grid detection (GCD-based, base-8 alignment scoring)
-- LLM brand identification from CSS usage patterns
-- Holistic design system quality score (0-100)
-- Visual spec page auto-generated in Figma
-- Benchmark comparison against established design systems
-- (Phase 5) Automated component generation from extracted tokens
-
-**Key competitors to watch:**
-- Dembrandt (1,300 stars) — does extraction better, but no analysis, no components
-- Tokens Studio (1M+ installs) — manages tokens, no extraction, no component generation
-- Knapsack ($10M funding) — building ingestion engine, biggest strategic threat
-- Figr Identity — generates components but from brand config, not extracted tokens
-- html.to.design — captures layouts but not tokens/variables/components
-- story.to.design — Storybook->Figma components, but needs full code pipeline
-
----
-
-## CRITIC REVIEW: SHOULD EACH COMPONENT STAY RULE-BASED OR USE LLM?
-
-Every rule-based component needs to justify itself. Rules are free and fast, but if they produce garbage that LLMs then have to fix, the "free" part is an illusion — you pay in bad output quality instead.
-
-### Decision Framework
-
-| Use Rules When... | Use LLM When... |
-|---|---|
-| Math with right answers (contrast ratio) | Judgment with context (is this the brand color?) |
-| Deterministic transforms (hex→RGB) | Ambiguous signals (is this a button or just a styled div?) |
-| Simple pattern matching (is 16 divisible by 8?) | Weighing competing evidence (high freq but wrong context) |
-| Zero tolerance for hallucination (export format) | Understanding intent (why is this color used here?) |
-| Must be 100% reproducible | Acceptable to vary slightly between runs |
-
----
-
-### 1. Color Naming (Normalizer) — ❌ RULES FAILING, NEEDS RETHINK
-
-**Current**: Rule-based. Two functions: keyword-match for role → numeric shade, fallback → word shade.
-
-**Critic's Question**: Can rules correctly name 30 colors with just CSS property + element context?
-
-**Honest Answer**: No. Here's why:
-
-The normalizer's `_infer_color_role()` searches for keywords like "primary", "button", "background" in the element/context strings. But:
-
-```
-Extracted color: #005aa3, freq=47
-  css_properties: ["background-color"]
-  elements: ["div", "a"]
-  contexts: ["background"]
-```
-
-No keyword "primary" or "button" anywhere. Rules classify this as "unknown role" → falls to word-based naming → `color.blue.base`. But this is CLEARLY the brand primary (used 47 times on links and divs with background-color).
-
-An LLM can reason: "47 uses on `<a>` elements with `background-color` = this is a CTA color = brand primary." Rules can't make that inference.
-
-**But**: An LLM to name 30 colors costs ~$0.001 and adds 2-3 seconds. For something that happens once per extraction, this is acceptable.
-
-**Verdict**:
-- **Keep rules for**: Hue family detection (HSL math), shade number assignment (luminance → 50-900), deduplication (exact hex + RGB distance)
-- **Move to LLM (AURORA)**: Semantic role assignment (brand.primary vs text.secondary vs background.primary). This is already AURORA's job — but currently AURORA only does it for 10 colors. Expand AURORA to name ALL colors.
-- **ELIMINATE from normalizer**: The `_generate_color_name_from_value()` function and the `_infer_color_role()` function. Replace with a simpler `_generate_preliminary_name()` that just uses hue + numeric shade. Let AURORA do the semantic naming.
-
-**New flow**:
-```
-Normalizer: "color.blue.500" (hue + shade, no role)
-     ↓
-AURORA: "color.brand.primary" (semantic role from context reasoning)
-     ↓
-Export: Uses AURORA name, falls back to normalizer name
-```
-
----
-
-### 2. Radius Processing — ✅ RULES ARE CORRECT APPROACH, JUST MISSING
-
-**Current**: No processing at all (raw values stored).
-
-**Critic's Question**: Does radius naming need LLM intelligence?
-
-**Honest Answer**: No. Radius is pure math:
-- Parse CSS value → px number
-- Skip multi-value shorthand (or take max)
-- Convert 50% → 9999px (full circle)
-- Sort by px value
-- Name by size tier: 0=none, 1-3=sm, 4-8=md, 9-16=lg, 17-24=xl, 25+=2xl, 9999=full
-
-No ambiguity, no judgment needed. An LLM would add nothing here.
-
-**Verdict**: Keep rule-based. Just implement the processing that's currently missing.
-
----
-
-### 3. Shadow Processing — ⚠️ MOSTLY RULES, BUT LLM COULD HELP WITH EDGE CASES
-
-**Current**: No processing at all (hash-based keys).
-
-**Critic's Question**: Can rules correctly name and sort shadows?
-
-**Mostly yes**:
-- Parse CSS shadow string → {x, y, blur, spread, color} — regex, no LLM needed
-- Sort by blur radius — math
-- Name by elevation tier (xs/sm/md/lg/xl) — math
-- Detect non-monotonic progression — math
-
-**But**: Some edge cases are hard for rules:
-- `0px 0px 0px 4px rgba(0,0,0,0.2)` — is this a shadow or a border simulation? (spread-only, no blur)
-- Multiple shadows on same element — which is the "primary" shadow?
-- `inset` shadows — different semantic meaning (inner glow vs elevation)
-
-These edge cases affect maybe 10% of shadows. Rules can handle 90% correctly.
-
-**Verdict**: Keep rule-based for parsing, sorting, naming. Add simple heuristic rules for edge cases (spread-only → treat as border, inset → separate category). NOT worth an LLM call.
-
----
-
-### 4. Accessibility Checking (Rule Engine) — ✅ RULES ARE THE ONLY CORRECT APPROACH
-
-**Current**: WCAG contrast math + fix suggestions.
-
-**Critic's Question**: Could an LLM improve accessibility checking?
-
-**Absolutely not.** WCAG is a mathematical standard. 4.5:1 is 4.5:1. An LLM cannot calculate contrast ratios — it would hallucinate them. The rule engine's `get_relative_luminance()` implementation follows the exact WCAG 2.1 spec. This MUST stay rule-based.
-
-**What rules CAN'T do** (and LLM CAN): Prioritize which failures matter most. "Brand primary fails AA" is more critical than "a decorative border color fails AA." This is judgment → belongs in SENTINEL.
-
-**Verdict**: Keep accessibility math 100% rule-based. Use SENTINEL to prioritize/contextualize the results.
-
----
-
-### 5. Type Scale Detection (Rule Engine) — ✅ RULES ARE CORRECT
-
-**Current**: Ratio calculation between consecutive font sizes, variance check, standard scale matching.
-
-**Critic's Question**: Could an LLM detect type scales better?
-
-**No.** Type scale detection is pure math: sizes → ratios → average → closest standard. An LLM would be slower and less accurate at arithmetic.
-
-**What rules CAN'T do**: Recommend which scale to adopt. "Your ratio is 1.18, should you round to 1.2 (Minor Third) or 1.25 (Major Third)?" — this depends on the site's purpose (content-heavy = 1.2, marketing = 1.333). This is judgment → belongs in ATLAS/NEXUS.
-
-**Verdict**: Keep rule-based. Already working correctly after the 10px filter fix.
-
----
-
-### 6. Spacing Grid Detection (Rule Engine) — ✅ RULES ARE CORRECT
-
-**Current**: GCD-based detection, alignment percentage, base-4/base-8 check.
-
-**Verdict**: Pure math, working correctly. Keep rule-based.
-
----
-
-### 7. Semantic Color Analysis (`semantic_analyzer.py`) — ⚠️ OVERLAPS WITH AURORA, CONSOLIDATE
-
-**Current**: Rule-based fallback + optional LLM call. Categorizes colors into brand/text/background/border/feedback.
-
-**Critic's Question**: This does THE SAME JOB as AURORA. Why do we have both?
-
-**The overlap**:
-- Semantic Analyzer: "This color is brand.primary because it's on buttons" (rule-based + optional LLM)
-- AURORA: "This color is brand.primary because it's used 47x on CTAs" (LLM)
-- Both produce semantic names for colors
-- Both feed into export
-
-**The problem**: They run at DIFFERENT STAGES:
-- Semantic Analyzer runs in Stage 1 (during extraction)
-- AURORA runs in Stage 2 (during analysis)
-- Their outputs can conflict
-- Export tries to merge both → more naming chaos
-
-**Verdict**: ELIMINATE the semantic analyzer as a separate component. Move its rule-based heuristics INTO the normalizer as `role_hint` field (e.g., "brand_candidate", "text_candidate"). These hints become INPUT to AURORA, not a competing output.
-
-```
-BEFORE:
-  Semantic Analyzer → state.semantic_analysis → AURORA (partially uses it)
-                                              → Export (also uses it, conflicts)
-
-AFTER:
-  Normalizer adds role_hints → AURORA uses hints as evidence → AURORA names → Export
-  (no separate semantic analyzer)
-```
-
----
-
-### 8. Color Deduplication (Normalizer) — ⚠️ RULES ARE CORRECT BUT THRESHOLD IS QUESTIONABLE
-
-**Current**: RGB Euclidean distance < 10 → merge.
-
-**Critic's Question**: Is RGB distance the right metric?
-
-**Not really.** RGB Euclidean distance is NOT perceptually uniform. Two colors that look identical to humans can have large RGB distance, and two that look different can have small RGB distance. The industry standard for perceptual color difference is Delta-E (CIE2000).
-
-However: For the purpose of "should we keep both #1a1a1a and #1b1b1b in the design system?" — RGB distance < 10 is a reasonable approximation. These truly are near-identical grays.
-
-The color_utils.py `color_distance()` function also uses RGB Euclidean. It's used in the rule engine for near-duplicate detection.
-
-**Verdict**: Keep rule-based, but consider switching to Delta-E (CIEDE2000) for better perceptual accuracy. Low priority — the current approach works for most cases.
-
----
-
-### 9. Color Statistics (Rule Engine) — ✅ RULES ARE CORRECT
-
-Counting uniques, duplicates, hue distribution — pure counting. Keep rule-based.
-
----
-
-### 10. Pre-Processing Layer (NEW — proposed in architecture) — SHOULD THIS BE AN LLM?
-
-**Current plan**: Deterministic pre-processing before Stage 2 agents.
-
-**Critic's Question**: The pre-processing unifies names, flattens radius, sorts shadows. Should this use an LLM?
-
-**No.** Everything pre-processing does is deterministic:
-- Rename color.blue.light → color.blue.300 (luminance lookup table)
-- Flatten "0px 0px 16px 16px" → skip or max(16)
-- Sort shadows by blur px
-
-No judgment needed, no ambiguity. Keep deterministic.
-
----
-
-## SUMMARY: WHAT STAYS RULE-BASED, WHAT MOVES TO LLM
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  KEEP RULE-BASED (correct, no LLM needed)                       │
-│                                                                  │
-│  ✅ WCAG contrast calculation                                    │
-│  ✅ Type scale ratio detection                                   │
-│  ✅ Spacing grid detection (GCD)                                 │
-│  ✅ Color deduplication (RGB/Delta-E distance)                   │
-│  ✅ Color statistics (counts, hue distribution)                  │
-│  ✅ Radius processing (parse, sort, name) — needs implementing   │
-│  ✅ Shadow processing (parse, sort, name) — needs implementing   │
-│  ✅ Color hue family detection (HSL math)                        │
-│  ✅ Color shade number assignment (luminance → 50-900)           │
-│  ✅ Pre-processing layer (rename, flatten, sort)                 │
-│  ✅ Post-validation layer (check conventions, ranges)            │
-│  ✅ AA fix suggestions (darken/lighten iteration)                │
-│  ✅ Export format (DTCG structure)                                │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│  MOVE TO LLM (requires judgment, context, ambiguity)            │
-│                                                                  │
-│  🤖 Color semantic naming (brand.primary vs text.secondary)     │
-│     Currently: normalizer (bad) + semantic analyzer (conflicts)  │
-│     Move to: AURORA (ReAct, names ALL colors)                    │
-│                                                                  │
-│  🤖 Prioritizing which AA failures matter most                  │
-│     Currently: all treated equally                               │
-│     Move to: SENTINEL (cites data, ranks by impact)              │
-│                                                                  │
-│  🤖 Scoring cohesion/consistency holistically                    │
-│     Currently: simple weighted formula                           │
-│     Move to: NEXUS (weighs competing dimensions)                 │
-│                                                                  │
-│  🤖 Recommending which design system to align with              │
-│     Currently: ATLAS (already LLM) — keep as is                  │
-│                                                                  │
-│  🤖 Recommending scale/spacing changes                           │
-│     Currently: defaults to "1.25 Major Third"                    │
-│     Move to: NEXUS (considers site purpose and brand)            │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│  ELIMINATE (redundant or actively harmful)                       │
-│                                                                  │
-│  ❌ normalizer._generate_color_name_from_value()                │
-│     Word-based shades (light/dark/base) — root cause of chaos   │
-│                                                                  │
-│  ❌ normalizer._infer_color_role()                              │
-│     Keyword matching for role — too low hit rate (5-40%)        │
-│     Replace with: role_hint from CSS property + element type    │
-│                                                                  │
-│  ❌ semantic_analyzer.py as separate component                   │
-│     Overlaps with AURORA, creates competing names               │
-│     Replace with: role_hints embedded in normalizer output      │
-│                                                                  │
-│  ❌ app.py _generate_color_name_from_hex()                      │
-│     Third naming system (numeric), conflicts with other two     │
-│     Replace with: normalizer's single naming path               │
-│                                                                  │
-│  ❌ app.py _get_semantic_color_overrides() 3-way merge          │
-│     Merges semantic + AURORA + NEXUS names → chaos              │
-│     Replace with: AURORA naming_map as single authority         │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### New LLM Budget After Critic Review
-
-No new LLM calls needed. We're just:
-1. Expanding AURORA from "name 10 colors" to "name ALL colors" (same 1 call, slightly larger output)
-2. Eliminating the semantic analyzer's optional LLM call (saves $0.001)
-3. All other changes are rule-based fixes
-
-Net LLM cost: Same or slightly less than today (~$0.005 per extraction).

PART2_COMPONENT_GENERATION.md

@@ -1,418 +0,0 @@
-# Design System Extractor — Part 2: Component Generation
-
-## Session Context
-
-**Prerequisite**: Part 1 (Token Extraction + Analysis) is COMPLETE at v3.2
-- Phases 1-3 DONE: Normalizer, Stage 2 agents, Export all working
-- 113 tests passing, W3C DTCG v1 compliant output
-- GitHub: https://github.com/hiriazmo/design-system-extractor-v3
-- Project: `/Users/yahya/design-system-extractor-v3/`
-
-**This session**: Build automated component generation from extracted tokens into Figma.
-
----
-
-## THE GAP: Nobody Does This
-
-Exhaustive research of 30+ tools (Feb 2026) confirms:
-
-**No production tool takes DTCG JSON and outputs Figma Components.**
-
-```
-YOUR EXTRACTOR                    THE GAP                     FIGMA
-+--------------+    +----------------------------+    +------------------+
-| DTCG JSON    |--->|  ??? Nothing does this     |--->| Button component |
-| with tokens  |    |  tokens -> components      |    | with 60 variants |
-+--------------+    +----------------------------+    +------------------+
-```
-
-### What Exists (and What It Can't Do)
-
-| Category | Best Tool | What It Does | Creates Components? |
-|----------|-----------|-------------|-------------------|
-| Token Importers | Tokens Studio (1M+ installs) | JSON -> Figma Variables | NO - variables only |
-| AI Design | Figma Make | Prompt -> prototype | NO - not token-driven |
-| MCP Bridges | Figma Console MCP (543 stars) | AI writes to Figma | YES but non-deterministic |
-| Code-to-Figma | story.to.design | Storybook -> Figma components | YES but needs full Storybook |
-| Generators | Figr Identity | Brand config -> components | YES but can't consume YOUR tokens |
-| Commercial | Knapsack ($10M), Supernova | Token management | NO - manages, doesn't create |
-| DEAD | Specify.app (shutting down), Backlight.dev (shut down June 2025) | - | - |
-
-### Key Findings Per Category
-
-**Token Importers** (7+ tools evaluated): Tokens Studio, TokensBrucke, Styleframe, DTCG Token Manager, GitFig, Supa Design Tokens, Design System Automator — ALL create Figma Variables from JSON, NONE create components.
-
-**MCP Bridges** (5 tools): Figma Console MCP (Southleft), claude-talk-to-figma-mcp, cursor-talk-to-figma-mcp (Grab), figma-mcp-write-server, Figma-MCP-Write-Bridge — ALL have full write access, but component creation is AI-interpreted (non-deterministic, varies per run).
-
-**Code-to-Figma**: story.to.design is the standout — creates REAL Figma components with proper variants from Storybook. But requires a full coded component library + running Storybook instance as intermediary.
-
-**figma-json2component** (GitHub): Experimental proof-of-concept that generates components from custom JSON schema. Not DTCG, not production quality, but validates the concept IS possible.
-
----
-
-## FOUR APPROACHES — RANKED
-
-### Option A: Custom Figma Plugin (RECOMMENDED)
-```
-DTCG JSON -> Your Plugin reads JSON -> Creates Variables -> Generates Components -> Done
-```
-- **Effort**: 4-8 weeks (~1400 lines of plugin code for 5 MVP components)
-- **Quality**: Highest — fully deterministic, consistent every run
-- **Advantage**: We already have a working plugin (code.js) that imports tokens
-- **Risk**: Low — Figma Plugin API supports everything needed
-
-### Option B: Pipeline — shadcn + Storybook + story.to.design
-```
-DTCG JSON -> Style Dictionary -> CSS vars -> shadcn themed -> Storybook -> story.to.design -> Figma
-```
-- **Effort**: 2-3 days setup, then 15-30 min per extraction
-- **Quality**: High — battle-tested shadcn components
-- **Dependency**: story.to.design (commercial, paid)
-- **Risk**: Medium — many moving parts
-
-### Option C: MCP + Claude AI Chain
-```
-DTCG JSON -> Claude reads tokens -> Figma Console MCP -> AI creates components -> Figma
-```
-- **Effort**: 2-3 weeks
-- **Quality**: Medium — non-deterministic
-- **Risk**: High — AI output varies per run
-
-### Option D: Figr Identity + Manual Token Swap
-```
-Figr Identity generates base system -> Manually swap tokens -> Adjust
-```
-- **Effort**: 1-2 days
-- **Quality**: Medium — not YOUR tokens
-- **Risk**: Medium — manual alignment needed
-
-**Decision: Option A (Custom Plugin)** — we already have 80% of the infrastructure, it's deterministic, no external dependencies, and fills a genuine market gap.
-
----
-
-## FIGMA PLUGIN API: FULL CAPABILITY CHECK
-
-Every feature needed for component generation is supported:
-
-| Requirement | API Method | Status |
-|------------|-----------|--------|
-| Create components | `figma.createComponent()` | Supported |
-| Variant sets (60 variants) | `figma.combineAsVariants()` | Supported |
-| Auto-layout with padding | `layoutMode`, `paddingTop/Right/Bottom/Left`, `itemSpacing` | Supported |
-| Text labels | `figma.createText()` + `loadFontAsync()` | Supported |
-| Icon slot (optional) | `addComponentProperty("ShowIcon", "BOOLEAN", true)` | Supported |
-| Instance swap (icons) | `addComponentProperty("Icon", "INSTANCE_SWAP", id)` | Supported |
-| Border radius from tokens | `setBoundVariable('topLeftRadius', radiusVar)` | Supported |
-| Colors from tokens | `setBoundVariableForPaint()` -> binds to variables | Supported |
-| Shadows from tokens | `setBoundVariableForEffect()` | Supported (has spread bug, workaround exists) |
-| Hover/press interactions | `node.setReactionsAsync()` with `ON_HOVER`/`ON_PRESS` | Supported |
-| Expose text property | `addComponentProperty("Label", "TEXT", "Button")` | Supported |
-| Disabled opacity | `node.opacity = 0.5` | Supported |
-
----
-
-## MVP SCOPE: 5 Components, 62 Variants
-
-| Component | Variants | Automatable? | Effort |
-|-----------|---------|-------------|--------|
-| **Button** | 4 variants x 3 sizes x 5 states = 60 | Fully | 2-3 days |
-| **Text Input** | 4 states x 2 sizes = 8 | Fully | 1-2 days |
-| **Card** | 2 configurations | Semi | 1 day |
-| **Toast/Notification** | 4 types (success/error/warn/info) | Fully | 1 day |
-| **Checkbox + Radio** | ~12 variants | Fully | 1-2 days |
-| **Total** | **~86 variants** | | **8-12 days** |
-
-### Post-MVP Components
-
-| Component | Variants | Automatable? | Effort |
-|-----------|---------|-------------|--------|
-| Toggle/Switch | on/off x enabled/disabled = 4 | Fully | 0.5 day |
-| Select/Dropdown | Multiple states | Semi | 1-2 days |
-| Modal/Dialog | 3 sizes | Semi | 1 day |
-| Table | Header + data rows | Template-based | 2 days |
-
----
-
-## TOKEN-TO-COMPONENT MAPPING
-
-How extracted tokens bind to component properties:
-
-### Button Example
-```
-Token                    -> Figma Property
--------------------------------------------------
-color.brand.primary      -> Fill (default state)
-color.brand.600          -> Fill (hover state)
-color.brand.700          -> Fill (pressed state)
-color.text.inverse       -> Text color
-color.neutral.200        -> Fill (secondary variant)
-color.neutral.300        -> Fill (secondary hover)
-radius.md                -> Corner radius (all corners)
-shadow.sm                -> Drop shadow (elevated variant)
-spacing.3                -> Padding horizontal (16px)
-spacing.2                -> Padding vertical (8px)
-font.body.md             -> Text style (label)
-```
-
-### Variable Collections Needed
-```
-1. Primitives     -> Raw color palette (blue.50 through blue.900, etc.)
-2. Semantic       -> Role-based aliases (brand.primary -> blue.500)
-3. Spacing        -> 4px grid (spacing.1=4, spacing.2=8, spacing.3=12...)
-4. Radius         -> none/sm/md/lg/xl/full
-5. Shadow         -> xs/sm/md/lg/xl elevation levels
-6. Typography     -> Font families, sizes, weights, line-heights
-```
-
----
-
-## COMPONENT DEFINITION SCHEMA (Proposed)
-
-Each component needs a JSON definition describing its anatomy, token bindings, and variant matrix:
-
-```json
-{
-  "component": "Button",
-  "anatomy": {
-    "root": {
-      "type": "frame",
-      "layout": "horizontal",
-      "padding": { "h": "spacing.3", "v": "spacing.2" },
-      "radius": "radius.md",
-      "fill": "color.brand.primary",
-      "gap": "spacing.2"
-    },
-    "icon_slot": {
-      "type": "instance_swap",
-      "size": 16,
-      "visible": false,
-      "property": "ShowIcon"
-    },
-    "label": {
-      "type": "text",
-      "style": "font.body.md",
-      "color": "color.text.inverse",
-      "content": "Button",
-      "property": "Label"
-    }
-  },
-  "variants": {
-    "Variant": ["Primary", "Secondary", "Outline", "Ghost"],
-    "Size": ["Small", "Medium", "Large"],
-    "State": ["Default", "Hover", "Pressed", "Focused", "Disabled"]
-  },
-  "variant_overrides": {
-    "Variant=Secondary": {
-      "root.fill": "color.neutral.200",
-      "label.color": "color.text.primary"
-    },
-    "Variant=Outline": {
-      "root.fill": "transparent",
-      "root.stroke": "color.border.primary",
-      "root.strokeWeight": 1,
-      "label.color": "color.brand.primary"
-    },
-    "Variant=Ghost": {
-      "root.fill": "transparent",
-      "label.color": "color.brand.primary"
-    },
-    "State=Hover": {
-      "root.fill": "color.brand.600"
-    },
-    "State=Pressed": {
-      "root.fill": "color.brand.700"
-    },
-    "State=Disabled": {
-      "root.opacity": 0.5
-    },
-    "Size=Small": {
-      "root.padding.h": "spacing.2",
-      "root.padding.v": "spacing.1",
-      "label.style": "font.body.sm"
-    },
-    "Size=Large": {
-      "root.padding.h": "spacing.4",
-      "root.padding.v": "spacing.3",
-      "label.style": "font.body.lg"
-    }
-  }
-}
-```
-
-### Component Generation Pattern (Plugin Code)
-
-Every component follows the same pipeline:
-```
-1. Read tokens from DTCG JSON
-2. Create Variable Collections (if not exist)
-3. For each variant combination:
-   a. Create frame with auto-layout
-   b. Add child nodes (icon slot, label, etc.)
-   c. Apply token bindings via setBoundVariable()
-   d. Apply variant-specific overrides
-4. combineAsVariants() -> component set
-5. Add component properties (Label text, ShowIcon boolean)
-```
-
----
-
-## ARCHITECTURE FOR PLUGIN EXTENSION
-
-Current plugin (`code.js`) already does:
-- Parse DTCG JSON (isDTCGFormat detection)
-- Create paint styles from colors
-- Create text styles from typography
-- Create effect styles from shadows
-- Create variable collections
-
-What needs to be ADDED:
-```
-code.js (existing ~1200 lines)
-  |
-  +-- componentGenerator.js (NEW ~1400 lines)
-  |     |-- generateButton()      ~250 lines
-  |     |-- generateTextInput()   ~200 lines
-  |     |-- generateCard()        ~150 lines
-  |     |-- generateToast()       ~150 lines
-  |     |-- generateCheckbox()    ~200 lines
-  |     |-- generateRadio()       ~150 lines
-  |     +-- shared utilities      ~300 lines
-  |          |-- createAutoLayoutFrame()
-  |          |-- bindTokenToVariable()
-  |          |-- buildVariantMatrix()
-  |          |-- resolveTokenValue()
-  |
-  +-- componentDefinitions.json (NEW ~500 lines)
-        |-- Button definition
-        |-- TextInput definition
-        |-- Card definition
-        |-- Toast definition
-        +-- Checkbox/Radio definition
-```
-
-### Implementation Order
-```
-Week 1-2: Infrastructure
-  - Variable collection builder (primitives, semantic, spacing, radius, shadow)
-  - Token resolver (DTCG path -> Figma variable reference)
-  - Auto-layout frame builder with token bindings
-  - Variant matrix generator
-
-Week 3-4: MVP Components
-  - Button (60 variants) — most complex, validates the full pipeline
-  - TextInput (8 variants) — validates form patterns
-  - Toast (4 variants) — validates feedback patterns
-
-Week 5-6: Remaining MVP + Polish
-  - Card (2 configs) — validates layout composition
-  - Checkbox + Radio (12 variants) — validates toggle patterns
-  - Error handling, edge cases, testing
-
-Week 7-8: Post-MVP (if time)
-  - Toggle/Switch, Select, Modal
-  - Documentation
-```
-
----
-
-## EXISTING FILES TO KNOW ABOUT
-
-| File | Purpose | Lines |
-|------|---------|-------|
-| `app.py` | Main Gradio app, token extraction orchestration | ~5000 |
-| `agents/llm_agents.py` | AURORA, ATLAS, SENTINEL, NEXUS LLM agents | ~1200 |
-| `agents/normalizer.py` | Token normalization (colors, radius, shadows) | ~950 |
-| `core/color_classifier.py` | Rule-based color classification (PRIMARY authority) | ~815 |
-| `core/color_utils.py` | Color math (hex/RGB/HSL, contrast, ramps) | ~400 |
-| `core/rule_engine.py` | Type scale, WCAG, spacing grid analysis | ~1100 |
-| `output_json/figma-plugin-extracted/figma-design-token-creator 5/src/code.js` | **Figma plugin — EXTEND THIS** | ~1200 |
-| `output_json/figma-plugin-extracted/figma-design-token-creator 5/src/ui.html` | Plugin UI | ~500 |
-
-### DTCG Output Format (What the Plugin Receives)
-
-```json
-{
-  "color": {
-    "brand": {
-      "primary": {
-        "$type": "color",
-        "$value": "#005aa3",
-        "$description": "[classifier] brand: primary_action",
-        "$extensions": {
-          "com.design-system-extractor": {
-            "frequency": 47,
-            "confidence": "high",
-            "category": "brand",
-            "evidence": ["background-color on <a>", "background-color on <button>"]
-          }
-        }
-      }
-    }
-  },
-  "radius": {
-    "md": { "$type": "dimension", "$value": "8px" },
-    "lg": { "$type": "dimension", "$value": "16px" },
-    "full": { "$type": "dimension", "$value": "9999px" }
-  },
-  "shadow": {
-    "sm": {
-      "$type": "shadow",
-      "$value": {
-        "offsetX": "0px",
-        "offsetY": "2px",
-        "blur": "8px",
-        "spread": "0px",
-        "color": "#00000026"
-      }
-    }
-  },
-  "typography": {
-    "body": {
-      "md": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "Inter",
-          "fontSize": "16px",
-          "fontWeight": 400,
-          "lineHeight": 1.5,
-          "letterSpacing": "0px"
-        }
-      }
-    }
-  },
-  "spacing": {
-    "1": { "$type": "dimension", "$value": "4px" },
-    "2": { "$type": "dimension", "$value": "8px" },
-    "3": { "$type": "dimension", "$value": "16px" }
-  }
-}
-```
-
----
-
-## COMPETITIVE ADVANTAGE
-
-Building this fills a genuine market gap:
-- **Tokens Studio** (1M+ installs) = token management, no component generation
-- **Figr Identity** = generates components but from brand config, not YOUR tokens
-- **story.to.design** = needs full Storybook pipeline as intermediary
-- **MCP bridges** = non-deterministic AI interpretation
-- **Us** = DTCG JSON in, deterministic Figma components out. Nobody else does this.
-
-### Strategic Position
-```
-[Extract from website] -> [Analyze & Score] -> [Generate Components in Figma]
-     Part 1 (DONE)          Part 1 (DONE)          Part 2 (THIS)
-```
-
-We become the only tool that goes from URL to complete Figma design system with components — fully automated.
-
----
-
-## OPEN QUESTIONS FOR THIS SESSION
-
-1. Should component definitions live in JSON (data-driven) or be hardcoded in JS (simpler)?
-2. Should we generate all 60 Button variants at once, or let user pick which variants?
-3. How to handle missing tokens? (e.g., site has no shadow tokens — skip shadow on buttons or use defaults?)
-4. Should we support dark mode variants from the start, or add later?
-5. Icon system — use a bundled icon set (Lucide?) or just placeholder frames?

PLAN_W3C_DTCG_UPDATE.md

@@ -1,318 +0,0 @@
-# PLAN: Update to W3C DTCG Design Token Format
-
-## Overview
-
-Update both the **Design System Extractor export** and the **Figma plugin** to use the official **W3C DTCG (Design Tokens Community Group)** format - the industry standard as of October 2025.
-
----
-
-## Current vs Target Format
-
-### CURRENT (Custom/Legacy)
-```json
-{
-  "global": {
-    "colors": {
-      "color.brand.primary": {
-        "value": "#540b79",
-        "type": "color"
-      }
-    },
-    "typography": {
-      "font.heading.xl.desktop": {
-        "value": {
-          "fontFamily": "Open Sans",
-          "fontSize": "32px",
-          "fontWeight": "700",
-          "lineHeight": "1.3"
-        },
-        "type": "typography"
-      }
-    },
-    "spacing": {
-      "space.1.desktop": {
-        "value": "8px",
-        "type": "dimension"
-      }
-    },
-    "borderRadius": {
-      "radius.md": {
-        "value": "8px",
-        "type": "borderRadius"
-      }
-    },
-    "shadows": {
-      "shadow.sm": {
-        "value": { "x": "0", "y": "2", "blur": "4", ... },
-        "type": "boxShadow"
-      }
-    }
-  }
-}
-```
-
-### TARGET (W3C DTCG Standard)
-```json
-{
-  "color": {
-    "brand": {
-      "primary": {
-        "$type": "color",
-        "$value": "#540b79",
-        "$description": "Main brand color"
-      }
-    }
-  },
-  "font": {
-    "heading": {
-      "xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "32px",
-            "fontWeight": "700",
-            "lineHeight": "1.3"
-          }
-        }
-      }
-    }
-  },
-  "spacing": {
-    "1": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "8px"
-      }
-    }
-  },
-  "borderRadius": {
-    "md": {
-      "$type": "dimension",
-      "$value": "8px"
-    }
-  },
-  "shadow": {
-    "sm": {
-      "$type": "shadow",
-      "$value": {
-        "color": "#00000026",
-        "offsetX": "0px",
-        "offsetY": "2px",
-        "blur": "4px",
-        "spread": "0px"
-      }
-    }
-  }
-}
-```
-
----
-
-## Key Changes Summary
-
-| Aspect | Current | DTCG Target |
-|--------|---------|-------------|
-| Property prefix | `value`, `type` | `$value`, `$type` |
-| Root wrapper | `global` | None (flat root) |
-| Token nesting | Flat keys (`color.brand.primary`) | Nested objects (`color.brand.primary`) |
-| Color type | `"type": "color"` | `"$type": "color"` |
-| Typography type | `"type": "typography"` | `"$type": "typography"` |
-| Spacing type | `"type": "dimension"` | `"$type": "dimension"` |
-| Radius type | `"type": "borderRadius"` | `"$type": "dimension"` |
-| Shadow type | `"type": "boxShadow"` | `"$type": "shadow"` |
-
----
-
-## Files to Update
-
-### 1. Export Functions (`app.py`)
-
-**File:** `/Users/yahya/design-system-extractor-v2-hf-fix/app.py`
-
-**Functions to modify:**
-- `export_stage1_json()` (~line 3095)
-- `export_tokens_json()` (~line 3248)
-
-**Changes:**
-1. Remove `global` wrapper - tokens at root level
-2. Change `value` → `$value`, `type` → `$type`
-3. Convert flat keys to nested structure:
-   - `color.brand.primary` → `{ color: { brand: { primary: {...} } } }`
-   - `font.heading.xl.desktop` → `{ font: { heading: { xl: { desktop: {...} } } } }`
-4. Add helper function to convert flat key to nested object
-5. Update shadow format to DTCG spec
-6. Keep `$description` for semantic tokens
-
-### 2. Figma Plugin (`code.js`)
-
-**File:** `/Users/yahya/design-system-extractor-v2-hf-fix/output_json/figma-plugin-extracted/figma-design-token-creator 5/src/code.js`
-
-**Changes:**
-1. Update `normalizeTokens()` to detect DTCG format (look for `$value`, `$type`)
-2. Update `extractColors()` to handle:
-   - `$value` instead of `value`
-   - Nested structure traversal
-3. Update `extractTypography()` to handle DTCG composite format
-4. Update `extractSpacing()` for dimension tokens
-5. Add shadow extraction (currently not implemented)
-6. Support both legacy AND DTCG formats for backwards compatibility
-
-### 3. Plugin UI (`ui.html`)
-
-**File:** `/Users/yahya/design-system-extractor-v2-hf-fix/output_json/figma-plugin-extracted/figma-design-token-creator 5/ui/ui.html`
-
-**Changes:**
-1. Update `extractColorsForPreview()` to handle `$value`
-2. Update `extractSpacingForPreview()` to handle `$value`
-3. Update `buildTypographyPreview()` for nested + DTCG format
-4. Add format detection message for DTCG
-5. Add shadow preview section
-
----
-
-## Detailed Implementation Steps
-
-### Step 1: Create DTCG Export Helper Functions (app.py)
-
-```python
-def _key_to_nested_path(flat_key: str) -> list:
-    """Convert 'color.brand.primary' to ['color', 'brand', 'primary']"""
-    return flat_key.split('.')
-
-def _set_nested_value(obj: dict, path: list, value: dict):
-    """Set a value at a nested path in a dictionary"""
-    for key in path[:-1]:
-        if key not in obj:
-            obj[key] = {}
-        obj = obj[key]
-    obj[path[-1]] = value
-
-def _to_dtcg_token(value, token_type: str, description: str = None) -> dict:
-    """Convert to DTCG format with $value, $type, $description"""
-    token = {
-        "$type": token_type,
-        "$value": value
-    }
-    if description:
-        token["$description"] = description
-    return token
-```
-
-### Step 2: Update Export Functions (app.py)
-
-Rewrite `export_stage1_json()` and `export_tokens_json()` to:
-1. Build nested structure instead of flat
-2. Use `$value`, `$type`, `$description`
-3. Map token types correctly:
-   - `borderRadius` → `dimension` (DTCG uses dimension for radii)
-   - `boxShadow` → `shadow`
-   - Keep `color`, `typography`, `dimension`
-
-### Step 3: Update Plugin Token Extraction (code.js)
-
-Add DTCG detection and extraction:
-
-```javascript
-// Detect if DTCG format
-function isDTCGFormat(obj) {
-  if (!obj || typeof obj !== 'object') return false;
-  var keys = Object.keys(obj);
-  for (var i = 0; i < keys.length; i++) {
-    var val = obj[keys[i]];
-    if (val && typeof val === 'object') {
-      if (val['$value'] !== undefined || val['$type'] !== undefined) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-// Extract from DTCG format
-function extractColorsDTCG(obj, prefix, results) {
-  // Handle $value, $type
-  // Recursively traverse nested structure
-}
-```
-
-### Step 4: Update Plugin UI (ui.html)
-
-Update preview functions to handle both formats.
-
-### Step 5: Add Shadow Support to Plugin
-
-Currently the plugin doesn't create Effect Styles for shadows. Add:
-
-```javascript
-// CREATE EFFECT STYLES (Shadows)
-for (var si = 0; si < tokens.shadows.length; si++) {
-  var shadowToken = tokens.shadows[si];
-  var effectStyle = figma.createEffectStyle();
-  effectStyle.name = 'shadows/' + shadowToken.name;
-  effectStyle.effects = [{
-    type: 'DROP_SHADOW',
-    color: { r: 0, g: 0, b: 0, a: 0.25 },
-    offset: { x: parseFloat(shadowToken.value.offsetX), y: parseFloat(shadowToken.value.offsetY) },
-    radius: parseFloat(shadowToken.value.blur),
-    spread: parseFloat(shadowToken.value.spread),
-    visible: true,
-    blendMode: 'NORMAL'
-  }];
-}
-```
-
----
-
-## Testing Checklist
-
-After implementation, verify:
-
-- [ ] Export Stage 1 JSON produces valid DTCG format
-- [ ] Export Final JSON produces valid DTCG format
-- [ ] Token names are properly nested (`color.brand.primary` → nested object)
-- [ ] All `$value`, `$type` prefixes present
-- [ ] Figma plugin successfully imports DTCG JSON
-- [ ] Colors → Paint Styles created correctly
-- [ ] Typography → Text Styles created correctly
-- [ ] Spacing → Variables created correctly
-- [ ] Border Radius → Variables created correctly
-- [ ] Shadows → Effect Styles created correctly
-- [ ] Plugin still works with legacy format (backwards compatible)
-
----
-
-## Benefits After Implementation
-
-1. **Interoperability** - Works with Figma, Sketch, Framer, Style Dictionary, Tokens Studio
-2. **Future-proof** - Official W3C standard, adopted by industry
-3. **Tool ecosystem** - Compatible with 10+ design tools
-4. **Code generation** - Works with Style Dictionary for CSS/iOS/Android
-5. **No vendor lock-in** - Standard format, portable
-
----
-
-## Estimated Effort
-
-| Task | Complexity | Time |
-|------|------------|------|
-| Export helper functions | Low | 15 min |
-| Update export_stage1_json | Medium | 30 min |
-| Update export_tokens_json | Medium | 30 min |
-| Update plugin code.js | Medium | 45 min |
-| Update plugin ui.html | Low | 20 min |
-| Add shadow support to plugin | Medium | 30 min |
-| Testing & fixes | Medium | 30 min |
-| **Total** | | **~3 hours** |
-
----
-
-## Awaiting Confirmation
-
-Please confirm:
-1. ✅ Proceed with W3C DTCG format update?
-2. ✅ Update both app.py export AND Figma plugin?
-3. ✅ Add shadow Effect Style support to plugin?
-4. ✅ Maintain backwards compatibility for legacy format in plugin?
-
-**Reply "approved" or provide feedback to proceed.**

PROJECT_CONTEXT.md

@@ -1,170 +0,0 @@
-# Design System Extractor v2 — Project Context
-
-## Architecture Overview
-
-```
-Stage 0: Configuration         Stage 1: Discovery & Extraction         Stage 2: AI Analysis              Stage 3: Export
- ┌──────────────────┐           ┌──────────────────────────┐           ┌──────────────────────────┐     ┌──────────────┐
- │ HF Token Setup   │ ──────>  │ URL Discovery (sitemap/   │ ──────>  │ Layer 1: Rule Engine     │ ──> │ Figma Tokens │
- │ Benchmark Select │           │ crawl) + Token Extraction │           │ Layer 2: Benchmarks      │     │ JSON Export   │
- └──────────────────┘           │ (Desktop + Mobile CSS)    │           │ Layer 3: LLM Agents (x3) │     └──────────────┘
-                                └──────────────────────────┘           │ Layer 4: HEAD Synthesizer│
-                                                                       └──────────────────────────┘
-```
-
-### Stage 1: Discovery & Extraction (Rule-Based, Free)
-- **Discover Pages**: Fetches sitemap.xml or crawls site to find pages
-- **Extract Tokens**: Playwright visits each page at 2 viewports (Desktop 1440px, Mobile 375px), extracts computed CSS for colors, typography, spacing, radius, shadows
-- **User Review**: Interactive tables with Accept/Reject checkboxes + visual previews
-
-### Stage 2: AI-Powered Analysis (4 Layers)
-
-| Layer | Type | What It Does | Cost |
-|-------|------|--------------|------|
-| **Layer 1** | Rule Engine | Type scale detection, AA contrast checking, spacing grid analysis, color statistics | FREE |
-| **Layer 2** | Benchmark Research | Compare against Material Design 3, Apple HIG, Tailwind, etc. | ~$0.001 |
-| **Layer 3** | LLM Agents (x3) | AURORA (Brand ID) + ATLAS (Benchmark) + SENTINEL (Best Practices) | ~$0.002 |
-| **Layer 4** | HEAD Synthesizer | NEXUS combines all outputs into final recommendations | ~$0.001 |
-
-### Stage 3: Export
-- Apply/reject individual color, typography, spacing recommendations
-- Export Figma Tokens Studio-compatible JSON
-
----
-
-## Agent Roster
-
-| Agent | Codename | Model | Temp | Input | Output | Specialty |
-|-------|----------|-------|------|-------|--------|-----------|
-| Brand Identifier | **AURORA** | Qwen/Qwen2.5-72B-Instruct | 0.4 | Color tokens + semantic CSS analysis | Brand primary/secondary/accent, palette strategy, cohesion score, semantic names | Creative/visual reasoning, color harmony assessment |
-| Benchmark Advisor | **ATLAS** | meta-llama/Llama-3.3-70B-Instruct | 0.25 | User's type scale, spacing, font sizes + benchmark comparison data | Recommended benchmark, alignment changes, pros/cons | 128K context for large benchmark data, comparative reasoning |
-| Best Practices Validator | **SENTINEL** | Qwen/Qwen2.5-72B-Instruct | 0.2 | Rule Engine results (typography, accessibility, spacing, color stats) | Overall score (0-100), check results, prioritized fix list | Methodical rule-following, precise judgment |
-| HEAD Synthesizer | **NEXUS** | meta-llama/Llama-3.3-70B-Instruct | 0.3 | All 3 agent outputs + Rule Engine facts | Executive summary, scores, top 3 actions, color/type/spacing recs | 128K context for combined inputs, synthesis capability |
-
-### Why These Models
-
-- **Qwen 72B** (AURORA, SENTINEL): Strong creative reasoning for brand analysis; methodical structured output for best practices. Available on HF serverless without gated access.
-- **Llama 3.3 70B** (ATLAS, NEXUS): 128K context window handles large combined inputs from multiple agents. Excellent comparative and synthesis reasoning.
-- **Fallback**: Qwen/Qwen2.5-7B-Instruct (free tier, available when primary models fail)
-
-### Temperature Rationale
-
-- **0.4** (AURORA): Allows creative interpretation of color stories and palette harmony
-- **0.25** (ATLAS): Analytical comparison needs consistency but some flexibility for trade-off reasoning
-- **0.2** (SENTINEL): Strict rule evaluation — consistency is critical for compliance scoring
-- **0.3** (NEXUS): Balanced — needs to synthesize creatively but stay grounded in agent data
-
----
-
-## Evaluation & Scoring
-
-### Self-Evaluation (All Agents)
-Each agent includes a `self_evaluation` block in its JSON output:
-```json
-{
-  "confidence": 8,          // 1-10: How confident the agent is
-  "reasoning": "Clear usage patterns with 20+ colors",
-  "data_quality": "good",   // good | fair | poor
-  "flags": []               // e.g., ["insufficient_context", "ambiguous_data"]
-}
-```
-
-### AURORA Scoring Rubric (Cohesion 1-10)
-- **9-10**: Clear harmony rule, distinct brand colors, consistent palette
-- **7-8**: Mostly harmonious, clear brand identity
-- **5-6**: Some relationships visible but not systematic
-- **3-4**: Random palette, no clear strategy
-- **1-2**: Conflicting colors, no brand identity
-
-### SENTINEL Scoring Rubric (Overall 0-100)
-Weighted checks:
-- AA Compliance: 25 points
-- Type Scale Consistency: 15 points
-- Base Size Accessible: 15 points
-- Spacing Grid: 15 points
-- Type Scale Standard Ratio: 10 points
-- Color Count: 10 points
-- No Near-Duplicates: 10 points
-
-### NEXUS Scoring Rubric (Overall 0-100)
-- **90-100**: Production-ready, minor polishing only
-- **75-89**: Solid foundation, 2-3 targeted improvements
-- **60-74**: Functional but needs focused attention
-- **40-59**: Significant gaps requiring systematic improvement
-- **20-39**: Major rework needed
-- **0-19**: Fundamental redesign recommended
-
-### Evaluation Summary (Logged After Analysis)
-```
-═══════════════════════════════════════════════════
-🔍 AGENT EVALUATION SUMMARY
-═══════════════════════════════════════════════════
-   🎨 AURORA  (Brand ID):    confidence=8/10, data=good
-   🏢 ATLAS   (Benchmark):   confidence=7/10, data=good
-   ✅ SENTINEL (Practices):  confidence=9/10, data=good, score=72/100
-   🧠 NEXUS   (Synthesis):   confidence=8/10, data=good, overall=65/100
-═══════════════════════════════════════════════════
-```
-
----
-
-## User Journey
-
-1. **Enter HF Token** — Required for LLM inference (free tier works)
-2. **Enter Website URL** — The site to extract design tokens from
-3. **Discover Pages** — Auto-finds pages via sitemap or crawling
-4. **Select Pages** — Check/uncheck pages to include (max 10)
-5. **Extract Tokens** — Scans selected pages at Desktop + Mobile viewports
-6. **Review Stage 1** — Interactive tables: Colors, Typography, Spacing, Radius, Shadows, Semantic Colors. Each tab has a data table + visual preview accordion. Accept/reject individual tokens.
-7. **Proceed to Stage 2** — Select benchmarks to compare against
-8. **Run AI Analysis** — 4-layer pipeline executes (Rule Engine -> Benchmarks -> LLM Agents -> Synthesis)
-9. **Review Analysis** — Dashboard with scores, recommendations, benchmark comparison, color recs
-10. **Apply Upgrades** — Accept/reject individual recommendations
-11. **Export JSON** — Download Figma Tokens Studio-compatible JSON
-
----
-
-## File Structure
-
-| File | Responsibility |
-|------|----------------|
-| `app.py` | Main Gradio UI — all stages, CSS, event bindings, formatting functions |
-| `agents/llm_agents.py` | 4 LLM agent classes (AURORA, ATLAS, SENTINEL, NEXUS) + dataclasses |
-| `agents/semantic_analyzer.py` | Semantic color categorization (brand, text, background, etc.) |
-| `config/settings.py` | Model routing, env var loading, agent-to-model mapping |
-| `core/hf_inference.py` | HF Inference API client, model registry, temperature mapping |
-| `core/preview_generator.py` | HTML preview generators for Stage 1 visual previews |
-| `core/rule_engine.py` | Layer 1: Type scale, AA contrast, spacing grid, color stats |
-| `core/benchmarks.py` | Benchmark definitions (Material Design 3, Apple HIG, etc.) |
-| `core/extractor.py` | Playwright-based CSS token extraction |
-| `core/discovery.py` | Page discovery via sitemap.xml / crawling |
-
----
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `HF_TOKEN` | (required) | HuggingFace API token |
-| `BRAND_IDENTIFIER_MODEL` | `Qwen/Qwen2.5-72B-Instruct` | Model for AURORA |
-| `BENCHMARK_ADVISOR_MODEL` | `meta-llama/Llama-3.3-70B-Instruct` | Model for ATLAS |
-| `BEST_PRACTICES_MODEL` | `Qwen/Qwen2.5-72B-Instruct` | Model for SENTINEL |
-| `HEAD_SYNTHESIZER_MODEL` | `meta-llama/Llama-3.3-70B-Instruct` | Model for NEXUS |
-| `FALLBACK_MODEL` | `Qwen/Qwen2.5-7B-Instruct` | Fallback when primary fails |
-| `HF_MAX_NEW_TOKENS` | `2048` | Max tokens per LLM response |
-| `HF_TEMPERATURE` | `0.3` | Global default temperature |
-| `MAX_PAGES` | `20` | Max pages to discover |
-| `BROWSER_TIMEOUT` | `30000` | Playwright timeout (ms) |
-
-### Model Override Examples
-```bash
-# Use Llama for all agents
-export BRAND_IDENTIFIER_MODEL="meta-llama/Llama-3.3-70B-Instruct"
-export BEST_PRACTICES_MODEL="meta-llama/Llama-3.3-70B-Instruct"
-
-# Use budget models
-export BRAND_IDENTIFIER_MODEL="Qwen/Qwen2.5-7B-Instruct"
-export BENCHMARK_ADVISOR_MODEL="mistralai/Mixtral-8x7B-Instruct-v0.1"
-```

README.md

@@ -1,5 +1,5 @@
 ---
-title: Design System Extractor v3
+title: Design System Automation v3
 emoji: 🎨
 colorFrom: purple
 colorTo: blue
@@ -8,7 +8,7 @@ pinned: false
 license: mit
 ---
 
-# Design System Extractor v3
+# Design System Automation v3
 
 > 🎨 A semi-automated, human-in-the-loop agentic system that reverse-engineers design systems from live websites.
 
@@ -65,7 +65,7 @@ This is **not a magic button** — it's a design-aware co-pilot.
 ```bash
 # Clone the repository
 git clone <repo-url>
-cd design-system-extractor
+cd design-system-automation
 
 # Create virtual environment
 python -m venv venv
@@ -118,7 +118,7 @@ Open `http://localhost:7860` in your browser.
 ## 📁 Project Structure
 
 ```
-design-system-extractor/
+design-system-automation/
 ├── app.py                          # Main Gradio application
 ├── requirements.txt
 ├── README.md

agents/__init__.py

@@ -1,5 +1,5 @@
 """
-Agents for Design System Extractor v2.
+Agents for Design System Automation.
 
 This package contains:
 - Stage 1 Agents: Crawler, Extractor, Normalizer, Semantic Analyzer

agents/advisor.py

@@ -1,6 +1,6 @@
 """
 Agent 3: Design System Best Practices Advisor
-Design System Extractor v2
+Design System Automation
 
 Persona: Senior Staff Design Systems Architect
 

agents/crawler.py

@@ -1,6 +1,6 @@
 """
 Agent 1: Website Crawler
-Design System Extractor v2
+Design System Automation
 
 Persona: Meticulous Design Archaeologist
 

agents/extractor.py

@@ -1,6 +1,6 @@
 """
 Agent 1: Token Extractor
-Design System Extractor v2
+Design System Automation
 
 Persona: Meticulous Design Archaeologist
 

agents/firecrawl_extractor.py

@@ -1,6 +1,6 @@
 """
 Agent 1B: Firecrawl CSS Extractor
-Design System Extractor v2
+Design System Automation
 
 Persona: CSS Deep Diver
 

agents/graph.py

@@ -1,6 +1,6 @@
 """
 LangGraph Workflow Orchestration
-Design System Extractor v2
+Design System Automation
 
 Defines the main workflow graph with agents, checkpoints, and transitions.
 """

agents/normalizer.py

@@ -1,6 +1,6 @@
 """
 Agent 2: Token Normalizer & Structurer
-Design System Extractor v3
+Design System Automation v3
 
 Persona: Design System Librarian
 

agents/semantic_analyzer.py

@@ -1,6 +1,6 @@
 """
 Agent 1C: Semantic Color Analyzer
-Design System Extractor v2
+Design System Automation
 
 ⚠️  DEPRECATED in v3.2 — Superseded by:
   - core/color_classifier.py (rule-based, primary naming authority)

agents/state.py

@@ -1,6 +1,6 @@
 """
 LangGraph State Definitions
-Design System Extractor v2
+Design System Automation
 
 Defines the state schema and type hints for LangGraph workflow.
 """

app.py

@@ -1,5 +1,5 @@
 """
-Design System Extractor v2 — Main Application
+Design System Automation — Main Application
 ==============================================
 
 Flow:
@@ -2969,7 +2969,7 @@ def _to_dtcg_token(value, token_type: str, description: str = None,
     elif description:
         token["$description"] = description
     if extensions:
-        token["$extensions"] = {"com.design-system-extractor": extensions}
+        token["$extensions"] = {"com.design-system-automation": extensions}
     return token
 
 
@@ -4473,7 +4473,7 @@ def create_ui():
     """
     
     with gr.Blocks(
-        title="Design System Extractor v3",
+        title="Design System Automation v3",
         theme=corporate_theme,
         css=custom_css
     ) as app:
@@ -4481,7 +4481,7 @@ def create_ui():
         # Header with branding
         gr.HTML("""
         <div class="app-header">
-            <h1>🎨 Design System Extractor</h1>
+            <h1>🎨 Design System Automation</h1>
             <p>Reverse-engineer design systems from live websites • AI-powered analysis • Figma-ready export</p>
         </div>
         """)
@@ -5077,7 +5077,7 @@ def create_ui():
         gr.Markdown("""
         ---
         <div style="text-align: center; color: #94a3b8; font-size: 12px; padding: 12px 0;">
-        <strong>Design System Extractor v3</strong> · Playwright + Firecrawl + HuggingFace<br/>
+        <strong>Design System Automation v3</strong> · Playwright + Firecrawl + HuggingFace<br/>
         Rule Engine (FREE) + ReAct LLM Agents (AURORA · ATLAS · SENTINEL · NEXUS)
         </div>
         """)

config/agents.yaml

@@ -1,5 +1,5 @@
 # =============================================================================
-# DESIGN SYSTEM EXTRACTOR v2 - AGENT CONFIGURATIONS
+# DESIGN SYSTEM AUTOMATION - AGENT CONFIGURATIONS
 # =============================================================================
 # 
 # This file defines the personas and configurations for each agent in the

config/settings.py

@@ -1,6 +1,6 @@
 """
 Application Settings
-Design System Extractor v2
+Design System Automation
 
 Loads configuration from environment variables and YAML files.
 """

content/LINKEDIN_POST.md

@@ -1,40 +0,0 @@
-# LinkedIn Post
-
----
-
-I built a system that audits any website's design system — automatically.
-
-Point it at a URL. It extracts every color, font, spacing value from the DOM. Then 4 AI agents analyze it like a senior design team.
-
-The secret? Not everything needs AI.
-
-Layer 1 (free, <1 second):
-- WCAG contrast checker (pure math)
-- Type scale detection
-- Spacing grid analysis
-- Color deduplication
-
-Layer 2 (~$0.003):
-- AURORA: identifies brand colors from usage context
-- ATLAS: recommends which design system to align with
-- SENTINEL: prioritizes fixes by business impact
-- NEXUS: synthesizes everything into a final report
-
-My V1 used LLMs for everything.
-Cost: ~$1/run. Accuracy: mediocre (LLMs hallucinate math).
-
-V2 flipped the approach:
-Deterministic code handles certainty. LLMs handle ambiguity.
-
-Result: 100-300x cheaper. More accurate. Always produces output even when LLMs fail.
-
-The rule engine does 80% of the work for $0.
-The agents handle the 20% that requires judgment.
-
-Built with: Playwright + HuggingFace Inference API (Qwen 72B, Llama 3.3 70B) + Gradio + Docker
-
-Full write-up on Medium (link in comments).
-
-What design workflows are you automating? Would love to hear.
-
-#UXDesign #AIEngineering #DesignSystems #HuggingFace #LLM #Accessibility #WCAG #MultiAgent #Gradio #BuildInPublic

content/MEDIUM_ARTICLE.md

@@ -1,406 +0,0 @@
-# 🚅 AI in My Daily Work — Episode [X]: Building a Design System Analyzer with 4 AI Agents + a Free Rule Engine
-
-*How I built a system that extracts any website's design tokens and audits them like a senior design team — for ~$0.003 per run.*
-
-[IMAGE: Hero banner — Gradio UI showing the pipeline output]
-
----
-
-## The Problem
-
-Every week, the same story.
-
-A designer opens a website and squints: "Is that our brand blue? Why does this button look different on mobile? How many shades of gray are we actually using?"
-
-Design systems are supposed to prevent this. But **auditing** one? That's a different problem entirely.
-
-- Open DevTools on every page
-- Manually extract colors, fonts, spacing
-- Cross-reference against WCAG accessibility guidelines
-- Compare to industry benchmarks like Material Design or Polaris
-- Write a report with prioritized recommendations
-
-For a 20-page website, this takes **2–3 days of manual work**. And by the time you're done, the codebase has already changed.
-
-I wanted a system that could think like a design team:
-
-- a **crawler** discovering every page
-- an **extractor** pulling every token from the DOM
-- a **rule engine** checking accessibility and consistency — for free
-- and **specialized AI agents** interpreting what the numbers actually mean
-
-So I built one.
-
----
-
-## The Solution (In One Sentence)
-
-I built a 4-agent system backed by a free rule engine that acts like an entire design audit team: data extraction + WCAG compliance + benchmark comparison + brand analysis + prioritized recommendations. It runs on HuggingFace Spaces, costs ~$0.003 per analysis, and delivers actionable output automatically.
-
----
-
-## Architecture Overview: Two Layers, Four Agents
-
-My first attempt (V1) made a classic mistake:
-**I used a large language model for everything.**
-
-### Why Two Layers?
-
-My V1 mistake: Used GPT-4 for everything
-❌ Cost: $0.50–1.00 per run
-❌ Speed: 15+ seconds for basic math
-❌ Accuracy: LLMs hallucinate contrast ratios
-
-The fix: **Not every task needs AI. Some need good engineering.**
-
-V2 flipped the approach.
-
-> **Deterministic code handles certainty. LLMs handle ambiguity.**
-
-This led to a two-layer architecture.
-
-[IMAGE: Architecture diagram — Layer 1 (Deterministic) → Layer 2 (AI Agents)]
-
-```
-┌─────────────────────────────────────────────────┐
-│  LAYER 1: DETERMINISTIC (Free — $0.00)          │
-│  ├─ Crawler + Extractor + Normalizer            │
-│  ├─ WCAG Contrast Checker (math)                │
-│  ├─ Type Scale Detection (ratio math)           │
-│  ├─ Spacing Grid Analysis (GCD math)            │
-│  └─ Color Statistics (deduplication)             │
-├─────────────────────────────────────────────────┤
-│  LAYER 2: AI AGENTS (~$0.003)                   │
-│  ├─ AURORA  — Brand Color Analyst               │
-│  ├─ ATLAS   — Benchmark Advisor                 │
-│  ├─ SENTINEL — Best Practices Auditor           │
-│  └─ NEXUS   — Head Synthesizer                  │
-└─────────────────────────────────────────────────┘
-```
-
----
-
-## Layer 1: Deterministic Intelligence (No LLM)
-
-These agents do the heavy lifting — no LLMs involved.
-
-### What This Layer Does
-
-- Crawls every page with Playwright (desktop 1440px + mobile 375px)
-- Extracts tokens from **7 sources**: DOM computed styles, CSS variables, SVG colors, inline styles, stylesheet rules, external CSS files (Firecrawl), brute-force page scan
-- Deduplicates colors (exact hex + Delta-E distance)
-- Checks **actual FG/BG pairs** against WCAG — not just "color vs white"
-- Detects type scale ratio and spacing grid
-- Scores overall consistency (0–100)
-
-### Rule Engine Output:
-
-```
-📐 TYPE SCALE ANALYSIS
-├─ Detected Ratio: 1.167
-├─ Closest Standard: Minor Third (1.2)
-├─ Consistent: ⚠️ No (variance: 0.24)
-└─ 💡 Recommendation: 1.25 (Major Third)
-
-♿ ACCESSIBILITY CHECK (WCAG AA/AAA)
-├─ Colors Analyzed: 210
-├─ FG/BG Pairs Checked: 220
-├─ AA Pass: 143 ✅
-├─ AA Fail (real FG/BG pairs): 67 ❌
-│  ├─ fg:#06b2c4 on bg:#ffffff → 💡 Fix: #048391 (4.5:1)
-│  ├─ fg:#999999 on bg:#ffffff → 💡 Fix: #757575 (4.6:1)
-│  └─ ... and 62 more
-
-📏 SPACING GRID
-├─ Detected Base: 1px (GCD)
-├─ Grid Aligned: ⚠️ 0%
-└─ 💡 Recommendation: 8px grid
-
-📊 CONSISTENCY SCORE: 52/100
-```
-
-This entire layer runs **in under 1 second** and costs nothing beyond compute — the single biggest cost optimization in the system.
-
----
-
-## Layer 2: AI Analysis & Interpretation (4 Agents)
-
-This is where language models actually add value — tasks that require **context, reasoning, and judgment**.
-
-[IMAGE: Agent pipeline diagram — AURORA → ATLAS → SENTINEL → NEXUS]
-
----
-
-### Agent 1: AURORA — Brand Color Analyst
-**Model:** Qwen 72B (HuggingFace PRO)
-**Cost:** Free within PRO subscription ($9/month)
-**Temperature:** 0.4
-
-**The Challenge:** The rule engine found 143 colors. Which one is the *brand* primary?
-
-A rule engine can count that `#06b2c4` appears in 33 buttons. But it can't reason: "33 buttons + 12 CTAs + dominant accent positioning = this is almost certainly the brand primary." That requires **context understanding**.
-
-**Sample Output:**
-
-```
-AURORA's Analysis:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎨 Brand Primary:  #06b2c4 (confidence: HIGH)
-   └─ 33 buttons, 12 CTAs, dominant accent
-
-🎨 Brand Secondary: #373737 (confidence: HIGH)
-   └─ 89 text elements, consistent dark tone
-
-Palette Strategy: Complementary
-Cohesion Score: 7/10
-   └─ "Clear hierarchy, accent colors differentiated"
-
-Self-Evaluation: confidence=8/10, data=good
-```
-
----
-
-### Agent 2: ATLAS — Benchmark Advisor
-**Model:** Llama 3.3 70B (128K context)
-**Cost:** Free within PRO subscription
-**Temperature:** 0.25
-
-**Unique Capability:** Industry benchmarking against 8 design systems (Material 3, Polaris, Atlassian, Carbon, Apple HIG, Tailwind, Ant, Chakra).
-
-[IMAGE: Benchmark comparison table from the UI]
-
-This agent doesn't just pick the closest match — it reasons about **effort vs. value**:
-
-```
-ATLAS's Recommendation:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Recommended: Shopify Polaris (87% match)
-
-Alignment Changes:
-  ├─ Type scale: 1.17 → 1.25 (effort: medium)
-  ├─ Spacing grid: mixed → 4px (effort: high)
-  └─ Base size: 16px → 16px (already aligned ✅)
-
-Pros: Closest match, e-commerce proven, well-documented
-Cons: Spacing migration is significant effort
-
-Alternative: Material 3 (77% match)
-  └─ "Stronger mobile patterns, but 8px grid
-       requires more restructuring"
-```
-
-ATLAS's Value Add:
-
-> "You're 87% aligned to Polaris already. Closing the gap on type scale takes ~1 hour and makes your system industry-standard. **Priority: MEDIUM.**"
-
----
-
-### Agent 3: SENTINEL — Best Practices Auditor
-**Model:** Qwen 72B
-**Cost:** Free within PRO subscription
-**Temperature:** 0.2 (strict, consistent)
-
-**The Challenge:** The rule engine says "67 AA failures." But which ones matter most?
-
-SENTINEL prioritizes by **business impact** — not just severity:
-
-```
-SENTINEL's Priority Fixes:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Overall Score: 68/100
-
-Checks:
-  ├─ ✅ Type Scale Standard (1.25 ratio)
-  ├─ ⚠️ Type Scale Consistency (variance 0.18)
-  ├─ ✅ Base Size Accessible (16px)
-  ├─ ❌ AA Compliance (67 failures)
-  ├─ ⚠️ Spacing Grid (0% aligned)
-  └─ ❌ Near-Duplicates (351 pairs)
-
-Priority Fixes:
-  #1 Fix brand color AA compliance
-     Impact: HIGH | Effort: 5 min
-     → "Affects 40% of interactive elements"
-
-  #2 Consolidate near-duplicate colors
-     Impact: MEDIUM | Effort: 2 hours
-
-  #3 Align spacing to 8px grid
-     Impact: MEDIUM | Effort: 1 hour
-```
-
----
-
-### Agent 4: NEXUS — Head Synthesizer (Final Output)
-**Model:** Llama 3.3 70B (128K context)
-**Cost:** ~$0.001
-**Temperature:** 0.3
-
-**No AI for Agents 1–3 can replace this.** NEXUS takes outputs from ALL three agents + the rule engine and synthesizes a final recommendation — **resolving contradictions**, weighting scores, and producing the executive summary the user actually sees.
-
-If ATLAS says "close to Polaris" but SENTINEL says "spacing misaligned," NEXUS reconciles: *"Align to Polaris type scale now (low effort) but defer spacing migration (high effort)."*
-
-```
-NEXUS Final Synthesis:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📝 Executive Summary:
-"Your design system scores 68/100. Critical:
-67 color pairs fail AA. Top action: fix brand
-primary contrast (5 min, high impact)."
-
-📊 Scores:
-  ├─ Overall:       68/100
-  ├─ Accessibility:  45/100
-  ├─ Consistency:    75/100
-  └─ Organization:   70/100
-
-🎯 Top 3 Actions:
-  1. Fix brand color AA (#06b2c4 → #048391)
-     Impact: HIGH | Effort: 5 min
-  2. Align type scale to 1.25
-     Impact: MEDIUM | Effort: 1 hour
-  3. Consolidate 143 → ~20 semantic colors
-     Impact: MEDIUM | Effort: 2 hours
-
-🎨 Color Recommendations:
-  ├─ ✅ brand.primary: #06b2c4 → #048391 (auto-accept)
-  ├─ ✅ text.secondary: #999999 → #757575 (auto-accept)
-  └─ ❌ brand.accent: #FF6B35 → #E65100 (user decides)
-```
-
----
-
-## Real Analysis: Two Websites
-
-### Website A: The Clean System
-
-```
-Landing → Product → Cart → Checkout
-```
-
-**Consistency Score:** 78/100
-**AA Failures:** 3 (all minor text colors)
-**Type Scale:** 1.25 ratio, consistent across pages
-**Agent Insight:** "Well-structured system. Minor AA fixes on secondary text. Already 92% aligned to Material 3."
-
-### Website B: The Messy System
-
-```
-Landing → Features → Pricing → ⚠️ Contact → Signup
-```
-
-**Consistency Score:** 34/100
-**AA Failures:** 67
-**Colors:** 143 unique (351 near-duplicates)
-**Agent Insight:** "No clear type scale. Brand primary fails AA on every interactive element. 143 colors suggests no design system is actually enforced."
-
-**NEXUS's Diagnosis:**
-> "This isn't a broken design system — it's the absence of one. Start with AA compliance (5 min fix), then consolidate to ~20 semantic colors (2 hours). Align to Polaris as your foundation."
-
-That last line is the difference between a report and an **action plan**.
-
----
-
-## Cost & Model Strategy
-
-Different agents use different models — intentionally.
-
-[IMAGE: Cost comparison table]
-
-| Agent | Model | Why This Model | Cost |
-|-------|-------|---------------|------|
-| Rule Engine | None | Math doesn't need AI | $0.00 |
-| AURORA | Qwen 72B | Creative color reasoning | ~Free (HF PRO) |
-| ATLAS | Llama 3.3 70B | 128K context for benchmarks | ~Free (HF PRO) |
-| SENTINEL | Qwen 72B | Strict, consistent evaluation | ~Free (HF PRO) |
-| NEXUS | Llama 3.3 70B | 128K context for synthesis | ~$0.001 |
-| **Total** | | | **~$0.003** |
-
-For designer-scale usage (weekly runs), inference costs are effectively negligible, with HuggingFace PRO ($9/month) covering most models.
-
-Compared to V1, this architecture delivers:
-- **~100–300x cost reduction**
-- **Faster execution** (rule engine: <1s vs LLM: 15s for the same math)
-- **Better accuracy** (LLMs hallucinate math; rule engines don't)
-- **Graceful degradation** (always produces output, even when LLMs fail)
-
----
-
-## Graceful Degradation
-
-The system **always produces output**, even when components fail:
-
-| If This Fails... | What Happens |
-|-------------------|-------------|
-| LLM agents down | Rule engine analysis still works (free) |
-| Firecrawl unavailable | DOM-only extraction (slightly fewer tokens) |
-| Benchmark fetch fails | Hardcoded fallback data from 8 systems |
-| NEXUS synthesis fails | `create_fallback_synthesis()` from rule engine |
-| **Entire AI layer** | **Full rule-engine-only report — still useful** |
-
----
-
-## What I Learned
-
-**1. Overusing LLMs is a design failure.**
-If rules can do it faster and cheaper — use rules. My WCAG checker is 100% accurate. An LLM's contrast ratio calculation? Maybe 85% accurate, and 100x slower.
-
-**2. Industry benchmarks are gold.**
-Without benchmarks: "Your type scale is inconsistent" → *PM nods*
-With benchmarks: "You're 87% aligned to Shopify Polaris. Closing the gap takes 1 hour and makes your system industry-standard." → *PM schedules meeting*
-
-Time to build benchmark database: 1 day
-Value: Transforms analysis into prioritized action
-
-**3. Specialized agents > one big prompt.**
-One mega-prompt doing brand analysis + benchmark comparison + accessibility audit + synthesis = confused, unfocused output. Four agents, each with a single responsibility = sharp, reliable analysis.
-
-The same principle as microservices: do one thing well.
-
-**4. UX skills transfer directly to AI systems.**
-Agent design feels a lot like service design:
-- flows
-- handoffs
-- failure modes
-- human interpretation
-
-The best AI architectures are the ones designed like good products.
-
----
-
-## A Note on the Tech Stack
-
-**On HuggingFace Spaces:** I'm using HF Spaces as the hosting platform with a Gradio frontend running in Docker. The LLM models (Qwen 72B, Llama 3.3 70B) are called via HuggingFace Inference API. Browser automation (Playwright + Chromium) runs inside the container.
-
-**On the Data:** This system works on **live websites** — point it at any URL and it extracts real design tokens from the actual DOM. No synthetic data. The architecture, LLM integrations, and rule engine are production-ready.
-
-🔗 **HuggingFace Space** (Live Demo): [link]
-
-[IMAGE: Screenshot of the Gradio UI showing full analysis results]
-
----
-
-## Closing Thought
-
-AI engineering isn't about fancy models or complex architecture. It's about knowing which problems need AI vs good engineering.
-
-It's **compression** — compressing days of manual audit, multiple expert perspectives, and industry benchmarking into something a team can act on Monday morning.
-
-Instead of 2–3 days reviewing DevTools, your team gets:
-> "Top 3 issues, ranked by impact, with specific fixes, benchmark alignment, and brand color identification"
-
-That's AI amplifying design systems impact.
-
-🔗 Full code on GitHub: [link]
-
----
-
-*This is Episode [X] of "AI in My Daily Work."*
-
-*If you missed the previous episodes:*
-- *Episode 5: Building a 7-Agent UX Friction Analysis System in Databricks*
-- *Episode 4: Automating UI Regression Testing with AI Agents (Part-1)*
-- *Episode 3: Building a Multi-Agent Review Intelligence System*
-- *Episode 2: How I Use a Team of AI Agents to Automate Secondary Research*
-
-*What problems are you automating with AI? Drop a comment — I'd love to discuss what you're building.*

core/__init__.py

@@ -1,5 +1,5 @@
 """
-Core utilities for Design System Extractor v2.
+Core utilities for Design System Automation.
 """
 
 from core.token_schema import (

core/color_classifier.py

@@ -1,6 +1,6 @@
 """
 Rule-Based Color Classifier
-Design System Extractor v3.1
+Design System Automation v3.1
 
 100% deterministic color classification and naming.
 NO LLM involved. Every decision logged with evidence.

core/color_utils.py

@@ -1,6 +1,6 @@
 """
 Color Utilities
-Design System Extractor v2
+Design System Automation
 
 Functions for color analysis, contrast calculation, and ramp generation.
 """

core/hf_inference.py

@@ -1,6 +1,6 @@
 """
 HuggingFace Inference Client
-Design System Extractor v2
+Design System Automation
 
 Handles all LLM inference calls using HuggingFace Inference API.
 Supports diverse models from different providers for specialized tasks.

core/logging.py

@@ -1,5 +1,5 @@
 """
-Structured Logging for Design System Extractor
+Structured Logging for Design System Automation
 ================================================
 
 Provides consistent logging across the application using loguru.

core/token_schema.py

@@ -1,6 +1,6 @@
 """
 Token Schema Definitions
-Design System Extractor v3
+Design System Automation v3
 
 Pydantic models for all token types and extraction results.
 These are the core data structures used throughout the application.
@@ -401,7 +401,7 @@ class TokenMetadata(BaseModel):
     extracted_at: datetime
     version: str
     viewport: Viewport
-    generator: str = "Design System Extractor v3"
+    generator: str = "Design System Automation v3"
 
 
 class FinalTokens(BaseModel):

docs/CONTEXT.md

@@ -1,190 +0,0 @@
-# Design System Extractor v3.2 — Master Context File
-
-> **Upload this file to refresh Claude's context when continuing work on this project.**
-
-**Last Updated:** February 2026
-
----
-
-## Current Status
-
-| Component | Status | Version |
-|-----------|--------|---------|
-| Token Extraction (Part 1) | COMPLETE | v3.2 |
-| Color Classification | COMPLETE | v3.1 |
-| DTCG Compliance | COMPLETE | v3.2 |
-| Naming Authority Chain | COMPLETE | v3.2 |
-| Figma Plugin (Visual Spec) | COMPLETE | v7 |
-| Component Generation (Part 2) | RESEARCH DONE | - |
-| Tests | 113 passing | - |
-
----
-
-## Project Goal
-
-Build a **semi-automated, human-in-the-loop system** that:
-1. Reverse-engineers a design system from a live website
-2. Classifies colors deterministically by CSS evidence
-3. Audits against industry benchmarks and best practices
-4. Outputs W3C DTCG v1 compliant JSON
-5. Generates Figma Variables, Styles, and Visual Spec pages
-6. (Part 2) Auto-generates Figma components from tokens
-
-**Philosophy:** AI as copilot, not autopilot. Humans decide, agents propose.
-
----
-
-## Architecture (v3.2)
-
-```
-+--------------------------------------------------+
-|  LAYER 1: EXTRACTION + NORMALIZATION (Free)       |
-|  +- Crawler + 7-Source Extractor (Playwright)     |
-|  +- Normalizer: colors, radius, shadows, typo     |
-|  +- Firecrawl: deep CSS parsing                   |
-+--------------------------------------------------+
-|  LAYER 2: CLASSIFICATION + RULE ENGINE (Free)     |
-|  +- Color Classifier (815 lines, deterministic)   |
-|  +- WCAG Contrast Checker (actual FG/BG pairs)    |
-|  +- Type Scale Detection (ratio math)             |
-|  +- Spacing Grid Analysis (GCD math)              |
-+--------------------------------------------------+
-|  LAYER 3: 4 AI AGENTS (~$0.003)                   |
-|  +- AURORA   - Brand Advisor        (Qwen 72B)   |
-|  +- ATLAS    - Benchmark Advisor    (Llama 70B)   |
-|  +- SENTINEL - Best Practices Audit (Qwen 72B)   |
-|  +- NEXUS    - Head Synthesizer     (Llama 70B)   |
-+--------------------------------------------------+
-|  EXPORT: W3C DTCG v1 Compliant JSON               |
-|  +- $type, $value, $description, $extensions      |
-|  +- Figma Plugin: Variables + Styles + Visual Spec|
-+--------------------------------------------------+
-```
-
-### Naming Authority Chain (v3.2)
-
-```
-1. Color Classifier (PRIMARY) - deterministic, covers ALL colors
-   +- CSS evidence -> category -> token name
-   +- 100% reproducible, logged with evidence
-
-2. AURORA LLM (SECONDARY) - semantic role enhancer ONLY
-   +- Can promote "color.blue.500" -> "color.brand.primary"
-   +- CANNOT rename palette colors
-   +- filter_aurora_naming_map() enforces boundary
-
-3. Normalizer (FALLBACK) - preliminary hue+shade names
-```
-
----
-
-## File Structure
-
-```
-design-system-extractor-v3/
-+-- app.py                          # Main Gradio app (~5000 lines)
-+-- CLAUDE.md                       # Project context and architecture
-+-- PART2_COMPONENT_GENERATION.md   # Part 2 research + plan
-|
-+-- agents/
-|   +-- crawler.py                  # Page discovery
-|   +-- extractor.py                # Playwright 7-source extraction
-|   +-- firecrawl_extractor.py      # Deep CSS parsing
-|   +-- normalizer.py               # Token normalization (~950 lines)
-|   +-- llm_agents.py               # AURORA, ATLAS, SENTINEL, NEXUS
-|   +-- semantic_analyzer.py        # DEPRECATED in v3.2
-|   +-- stage2_graph.py             # DEPRECATED in v3.2
-|
-+-- core/
-|   +-- color_classifier.py         # Rule-based classification (815 lines)
-|   +-- color_utils.py              # Color math (hex/RGB/HSL, contrast)
-|   +-- rule_engine.py              # Type scale, WCAG, spacing grid (~1100 lines)
-|   +-- hf_inference.py             # HuggingFace Inference API client
-|   +-- token_schema.py             # Pydantic models
-|
-+-- config/
-|   +-- settings.py                 # Configuration
-|
-+-- tests/
-|   +-- test_stage1_extraction.py   # 82 deterministic tests
-|   +-- test_agent_evals.py         # 27 LLM agent schema/behavior tests
-|   +-- test_stage2_pipeline.py     # Pipeline integration tests
-|
-+-- output_json/
-|   +-- figma-plugin-extracted/
-|       +-- figma-design-token-creator 5/
-|           +-- src/code.js          # Figma plugin (~1200 lines)
-|           +-- src/ui.html          # Plugin UI (~500 lines)
-|
-+-- docs/
-    +-- MEDIUM_ARTICLE_EPISODE_6.md  # Medium article
-    +-- LINKEDIN_POST_EPISODE_6.md   # LinkedIn post
-    +-- IMAGE_GUIDE_EPISODE_6.md     # Image specs for article
-    +-- FIGMA_SPECIMEN_IDEAS.md      # Visual spec layout reference
-    +-- CONTEXT.md                   # THIS FILE
-```
-
----
-
-## Model Assignments
-
-| Agent | Model | Temperature | Role |
-|-------|-------|-------------|------|
-| Rule Engine | None | - | WCAG, type scale, spacing (FREE) |
-| Color Classifier | None | - | CSS evidence -> category (FREE) |
-| AURORA | Qwen/Qwen2.5-72B-Instruct | 0.4 | Brand advisor (SECONDARY) |
-| ATLAS | meta-llama/Llama-3.3-70B-Instruct | 0.25 | Benchmark comparison |
-| SENTINEL | Qwen/Qwen2.5-72B-Instruct | 0.2 | Best practices audit |
-| NEXUS | meta-llama/Llama-3.3-70B-Instruct | 0.3 | Final synthesis |
-
-**Total cost per analysis:** ~$0.003
-
----
-
-## Key Technical Decisions
-
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| Color naming | Numeric shades (50-900) | Never words (light/dark/base) |
-| Naming authority | Classifier PRIMARY, LLM SECONDARY | One source of truth |
-| Export format | W3C DTCG v1 | Industry standard (Oct 2025) |
-| Token metadata | $extensions (namespaced) | Frequency, confidence, evidence |
-| Radius processing | Parse, deduplicate, sort, name | none/sm/md/lg/xl/2xl/full |
-| Shadow processing | Parse, sort by blur, name | xs/sm/md/lg/xl (always 5 levels) |
-| Accessibility | Actual FG/BG pairs from DOM | Not just color vs white |
-| Figma output | Variables + Styles + Visual Spec | Auto-generated specimen page |
-| LLM role | Advisory only, never naming authority | Deterministic reproducibility |
-
----
-
-## Execution Status
-
-### Part 1: Token Extraction + Analysis (COMPLETE)
-
-```
-PHASE 1: NORMALIZER       [DONE]
-PHASE 2: STAGE 2 AGENTS   [DONE]
-PHASE 3: EXPORT + DTCG    [DONE]
-PHASE 4: EXTRACTION IMPROVEMENTS [NOT STARTED]
-  4a. Font family detection (still returns "sans-serif")
-  4b. Rule engine: radius grid analysis
-  4c. Rule engine: shadow elevation analysis
-```
-
-### Part 2: Component Generation (RESEARCH COMPLETE)
-
-**Decision:** Custom Figma Plugin (Option A)
-**Scope:** 5 MVP components, ~86 variants, ~1400 lines new plugin code
-**See:** `PART2_COMPONENT_GENERATION.md` for full details
-
----
-
-## GitHub
-
-- **Repository:** https://github.com/hiriazmo/design-system-extractor-v3
-- **Latest commit:** `6b43e51` (DTCG compliance + naming authority)
-- **Tests:** 113 passing
-
----
-
-*Last updated: 2026-02-23*

docs/FIGMA_SPECIMEN_IDEAS.md

@@ -1,508 +0,0 @@
-# Figma Design System Specimen Page Ideas
-
-## Purpose
-After importing the JSON (AS-IS or TO-BE) via your plugin, you need a visual way to **display and review** the design tokens. This document provides layout ideas and methods to auto-generate specimen pages.
-
----
-
-## Specimen Page Layout
-
-### Overall Structure
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                                                                             │
-│   DESIGN SYSTEM SPECIMEN                                                    │
-│   [AS-IS] or [TO-BE]                                                       │
-│   Source: example.com | Generated: Jan 29, 2026                            │
-│                                                                             │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│   ┌─────────────────────────────┐  ┌─────────────────────────────┐        │
-│   │     TYPOGRAPHY DESKTOP      │  │     TYPOGRAPHY MOBILE       │        │
-│   └─────────────────────────────┘  └─────────────────────────────┘        │
-│                                                                             │
-│   ┌─────────────────────────────────────────────────────────────┐          │
-│   │                         COLORS                               │          │
-│   │   Brand | Text | Background | Border | Feedback              │          │
-│   └─────────────────────────────────────────────────────────────┘          │
-│                                                                             │
-│   ┌─────────────────────────────┐  ┌─────────────────────────────┐        │
-│   │          SPACING            │  │       BORDER RADIUS         │        │
-│   └─────────────────────────────┘  └─────────────────────────────┘        │
-│                                                                             │
-│   ┌─────────────────────────────────────────────────────────────┐          │
-│   │                        SHADOWS                               │          │
-│   └─────────────────────────────────────────────────────────────┘          │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Section 1: Typography
-
-### Desktop Typography (Left Column)
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  TYPOGRAPHY — DESKTOP (1440px)                                  │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  Display XL                                                     │
-│  The quick brown fox                                           │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 72px · Bold · 1.1 line-height                     │
-│  Token: font.display.xl.desktop                                │
-│                                                                 │
-│  ─────────────────────────────────────────────────────────     │
-│                                                                 │
-│  Heading 1                                                      │
-│  The quick brown fox jumps                                     │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 48px · Bold · 1.2 line-height                     │
-│  Token: font.heading.1.desktop                                 │
-│                                                                 │
-│  ─────────────────────────────────────────────────────────     │
-│                                                                 │
-│  Heading 2                                                      │
-│  The quick brown fox jumps over                                │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 36px · Semibold · 1.25 line-height                │
-│  Token: font.heading.2.desktop                                 │
-│                                                                 │
-│  ─────────────────────────────────────────────────────────     │
-│                                                                 │
-│  Heading 3                                                      │
-│  The quick brown fox jumps over the lazy dog                   │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 28px · Semibold · 1.3 line-height                 │
-│  Token: font.heading.3.desktop                                 │
-│                                                                 │
-│  ─────────────────────────────────────────────────────────     │
-│                                                                 │
-│  Body Large                                                     │
-│  The quick brown fox jumps over the lazy dog. Pack my box      │
-│  with five dozen liquor jugs.                                  │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 18px · Regular · 1.5 line-height                  │
-│  Token: font.body.lg.desktop                                   │
-│                                                                 │
-│  ─────────────────────────────────────────────────────────     │
-│                                                                 │
-│  Body                                                           │
-│  The quick brown fox jumps over the lazy dog. Pack my box      │
-│  with five dozen liquor jugs. How vexingly quick daft zebras   │
-│  jump!                                                         │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 16px · Regular · 1.5 line-height                  │
-│  Token: font.body.desktop                                      │
-│                                                                 │
-│  ─────────────────────────────────────────────────────────     │
-│                                                                 │
-│  Caption                                                        │
-│  The quick brown fox jumps over the lazy dog                   │
-│  ───────────────────────────────────────────────               │
-│  Open Sans · 12px · Regular · 1.4 line-height                  │
-│  Token: font.caption.desktop                                   │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Mobile Typography (Right Column)
-Same structure but with mobile values:
-- Smaller sizes (e.g., Display XL: 48px instead of 72px)
-- Token names: font.display.xl.mobile
-
-### Typography Comparison View (Alternative)
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  TYPOGRAPHY SCALE COMPARISON                                                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  Token              Desktop         Mobile          Ratio                   │
-│  ─────────────────────────────────────────────────────────────────────     │
-│  display.xl         72px            48px            1.5x                   │
-│  heading.1          48px            36px            1.33x                  │
-│  heading.2          36px            28px            1.29x                  │
-│  heading.3          28px            24px            1.17x                  │
-│  body.lg            18px            16px            1.13x                  │
-│  body               16px            16px            1x                     │
-│  caption            12px            12px            1x                     │
-│                                                                             │
-│  Scale Ratio: 1.25 (Major Third)                                           │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Section 2: Colors
-
-### Semantic Color Groups
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  COLORS                                                                     │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  🎨 BRAND                                                                   │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐                                  │
-│  │          │  │          │  │          │                                  │
-│  │ #06b2c4  │  │ #c1df1f  │  │ #3860be  │                                  │
-│  │          │  │          │  │          │                                  │
-│  └──────────┘  └──────────┘  └──────────┘                                  │
-│   Primary       Secondary     Accent                                        │
-│   AA: ⚠️ 3.2    AA: ⚠️ 2.1    AA: ✓ 4.8                                    │
-│                                                                             │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  📝 TEXT                                                                    │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
-│  │          │  │          │  │          │  │          │                   │
-│  │ #1a1a1a  │  │ #373737  │  │ #666666  │  │ #999999  │                   │
-│  │          │  │          │  │          │  │          │                   │
-│  └──────────┘  └──────────┘  └──────────┘  └──────────┘                   │
-│   Primary       Secondary     Tertiary      Muted                          │
-│   AA: ✓ 16.1    AA: ✓ 12.6    AA: ✓ 5.7     AA: ⚠️ 3.0                    │
-│                                                                             │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  🖼️ BACKGROUND                                                             │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
-│  │          │  │          │  │          │  │          │                   │
-│  │ #ffffff  │  │ #f5f5f5  │  │ #e8e8e8  │  │ #1a1a1a  │                   │
-│  │          │  │          │  │          │  │          │                   │
-│  └──────────┘  └──────────┘  └──────────┘  └──────────┘                   │
-│   Primary       Secondary     Tertiary      Inverse                        │
-│                                                                             │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  📏 BORDER                                                                  │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐                                  │
-│  │  ┌────┐  │  │  ┌────┐  │  │  ┌────┐  │                                  │
-│  │  │    │  │  │  │    │  │  │  │    │  │                                  │
-│  │  └────┘  │  │  └────┘  │  │  └────┘  │                                  │
-│  └──────────┘  └──────────┘  └──────────┘                                  │
-│   #e0e0e0       #d0d0d0       #c0c0c0                                      │
-│   Default       Strong        Focus                                        │
-│                                                                             │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  🚨 FEEDBACK                                                                │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
-│  │          │  │          │  │          │  │          │                   │
-│  │ #dc2626  │  │ #16a34a  │  │ #f59e0b  │  │ #3b82f6  │                   │
-│  │          │  │          │  │          │  │          │                   │
-│  └──────────┘  └──────────┘  └──────────┘  └──────────┘                   │
-│   Error         Success       Warning       Info                           │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Color Ramps (If Generated)
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  COLOR RAMPS                                                                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  Brand Primary                                                              │
-│  ┌────┬────┬────┬────┬────┬��───┬────┬────┬────┬────┬────┐                 │
-│  │ 50 │100 │200 │300 │400 │500 │600 │700 │800 │900 │950 │                 │
-│  │    │    │    │    │    │ ◆  │    │    │    │    │    │                 │
-│  └────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘                 │
-│   ◆ = Base color (#06b2c4)                                                 │
-│                                                                             │
-│  Neutral                                                                    │
-│  ┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐                 │
-│  │ 50 │100 │200 │300 │400 │500 │600 │700 │800 │900 │950 │                 │
-│  └────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘                 │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Section 3: Spacing
-
-### Visual Spacing Scale
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  SPACING SCALE (8px Grid)                                                   │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  Token           Value    Visual                                            │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  space.0         0px      (none)                                           │
-│                                                                             │
-│  space.1         4px      ████                                             │
-│                                                                             │
-│  space.2         8px      ████████                                         │
-│                                                                             │
-│  space.3         12px     ████████████                                     │
-│                                                                             │
-│  space.4         16px     ████████████████                                 │
-│                                                                             │
-│  space.5         20px     ████████████████████                             │
-│                                                                             │
-│  space.6         24px     ████████████████████████                         │
-│                                                                             │
-│  space.8         32px     ████████████████████████████████                 │
-│                                                                             │
-│  space.10        40px     ████████████████████████████████████████         │
-│                                                                             │
-│  space.12        48px     ████████████████████████████████████████████████ │
-│                                                                             │
-│  space.16        64px     ████████████████████████████████████████████...  │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Spacing with Boxes
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  SPACING — VISUAL REFERENCE                                                 │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  4px        8px         16px          24px           32px          48px    │
-│  space.1    space.2     space.4       space.6        space.8       space.12│
-│                                                                             │
-│   ┌┐        ┌──┐        ┌────┐        ┌──────┐       ┌────────┐    ┌──────┐│
-│   └┘        └──┘        │    │        │      │       │        │    │      ││
-│                         └────┘        │      │       │        │    │      ││
-│                                       └──────┘       │        │    │      ││
-│                                                      └────────┘    │      ││
-│                                                                    │      ││
-│                                                                    └──────┘│
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Section 4: Border Radius
-
-### Radius Visual Display
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  BORDER RADIUS                                                              │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐    ╭────────╮        │
-│  │        │    │        │    │        │    │        │    │        │        │
-│  │        │    │        │    │        │    │        │    │        │        │
-│  │        │    │        │    │        │    │        │    │        │        │
-│  └────────┘    └────────┘    └────────┘    └────────┘    ╰────────╯        │
-│                                                                             │
-│   0px           4px           8px           12px          9999px           │
-│   radius.none   radius.sm     radius.md     radius.lg     radius.full      │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Section 5: Shadows
-
-### Shadow Visual Display
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│  SHADOWS / ELEVATION                                                        │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐                 │
-│  │             │      │             │      │             │                 │
-│  │             │      │             │      │             │                 │
-│  │   Level 1   │      │   Level 2   │      │   Level 3   │                 │
-│  │             │      │             │      │             │                 │
-│  │             │      │             │      │             │                 │
-│  └─────────────┘      └─────────────┘      └─────────────┘                 │
-│   ░░░░░░░░░░░░░        ▒▒▒▒▒▒▒▒▒▒▒▒▒        ▓▓▓▓▓▓▓▓▓▓▓▓▓                 │
-│                                                                             │
-│   shadow.sm            shadow.md            shadow.lg                       │
-│   0 1px 2px            0 4px 8px            0 8px 24px                     │
-│   rgba(0,0,0,0.05)     rgba(0,0,0,0.1)      rgba(0,0,0,0.15)               │
-│                                                                             │
-│   Use: Subtle lift     Use: Cards, menus    Use: Modals, dialogs           │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Methods to Auto-Generate Specimen in Figma
-
-### Method 1: Figma Plugin Extension (Recommended)
-
-Extend your existing plugin to:
-1. Import JSON → Create Variables (already done)
-2. **NEW: Generate Specimen Page**
-   - Create a new page called "📋 Design System Specimen"
-   - Auto-generate frames for each token category
-   - Apply variables to the specimen elements
-
-**Plugin Code Concept:**
-```javascript
-// After importing variables...
-async function generateSpecimenPage() {
-  // Create page
-  const page = figma.createPage();
-  page.name = "📋 Design System Specimen";
-  
-  // Create Typography section
-  const typoFrame = createTypographySpecimen(typographyVariables);
-  
-  // Create Colors section
-  const colorFrame = createColorSpecimen(colorVariables);
-  
-  // Create Spacing section
-  const spacingFrame = createSpacingSpecimen(spacingVariables);
-  
-  // ... etc
-}
-```
-
-### Method 2: Figma Template + Variables
-
-1. **Create a Master Template** (one-time setup):
-   - Design the specimen layout manually
-   - Use placeholder text/colors
-   
-2. **Connect to Variables**:
-   - Bind text layers to typography variables
-   - Bind fills to color variables
-   - Bind auto-layout gaps to spacing variables
-
-3. **On Import**:
-   - Variables update → Specimen auto-updates
-
-**Advantage:** Beautiful, customized design
-**Disadvantage:** Manual template creation
-
-### Method 3: Community Plugin — "Design Tokens to Figma"
-
-Use existing plugins that can generate visual specimens:
-- **Tokens Studio for Figma** — Has specimen generation
-- **Themer** — Creates color ramps visually
-- **Design System Organizer** — Structures tokens
-
-### Method 4: Widget (Most Interactive)
-
-Create a **Figma Widget** that:
-- Reads variables from the document
-- Renders an interactive specimen
-- Updates in real-time
-
-**Advantage:** Live, interactive
-**Disadvantage:** More complex to build
-
----
-
-## Recommended Approach for You
-
-Given you already have a plugin:
-
-### Quick Win (30 min)
-1. Create a **Figma template file** with the specimen layout
-2. Manually connect elements to variables
-3. Duplicate template for each project
-
-### Better Solution (2-4 hours)
-Extend your plugin to auto-generate the specimen page:
-
-```javascript
-// Add to your existing plugin
-figma.ui.onmessage = async (msg) => {
-  if (msg.type === 'import-json') {
-    // Your existing import code...
-    await importVariables(msg.data);
-    
-    // NEW: Generate specimen
-    if (msg.generateSpecimen) {
-      await generateSpecimenPage();
-    }
-  }
-};
-
-async function generateSpecimenPage() {
-  const page = figma.createPage();
-  page.name = `📋 Specimen — ${new Date().toLocaleDateString()}`;
-  figma.currentPage = page;
-  
-  let yOffset = 0;
-  
-  // Typography
-  yOffset = await createTypographySection(0, yOffset);
-  
-  // Colors  
-  yOffset = await createColorSection(0, yOffset + 100);
-  
-  // Spacing
-  yOffset = await createSpacingSection(0, yOffset + 100);
-  
-  // Radius
-  yOffset = await createRadiusSection(0, yOffset + 100);
-  
-  // Shadows
-  await createShadowSection(0, yOffset + 100);
-  
-  figma.viewport.scrollAndZoomIntoView(page.children);
-}
-```
-
----
-
-## AS-IS vs TO-BE Comparison View
-
-For comparing before/after:
-
-```
-┌────────────────────────────────────────────���────────────────────────────────┐
-│  COMPARISON: AS-IS → TO-BE                                                  │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                             │
-│  TYPOGRAPHY                                                                 │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  Token              AS-IS           TO-BE           Change                  │
-│  display.xl         72px            72px            —                       │
-│  heading.1          46px            48px            +2px (scale aligned)    │
-│  heading.2          34px            36px            +2px (scale aligned)    │
-│  body               16px            16px            —                       │
-│                                                                             │
-│  Scale Ratio:       ~1.18 (random)  1.25 (Major Third)  ✓ Improved         │
-│                                                                             │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  COLORS                                                                     │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  Token              AS-IS           TO-BE           Change                  │
-│                                                                             │
-│  brand.primary      #06b2c4         #0891a8         AA: 3.2 → 4.6 ✓        │
-│                     ┌────┐          ┌────┐                                 │
-│                     │    │    →     │    │                                 │
-│                     └────┘          └────┘                                 │
-│                                                                             │
-│  text.primary       #373737         #373737         — (no change)          │
-│                                                                             │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  SPACING                                                                    │
-│  ─────────────────────────────────────────────────────────────────────     │
-│                                                                             │
-│  Grid:              Mixed           8px             ✓ Standardized         │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Summary
-
-| Method | Effort | Best For |
-|--------|--------|----------|
-| Template + Variables | Low | Quick setup, one-off projects |
-| Plugin Extension | Medium | Reusable, consistent output |
-| Widget | High | Interactive, real-time updates |
-| Community Plugin | None | If existing solution fits |
-
-**My Recommendation:** Extend your plugin to auto-generate the specimen page. It's a one-time investment that pays off every time you use the workflow.

docs/IMAGE_GUIDE_EPISODE_6.md

@@ -179,7 +179,7 @@ Category Caps: brand(3) text(3) bg(3) border(3) feedback(4) palette(rest)
         "$type": "color",
         "$value": "#005aa3",
         "$extensions": {
-          "com.design-system-extractor": {
+          "com.design-system-automation": {
             "frequency": 47,
             "confidence": "high"
           }

docs/LINKEDIN_POST_EPISODE_6.md

@@ -1,4 +1,4 @@
-# LinkedIn Post - Episode 6: Design System Extractor v3.2
+# LinkedIn Post - Episode 6: Design System Automation v3.2
 
 ## Main Post (Copy-Paste Ready)
 

docs/MEDIUM_ARTICLE_EPISODE_6.md

@@ -487,7 +487,7 @@ V3's export follows the W3C Design Tokens Community Group specification (stable
         "$value": "#005aa3",
         "$description": "[classifier] brand: primary_action",
         "$extensions": {
-          "com.design-system-extractor": {
+          "com.design-system-automation": {
             "frequency": 47,
             "confidence": "high",
             "category": "brand",

docs/MEDIUM_ARTICLE_EPISODE_6_V2.md

@@ -0,0 +1,264 @@
+# AI in My Daily Work — Episode 6: How 4 AI Agents + a Color Classifier Reverse-Engineer Any Website's Design System
+
+## From URL to Figma in 15 Minutes (Not 5 Days)
+
+*I built a system that extracts design tokens from any live website, classifies colors by actual CSS usage, audits everything against industry standards, and drops it into Figma as a visual spec — for less than a cent per run.*
+
+[IMAGE: Hero - Website URL -> AI Agents -> Figma Visual Spec]
+
+---
+
+## The 5-Day Problem
+
+If you've ever inherited a website and needed to understand its design system, you know the drill. Open DevTools. Click an element. Copy the hex code. Repeat 200 times. Manually check contrast ratios. Squint at font sizes trying to figure out if they follow a scale. Paste everything into a spreadsheet. Spend another day recreating it in Figma.
+
+I've done this dozens of times across 10+ years managing design systems. It takes **3-5 days per site**. And honestly? The result is never complete.
+
+I wanted something that thinks the way a design team does — one person extracting values, another classifying colors, someone checking accessibility, and a lead synthesizing it all into clear recommendations.
+
+So I built one. Three versions and many mistakes later, here's what actually works.
+
+---
+
+## What It Does (The 30-Second Version)
+
+You paste a URL. The system visits the site, extracts every design token it can find (colors, fonts, spacing, shadows, border radius), classifies and normalizes them, runs accessibility and consistency checks, then hands the data to 4 AI agents who analyze it like a senior design team.
+
+You get a clean JSON file. Drop it into Figma with a custom plugin. Out comes a full visual spec page — every token displayed, organized, with AA compliance badges.
+
+**15 minutes. Not 5 days.**
+
+---
+
+## How It Works: One Workflow, Three Layers
+
+The biggest lesson from building V1 and V2 was this: **don't use AI for things math can do better.** My first version used a language model for everything — including contrast ratio calculations. It cost $1 per run and hallucinated the math.
+
+V3 splits the work into three layers. The first two are free. Only the third uses AI, and only for tasks that genuinely need judgment.
+
+[IMAGE: Architecture + Workflow combined — URL enters Layer 1, flows through Layer 2, then Layer 3, out to Figma]
+
+### Layer 1 — Extraction & Normalization (Free, ~90 seconds)
+
+A headless browser (Playwright) visits your site at two screen sizes — desktop and mobile — and pulls design values from **8 different sources**: computed styles, CSS variables, inline styles, SVG attributes, stylesheets, external CSS files, page scan, and a deep CSS parser (Firecrawl) that bypasses restrictions.
+
+Why 8 sources? Because no single method catches everything. A brand color might live in a CSS variable, an inline style on a hero section, and an SVG logo — all at once. Casting a wide net means fewer missed tokens.
+
+The raw output is messy. You'll get the same blue in three slightly different hex values. Border radius values like `"0px 0px 16px 16px"` that Figma can't use. Shadow CSS strings with no meaningful names.
+
+The normalizer cleans all of this:
+
+- **Colors** — Merges near-duplicates (if two blues are almost identical, keep one). Assigns a hue family and numeric shade: `color.blue.500`, `color.neutral.200`. Never vague labels like "light" or "dark."
+- **Border Radius** — Parses multi-value shorthand, converts percentages and rem units to pixels, removes duplicates, and names them logically: `radius.sm` (4px), `radius.md` (8px), `radius.full` (9999px).
+- **Shadows** — Breaks down CSS shadow strings into components, filters out fake shadows (like spread-only borders), sorts by blur amount, and always produces 5 clean elevation levels: `shadow.xs` through `shadow.xl`.
+
+Nothing here uses AI. It's parsing, math, and sorting.
+
+### Layer 2 — Classification & Rules (Free, <1 second)
+
+This is where V3 made its biggest leap. Instead of asking an AI to figure out which color is "brand primary," I wrote 815 lines of deterministic code that reads the CSS evidence directly.
+
+**The Color Classifier** looks at how each color is actually used on the page:
+
+- A saturated color on `<button>` elements, appearing 30+ times? That's a brand color.
+- A low-saturation color on `<p>` and `<span>` text? That's a text color.
+- A neutral on `<div>` and `<body>` backgrounds? That's a background color.
+- A red with high saturation appearing infrequently? Likely an error/feedback color.
+- Everything else goes into the palette by hue family.
+
+Every single decision gets logged with evidence: *"#06b2c4 classified as brand — found on background-color of button elements, frequency 33."* Run it twice, get the exact same result. An LLM can't promise that.
+
+The classifier also caps each category (max 3 brand colors, max 3 text colors, etc.) so you don't end up with 15 things all called "brand."
+
+**The Rule Engine** then runs pure-math checks on the classified tokens:
+
+- **Accessibility**: Tests actual foreground/background color pairs found on the page (not just "does this color pass on white?"). Generates AA-compliant alternatives automatically.
+- **Type Scale**: Calculates the ratio between consecutive font sizes, finds the closest standard scale (Major Third, Minor Third, etc.), and flags inconsistencies.
+- **Spacing Grid**: Detects the mathematical base (4px? 8px?) and measures how well the site's spacing values align.
+- **Color Statistics**: Counts near-duplicates, hue distribution, and saturation patterns.
+
+The result is a consistency score out of 100, backed entirely by data.
+
+### Layer 3 — 4 AI Agents (~$0.003)
+
+Now the AI enters — but with strict guardrails. Each agent has one job, uses one model, and is **advisory only**. They cannot override the classifier's naming.
+
+**AURORA (Brand Advisor)** — *Qwen 72B*
+Looks at the classified colors and identifies brand strategy. Is it complementary? Monochrome? Which palette color deserves promotion to a semantic role like `brand.primary`? AURORA can suggest promotions, but a filter (`filter_aurora_naming_map`) rejects anything that isn't a valid semantic role. No creative renaming allowed.
+
+**ATLAS (Benchmark Advisor)** — *Llama 3.3 70B*
+Compares your extracted system against 8 industry design systems (Material 3, Shopify Polaris, Atlassian, Carbon, Apple HIG, Tailwind, Ant Design, Chakra). Tells you which one you're closest to and what it would take to align: *"You're 87% aligned to Polaris. Closing the type scale gap takes about an hour."*
+
+**SENTINEL (Best Practices Auditor)** — *Qwen 72B*
+Scores your system across 6 checks (AA compliance, type scale consistency, spacing grid, near-duplicates, etc.) and prioritizes fixes by business impact. Must cite actual data from the rule engine — if the engine found 67 AA failures, SENTINEL can't claim accessibility "passes." A cross-reference critic catches contradictions.
+
+**NEXUS (Head Synthesizer)** — *Llama 3.3 70B*
+Takes everything — classifier output, rule engine scores, all three agents' analyses — and produces a final executive summary. Evaluates from two perspectives (accessibility-weighted vs. balanced), picks the one that best reflects reality, and outputs a ranked top-3 action list with specific hex values and effort estimates.
+
+```
+NEXUS Summary:
+  Score: 68/100
+  Top Action: Fix brand primary contrast (#06b2c4 -> #048391)
+              Impact: HIGH | Effort: 5 min | Affects 40% of CTAs
+```
+
+---
+
+## The Naming Problem (And Why It Matters)
+
+This deserves its own callout because it was the hardest problem to solve — and it's invisible to most people.
+
+In V2, three different systems produced color names:
+
+| System | Output | Example |
+|--------|--------|---------|
+| Normalizer | Word shades | `color.blue.light` |
+| Export function | Numeric shades | `color.blue.500` |
+| AURORA (LLM) | Creative names | `brand.primary` |
+
+The result in Figma? `blue.300`, `blue.dark`, `blue.light`, and `blue.base` — all in the same file. Completely unusable.
+
+V3 established a strict chain of command:
+
+1. **Color Classifier** (primary authority) — names every color, deterministically
+2. **AURORA** (secondary, advisory) — can suggest semantic role promotions only
+3. **Normalizer** (fallback) — only if the classifier hasn't run
+
+One authority. No conflicts. Clean output every time.
+
+---
+
+## Into Figma: The Last Mile
+
+The system exports W3C DTCG-compliant JSON — the industry standard for design tokens (finalized October 2025). Every token includes its type, value, description, and extraction metadata:
+
+```json
+{
+  "color": {
+    "brand": {
+      "primary": {
+        "$type": "color",
+        "$value": "#005aa3",
+        "$description": "[classifier] brand: primary_action"
+      }
+    }
+  },
+  "radius": {
+    "md": { "$type": "dimension", "$value": "8px" }
+  }
+}
+```
+
+A custom Figma plugin imports this JSON and:
+
+1. Creates **Figma Variables** (color, number, and string collections)
+2. Creates **Styles** (paint, text, and effect styles)
+3. Auto-generates a **Visual Spec Page** — separate frames for typography, colors, spacing, radius, and shadows, with AA compliance badges on every color swatch
+
+[IMAGE: Figma visual spec page showing organized tokens with AA badges]
+
+You run the full workflow twice — once for the AS-IS (what exists today) and once for the TO-BE (with accepted improvements). Place them side by side in Figma and the story tells itself:
+
+| Token | AS-IS | TO-BE |
+|-------|-------|-------|
+| Brand Primary | #06b2c4 (fails AA) | #048391 (passes AA) |
+| Type Scale | ~1.18 (random) | 1.25 (Major Third) |
+| Spacing | Mixed values | 8px grid |
+| Unique Colors | 143 | ~20 semantic |
+| Radius | Raw CSS garbage | none/sm/md/lg/xl/full |
+| Shadows | Unsorted, unnamed | 5 progressive levels |
+
+---
+
+## What It Costs
+
+| Component | Cost |
+|-----------|------|
+| Extraction + Normalization | $0.00 |
+| Color Classifier (815 lines of code) | $0.00 |
+| Rule Engine (WCAG, type scale, spacing) | $0.00 |
+| 4 AI Agents (via HuggingFace Inference) | ~$0.003 |
+| **Total per analysis** | **~$0.003** |
+
+The free layers do 90% of the work. The AI adds context, benchmarks, and synthesis — the parts that genuinely need language understanding.
+
+For context, V1 (all-LLM) cost $0.50-1.00 per run. Same output quality? Worse, actually — it hallucinated contrast ratios and named colors inconsistently.
+
+---
+
+## When Things Break
+
+The system always produces output, even when parts fail:
+
+| Failure | What Happens |
+|---------|-------------|
+| AI agents are down | Classifier + rule engine still work (free) |
+| Firecrawl unavailable | 7 Playwright sources still extract |
+| AURORA returns nonsense | Filter strips invalid names automatically |
+| Full AI layer offline | You still get classified tokens + accessibility audit |
+
+The architecture was designed so that the free deterministic layers are independently useful. The AI layer is a bonus, not a dependency.
+
+---
+
+## What I Learned Building Three Versions
+
+**Use AI where it adds value, not everywhere.** My WCAG contrast checker is mathematically exact. An LLM doing the same calculation? Slower, expensive, and sometimes wrong. Rules handle certainty. AI handles ambiguity.
+
+**When multiple systems touch the same data, pick one authority.** V2's three competing naming systems was the single worst architectural decision. Not because any individual system was bad — but because nobody was in charge.
+
+**Benchmarks change conversations.** "Your type scale is inconsistent" gets a nod. "You're 87% aligned to Shopify Polaris and closing the gap takes an hour" gets a meeting scheduled.
+
+**Specialized agents beat mega-prompts.** One giant prompt doing brand analysis + benchmarking + accessibility audit = confused output. Four agents, each with a single job = focused, reliable results.
+
+**Semi-automation beats full automation.** The workflow has deliberate human checkpoints: review the AS-IS before modernizing, accept or reject each suggestion, inspect the TO-BE before shipping. AI as copilot, not autopilot.
+
+**Standards create ecosystems.** Adopting W3C DTCG v1 means our output works with Tokens Studio, Style Dictionary v4, and any tool following the spec. Custom formats create lock-in.
+
+---
+
+## The Tech Under the Hood
+
+**AI Agent App:** Playwright (extraction), Firecrawl (deep CSS), Gradio (UI), Qwen 72B + Llama 3.3 70B (agents), HuggingFace Spaces + Inference API (hosting), Docker, 148 tests.
+
+**Figma Plugin:** Custom plugin (v7), W3C DTCG v1 import, Variables API, auto-generated visual spec pages, Tokens Studio compatible.
+
+**Open Source:** Full code on GitHub — [link]
+
+---
+
+## What's Next: From Tokens to Components
+
+The token story is complete. But design systems aren't just tokens — they're **components**.
+
+After researching 30+ tools, I found a genuine gap: **no production tool takes DTCG JSON and outputs Figma components with proper variants.** Every existing tool either imports tokens without creating components, creates components from its own format but can't consume yours, or uses AI non-deterministically.
+
+The Figma Plugin API supports everything needed. Coming in Episode 7: auto-generating Button (60 variants), TextInput, Card, Toast, and Checkbox/Radio — directly from the extracted tokens. Same tokens in, same components out.
+
+---
+
+*Episode 6 of "AI in My Daily Work."*
+
+*Previous episodes:*
+- *Episode 5: Building a 7-Agent UX Friction Analysis System in Databricks*
+- *Episode 4: Automating UI Regression Testing with AI Agents (Part-1)*
+- *Episode 3: Building a Multi-Agent Review Intelligence System*
+- *Episode 2: How I Use a Team of AI Agents to Automate Secondary Research*
+
+*What are you automating? Drop a comment — I'd love to hear what you're building.*
+
+---
+
+**About the Author**
+
+I'm Riaz, a UX Design Manager with 10+ years in consumer apps. I combine design thinking with AI engineering to build tools that make design decisions faster and more data-driven.
+
+**Connect:** LinkedIn | Medium: @designwithriaz | GitHub
+
+---
+
+#AIAgents #DesignSystems #UXDesign #Figma #DesignTokens #Automation #AIEngineering #HuggingFace #WCAG #W3CDTCG
+
+---
+
+*~9 min read*

output_json/file (16).json

@@ -1,584 +0,0 @@
-{
-  "color": {
-    "background": {
-      "primary": {
-        "$type": "color",
-        "$value": "#ebedef"
-      },
-      "secondary": {
-        "$type": "color",
-        "$value": "#bfbfbf"
-      }
-    },
-    "border": {
-      "default": {
-        "$type": "color",
-        "$value": "#122f44"
-      }
-    },
-    "text": {
-      "primary": {
-        "$type": "color",
-        "$value": "#000000"
-      },
-      "secondary": {
-        "$type": "color",
-        "$value": "#999999"
-      },
-      "muted": {
-        "$type": "color",
-        "$value": "#cccccc"
-      }
-    },
-    "brand": {
-      "primary": {
-        "$type": "color",
-        "$value": "#005aa3"
-      },
-      "secondary": {
-        "$type": "color",
-        "$value": "#ff0000"
-      }
-    },
-    "feedback": {
-      "success": {
-        "$type": "color",
-        "$value": "#3c7312"
-      },
-      "warning": {
-        "$type": "color",
-        "$value": "#ffdc00"
-      }
-    },
-    "button": {
-      "$type": "color",
-      "$value": "#ffffff"
-    },
-    "purple": {
-      "500": {
-        "$type": "color",
-        "$value": "#885b9a"
-      }
-    },
-    "neutral": {
-      "dark": {
-        "$type": "color",
-        "$value": "#333333"
-      },
-      "light": {
-        "$type": "color",
-        "$value": "#b2b8bf"
-      }
-    },
-    "blue": {
-      "dark": {
-        "$type": "color",
-        "$value": "#2c3e50"
-      },
-      "light": {
-        "$type": "color",
-        "$value": "#b9daff"
-      },
-      "300": {
-        "$type": "color",
-        "$value": "#7fdbff"
-      },
-      "base": {
-        "$type": "color",
-        "$value": "#6f7597"
-      }
-    },
-    "yellow": {
-      "light": {
-        "$type": "color",
-        "$value": "#fff6db"
-      }
-    },
-    "orange": {
-      "light": {
-        "$type": "color",
-        "$value": "#d0bfa4"
-      },
-      "base": {
-        "$type": "color",
-        "$value": "#a85410"
-      },
-      "100": {
-        "$type": "color",
-        "$value": "#fdebdd"
-      }
-    },
-    "green": {
-      "500": {
-        "$type": "color",
-        "$value": "#2ecc40"
-      }
-    },
-    "red": {
-      "base": {
-        "$type": "color",
-        "$value": "#ff2d55"
-      }
-    }
-  },
-  "font": {
-    "display": {
-      "2xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "68px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "60px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      },
-      "xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "58px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "50px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      },
-      "lg": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "48px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "42px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      },
-      "md": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "40px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "34px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      }
-    },
-    "heading": {
-      "xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "34px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "30px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      },
-      "lg": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "28px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "24px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      },
-      "md": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "24px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "20px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      },
-      "sm": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "20px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "16px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      }
-    },
-    "body": {
-      "lg": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "16px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "14px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        }
-      },
-      "md": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "14px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "12px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        }
-      },
-      "sm": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "12px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "sans-serif",
-            "fontSize": "10px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        }
-      }
-    },
-    "caption": {
-      "desktop": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "sans-serif",
-          "fontSize": "10px",
-          "fontWeight": "400",
-          "lineHeight": "1.4"
-        }
-      },
-      "mobile": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "sans-serif",
-          "fontSize": "8px",
-          "fontWeight": "400",
-          "lineHeight": "1.4"
-        }
-      }
-    },
-    "overline": {
-      "desktop": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "sans-serif",
-          "fontSize": "8px",
-          "fontWeight": "500",
-          "lineHeight": "1.2"
-        }
-      },
-      "mobile": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "sans-serif",
-          "fontSize": "6px",
-          "fontWeight": "500",
-          "lineHeight": "1.2"
-        }
-      }
-    }
-  },
-  "space": {
-    "1": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "8px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "8px"
-      }
-    },
-    "2": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "16px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "16px"
-      }
-    },
-    "3": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "24px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "24px"
-      }
-    },
-    "4": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "32px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "32px"
-      }
-    },
-    "5": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "40px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "40px"
-      }
-    },
-    "6": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "48px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "48px"
-      }
-    },
-    "8": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "56px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "56px"
-      }
-    },
-    "10": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "64px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "64px"
-      }
-    },
-    "12": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "72px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "72px"
-      }
-    },
-    "16": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "80px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "80px"
-      }
-    }
-  },
-  "radius": {
-    "xl": {
-      "$type": "dimension",
-      "$value": "16px"
-    },
-    "3xl": {
-      "$type": "dimension",
-      "$value": "50px"
-    },
-    "full": {
-      "$type": "dimension",
-      "$value": "50%",
-      "9999": {
-        "$type": "dimension",
-        "$value": "9999px"
-      },
-      "100": {
-        "$type": "dimension",
-        "$value": "100%"
-      }
-    },
-    "2xl": {
-      "$type": "dimension",
-      "$value": "24px"
-    },
-    "md": {
-      "$type": "dimension",
-      "$value": "0px 0px 16px 16px",
-      "4": {
-        "$type": "dimension",
-        "$value": "4px"
-      }
-    },
-    "lg": {
-      "$type": "dimension",
-      "$value": "8px"
-    }
-  },
-  "shadow": {
-    "xs": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.2)",
-        "offsetX": "0px",
-        "offsetY": "10px",
-        "blur": "25px",
-        "spread": "0px"
-      }
-    },
-    "sm": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.2)",
-        "offsetX": "0px",
-        "offsetY": "2px",
-        "blur": "30px",
-        "spread": "0px"
-      }
-    },
-    "md": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.04)",
-        "offsetX": "0px",
-        "offsetY": "0px",
-        "blur": "80px",
-        "spread": "0px"
-      }
-    },
-    "lg": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.06)",
-        "offsetX": "0px",
-        "offsetY": "0px",
-        "blur": "80px",
-        "spread": "0px"
-      }
-    },
-    "xl": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.3)",
-        "offsetX": "0px",
-        "offsetY": "16px",
-        "blur": "90px",
-        "spread": "0px"
-      }
-    }
-  }
-}

output_json/file (18).json

@@ -1,584 +0,0 @@
-{
-  "color": {
-    "text": {
-      "primary": {
-        "$type": "color",
-        "$value": "#373737"
-      },
-      "secondary": {
-        "$type": "color",
-        "$value": "#000000"
-      },
-      "tertiary": {
-        "$type": "color",
-        "$value": "#999999"
-      },
-      "quaternary": {
-        "$type": "color",
-        "$value": "#4e4c4a"
-      },
-      "quinary": {
-        "$type": "color",
-        "$value": "#808080"
-      },
-      "senary": {
-        "$type": "color",
-        "$value": "#cccccc"
-      },
-      "septenary": {
-        "$type": "color",
-        "$value": "#404040"
-      },
-      "octonary": {
-        "$type": "color",
-        "$value": "#727272"
-      },
-      "nonary": {
-        "$type": "color",
-        "$value": "#aaaaaa"
-      },
-      "decenary": {
-        "$type": "color",
-        "$value": "#656565"
-      },
-      "undecenary": {
-        "$type": "color",
-        "$value": "#0e0c24"
-      },
-      "duodecenary": {
-        "$type": "color",
-        "$value": "#282828"
-      },
-      "tredecenary": {
-        "$type": "color",
-        "$value": "#151414"
-      }
-    },
-    "bg": {
-      "primary": {
-        "$type": "color",
-        "$value": "#ffffff"
-      },
-      "light": {
-        "$type": "color",
-        "$value": "#f6f6f6"
-      },
-      "medium": {
-        "$type": "color",
-        "$value": "#ecedee"
-      },
-      "error": {
-        "$type": "color",
-        "$value": "#fff2f2"
-      }
-    },
-    "border": {
-      "light": {
-        "$type": "color",
-        "$value": "#d3d3d3"
-      },
-      "medium": {
-        "$type": "color",
-        "$value": "#e4e4e4"
-      },
-      "dark": {
-        "$type": "color",
-        "$value": "#b3b3b3"
-      },
-      "heavy": {
-        "$type": "color",
-        "$value": "#2c3e50"
-      }
-    },
-    "brand": {
-      "primary": {
-        "$type": "color",
-        "$value": "#06b2c4"
-      },
-      "secondary": {
-        "$type": "color",
-        "$value": "#bcd432"
-      },
-      "accent": {
-        "$type": "color",
-        "$value": "#ff1857"
-      },
-      "error": {
-        "$type": "color",
-        "$value": "#f20000"
-      },
-      "info": {
-        "$type": "color",
-        "$value": "#33cccc"
-      },
-      "warning": {
-        "$type": "color",
-        "$value": "#ff8f00"
-      },
-      "success": {
-        "$type": "color",
-        "$value": "#65a121"
-      }
-    },
-    "#333333": {
-      "$type": "color",
-      "$value": "#333333"
-    },
-    "neutral": {
-      "400": {
-        "$type": "color",
-        "$value": "#78808e"
-      }
-    }
-  },
-  "font": {
-    "display": {
-      "2xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "68px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "60px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      },
-      "xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "58px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "50px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      },
-      "lg": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "48px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "42px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      },
-      "md": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "40px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "34px",
-            "fontWeight": "700",
-            "lineHeight": "1.2"
-          }
-        }
-      }
-    },
-    "heading": {
-      "xl": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "34px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "30px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      },
-      "lg": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "28px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "24px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      },
-      "md": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "24px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "20px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      },
-      "sm": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "20px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "16px",
-            "fontWeight": "600",
-            "lineHeight": "1.3"
-          }
-        }
-      }
-    },
-    "body": {
-      "lg": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "16px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "14px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        }
-      },
-      "md": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "14px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "12px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        }
-      },
-      "sm": {
-        "desktop": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "12px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        },
-        "mobile": {
-          "$type": "typography",
-          "$value": {
-            "fontFamily": "Open Sans",
-            "fontSize": "10px",
-            "fontWeight": "400",
-            "lineHeight": "1.5"
-          }
-        }
-      }
-    },
-    "caption": {
-      "desktop": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "Open Sans",
-          "fontSize": "10px",
-          "fontWeight": "400",
-          "lineHeight": "1.4"
-        }
-      },
-      "mobile": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "Open Sans",
-          "fontSize": "8px",
-          "fontWeight": "400",
-          "lineHeight": "1.4"
-        }
-      }
-    },
-    "overline": {
-      "desktop": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "Open Sans",
-          "fontSize": "8px",
-          "fontWeight": "500",
-          "lineHeight": "1.2"
-        }
-      },
-      "mobile": {
-        "$type": "typography",
-        "$value": {
-          "fontFamily": "Open Sans",
-          "fontSize": "6px",
-          "fontWeight": "500",
-          "lineHeight": "1.2"
-        }
-      }
-    }
-  },
-  "space": {
-    "1": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "8px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "8px"
-      }
-    },
-    "2": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "16px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "16px"
-      }
-    },
-    "3": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "24px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "24px"
-      }
-    },
-    "4": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "32px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "32px"
-      }
-    },
-    "5": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "40px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "40px"
-      }
-    },
-    "6": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "48px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "48px"
-      }
-    },
-    "8": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "56px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "56px"
-      }
-    },
-    "10": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "64px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "64px"
-      }
-    },
-    "12": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "72px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "72px"
-      }
-    },
-    "16": {
-      "desktop": {
-        "$type": "dimension",
-        "$value": "80px"
-      },
-      "mobile": {
-        "$type": "dimension",
-        "$value": "80px"
-      }
-    }
-  },
-  "radius": {
-    "xs": {
-      "$type": "dimension",
-      "$value": "1px"
-    },
-    "sm": {
-      "$type": "dimension",
-      "$value": "2px",
-      "3": {
-        "$type": "dimension",
-        "$value": "3px"
-      }
-    },
-    "md": {
-      "$type": "dimension",
-      "$value": "4px",
-      "5": {
-        "$type": "dimension",
-        "$value": "5px"
-      },
-      "6": {
-        "$type": "dimension",
-        "$value": "6px"
-      },
-      "100": {
-        "$type": "dimension",
-        "$value": "100px"
-      }
-    },
-    "lg": {
-      "$type": "dimension",
-      "$value": "8px",
-      "10": {
-        "$type": "dimension",
-        "$value": "10px"
-      }
-    },
-    "xl": {
-      "$type": "dimension",
-      "$value": "16px",
-      "17": {
-        "$type": "dimension",
-        "$value": "17px"
-      }
-    },
-    "2xl": {
-      "$type": "dimension",
-      "$value": "20px"
-    },
-    "3xl": {
-      "$type": "dimension",
-      "$value": "50px"
-    },
-    "full": {
-      "$type": "dimension",
-      "$value": "9999px"
-    }
-  },
-  "shadow": {
-    "xs": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.5)",
-        "offsetX": "0px",
-        "offsetY": "2px",
-        "blur": "4px",
-        "spread": "0px"
-      }
-    },
-    "sm": {
-      "$type": "shadow",
-      "$value": {
-        "color": "rgba(0, 0, 0, 0.15)",
-        "offsetX": "0px",
-        "offsetY": "0px",
-        "blur": "16px",
-        "spread": "0px"
-      }
-    }
-  }
-}

requirements.txt

@@ -1,5 +1,5 @@
 # =============================================================================
-# Design System Extractor v2 — Dependencies
+# Design System Automation — Dependencies
 # =============================================================================
 
 # -----------------------------------------------------------------------------

storage/benchmark_cache.json

@@ -1,20 +0,0 @@
-{
-  "test_system": {
-    "key": "test_system",
-    "name": "Test System",
-    "short_name": "Test",
-    "vendor": "Test Vendor",
-    "icon": "\ud83e\uddea",
-    "typography": {
-      "scale_ratio": 1.25,
-      "base_size": 16
-    },
-    "spacing": {
-      "base": 8
-    },
-    "colors": {},
-    "fetched_at": "2026-02-15T12:12:38.917158",
-    "confidence": "high",
-    "best_for": []
-  }
-}