reverse-ui

Reverse-Engineer UI — Pixel-Perfect Reproduction Kit

Extract everything needed to reproduce a web application pixel-perfect: design tokens, DOM structure per page, text content, asset inventory, and responsive screenshots.

Input: $ARGUMENTS = <base-url> [/path1,/path2,...] [--kit <path>]

• First token: base URL (required). If empty, ask for one.

• Second token: comma-separated route paths (optional). Defaults to the path of the base URL (or / if none).

• --kit flag (optional): custom Design Kit output path.

  • Omitted → generates kit at ./design-kit-{domain}/ (default)
  • --kit ./my-folder → generates kit at the specified path

• Always generated: Design Kit (Phase 9) and Component Kit (Phase 10) — no way to skip either.

• Always published: Publishes to ./specs/assets/ — automatically creates specs/ directory if it doesn't exist.

• Examples:

  • /reverse-ui https://example.com → extracts / + generates kits + publishes to specs/assets (creates specs/ if needed)
  • /reverse-ui https://example.com /,/pricing,/about → extracts 3 pages + generates kits + publishes
  • /reverse-ui http://localhost:3000 /,/ideation → extracts Home + Ideation + publishes
  • /reverse-ui http://localhost:3000 / --kit ./my-design → kit output to ./my-design/ + publishes

Prerequisites

• agent-browser CLI must be installed (npm i -g agent-browser)
• For authenticated pages, pre-authenticate:

  agent-browser --session-name myapp open https://app.example.com/login
  # ... login manually ...
  

Output Structure

Two directories are generated: a temporary raw extraction (for reference) and a permanent, unified specs/assets/ directory:

reverse-ui-{domain}/                # Temporary raw extraction — JSON + screenshots (AI reference, can be .gitignored)
  manifest.json                     # Index tying everything together
  design-tokens.json                # Global: colors, typography, spacing, shadows, animations, breakpoints, components, layout
  assets.json                       # Global: images, SVGs, fonts, favicons, background images, logos
  images/                           # Downloaded image assets
    photo-1580273916550.jpg
    ...
  pages/
    {page-name}/                    # One directory per page ("/" → "home", "/pricing" → "pricing")
      structure.json                # Semantic DOM tree + text content map (desktop 1440px)
      structure-768.json            # Semantic DOM tree at tablet breakpoint
      structure-375.json            # Semantic DOM tree at mobile breakpoint
      svgs.json                     # Full SVG outerHTML for every inline icon/illustration
      interactions.json             # Animation libraries, scroll triggers, data attributes
      animations.gif                # GIF recording of page scroll + hover interactions
      screenshot-1440.png           # Desktop viewport
      screenshot-1440-full.png      # Desktop full page
      annotated-1440.png            # Desktop with labeled interactive elements
      screenshot-768.png            # Tablet viewport
      screenshot-375.png            # Mobile viewport

specs/assets/                        # Canonical, unified destination — design system + components + raw extraction (Phase 9.5 published here directly)
  manifest.json                      # Unified index (designSystem, components, layouts, tokens, pages sections)
  design-system/                     # Design tokens — CSS + JSON (Phase 9 output, versionable)
    tokens.css                       # CSS custom properties (ready for @theme or :root)
    typography.css                   # @import font URLs + @font-face + font-family mappings
    animations.css                   # @keyframes definitions + animation utility classes
    shadows.css                      # Box-shadow and drop-shadow token definitions
    colors.json                      # Semantic color palette (name → hex/rgba, grouped by role)
    breakpoints.json                 # Named breakpoints with Tailwind prefix mapping
    z-index.json                     # Z-index scale with layer names
    icons/                           # Individual SVG files (deduplicated across pages)
      home.svg
      trends.svg
      ...
  components/                        # Component blueprints + co-located docs (Phase 10 output, versionable)
    sidebar/
      spec.json                      # Component specification
      README.md                      # Component documentation
    module-card/
      spec.json
      README.md
    header/
      spec.json
      README.md
    ...
  layout/                            # Page composition blueprints (Phase 10 output)
    home.json                        # Which components, what grid, what order
    ideation.json
    ...
  tokens/                            # Semantic token mappings (Phase 10 output)
    semantic-tokens.json             # Mapped: "sidebar-bg" → rgba(2,4,16,0.8)
  pages/                             # Raw extraction data (Phase 5 output, organized by page)
    home/
      structure.json
      structure-768.json
      structure-375.json
      svgs.json
      interactions.json
      canvas.json
      screenshot-1440.png
      screenshot-1440-full.png
      annotated-1440.png
      screenshot-768.png
      screenshot-375.png
    ideation/
      (same set)
  images/                            # Downloaded asset images
    photo-*.jpg
  design-tokens.json                 # Raw browser extraction (full token data with enrichment metadata)
  assets.json                        # Images/SVGs inventory from raw extraction