antigravity-ipa-workflow/skills/ipa-mockup-analyze/SKILL.md

name: ipa-mockup-analyze description: Extract design specifications from HTML mockups using AI vision and CSS parsing to generate a UI_DESIGN_SPEC.md with design tokens, component mapping, and responsive specs. Use when converting visual prototypes into implementation-ready specs, analyzing HTML mockups for design system extraction, or preparing tech-stack-specific component mappings. Trigger phrases: "analyze html mockups", "extract design tokens from prototypes", "generate ui design spec from mockups".

Overview

Generates docs/UI_DESIGN_SPEC.md from HTML mockups using a hybrid approach: AI vision analysis for visual patterns plus HTML/CSS parsing for exact values. Output serves as single source of truth for UI implementation.

When to Use

• HTML/CSS mockups exist and need to be converted to implementation specs
• Design tokens need to be extracted for a component library
• Tech-stack-specific component mappings are needed (e.g., shadcn/ui, Tailwind)
• Preparing accurate implementation tasks from visual designs

Don't Use When

• No HTML mockups exist yet (run ipa-design first)
• Only text-based specifications are needed

Input

Default mockup directory: docs/UI-new-mock/ or docs/prototypes/

Custom: pass path as argument.

Workflow

Step 1: Discover Mockup Files

Find all HTML files in mockup directory.

Step 2: Screenshot Each Mockup

Capture visual representation of each HTML file.

Step 3: AI Vision Analysis

For each screenshot, extract:

1. Color Palette (hex values)
2. Typography (fonts, sizes, weights)
3. Spacing System (padding, margin, gap)
4. Border and Effects (radius, shadows, blur)
5. Component Patterns (buttons, inputs, cards)
6. Layout Structure (grid, container widths)
7. Responsive Behavior (breakpoint changes)

Step 4: HTML/CSS Parsing (Verification)

Parse HTML/CSS to verify AI vision analysis:

• Extract CSS custom properties (--color-*, --font-*, etc.)
• Extract Tailwind config if present
• Priority: CSS values > AI vision estimates (CSS is ground truth)

Step 5: Component Mapping

Map HTML patterns to target tech stack:

• Which component library component?
• Which utility classes?
• Custom component needed?

Step 6: Generate UI_DESIGN_SPEC.md

Write docs/UI_DESIGN_SPEC.md with design tokens, component mapping, and responsive specs.

Output Template

# UI Design Specification

**Generated:** {date}
**Source:** {mockup-directory}
**Screens Analyzed:** {count}

## Design Tokens

### Colors
| Token | Hex | Tailwind | Usage | Mockup Source |
|-------|-----|----------|-------|---------------|
| primary | #2563EB | blue-600 | Primary CTA, links | 01-login.html line 12 |

### Typography
| Element | Font | Size | Weight | Tailwind |
|---------|------|------|--------|----------|
| H1 | Outfit | 48px | 700 | text-5xl font-bold |

### Spacing System
| Token | Value | Tailwind | Usage |
|-------|-------|----------|-------|
| md | 16px | p-4 | Card padding |

## Component Mapping

### 01-login-screen.html
**HTML Structure:** [Extracted HTML]
**Tech Stack Implementation:** [Framework-specific code]

## Quality Checklist
- [ ] All colors extracted
- [ ] All fonts identified
- [ ] Spacing system consistent
- [ ] Components mapped
- [ ] Responsive tested

Notes

• AI vision provides visual pattern extraction
• HTML/CSS parsing provides exact values (ground truth)
• Hybrid approach ensures accuracy
• Does not modify or create code files