design-oracle

Design Oracle is an MIT-licensed tool for analyzing a website and extracting its complete design system. It combines a Next.js frontend, FastAPI backend, ARQ worker, Redis, SQLite, and a Playwright/Chromium analysis pipeline. Core capabilities include full-page capture with Playwright, design DNA classification with a visual score and heuristics, component detection for elements such as hero, pricing, nav, and FAQ with bounding boxes, live progress via SSE plus Redis pub/sub, and exports as Tailwind v4 config, React JSX components, JSON design tokens, and a Markdown DESIGN.md report. It also exposes analysis tools through MCP for AI workflows. For setup, Docker Compose is recommended: the repository describes copying .env.example to .env and running docker compose up --build -d, then opening http://localhost:3000. A local start.sh option requires Python 3.12+, Node.js 20+, and Redis 7+, and launches the virtual environment, Playwright Chromium, Redis, ARQ worker, Next.js on port 3000, and FastAPI on port 5000. The API includes health, analyze, status, result, SSE events, screenshot, delete, designs list, and export endpoints for Tailwind, components, design.md, and tokens. Each analysis writes to analyses/{id}/ with screenshot.png, screenshot-overlay.png, result.json, DESIGN.md, tailwind.config.js, components.jsx, and design-tokens.json. The MCP server is available over HTTP SSE at http://localhost:5000/mcp or standalone in stdio mode. A lightweight uvx CLI, design-oracle-mcp, calls the backend over HTTP without requiring Playwright/Chromium. Tool snippets are documented for opencode, Cursor, and Claude Code. A Cloudflare Tunnel script, start-public.sh, can expose the app via a temporary public HTTPS URL. Known limitations: analysis currently uses a single 1440x900 viewport; bot-protected sites may block Playwright, with an optional STEALTH_MODE for basic and intermediate protections, though enterprise protections may still require CAPTCHA or paid proxies; component detection is heuristic rather than ML/vision-based; and SQLite storage is suitable for local or single-user use, not multi-tenant deployments.