theme-analyzer — UI design token extraction

Analyzes UI screenshots to extract a complete design token set using Gemini 2.5 Flash (vision) via OpenRouter. Produces three output files: JSON tokens, CSS custom properties, and a human-readable theme report.

Setup

On first use, create the analyze.py script from the embedded source in this file. Write it to ~/.claude/skills/theme-analyzer/analyze.py and make it executable (chmod +x).

Prerequisites

The user's OpenRouter API key must be available as the OPENROUTER_API_KEY environment variable.

When to use

From a screenshot or image file:

• "analyze this UI" + path to screenshot
• "extract the theme from this design"
• "what colors/fonts does this UI use?"
• "reprint this theme" / "recreate this style"
• "get the design tokens from this screenshot"
• "clone this UI's color scheme"

From a live URL:

• "analyze the theme at https://example.com"
• "extract the design tokens from this website"
• "what theme does this site use?"

How to invoke

From an image file

python3 ~/.claude/skills/theme-analyzer/analyze.py "/path/to/screenshot.png"

With a custom theme name

python3 ~/.claude/skills/theme-analyzer/analyze.py "/path/to/screenshot.png" --name "my-app-dark"

From a URL (two-step)

When the user provides a URL instead of an image:

1. First, take a screenshot of the URL using Chrome browser tools:

   • Use mcp__Claude_in_Chrome__tabs_context_mcp to get a tab
   • Navigate to the URL with mcp__Claude_in_Chrome__navigate
   • Take a screenshot with mcp__Claude_in_Chrome__computer (action: screenshot, save_to_disk: true)
   • Use the saved screenshot path

2. Then, run the analyzer on the saved screenshot:

   python3 ~/.claude/skills/theme-analyzer/analyze.py "/path/to/saved/screenshot.png" --name "site-name"
   

Full options

python3 ~/.claude/skills/theme-analyzer/analyze.py "/path/to/image.png" \
  --name "theme-name" \
  --out ~/Pictures/theme-analyzer \
  --no-open

Output

The script produces three files and prints their paths:

1. theme-<ts>-<slug>-tokens.json — Structured design tokens (colors, typography, spacing, borders, shadows)
2. theme-<ts>-<slug>-variables.css — CSS custom properties ready to paste into any project
3. theme-<ts>-<slug>-report.md — Human-readable report with all tokens in organized tables

After running, always read and display the report contents to the user so they can see the extracted theme at a glance.

Error handling

• Missing OPENROUTER_API_KEY → exits 2
• API error → exits 1 with error details
• Failed to parse model response as JSON → exits 3