# 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"
```