design-system-cli

name	design-system-cli
description	Complete Design System Reverse Engineering (DSRE) + Functional Cloning CLI - Extract visual design (tokens, assets) AND functional behavior (workflows, state machines, business rules) from any web application
license	MIT
allowed-tools	["Read","Write","Edit","Bash","Grep","Glob"]

Design System CLI Skill

Complete reverse engineering toolkit for cloning BOTH the visual design AND functional behavior of web applications.

Overview

The design-system-cli provides two complementary capabilities:

Part A: Visual Cloning (Phases 1-8)

1. Design Tokens: Colors, typography, spacing, border-radius, shadows, breakpoints
2. Visual Assets: Images, videos, SVG icons, background images with metadata
3. Asset Prompts: LLM-ready prompts for recreating extracted visual assets
4. Component Generation: React components from HTML structure
5. Hard Fork & Rebrand: Transform sites into legally clean templates

Part B: Functional Cloning (Phases 9-12)

1. Interaction Recording: Capture user sessions with clicks, typing, network calls
2. Flow Extraction: Identify screens and user journeys
3. Entity Inference: Extract data models from API payloads
4. Business Rules: State machines, validation rules, permissions
5. App Generation: Generate working Next.js applications from behavioral data

Result: Clone BOTH the look AND behavior of any web application

Core Capabilities

Part A: Visual Cloning (Phases 1-8)

1. Design Token Extraction

Command: ds pipeline --url <url> --framework <framework>

Frameworks Supported:

• react-tailwind - Tailwind CSS config for React
• vue-tailwind - Tailwind CSS config for Vue
• react-mui - Material-UI theme for React
• angular-material - Angular Material theme
• css-variables - Plain CSS custom properties

Output Files:

• raw-tokens.json - Raw extracted tokens
• normalized-tokens.json - Normalized design system
• <framework>.config.js - Framework-specific config

Example:

ds pipeline --url https://labs.google/aifuturesfund/ --framework react-tailwind

2. Visual Asset Extraction

Command: ds pipeline --url <url> --assets-out <path>

Extracts:

• Images (<img> tags) with dimensions, alt text, aspect ratio
• Videos (<video> tags) with dimensions, controls, autoplay state
• SVG icons and illustrations
• Background images from computed styles
• Dominant colors from each asset

Asset Metadata:

• id: Unique identifier (img-1, video-1, svg-1, bg-1)
• type: image | video | icon | illustration | animation
• role: hero | thumbnail | avatar | background | decoration | content
• src: Asset URL
• alt: Alternative text (images only)
• aspectRatio: Width:height ratio (16:9, 1:1, etc.)
• dominantColors: Array of prominent colors
• dimensions: {width, height} in pixels

Output:

{
  "page": "https://example.com",
  "capturedAt": "2025-11-19T13:18:46.363Z",
  "assets": [
    {
      "id": "img-1",
      "type": "image",
      "role": "hero",
      "src": "https://example.com/hero.webp",
      "alt": "Hero image description",
      "aspectRatio": "16:9",
      "dominantColors": ["#1a73e8", "#ffffff"],
      "dimensions": {"width": 1920, "height": 1080}
    }
  ]
}

3. Asset Prompt Generation

Command: ds assets-prompts --assets <assets.json> --out <asset-prompts.json>

Generates LLM-ready prompts for image recreation via fal-ai models:

Output Format:

{
  "page": "https://example.com",
  "items": [
    {
      "id": "img-1",
      "type": "image",
      "target_model": "fal-ai/image",
      "prompt": "TODO: describe hero for https://example.com",
      "negative_prompt": "text, watermark, logos, UI chrome",
      "guidance": {
        "aspect_ratio": "16:9",
        "color_palette": ["#1a73e8", "#ffffff"],
        "style_notes": "role: hero",
        "role": "hero"
      }
    }
  ]
}

Workflow:

1. Extract assets with ds pipeline --assets-out assets.json
2. Generate prompts with ds assets-prompts --assets assets.json --out asset-prompts.json
3. Review and enhance prompts with asset context
4. Use prompts with fal-ai image generation models
5. Replace original assets with AI-generated versions

4. Figma Integration

Command: ds figma --tokens <normalized-tokens.json> --out <figma-plugin/>

Generates a ready-to-use Figma plugin with:

• Color styles from token palette
• Text styles from typography tokens
• Interactive UI for import confirmation
• Complete manifest.json configuration

Plugin Usage:

1. Generate plugin: ds figma --tokens normalized-tokens.json
2. Load plugin in Figma: Plugins → Development → Import from manifest
3. Run plugin to import design tokens as Figma styles

---

Part B: Functional Cloning (Phases 9-12)

Clone the behavior and workflows of applications, not just the visual design.

5. Interaction Recording (Phase 9)

Command: ds trace --url <url> --out trace.json --duration <ms>

Captures:

• User interactions (clicks, typing, navigation, scrolls)
• Network requests and responses with full payloads
• DOM snapshots at each screen transition
• Form submissions and API calls
• Session replay data

Output: trace.json with complete interaction history

Example:

ds trace --url https://gradual.com --out gradual-trace.json --duration 30000

Use Cases:

• Record user workflows for analysis
• Document complex application flows
• Capture API contracts and data models
• Build behavioral test suites

6. Flow Extraction (Phase 10)

Command: ds flows --trace <trace.json> --out-screens <screens.json> --out-flows <flows.json>

Extracts:

• Distinct screens from DOM snapshots
• User journeys and navigation patterns
• Screen transition triggers
• Flow confidence scoring

Outputs:

• screens.json - Unique screens with metadata
• flows.json - User journeys with step-by-step actions

Example:

ds flows --trace gradual-trace.json --out-screens screens.json --out-flows flows.json

Use Cases:

• Map application navigation structure
• Document user journeys
• Identify key user paths
• Analyze flow complexity

7. Entity Inference (Phase 11)

Command: ds entities --trace <trace.json> --out entities.json

Infers:

• Data models from network payloads
• Field types and schemas (string, number, boolean, date-time, array, object)
• Required vs optional fields
• CRUD operations per entity
• Field relationships and metadata

Output: entities.json with complete data model

Example:

ds entities --trace gradual-trace.json --out entities.json

Use Cases:

• Reverse engineer database schemas
• Document API contracts
• Generate TypeScript types
• Build data models for new systems

8. Business Rules Extraction (Phase 12)

Command: ds rules --trace <trace.json> --flows <flows.json> --entities <entities.json> --out rules.json

Extracts:

• State machines from entity status fields
• State transitions from user flows
• Validation rules from field types and API errors
• Permission rules from CRUD operation patterns
• Business rules for workflows and immutability

Output: rules.json with complete rule system

Example:

ds rules \
  --trace gradual-trace.json \
  --flows flows.json \
  --entities entities.json \
  --out rules.json

Rule Types:

• State Machines: Lifecycle states and transitions (draft → active → archived)
• Validation Rules: Field constraints (required, email, max:500, min:3)
• Permission Rules: Authorization requirements (create, update, delete, approve)
• Business Rules: Workflow logic and field immutability

9. Functional App Generation (Phase 12)

Command: ds fx-codegen --screens <screens.json> --flows <flows.json> --entities <entities.json> --rules <rules.json> --out <dir>

Generates:

• Complete Next.js 14 application with App Router
• Typed API clients for each entity
• List and detail pages for all entities
• TypeScript types from entity schemas
• React components with validation
• README with functionality spec

Output: Working Next.js application

Example:

ds fx-codegen \
  --screens screens.json \
  --flows flows.json \
  --entities entities.json \
  --rules rules.json \
  --out apps/gradual-clone

Generated Structure:

apps/gradual-clone/
├── app/
│   ├── layout.tsx          # App shell with navigation
│   ├── [entity]s/
│   │   ├── page.tsx       # List page
│   │   └── [id]/page.tsx  # Detail page
├── lib/
│   ├── types.ts           # TypeScript types from entities
│   └── api/
│       └── [entity]s.ts   # CRUD API clients
├── package.json           # Next.js 14 dependencies
└── README.md             # Functionality spec

Complete Workflows

Workflow 1: Complete Functional Clone (Phases 9-12)

Goal: Clone an entire SaaS application (like Gradual, Linear, or Notion)

# Step 1: Record user interactions (30 seconds)
ds trace --url https://gradual.com --out gradual-trace.json --duration 30000

# Step 2: Extract screens and user flows
ds flows --trace gradual-trace.json --out-screens gradual-screens.json --out-flows gradual-flows.json

# Step 3: Infer data models from API calls
ds entities --trace gradual-trace.json --out gradual-entities.json

# Step 4: Extract business rules and state machines
ds rules \
  --trace gradual-trace.json \
  --flows gradual-flows.json \
  --entities gradual-entities.json \
  --out gradual-rules.json

# Step 5: Generate working Next.js application
ds fx-codegen \
  --screens gradual-screens.json \
  --flows gradual-flows.json \
  --entities gradual-entities.json \
  --rules gradual-rules.json \
  --out apps/gradual-clone

# Step 6: Run the cloned application
cd apps/gradual-clone
npm install
npm run dev  # http://localhost:3000

Result: Complete working application with:

• All screens and navigation
• Full data models and TypeScript types
• State machines and lifecycle management
• Validation rules and permissions
• CRUD operations and API clients

Workflow 2: Combined Visual + Functional Clone

Goal: Clone BOTH the look AND behavior of an application

# Part A: Visual Cloning
ds pipeline --url https://example.com --framework react-tailwind --assets-out assets.json
ds assets-prompts --assets assets.json --out asset-prompts.json

# Part B: Functional Cloning
ds trace --url https://example.com --out trace.json --duration 30000
ds flows --trace trace.json --out-screens screens.json --out-flows flows.json
ds entities --trace trace.json --out entities.json
ds rules --trace trace.json --flows flows.json --entities entities.json --out rules.json
ds fx-codegen --screens screens.json --flows flows.json --entities entities.json --rules rules.json --out apps/full-clone

# Part C: Merge Results
# Copy visual assets into functional app
cp -r design-system/* apps/full-clone/
# Use generated Tailwind config
cp tailwind.config.js apps/full-clone/

# Run complete clone
cd apps/full-clone
npm install
npm run dev

Result: Pixel-perfect visual clone with complete functional behavior

Use Cases

Visual Cloning Use Cases

Full Design System Extraction

# Extract everything from a website
ds pipeline --url https://example.com --framework react-tailwind --assets-out assets.json

# Generate asset recreation prompts
ds assets-prompts --assets assets.json --out asset-prompts.json

# Generate Figma plugin
ds figma --tokens normalized-tokens.json --out figma-plugin/

Functional Cloning Use Cases

Clone SaaS Application Workflows

# Record and clone key user journeys
ds trace --url https://linear.app --out linear-trace.json
ds flows --trace linear-trace.json --out-screens screens.json --out-flows flows.json
ds fx-codegen --screens screens.json --flows flows.json --entities entities.json --rules rules.json --out apps/linear-clone

Use Cases:

• Recreate project management workflows (Linear, Asana, Jira)
• Clone CRM functionality (Salesforce, HubSpot)
• Reverse engineer SaaS features for competitive analysis
• Build similar apps with custom branding

Document Legacy Applications

# Record enterprise application behavior
ds trace --url https://sap-system.company.com --out sap-trace.json
ds flows --trace sap-trace.json --out-screens sap-screens.json --out-flows sap-flows.json
ds entities --trace sap-trace.json --out sap-entities.json

Use Cases:

• Document undocumented legacy systems
• Extract business rules from old applications
• Modernize legacy workflows
• Create training materials and documentation

Extract API Contracts

# Capture all API calls and payloads
ds trace --url https://api-driven-app.com --out api-trace.json
ds entities --trace api-trace.json --out api-entities.json

Use Cases:

• Reverse engineer API specifications
• Generate TypeScript types from live APIs
• Document third-party integrations
• Build API client libraries

Asset Recreation Workflow

# 1. Extract visual assets with metadata
ds pipeline --url https://example.com --assets-out assets.json

# 2. Generate LLM-ready prompts
ds assets-prompts --assets assets.json --out asset-prompts.json

# 3. Review asset-prompts.json and enhance TODO prompts with descriptions
# Example: Change "TODO: describe hero for https://example.com"
#       To: "Modern abstract geometric pattern in blue and white, minimalist design, hero banner"

# 4. Use enhanced prompts with fal-ai for image generation
# 5. Replace original assets with AI-generated versions in your codebase

Token-Only Extraction

# Extract design tokens without assets
ds extract --url https://example.com --out raw-tokens.json
ds normalize --raw raw-tokens.json --out normalized-tokens.json
ds codegen --normalized normalized-tokens.json --framework react-tailwind

Integration with SuperClaude

Auto-Activation Keywords

Visual Cloning:

• design system, extract tokens, recreate page
• Tailwind config, MUI theme, component library
• design tokens, Figma, design analysis
• visual assets, asset recreation, image generation
• fal-ai, asset prompts, regenerate images

Functional Cloning:

• clone application, reverse engineer, extract workflows
• trace interactions, record behavior, user flows
• state machine, business rules, validation rules
• data models, API contracts, TypeScript types
• functional clone, behavior extraction, workflow analysis

File Pattern Detection

• tailwind.config.*, theme.*, tokens.*
• *.design.json
• assets.json, asset-prompts.json
• trace.json, flows.json, entities.json, rules.json
• screens.json

Typical Operations

Visual Operations:

• extract - Extract raw design tokens from website
• normalize - Normalize tokens to standard format
• generate - Generate framework-specific configs
• analyze - Analyze design system consistency
• recreate - Recreate page with extracted design system
• regenerate_assets - Regenerate visual assets with AI
• create_prompts - Create LLM-ready asset prompts

Functional Operations:

• trace - Record user interactions and network calls
• extract_flows - Extract screens and user journeys
• infer_entities - Infer data models from API calls
• extract_rules - Extract business rules and state machines
• generate_app - Generate functional Next.js application
• clone_behavior - Clone application workflows
• document_system - Document legacy application behavior

Command Integration

Visual Cloning:

• /build + design-system-cli → Extract and generate configs
• /analyze + design-system-cli → Analyze design consistency
• /improve + design-system-cli → Enhance design system
• /design + design-system-cli → Design system workflows

Functional Cloning:

• /analyze + design-system-cli → Analyze application workflows
• /document + design-system-cli → Document application behavior
• /build + design-system-cli → Generate functional clone
• /troubleshoot + design-system-cli → Debug workflow extraction

Asset Context Schema

Complete schema documentation: docs/asset_context_schema.md

Core Types:

• Asset: Individual visual asset with metadata
• AssetContext: Complete collection of assets from a page
• AssetPromptEntry: LLM-ready prompt for asset recreation
• AssetPromptsFile: Collection of prompts for all assets

Asset Roles (auto-detected):

• hero: Large prominent images in header/hero sections
• thumbnail: Small preview images in grids/lists
• avatar: Profile pictures and user avatars
• background: Background images and patterns
• decoration: Icons, illustrations, SVG graphics
• content: Main content images and media

Architecture

Monorepo Structure:

packages/
# Visual Cloning (Phases 1-8)
├── core/                   # Shared TypeScript interfaces
├── extractor/              # Playwright-based token and asset extraction
├── normalizer/             # Token normalization and standardization
├── codegen/                # Framework config generation + asset prompt generation
├── figma-bridge/           # Figma plugin generation

# Functional Cloning (Phases 9-12)
├── functional-trace/       # User interaction and network recording
├── functional-flows/       # Screen and flow extraction
├── functional-entities/    # Data model inference from APIs
├── functional-rules/       # Business rules and state machine extraction
└── functional-codegen/     # Next.js application scaffold generation

Complete Processing Pipeline:

VISUAL CLONING:
Website → Playwright → Raw Extraction → Normalization → Code Generation
                    ↓
                Assets.json → Asset Prompts → fal-ai → Regenerated Assets

FUNCTIONAL CLONING:
Website → User Interaction → Trace Recording → Flow Extraction
                                             ↓
                                    Entity Inference → Rules Extraction
                                             ↓
                                    Next.js App Generation

COMBINED:
Visual Design System + Functional Application = Complete Clone

Examples

Example 1: Extract from Google AI Futures Fund

ds pipeline --url https://labs.google/aifuturesfund/ --framework react-tailwind --assets-out assets.json

Output:

• tailwind.config.js with extracted color palette, typography, spacing
• assets.json with 92 visual assets (images, videos, SVGs)

Example 2: Generate Asset Recreation Prompts

ds assets-prompts --assets assets.json --out asset-prompts.json

Output:

• asset-prompts.json with 92 LLM-ready prompts for fal-ai

Example 3: Full Workflow

# Extract design system and assets
ds pipeline --url https://carbondesi

gnsystem.com --framework react-tailwind --assets-out carbon-assets.json

# Generate asset prompts
ds assets-prompts --assets carbon-assets.json --out carbon-prompts.json

# Generate Figma plugin
ds figma --tokens normalized-tokens.json --out figma-plugin/

# Result:
# - tailwind.config.js (design tokens)
# - carbon-assets.json (92 assets with metadata)
# - carbon-prompts.json (LLM-ready recreation prompts)
# - figma-plugin/ (ready-to-use Figma plugin)

Known Limitations

1. Asset Extraction:

   • SVG className handling (fixed with getClassName() helper)
   • Background images only from computed styles
   • No lazy-loaded image detection

2. Prompt Generation:

   • Generic TODO placeholders require manual enhancement
   • No automatic prompt quality assessment
   • Single target model (fal-ai/image)

3. Token Extraction:

   • JavaScript-rendered content requires headless browser
   • Dynamic CSS-in-JS may be missed
   • Some design tokens may be inferred incorrectly

Testing

E2E Test:

# Full pipeline test with real website
node bin/ds pipeline --url https://labs.google/aifuturesfund/ --framework react-tailwind --assets-out test-assets.json

# Verify outputs
ls -lh tailwind.config.js test-assets.json

# Generate and verify prompts
node bin/ds assets-prompts --assets test-assets.json --out test-prompts.json
ls -lh test-prompts.json

Documentation

• README.md - Project overview and getting started
• docs/asset_context_schema.md - Complete asset schema documentation
• SKILL.md - This file (SuperClaude integration guide)

Contributing

When enhancing this skill:

1. Update SKILL.md with new capabilities
2. Add examples for new workflows
3. Update ORCHESTRATOR.md keywords if needed
4. Maintain backward compatibility with existing outputs

Resources

• GitHub: (Repository URL)
• Documentation: docs/
• Examples: See Examples section above
• fal-ai Models: https://fal.ai/models (for asset recreation)