README.md

metadata

title: Design System Extractor v2
emoji: 🎨
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
license: mit

Design System Extractor v2

🎨 A semi-automated, human-in-the-loop agentic system that reverse-engineers design systems from live websites.

🎯 What It Does

When you have a website but no design system documentation (common when the original Sketch/Figma files are lost), this tool helps you:

1. Crawl your website to discover pages
2. Extract design tokens (colors, typography, spacing, shadows)
3. Review and validate extracted tokens with visual previews
4. Upgrade your system with modern best practices (optional)
5. Export production-ready JSON tokens for Figma/code

🧠 Philosophy

This is not a magic button — it's a design-aware co-pilot.

• Agents propose → Humans decide
• Every action is visible, reversible, and previewed
• No irreversible automation

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                        TECH STACK                            │
├──────────────────────────────────────────────────────────────┤
│  Frontend:       Gradio (interactive UI with live preview)   │
│  Orchestration:  LangGraph (agent workflow management)       │
│  Models:         Claude API (reasoning) + Rule-based         │
│  Browser:        Playwright (crawling & extraction)          │
│  Hosting:        Hugging Face Spaces                         │
└──────────────────────────────────────────────────────────────┘

Agent Personas

Agent	Persona	Job
Agent 1	Design Archaeologist	Discover pages, extract raw tokens
Agent 2	Design System Librarian	Normalize, dedupe, structure tokens
Agent 3	Senior DS Architect	Recommend upgrades (type scales, spacing, a11y)
Agent 4	Automation Engineer	Generate final JSON for Figma/code

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js (for some dependencies)

Installation

# Clone the repository
git clone <repo-url>
cd design-system-extractor

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

# Copy environment file
cp config/.env.example config/.env
# Edit .env and add your ANTHROPIC_API_KEY

Running

python app.py

Open http://localhost:7860 in your browser.

📖 Usage Guide

Stage 1: Discovery

1. Enter your website URL (e.g., https://example.com)
2. Click "Discover Pages"
3. Review discovered pages and select which to extract from
4. Ensure you have a mix of page types (homepage, listing, detail, etc.)

Stage 2: Extraction

1. Choose viewport (Desktop 1440px or Mobile 375px)
2. Click "Extract Tokens"
3. Review extracted:
   • Colors: With frequency, context, and AA compliance
   • Typography: Font families, sizes, weights
   • Spacing: Values with 8px grid fit indicators
4. Accept or reject individual tokens

Stage 3: Export

1. Review final token set
2. Export as JSON
3. Import into Figma via Tokens Studio or your plugin

📁 Project Structure

design-system-extractor/
├── app.py                          # Main Gradio application
├── requirements.txt
├── README.md
│
├── config/
│   ├── .env.example                # Environment template
│   ├── agents.yaml                 # Agent personas & settings
│   └── settings.py                 # Configuration loader
│
├── agents/
│   ├── state.py                    # LangGraph state definitions
│   ├── graph.py                    # Workflow orchestration
│   ├── crawler.py                  # Agent 1: Page discovery
│   ├── extractor.py                # Agent 1: Token extraction
│   ├── normalizer.py               # Agent 2: Normalization
│   ├── advisor.py                  # Agent 3: Best practices
│   └── generator.py                # Agent 4: JSON generation
│
├── core/
│   ├── token_schema.py             # Pydantic data models
│   └── color_utils.py              # Color analysis utilities
│
├── ui/
│   └── (Gradio components)
│
└── docs/
    └── CONTEXT.md                  # Context file for AI assistance

🔧 Configuration

Environment Variables

# Required
ANTHROPIC_API_KEY=your_key_here

# Optional
DEBUG=false
LOG_LEVEL=INFO
BROWSER_HEADLESS=true

Agent Configuration

Agent personas and behavior are defined in config/agents.yaml. This includes:

• Extraction targets (colors, typography, spacing)
• Naming conventions
• Confidence thresholds
• Upgrade options

🛠️ Development

Running Tests

pytest tests/

Adding New Features

1. Update token schema in core/token_schema.py
2. Add agent logic in agents/
3. Update UI in app.py
4. Update docs/CONTEXT.md for AI assistance

📦 Output Format

Tokens are exported in a platform-agnostic JSON format:

{
  "metadata": {
    "source_url": "https://example.com",
    "version": "v1-recovered",
    "viewport": "desktop"
  },
  "colors": {
    "primary-500": {
      "value": "#007bff",
      "source": "detected",
      "contrast_white": 4.5
    }
  },
  "typography": {
    "heading-lg": {
      "fontFamily": "Inter",
      "fontSize": "24px",
      "fontWeight": 700
    }
  },
  "spacing": {
    "md": {
      "value": "16px",
      "source": "detected"
    }
  }
}

🤝 Contributing

Contributions are welcome! Please read the contribution guidelines first.

📄 License

MIT

---

Built with ❤️ for designers who've lost their source files.