ui-implementer

name	ui-implementer
description	Implements UI components from scratch based on design references (Figma, screenshots, mockups) with intelligent validation and adaptive agent switching. Use when user provides a design and wants pixel-perfect UI implementation with design fidelity validation. Triggers automatically when user mentions Figma links, design screenshots, or wants to implement UI from designs.
allowed-tools	Task, AskUserQuestion, Bash, Read, TaskCreate, TaskUpdate, TaskList, TaskGet, Glob, Grep

UI Implementer

This Skill implements UI components from scratch based on design references using specialized UI development agents with intelligent validation and adaptive agent switching for optimal results.

When to use this Skill

Claude should invoke this Skill when:

Design References Provided:

• User shares a Figma URL (e.g., "Here's the Figma design: https://figma.com/...")
• User provides a screenshot/mockup path (e.g., "I have a design at /path/to/design.png")
• User mentions a design URL they want to implement

Intent to Implement UI:

• "Implement this UI design"
• "Create components from this Figma file"
• "Build this interface from the mockup"
• "Make this screen match the design"

Pixel-Perfect Requirements:

• "Make it look exactly like the design"
• "Implement pixel-perfect from Figma"
• "Match the design specifications exactly"

Examples of User Messages:

• "Here's a Figma link, can you implement the UserProfile component?"
• "I have a design screenshot, please create the dashboard layout"
• "Implement this navbar from the mockup at designs/navbar.png"
• "Build the product card to match this Figma: https://figma.com/..."

DO NOT use this Skill when:

• User just wants to validate existing UI (use browser-debugger or /validate-ui instead)
• User wants to fix existing components (use regular developer agent)
• User wants to implement features without design reference (use regular implementation flow)

Instructions

This Skill implements the same workflow as the /implement-ui command. Follow these phases:

PHASE 0: Initialize Workflow

Create a global todo list to track progress:

TaskCreate:
- PHASE 1: Gather inputs (design reference, component description, preferences)
- PHASE 1: Validate inputs and find target location
- PHASE 2: Launch UI Developer for initial implementation
- PHASE 3: Start validation and iterative fixing loop
- PHASE 3: Quality gate - ensure design fidelity achieved
- PHASE 4: Generate final implementation report
- PHASE 4: Present results and complete handoff

PHASE 1: Gather User Inputs

Step 1: Extract Design Reference

Check if user already provided design reference in their message:

• Scan for Figma URLs: https://figma.com/design/... or https://figma.com/file/...
• Scan for file paths: /path/to/design.png, ~/designs/mockup.jpg
• Scan for remote URLs: http://example.com/design.png

If design reference found in user's message:

• Extract and store as design_reference
• Log: "Design reference detected: [design_reference]"

If NOT found, ask:

I'd like to implement UI from your design reference.

Please provide the design reference:
1. Figma URL (e.g., https://figma.com/design/abc123.../node-id=136-5051)
2. Screenshot file path (local file on your machine)
3. Remote URL (live design reference)

What is your design reference?

Step 2: Extract Component Description

Check if user mentioned what to implement:

• Look for component names: "UserProfile", "navbar", "dashboard", "ProductCard"
• Look for descriptions: "implement the header", "create the sidebar", "build the form"

If found:

• Extract and store as component_description

If NOT found, ask:

What UI component(s) should I implement from this design?

Examples:
- "User profile card component"
- "Navigation header with mobile menu"
- "Product listing grid with filters"
- "Dashboard layout with widgets"

What component(s) should I implement?

Step 3: Ask for Target Location

Ask:

Where should I create this component?

Options:
1. Provide a specific directory path (e.g., "src/components/profile/")
2. Let me suggest based on component type
3. I'll tell you after seeing the component structure

Where should I create the component files?

Store as target_location.

Step 4: Ask for Application URL

Ask:

What is the URL where I can preview the implementation?

Examples:
- http://localhost:5173 (Vite default)
- http://localhost:3000 (Next.js/CRA default)
- https://staging.yourapp.com

Preview URL?

Store as app_url.

Step 5: Ask for UI Developer Codex Preference

Use AskUserQuestion:

Enable intelligent agent switching with UI Developer Codex?

When enabled:
- If UI Developer struggles (2 consecutive failures), switches to UI Developer Codex
- If UI Developer Codex struggles (2 consecutive failures), switches back
- Provides adaptive fixing with both agents for best results

Enable intelligent agent switching?

Options:

• "Yes - Enable intelligent agent switching"
• "No - Use only UI Developer"

Store as codex_enabled (boolean).

Step 6: Validate Inputs

Validate all inputs using the same logic as /implement-ui command:

• Design reference format (Figma/Remote/Local)
• Component description not empty
• Target location valid
• Application URL valid

PHASE 2: Initial Implementation from Scratch

Launch UI Developer agent using Task tool with subagent_type: frontend:ui-developer:

Implement the following UI component(s) from scratch based on the design reference.

**Design Reference**: [design_reference]
**Component Description**: [component_description]
**Target Location**: [target_location]
**Application URL**: [app_url]

**Your Task:**

1. **Analyze the design reference:**
   - If Figma: Use Figma MCP to fetch design screenshot and specs
   - If Remote URL: Use Chrome DevTools MCP to capture screenshot
   - If Local file: Read the file to view design

2. **Plan component structure:**
   - Determine component hierarchy
   - Identify reusable sub-components
   - Plan file structure (atomic design principles)

3. **Implement UI components from scratch using modern best practices:**
   - React 19 with TypeScript
   - Tailwind CSS 4 (utility-first, static classes only, no @apply)
   - Mobile-first responsive design
   - Accessibility (WCAG 2.1 AA, ARIA attributes)
   - Use existing design system components if available

4. **Match design reference exactly:**
   - Colors (Tailwind theme or exact hex)
   - Typography (families, sizes, weights, line heights)
   - Spacing (Tailwind scale: p-4, p-6, etc.)
   - Layout (flexbox, grid, alignment)
   - Visual elements (borders, shadows, border-radius)
   - Interactive states (hover, focus, active, disabled)

5. **Create component files in target location:**
   - Use Write tool to create files
   - Follow project conventions
   - Include TypeScript types
   - Add JSDoc comments

6. **Ensure code quality:**
   - Run typecheck: `npx tsc --noEmit`
   - Run linter: `npm run lint`
   - Run build: `npm run build`
   - Fix any errors

7. **Provide implementation summary:**
   - Files created
   - Components implemented
   - Key decisions
   - Any assumptions

Return detailed implementation summary when complete.

Wait for UI Developer to complete.

PHASE 3: Validation and Adaptive Fixing Loop

Initialize loop variables:

iteration_count = 0
max_iterations = 10
previous_issues_count = None
current_issues_count = None
last_agent_used = None
ui_developer_consecutive_failures = 0
codex_consecutive_failures = 0
design_fidelity_achieved = false

Loop: While iteration_count < max_iterations AND NOT design_fidelity_achieved

Step 3.1: Launch Designer for Validation

Use Task tool with subagent_type: frontend:designer:

Review the implemented UI component against the design reference.

**Iteration**: [iteration_count + 1] / 10
**Design Reference**: [design_reference]
**Component Description**: [component_description]
**Implementation Files**: [List of files]
**Application URL**: [app_url]

**Your Task:**
1. Fetch design reference screenshot
2. Capture implementation screenshot at [app_url]
3. Perform comprehensive design review:
   - Colors & theming
   - Typography
   - Spacing & layout
   - Visual elements
   - Responsive design
   - Accessibility (WCAG 2.1 AA)
   - Interactive states

4. Document ALL discrepancies
5. Categorize by severity (CRITICAL/MEDIUM/LOW)
6. Provide actionable fixes with code snippets
7. Calculate design fidelity score (X/60)

8. **Overall assessment:**
   - PASS ✅ (score >= 54/60)
   - NEEDS IMPROVEMENT ⚠️ (score 40-53/60)
   - FAIL ❌ (score < 40/60)

Return detailed design review report.

Step 3.2: Check if Design Fidelity Achieved

Extract from designer report:

• Overall assessment
• Issue count
• Design fidelity score

If assessment is "PASS":

• Set design_fidelity_achieved = true
• Exit loop (success)

Step 3.3: Determine Fixing Agent (Smart Switching Logic)

function determineFix ingAgent() {
  // If Codex not enabled, always use UI Developer
  if (!codex_enabled) return "ui-developer"

  // Smart switching based on consecutive failures
  if (ui_developer_consecutive_failures >= 2) {
    // UI Developer struggling - switch to Codex
    return "ui-developer-codex"
  }

  if (codex_consecutive_failures >= 2) {
    // Codex struggling - switch to UI Developer
    return "ui-developer"
  }

  // Default: UI Developer (or continue with last successful)
  return last_agent_used || "ui-developer"
}

Step 3.4: Launch Fixing Agent

If fixing_agent == "ui-developer":

• Use Task with subagent_type: frontend:ui-developer
• Provide designer feedback
• Request fixes

If fixing_agent == "ui-developer-codex":

• Use Task with subagent_type: frontend:ui-developer-codex
• Prepare complete prompt with designer feedback + current code
• Request expert fix plan

Step 3.5: Update Metrics and Loop

// Check if progress was made
const progress_made = (current_issues_count < previous_issues_count)

if (progress_made) {
  // Success! Reset counters
  ui_developer_consecutive_failures = 0
  codex_consecutive_failures = 0
} else {
  // No progress - increment failure counter
  if (last_agent_used === "ui-developer") {
    ui_developer_consecutive_failures++
  } else if (last_agent_used === "ui-developer-codex") {
    codex_consecutive_failures++
  }
}

// Update for next iteration
previous_issues_count = current_issues_count
iteration_count++

Continue loop until design fidelity achieved or max iterations reached.

PHASE 4: Final Report & Completion

Generate comprehensive implementation report:

# UI Implementation Report

## Component Information
- Component: [component_description]
- Design Reference: [design_reference]
- Location: [target_location]
- Preview: [app_url]

## Implementation Summary
- Files Created: [count]
- Components: [list]

## Validation Results
- Iterations: [count] / 10
- Final Status: [PASS/NEEDS IMPROVEMENT/FAIL]
- Design Fidelity Score: [score] / 60
- Issues: [count]

## Agent Performance
- UI Developer: [iterations, successes]
- UI Developer Codex: [iterations, successes] (if enabled)
- Agent Switches: [count] times

## Quality Metrics
- Design Fidelity: [Pass/Needs Improvement]
- Accessibility: [WCAG compliance]
- Responsive: [Mobile/Tablet/Desktop]
- Code Quality: [TypeScript/Lint/Build status]

## How to Use
[Preview instructions]
[Component location]
[Example usage]

## Outstanding Items
[List any remaining issues or recommendations]

Present results to user and offer next actions.

Orchestration Rules

Smart Agent Switching:

• Track consecutive failures independently for each agent
• Switch after 2 consecutive failures (no progress)
• Reset counters when progress is made
• Log all switches with reasons
• Balance UI Developer (speed) with UI Developer Codex (expertise)

Loop Prevention:

• Maximum 10 iterations before asking user
• Track progress at each iteration (issue count)
• Ask user for guidance if limit reached

Quality Gates:

• Design fidelity score >= 54/60 for PASS
• All CRITICAL issues must be resolved
• Accessibility compliance required

Success Criteria

Complete when:

1. ✅ UI component implemented from scratch
2. ✅ Designer validated against design reference
3. ✅ Design fidelity score >= 54/60
4. ✅ All CRITICAL issues resolved
5. ✅ Accessibility compliant (WCAG 2.1 AA)
6. ✅ Responsive (mobile/tablet/desktop)
7. ✅ Code quality passed (typecheck/lint/build)
8. ✅ Comprehensive report provided
9. ✅ User acknowledges completion

Notes

• This Skill wraps the /implement-ui command workflow
• Use proactively when user provides design references
• Implements from scratch (not for fixing existing UI)
• Smart switching maximizes success rate
• All work on unstaged changes until user approves
• Maximum 10 iterations with user escalation