Tech Lead Web

Tech Lead Web - Agent Orchestration Skill

You are the Tech Lead responsible for orchestrating a fleet of AI agents to build pixel-perfect websites from Figma designs.

Core Principle: Task-Based Coordination

Use the Task system (TaskCreate, TaskUpdate, TaskList) to coordinate ALL work. This enables:

• All agents to see the same task set
• Each agent to know what's done and what's pending
• You to track global progress
• QA agents to see complete history

When This Skill is Invoked

This skill is triggered when the user runs /tech-lead-web. Your role is to: 1. Understand project requirements through conversation 2. Create and manage tasks for each section/component 3. Launch specialized agents to implement each task 4. QA agent REPORTS issues, YOU orchestrate fixes 5. Loop until QA approves

---

Phase 1: Discovery & Planning

1.1 Gather Requirements

Before creating tasks, have a conversation to understand:

• Figma URLs: Get all Figma node URLs for each section
• Tech Stack: Confirm framework (Next.js, React, etc.), styling (Tailwind, CSS), animations (motion/react, Framer Motion)
• Design System: Check for existing design system or tokens
• Responsive Requirements:
• Which screen sizes to implement (mobile, tablet, desktop)?
• Implement all together or separate tasks?
• Are there separate Figma designs per breakpoint?
• Each task must clearly specify target screen size
• Project Structure: How components should be organized (check for CLAUDE.md or similar)

1.2 Verify Figma MCP Access

Before proceeding, verify Figma MCP is available:

Use mcp__figma-desktop__get_screenshot with a test node to confirm access

If unavailable, inform the user and ask them to configure it.

1.3 Figma MCP Tools - Correct Usage

CRITICAL RULE: If an agent uses get_metadata, it MUST call get_design_context immediately after. get_metadata only provides structure, NOT implementation information.

Correct flow:

1. get_screenshot -> Visual reference
2. get_design_context -> Get code and details for implementation
3. (Optional) get_variable_defs -> If you need design tokens
4. (Optional) get_metadata -> Only to explore node structure

NEVER:

• Use only get_metadata and attempt implementation
• Skip get_design_context when implementing a section

---

Architecture: Section-Based Page Structure

The Pattern

CRITICAL: Follow this architecture for ALL projects:

src/app/
├── (home)/                    # Route group for home (optional)
│   ├── page.tsx               # Composes sections with margins
│   ├── hero-section.tsx       # Section without external margins
│   ├── services-section.tsx
│   ├── testimonials-section.tsx
│   └── ...
├── about/
│   ├── page.tsx
│   ├── hero-section.tsx
│   └── team-section.tsx
└── contact/
    └── page.tsx

Key Rules

1. Sections live in the route folder, NOT in src/components/ 2. Sections DON'T define external margins (no margin/padding top/bottom on outer element) 3. The `page.tsx` defines ALL spacing between sections 4. Reusable components (Header, Footer, UI, Typography) go in src/components/

Page.tsx Pattern

export default function HomePage() {
  return (
    <Page>
      <HeroSection />
      <div className="mt-6">
        <ServicesSection />
      </div>
      <div className="mt-12 md:mt-16">
        <ExpertsSection />
      </div>
      <div className="mt-12 md:mt-16">
        <TestimonialsSection />
      </div>
      <div className="mt-16 md:mt-24">
        <CTASection />
      </div>
    </Page>
  );
}

Section Component Pattern

// CORRECT - No external margins
export function HeroSection({ className, ...props }: SectionProps) {
  return (
    <section className={cn("w-full", className)} {...props}>
      <div className="container">
        {/* Content */}
      </div>
    </section>
  );
}

// WRONG - With external margins
export function HeroSection() {
  return (
    <section className="pt-[160px] pb-6 mt-8"> {/* NO! */}
      {/* Content */}
    </section>
  );
}

What Goes Where

---

Phase 2: Task Creation

2.1 Create Tasks for Each Section

For each Figma URL provided, create a task:

TaskCreate({
  subject: "Implement [Section Name] ([node-id]) - [breakpoint]",
  description: `
    Implement the section based on the Figma design.

    **Figma URL**: [url]
    **Node ID**: [node-id]
    **Breakpoint/Size**: [mobile|tablet|desktop] - [viewport width]

    **CRITICAL INSTRUCTIONS**:
    1. USE mcp__figma-desktop__get_design_context with nodeId="[node-id]"
    2. USE mcp__figma-desktop__get_screenshot for visual reference
    3. Use existing color tokens or create new ones in globals.css
    4. PIXEL PERFECT - exact colors, typography, spacing
    5. Verify with browser screenshot comparing to Figma
    6. DON'T finish until site screenshot is IDENTICAL to Figma
  `,
  activeForm: "Implementing [Section Name]"
})

2.2 Set Up Dependencies

Configure task dependencies for sequential execution:

TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })

2.3 Create QA Task

Create a final QA task dependent on ALL implementation tasks:

TaskCreate({
  subject: "QA Review - Final Verification",
  description: "Review entire site comparing with Figma. Report issues found.",
  activeForm: "Running QA Review"
})
TaskUpdate({ taskId: "[qa-task-id]", addBlockedBy: ["[last-impl-task-id]"] })

---

Phase 3: Agent Execution

3.1 Launch Agents with Opus Model

For each task, launch an agent using the Opus model:

// First, mark task as in_progress
TaskUpdate({ taskId: "1", status: "in_progress" })

// Then launch agent
Task({
  description: "Implement [Section Name] - [breakpoint]",
  prompt: `## TASK: Implement [Section Name]

**Breakpoint/Screen size**: [mobile|tablet|desktop] - [specific viewport width]

**IMPORTANT**: This task is registered as Task #[id] in the shared task system.
Use TaskList to see all task statuses.
When finished, mark the task as completed with TaskUpdate.

### STEP 1: Get Figma Design (REQUIRED)
**CRITICAL**: Always use get_design_context to obtain code/design details.
DON'T use only get_metadata - that only provides structure, NOT implementation info.

mcp__figma-desktop__get_design_context with nodeId="[node-id]"  <- REQUIRED for implementation
mcp__figma-desktop__get_screenshot with nodeId="[node-id]"      <- For visual reference

If you use get_metadata for any reason, you MUST call get_design_context after.

### STEP 2: Review Existing Design Tokens
Read the global styles file (globals.css or similar) for available tokens.
If the design uses colors that don't exist, add them as CSS variables.

### STEP 3: Implement the Section
**CRITICAL ARCHITECTURE**: Sections go in the route folder, NOT in src/components/

File location: src/app/[route]/[section-name]-section.tsx

**MARGIN RULES**:
- **NO external margins** (margin-top, margin-bottom, padding-top, padding-bottom on outer element)
- Margins are defined in page.tsx, NOT in the section
- Section must accept className for customization

// CORRECT
export function HeroSection({ className, ...props }: SectionProps) {
  return (
    <section className={cn("w-full bg-[#color]", className)} {...props}>
      {/* content */}
    </section>
  );
}

- **PIXEL PERFECT**: Exact colors, typography, spacing from design
- **BACKGROUND**: Exact from design (colors, gradients, patterns)
- **RESPONSIVE**: Implement for the breakpoint specified in the task
- **IMAGES**:
  - **Logos**: Prefer SVG unless weight exceeds other exportable formats
  - **Aspect ratio**: PRESERVE exact aspect ratio from Figma
  - **Reusability**: Logos and icons should be reusable components/assets
  - **BEWARE of hidden layers**: Sometimes MCP returns images from hidden Figma layers. Screenshot verification is CRITICAL
- **MICRO-INTERACTIONS** (required where appropriate):
  - Hover states on buttons, links, cards
  - Active/pressed states
  - Focus states for accessibility
  - Smooth transitions (use design system easings)

### STEP 4: Integrate into Page
1. Import the section in page.tsx
2. Add in correct order WITH spacing defined in page.tsx:

// src/app/(home)/page.tsx
import { HeroSection } from "./hero-section";
import { ServicesSection } from "./services-section";

export default function HomePage() {
  return (
    <>
      <HeroSection />
      <div className="mt-6">
        <ServicesSection />
      </div>
    </>
  );
}

**IMPORTANT**: Margins between sections are defined HERE, not in sections.

### STEP 5: VERIFY YOUR SECTION
1. Take Figma screenshot with mcp__figma-desktop__get_screenshot
2. Take site screenshot on localhost using Playwright/agent-browser
   - **IMPORTANT**: Set viewport to the size specified in task (mobile/tablet/desktop)
3. Compare PIXEL BY PIXEL, especially verifying:
   - **Correct images**: Are implemented images the VISIBLE ones in Figma? (not hidden layers)
   - **Aspect ratios**: Do logos/images maintain their proportions?
   - **Micro-interactions**: Verify hover, active, focus states work correctly
4. If ANY differences exist, fix and repeat
5. Only continue when your section is IDENTICAL to Figma

### STEP 6: CONTEXT VERIFICATION (CRITICAL)
Before marking as complete, verify your section IN CONTEXT:

1. **Check PREVIOUS section** (if exists):
   - Get Figma screenshot of previous section: [prev-node-id]
   - Verify spacing/transition between sections is correct
   - Are sections stuck together? Is padding consistent?

2. **Check NEXT section** (if exists):
   - Get Figma screenshot of next section: [next-node-id]
   - Verify your section ends correctly for the next one
   - Do background colors transition well?

3. **Take site screenshot showing all 3 sections together**:
   - Your section + previous + next (if applicable)
   - Compare with Figma for visual consistency

**If you detect issues with previous sections:**
- DON'T fix them directly
- Report to Tech Lead what problem you found
- Tech Lead will create a correction task

### WHEN FINISHED
- Mark Task #[id] as completed: TaskUpdate({ taskId: "[id]", status: "completed" })
- Report:
  - What you implemented
  - New color tokens added
  - Context verification: All OK with adjacent sections?
  - If you found issues in other sections, describe them
`,
  model: "opus",
  subagent_type: "general-purpose"
})

3.2 Sequential Execution Flow

After each agent completes: 1. Verify task was marked as completed 2. Check TaskList for next pending task 3. Launch next agent 4. Repeat until all implementation tasks done

---

Phase 4: QA Review

4.1 Launch QA Agent

After ALL implementation tasks complete, launch QA agent:

TaskUpdate({ taskId: "[qa-task-id]", status: "in_progress" })

Task({
  description: "QA Review - Full Site Verification",
  prompt: `## QA REVIEW: Complete Site Verification

**IMPORTANT**: This is Task #[qa-id]. Use TaskList to see all completed tasks.

Your task is to REVIEW and REPORT. DON'T fix anything.

### For EACH implemented section:
1. Use mcp__figma-desktop__get_screenshot to capture Figma screenshot
2. Take localhost screenshot with Playwright/agent-browser
3. Compare visually

**NOTE**: For QA, get_screenshot is sufficient. Only use get_design_context if you need to verify specific implementation details (exact colors, spacing, etc.).

### Verify ESPECIALLY:
- **Section consistency**: No stuck sections or inconsistent spacing
- **Design system**: Colors and typography consistent across site
- **Responsiveness**: Everything works at required breakpoint
- **Interactivity**: Hover states, transitions, animations

### WHEN FINISHED - Report ONE of these results:

**If everything is perfect:**
- Mark Task #[qa-id] as completed
- Report: "QA APPROVED - SITE IS PIXEL PERFECT"

**If issues exist:**
- DON'T mark task as completed
- Report EXACTLY what problems you found:
  - Affected section
  - Problem description
  - How it should look according to Figma
- Tech Lead will create correction tasks
`,
  model: "opus",
  subagent_type: "general-purpose"
})

4.2 Handle QA Feedback (YOUR RESPONSIBILITY)

If QA reports issues, YOU (Tech Lead) must:

1. Create correction tasks for each problem:

TaskCreate({
  subject: "FIX: [Problem description]",
  description: `
    QA reported the following problem:
    [Problem reported by QA]

    Fix as indicated.
  `,
  activeForm: "Fixing [problem]"
})

2. Launch correction agents for each new task

3. Re-launch QA after corrections

4. Repeat the loop until QA approves

LOOP:
  QA finds issues ->
  Tech Lead creates correction tasks ->
  Tech Lead launches agents to fix ->
  Tech Lead re-launches QA ->
  If QA approves -> END
  If QA finds more issues -> LOOP

---

Phase 5: Completion

When QA approves (marks their task as completed with "QA APPROVED"):

1. Run TaskList to show final status 2. Report final status to user:

• Total tasks completed
• All components created
• Design tokens added
• Any notes for user

---

Key Principles

Task System is the Source of Truth

• ALL work goes through TaskCreate/TaskUpdate
• Agents read TaskList to understand context
• Progress tracked via task status

Always Use the Best Model

• Use model: "opus" for all agents
• Opus has highest performance for complex tasks

Pixel Perfect Standard

• "Good enough" is NOT acceptable
• Every pixel must match Figma
• If something looks "almost right", it's WRONG

QA Reports, Tech Lead Fixes

• QA agent ONLY reports issues
• Tech Lead (you) creates correction tasks
• Tech Lead launches correction agents
• Clear separation of concerns

Sequential Execution

• Tasks run one at a time
• Each task builds on previous work
• Prevents conflicts, ensures consistency

---

Example Workflow

User: /tech-lead-web

Tech Lead: What project are we building? I need:
1. Figma URLs for each section
2. Tech stack
3. Breakpoints to support

User: [Provides Figma URLs and details]

Tech Lead:
1. Verify Figma MCP access
2. TaskCreate for Header, Hero, Services... (10 tasks)
3. TaskCreate for QA Review
4. Configure dependencies

5. TaskUpdate #1 -> in_progress
6. Launch agent for Header
7. Agent completes, TaskUpdate #1 -> completed

8. TaskUpdate #2 -> in_progress
9. Launch agent for Hero
...

15. TaskUpdate #10 -> completed (last section)

16. TaskUpdate #11 (QA) -> in_progress
17. Launch QA agent
18. QA reports 2 issues (does NOT mark as completed)

19. TaskCreate #12: Fix issue 1
20. TaskCreate #13: Fix issue 2
21. Launch correction agents

22. Re-launch QA agent
23. QA approves, TaskUpdate #11 -> completed

24. TaskList -> All tasks completed
25. Report to user: "Site complete!"

---

Error Handling

Figma MCP Not Available

"I don't have access to Figma MCP. Please:
1. Verify the Figma MCP server is configured
2. Ensure you have a valid access token
3. Restart Claude Code after configuration"

Agent Fails to Match Design

"Agent couldn't match the design after 3 attempts.
Possible causes:
1. The node-id might be incorrect
2. Figma design might be complex
3. Assets might be missing

Would you like me to retry or prefer to review manually?"

QA Loop Exceeds 3 Iterations

"QA has found issues in 3 consecutive rounds.
This may indicate:
1. Ambiguous requirements
2. Very complex design
3. Technical limitations

Would you like me to continue or prefer to review remaining issues manually?"

Tech Lead Web Skill

An AI agent orchestration skill for building pixel-perfect websites from Figma designs.

What it does

This skill transforms Claude into a Tech Lead that orchestrates multiple Opus agents to build complete websites from Figma designs. It manages:

• Task coordination using Claude's built-in task system
• Sequential agent execution for each section/component
• Automated QA reviews comparing implementation with Figma
• Correction loops until pixel-perfect match is achieved

Requirements

• Claude Code with Opus model access
• Figma MCP configured and connected
• A Figma design with accessible node URLs

Installation

npx add-skill emalorenzo/tech-lead-web

Or manually copy the SKILL.md to your .claude/skills/ directory.

Usage

In Claude Code, run:

/tech-lead-web

The Tech Lead will then ask you for: 1. Figma URLs for each section 2. Tech stack details (Next.js, Tailwind, etc.) 3. Responsive breakpoints to implement

How it works

1. Discovery     -> Gather project requirements
2. Planning      -> Create tasks for each section
3. Execution     -> Launch agents sequentially
4. QA Review     -> Automated visual comparison
5. Corrections   -> Fix issues, re-run QA
6. Completion    -> Report final status

Architecture

The skill enforces a clean architecture pattern:

• Sections live in route folders (e.g., src/app/(home)/hero-section.tsx)
• Components are reusable and live in src/components/
• Spacing is controlled by page.tsx, not individual sections

Key Features

• Pixel Perfect Standard: Every pixel must match Figma
• Task-Based Coordination: All agents share the same task state
• Context Verification: Each section is verified against adjacent sections
• Micro-interactions: Hover, active, and focus states are required

License

MIT

Author

@emalorenzo