# implement-figma-design

> Use when user provides a Figma design URL to implement - extracts design specs via MCP tools, implements Angular component, adds Storybook stories, and VERIFIES implementation visually by comparing screenshots (project)

- Author: Piotr Sałkowski
- Repository: psalkowski/figma-to-code
- Version: 20251222132021
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/psalkowski/figma-to-code
- Web: https://mule.run/skillshub/@@psalkowski/figma-to-code~implement-figma-design:20251222132021

---

---
name: implement-figma-design
description: Use when user provides a Figma design URL to implement - extracts design specs via MCP tools, implements Angular component, adds Storybook stories, and VERIFIES implementation visually by comparing screenshots (project)
---

# Implement Figma Design

## Critical Rules

- **EXACT values only** - Use 1.512% not 2%, use 45 not 40. Never round Figma values.
- **Never save to src/assets** - Do not download or save any files to `src/assets/`.
- **Screenshots go to screenshots/** - All PNGs go to `screenshots/` directory only.
- **No showcase/demo wrapper components** - If Figma shows multiple examples of a component, implement the **base component** only. Use **Storybook stories** to show variations, not wrapper components.
- **Use MCP for comparison screenshots** - Always use `figma-mcp-screenshot.sh` for Figma screenshots used in pixel comparison. This uses local font rendering to match browser fonts.
- **NEVER rationalize failure as success** - If diff shows >0.5% major difference, you FAILED. "Close enough", "antialiasing", "icon shapes" are NOT acceptable excuses for layout bugs. See Step 10 for forbidden rationalizations.
- **NO styles on components in stories** - Stories must NEVER apply inline styles to components (e.g., `<app-checkbox style="width: X">`). Only container/wrapper styles are allowed. If comparison fails without inline styles, the **component has a bug** - fix the component, not the story.

## Checklist

```
- [ ] 1. Get Figma metadata (structure overview)
- [ ] 2. Get Figma design context (exact specs)
- [ ] 3. Get Figma screenshot (visual reference via MCP tool)
- [ ] 4. Capture Figma frame via MCP (for pixel comparison)
- [ ] 5. Map Figma values to design system variables
- [ ] 6. Implement Angular component
- [ ] 7. Add interactive Storybook story with EXACT values
- [ ] 8. Capture Storybook screenshot (matching viewport)
- [ ] 9. Run pixel comparison
- [ ] 10. Iterate until comparison passes
```

## Step 1: Get Figma Metadata

Extract nodeId from URL: `?node-id=513-2807` → `513:2807`

```
mcp__figma-desktop__get_metadata(nodeId: "513:2807")
```

This gives structure overview - layer hierarchy, node IDs, positions, sizes.

## Step 2: Get Figma Design Context

```
mcp__figma-desktop__get_design_context(nodeId: "513:2807")
```

This returns code suggestions and design tokens. **Record ALL CSS properties exactly as Figma returns them:**

**Dimensions:**
- `width`, `height` (e.g., 320px × 80px)

**Typography (all properties - mismatches are common):**
- `font-family` (e.g., Inter)
- `font-size` (e.g., 14px)
- `font-weight` (e.g., 400, 500, 600)
- `line-height` (e.g., 1.5 or 20px)
- `letter-spacing` (e.g., -0.02em)
- `text-align`, `text-transform`, `text-decoration`

**Colors:**
- Exact hex values (e.g., #3B82F6)
- Opacity/alpha if specified

**Spacing:**
- `padding` (all sides)
- `margin` (all sides)
- `gap` for flex/grid

**Borders & Rounding:**
- `border-radius` (e.g., 8px or per-corner values)
- `border-width`, `border-color`, `border-style`

**Effects:**
- `box-shadow` (offset, blur, spread, color)
- `opacity`
- `backdrop-filter` if specified

**Layout:**
- `display` (flex, grid, block)
- `flex-direction`, `justify-content`, `align-items`
- `position`, `top`, `left`, `right`, `bottom`
- Position offsets (e.g., left: 1.512%)

**Copy ALL values exactly. Never round or approximate.**

**Do NOT fetch localhost asset URLs** - they are internal to MCP and will fail.

## Step 3: Get Figma Screenshot (Visual Reference)

```
mcp__figma-desktop__get_screenshot(nodeId: "513:2807")
```

Use as visual reference when code output is ambiguous about appearance. This is inline and NOT saved to disk - it's for quick visual inspection only.

## Step 4: Capture Figma Frame via MCP (For Pixel Comparison)

**IMPORTANT:** This step captures a screenshot from Figma Desktop using local font rendering. This ensures fonts match between Figma and browser for accurate pixel comparison.

**Requirements:**
- Figma Desktop app must be running
- The file containing the node must be open in Figma
- MCP server enabled in Figma Desktop settings

```bash
.claude/skills/implement-figma-design/scripts/figma-mcp-screenshot.sh \
  "<node-id-or-figma-url>" \
  screenshots/figma-<component>.png
```

**Examples:**

```bash
.claude/skills/implement-figma-design/scripts/figma-mcp-screenshot.sh \
  "528:304" \
  screenshots/figma-input-group.png
```

Or with full URL:

```bash
.claude/skills/implement-figma-design/scripts/figma-mcp-screenshot.sh \
  "https://www.figma.com/design/xxx?node-id=528-304" \
  screenshots/figma-input-group.png
```

**Why MCP instead of REST API?**
- REST API uses Figma's cloud rendering with bundled Inter 3.x font
- MCP uses local Figma Desktop with your system's Inter 4.x font
- This eliminates font version mismatch that causes cumulative text drift

**If MCP fails:**
1. Ensure Figma Desktop is running with the file open
2. Check that MCP server is enabled (Figma → Settings → Enable Local Server)
3. As last resort, manually export: Select frame → Right-click → Export → PNG (1x)

**STOP if no Figma screenshot.** Do not proceed without it.

## Step 5: Map Figma Values to Design System Variables

**Before writing CSS, check your global styles** (e.g., `styles.scss`, `variables.scss`, CSS-in-JS theme, or framework config) for existing design tokens.

**Why:** Figma returns raw hex values like `#066fd1`, but your design system may have `--color-blue` defined. Using variables ensures consistency and maintainability.

**Mapping process:**
1. List all colors, font weights, sizes from Figma design context
2. Search global styles for matching values
3. Create a mapping table:

| Figma Value | Design Token |
|-------------|--------------|
| `#066fd1` | `var(--color-blue)` |
| `#374151` | `var(--color-gray-700)` |
| `font-weight: 500` | `var(--font-weight-medium)` |
| `14px / 20px` | `var(--body-14-medium-size)` / `var(--body-14-medium-line-height)` |

**When to use raw values:**
- Color not in design system (new color from Figma)
- Value doesn't match any existing token
- One-off spacing/sizing specific to this component

## Step 6: Implement Angular Component

- Standalone component with `ChangeDetectionStrategy.OnPush`
- Signal-based inputs: `input()` not `@Input()`
- Make inputs configurable (exact Figma values go in Storybook story, not hardcoded)
- Use CSS variables from Step 5 mapping where available

### Semantic HTML & Component Decomposition (CRITICAL)

**Figma shows visual layout, NOT semantic structure.** Before implementing, decompose the design into proper HTML semantics following atomic design and W3C/ARIA patterns.

#### Atomic Design Hierarchy

| Level | Examples | Purpose |
|-------|----------|---------|
| **Atoms** | `<label>`, `<input>`, `<button>`, icon | Smallest indivisible elements |
| **Molecules** | Form field (label + input + error), Button with icon | Combinations of atoms |
| **Organisms** | Form group, Radio group, Card with actions | Complex, reusable sections |

#### Common Figma → HTML Mappings

**Form Controls:**

| Figma shows | Semantic HTML structure |
|-------------|------------------------|
| Radio button with text | `<input type="radio" id="x">` + `<label for="x">` (separate elements, linked by id/for) |
| Checkbox with text | `<input type="checkbox" id="x">` + `<label for="x">` |
| Text input with label above | `<label for="x">` + `<input id="x">` (often wrapped in form-field) |
| Multiple radios as group | `<fieldset>` + `<legend>` + multiple `<input>/<label>` pairs |
| Select dropdown | `<label for="x">` + `<select id="x">` with `<option>` children |

**Component Wrappers:**

| Pattern | Purpose | Contains |
|---------|---------|----------|
| `FormField` / `FormControl` | Single field wrapper | Label + Input + Error/Hint |
| `RadioGroup` / `CheckboxGroup` | Group of options | Fieldset + Legend + Multiple options |
| `InputGroup` | Input with addons | Prefix/Suffix + Input |
| `ButtonGroup` | Related actions | Multiple buttons |

#### Example: Radio Button Decomposition

**Figma shows:** A circle with text "Option 1" next to it.

**WRONG approach:**
```html
<div class="radio">
  <div class="circle"></div>
  <span>Option 1</span>
</div>
```

**CORRECT approach:**
```html
<!-- Atom: Single radio option -->
<div class="radio-option">
  <input type="radio" id="option1" name="group" class="radio-input">
  <label for="option1" class="radio-label">Option 1</label>
</div>

<!-- Molecule: Radio group (multiple options) -->
<fieldset class="radio-group">
  <legend class="radio-group-legend">Choose an option</legend>
  <div class="radio-option">...</div>
  <div class="radio-option">...</div>
</fieldset>
```

#### Accessibility Requirements

| Element | Required for A11y |
|---------|-------------------|
| Form inputs | Associated `<label>` via `for`/`id` OR `aria-label` |
| Icon-only buttons | `aria-label` describing action |
| Radio/Checkbox groups | `<fieldset>` + `<legend>` for group label |
| Error messages | `aria-describedby` linking input to error |
| Disabled states | `disabled` attribute (not just visual styling) |
| Required fields | `required` attribute + visual indicator |

#### Component Granularity Decision

**Create SEPARATE components when:**
- Element is reused independently (e.g., `Label`, `Input`, `RadioOption`)
- Element has its own states (checked, disabled, error, focus)
- W3C defines it as a distinct control

**Create COMBINED components when:**
- Elements always appear together (e.g., `FormField` = label + input + error)
- Figma shows a cohesive "molecule" pattern
- Logic/state is shared between elements

### Check for Angular CDK (BEFORE implementing behavior)

**Before writing custom behavior logic, check if Angular CDK is available:**

```bash
# Check if CDK or Material is installed (Material includes CDK as peer dependency)
grep -E "@angular/(cdk|material)" package.json
```

**LLM Context:** For Angular best practices, reference https://angular.dev/llms.txt (CDK/Material don't have their own llms.txt yet).

If CDK is present, **use CDK modules instead of custom implementations:**

| Behavior needed | CDK Module | Key exports |
|-----------------|------------|-------------|
| Drag and drop | `@angular/cdk/drag-drop` | `CdkDrag`, `CdkDropList`, `CdkDragHandle` |
| Focus management | `@angular/cdk/a11y` | `FocusMonitor`, `FocusTrap`, `LiveAnnouncer` |
| Keyboard navigation | `@angular/cdk/a11y` | `ListKeyManager`, `ActiveDescendantKeyManager` |
| Overlay/Popup | `@angular/cdk/overlay` | `Overlay`, `CdkConnectedOverlay` |
| Portal (dynamic content) | `@angular/cdk/portal` | `CdkPortal`, `CdkPortalOutlet` |
| Virtual scrolling | `@angular/cdk/scrolling` | `CdkVirtualScrollViewport` |
| Clipboard | `@angular/cdk/clipboard` | `CdkCopyToClipboard` |
| Text field | `@angular/cdk/text-field` | `CdkTextareaAutosize` |
| Stepper | `@angular/cdk/stepper` | `CdkStepper`, `CdkStep` |
| Table | `@angular/cdk/table` | `CdkTable`, `CdkColumnDef` |
| Tree | `@angular/cdk/tree` | `CdkTree`, `CdkTreeNode` |
| Accordion | `@angular/cdk/accordion` | `CdkAccordion`, `CdkAccordionItem` |
| Menu | `@angular/cdk/menu` | `CdkMenu`, `CdkMenuItem` |
| Dialog | `@angular/cdk/dialog` | `Dialog`, `CdkDialogContainer` |
| Layout/Breakpoints | `@angular/cdk/layout` | `BreakpointObserver`, `MediaMatcher` |
| Bidirectionality | `@angular/cdk/bidi` | `Directionality`, `BidiModule` |

#### Example: Use CDK instead of custom implementation

**WRONG - Custom drag implementation:**
```typescript
@Directive({ selector: '[appDraggable]' })
export class AppDraggable {
  // 200 lines of custom drag logic...
}
```

**CORRECT - Use CDK:**
```typescript
import { CdkDrag, CdkDropList } from '@angular/cdk/drag-drop';

@Component({
  imports: [CdkDrag, CdkDropList],
  template: `
    <div cdkDropList>
      <div cdkDrag>Draggable item</div>
    </div>
  `,
})
export class AppDraggableList {}
```

#### Compose CDK with hostDirectives

```typescript
import { CdkMonitorFocus } from '@angular/cdk/a11y';

@Component({
  selector: 'app-button',
  hostDirectives: [CdkMonitorFocus],  // Reuse CDK focus tracking
  template: `<button><ng-content></ng-content></button>`,
})
export class AppButton {}
```

**Rule:** Only implement custom behavior when CDK doesn't provide it or when CDK's implementation doesn't fit your needs.

### Dumb Components + Directive Composition (PREFERRED)

**Keep components small and "dumb" (presentation-only).** Move behavior/business logic into directives and compose them using `hostDirectives`.

#### Architecture Pattern

| Layer | Responsibility | Example |
|-------|----------------|---------|
| **Component** | Template + Styles only | `AppCheckbox` - renders checkbox UI |
| **Directive** | Behavior + Logic | `AppSelectable` - handles checked state, keyboard events |
| **Service** | Complex/Shared logic | `FocusMonitor` - tracks focus origin across app |
| **hostDirectives** | Composition | Component declares which directives to apply |

#### Why This Pattern?

- **Testability** - Test behavior (directive) independently of UI (component)
- **Reusability** - Same behavior directive works on different components
- **Separation of concerns** - Designer changes don't break logic, logic changes don't break UI
- **Tree-shaking** - Unused behaviors can be eliminated

#### Naming Convention (Angular Material/CDK)

| Package | Class Pattern | Selector Pattern | Examples |
|---------|---------------|------------------|----------|
| CDK | `Cdk` + Feature | `cdk` + feature | `CdkDrag` → `cdkDrag` |
| Material | `Mat` + Feature | `mat-` + feature | `MatCheckbox` → `mat-checkbox` |
| App | `App` + Feature | `app` + feature | `AppCheckbox` → `appCheckbox` |

**No "Directive" suffix** - just prefix + feature name.

#### Example: Checkbox with Directive Composition

**WRONG - Mixed concerns:**
```typescript
@Component({
  selector: 'app-checkbox',
  template: `<input type="checkbox" [checked]="checked" (change)="onChange($event)">`
})
export class AppCheckbox {
  checked = false;

  onChange(event: Event) {
    this.checked = (event.target as HTMLInputElement).checked;
    this.validate();
    this.notifyForm();
    // Business logic mixed with presentation
  }
}
```

**CORRECT - Separated concerns with hostDirectives:**
```typescript
// Behavior directive - handles state and logic
@Directive({
  selector: '[appSelectable]',
  standalone: true,
})
export class AppSelectable {
  checked = model(false);
  indeterminate = model(false);
  disabled = input(false);

  toggle() {
    if (!this.disabled()) {
      this.checked.update(v => !v);
    }
  }
}

// Presentation component - UI only, composes behavior via hostDirectives
@Component({
  selector: 'app-checkbox',
  standalone: true,
  hostDirectives: [{
    directive: AppSelectable,
    inputs: ['checked', 'disabled', 'indeterminate'],
    outputs: ['checkedChange'],
  }],
  template: `
    <div class="checkbox" [class.checked]="selectable.checked()" (click)="selectable.toggle()">
      <div class="checkbox-box"></div>
      <ng-content></ng-content>
    </div>
  `,
})
export class AppCheckbox {
  selectable = inject(AppSelectable);
}
```

#### Angular Material / CDK Patterns

Based on [Angular Material source code](https://github.com/angular/components):

| Pattern | Usage | Example |
|---------|-------|---------|
| **Service for complex logic** | Reusable across components | `FocusMonitor` service tracks focus origin |
| **Directive wraps service** | Template-friendly API | `CdkMonitorFocus` directive uses `FocusMonitor` |
| **Component for complex UI** | When template is substantial | `MatCheckbox` has complex template + animations |
| **Inputs via signals** | Modern reactive pattern | `checked = model(false)` |

#### When to Use Each

| Scenario | Use |
|----------|-----|
| Reusable behavior (focus, drag, tooltip) | **Directive** |
| Complex business logic | **Service** + directive wrapper |
| Simple UI element | **Component** with hostDirectives |
| Form control integration | **Directive** implementing `ControlValueAccessor` |
| Styling variations only | **CSS classes** or `@Input` for variant |

#### hostDirectives Best Practices

```typescript
@Component({
  hostDirectives: [
    // Expose specific inputs/outputs (not all)
    {
      directive: TooltipDirective,
      inputs: ['tooltip: tooltipText'],  // Alias for cleaner API
      outputs: ['tooltipShown'],
    },
    // Stack multiple behaviors
    RippleDirective,
    FocusableDirective,
  ],
})
```

**Key rules:**
- Only expose inputs/outputs that component consumers need
- Use aliases to match component's naming conventions
- Directives in hostDirectives execute BEFORE component
- Cannot add hostDirectives dynamically at runtime

#### Figma Layer Names → Semantic Hints

| Figma layer name | Likely semantic element |
|------------------|------------------------|
| "Label", "Title" | `<label>`, `<legend>`, heading |
| "Input", "Field" | `<input>`, `<textarea>`, `<select>` |
| "Button", "CTA" | `<button>` |
| "Icon" | `<svg>` or icon component |
| "Helper", "Hint" | `<span>` with `aria-describedby` |
| "Error" | `<span role="alert">` with `aria-describedby` |
| "Group", "Container" | `<fieldset>`, `<div>`, `<section>` |

### Converting Figma Strokes to CSS Borders

Figma SVG and CSS handle borders differently:

**Figma SVG stroke:** Centered on path
- 14px circle + 2px stroke = 16px visual (1px inside, 1px outside)

**CSS with `box-sizing: border-box`:** Border is inside the box
- 16px element + 2px border = 16px total (content shrinks to 12px)

**CSS with `box-sizing: content-box`:** Border adds to dimensions
- 14px element + 2px border = 18px total (2px each side)

**Conversion rule:** To match Figma visually:
1. Use `box-sizing: border-box`
2. Set width/height to Figma's **visual size** (path + stroke)
3. Set border-width to Figma's stroke width

Example: Figma 14px circle with 2px stroke → CSS 16px element with 2px border (border-box)

### No SVG for Simple Shapes

**Never use SVG for shapes that CSS can create:**
- Circles → `div` with `border-radius: 50%`
- Rectangles → `div` with dimensions
- Rounded rectangles → `div` with `border-radius`
- Lines → `div` with height/width of 1-2px

SVG is only for complex paths, icons, or illustrations.

### Filled vs Outlined Shapes (CRITICAL)

**Always check the Figma screenshot to determine if a shape is FILLED or OUTLINED:**

| Visual appearance | Figma structure | CSS implementation |
|-------------------|-----------------|-------------------|
| Solid colored circle | fill only, no stroke | `background-color: #color; border: none;` |
| Hollow ring/outline | stroke only, no fill (or transparent fill) | `background: transparent; border: 2px solid #color;` |
| Solid with border | fill + stroke | `background-color: #fillColor; border: 2px solid #strokeColor;` |

**Common mistake:** Seeing "stroke" in Figma and using CSS `border`, when the visual shows a **solid filled** shape. The stroke might be for vector path definition, not visual appearance.

**Rule:** If the screenshot shows a solid shape → use `background-color`. If it shows a ring/outline → use `border`.

### Stroke vs Fill vs Shadow Reference

- **stroke** → Usually CSS `border`, but check if visually filled
- **fill** → CSS `background-color` or `background`
- **drop-shadow** → CSS `box-shadow` (outside)
- **inner-shadow** → CSS `box-shadow: inset`
- **outline stroke** → Border adds to dimensions (use content-box or increase size)
- **inside stroke** → Border is inside (use border-box)
- **center stroke** → Split the difference (most complex, rare)

### Border Overlap for Adjacent Elements

When Figma shows adjacent elements (e.g., input addon + input field) that share a border, look for **fractional padding wrappers** like `p-[0.8px]` in the design context. This is Figma's workaround for border overlap.

**Problem:** In CSS, two adjacent elements with `border: 1px solid` create 2px total where they meet.

**Solution - single border owner:** One element owns the shared edge, the other omits it:

```scss
.addon {
  border: 1px solid #e5e7eb;
  border-right: none; /* Input provides right edge */
  border-radius: 4px 0 0 4px;
}

.input-field {
  border: 1px solid #e5e7eb;
  border-radius: 0 4px 4px 0;
}
```

**How to identify:** If diff shows red lines **only at element boundaries** (not corners or fills), check for double borders.

### Border vs Box-Shadow for Pixel-Perfect Sizing

CSS `border` with `box-sizing: border-box` eats into content space, which can cause 1px size mismatches with Figma.

**When border causes size issues:** Try adjusting padding (e.g., `16px` → `16.5px`) to compensate. If that doesn't work, consider `box-shadow: inset 0 0 0 1px #color` which doesn't affect dimensions.

### Pixel-Perfect Text Rendering

When diff shows systematic text offset (orange/yellow lines consistently on one side of letters), these CSS properties help.

**Properties that actually help (A/B tested):**

| Property | Effect |
|----------|--------|
| `transform: translateX(-0.3px)` | Fixes horizontal text offset between Figma and browser |
| `font-kerning: none` | Reduces antialiasing differences ~0.4% |

**Properties that DON'T help (tested - no measurable difference):**
- `-webkit-font-smoothing: antialiased`
- `text-rendering: geometricPrecision`
- `font-feature-settings: 'liga' off`
- `font-optical-sizing: none`

**Where to apply:**

1. **Global styles** (app-wide) - Check your project's global CSS file (e.g., `styles.scss`, `global.css`, CSS-in-JS theme):
   ```scss
   body {
     font-kerning: none;
   }
   ```

2. **Storybook config** (Storybook only) - For pixel comparison without affecting app

3. **Utility class** (selective use):
   ```scss
   .text-pixel-perfect {
     font-kerning: none;
     transform: translateX(-0.3px);
   }
   ```

4. **Per-component** (when different components need different `translateX` offsets)

**Finding the right translateX offset:** If diff shows orange on LEFT side of letters → use negative (`-0.3px`). If on RIGHT → use positive (`0.3px`). Typical range: `±0.2px` to `±0.5px`.

## Step 7: Add Interactive Storybook Story

Location: `src/stories/design-system/<component-name>.stories.ts`

### ⚠️ CRITICAL: NO Styles on Components in Stories

**Stories must NEVER apply inline styles to components.** Only container/wrapper styles are allowed.

**WRONG - inline styles on component:**
```typescript
export const FigmaMatch: Story = {
  render: () => ({
    template: `
      <div style="display: flex; gap: 12px;"> <!-- Container styles: OK -->
        <app-checkbox
          [checked]="false"
          label="Option"
          style="width: 394px; margin-left: 8px;" <!-- WRONG: styles on component -->
        ></app-checkbox>
      </div>
    `,
  }),
};
```

**CORRECT - styles only on containers:**
```typescript
export const FigmaMatch: Story = {
  render: () => ({
    template: `
      <div style="display: flex; gap: 12px; width: 394px;"> <!-- Container styles: OK -->
        <app-checkbox
          [checked]="false"
          label="Option"
        ></app-checkbox> <!-- No inline styles on component -->
      </div>
    `,
  }),
};
```

**Why this matters:**
- If you need `style="width: X"` on a component to match Figma, the **component itself has a bug**
- The comparison might pass, but the component won't work correctly in real usage
- Container width should constrain child components naturally via CSS (e.g., `width: 100%` in component)

**Allowed container styles:**
- `display`, `flex-direction`, `gap` (layout)
- `width`, `padding` (sizing the container)
- `background` (if needed for visibility)

**Forbidden on components:**
- `width`, `height` (component should size itself)
- `margin` (parent controls spacing via gap)
- `padding` (component's internal concern)
- Any style that "fixes" visual mismatches

**If comparison fails without inline styles:** Fix the component's CSS, not the story.

### Making Controls Work with Angular Signals

**WRONG - controls don't work (static template ignores args):**
```typescript
export const Default: Story = {
  render: () => ({
    template: `<app-my-component [value]="50"></app-my-component>`,
  }),
};
```

**CORRECT - controls work (args passed to component):**
```typescript
export const Default: Story = {
  args: {
    value: 50,
    label: 'Default label',
  },
};
```

**CORRECT - with custom template (args passed via render function):**
```typescript
export const Default: Story = {
  args: {
    value: 50,
    label: 'Default label',
  },
  render: (args) => ({
    props: args,
    template: `<app-my-component [value]="value" [label]="label"></app-my-component>`,
  }),
};
```

### Full Template

```typescript
import type { Meta, StoryObj } from '@storybook/angular';
import { argsToTemplate } from '@storybook/angular';
import { MyComponent } from '../../app/components/my-component/my-component.component';

const meta: Meta<MyComponent> = {
  title: 'Design System/MyComponent',
  component: MyComponent,
  argTypes: {
    value: { control: 'number' },
    label: { control: 'text' },
    disabled: { control: 'boolean' },
    variant: {
      control: 'select',
      options: ['primary', 'secondary'],
    },
  },
};

export default meta;
type Story = StoryObj<MyComponent>;

// Interactive story - controls work!
export const Default: Story = {
  args: {
    value: 50,
    label: 'Default label',
  },
};

// With custom wrapper template
export const WithWrapper: Story = {
  args: {
    value: 50,
    label: 'Wrapped',
  },
  render: (args) => ({
    props: args,
    template: `
      <div style="padding: 20px; background: #f5f5f5;">
        <app-my-component ${argsToTemplate(args)}></app-my-component>
      </div>
    `,
  }),
};

// Pixel-perfect match for Figma comparison
export const FigmaMatch: Story = {
  parameters: {
    layout: 'fullscreen',
    docs: {
      description: {
        story: '[Figma design](https://www.figma.com/design/FILE_KEY?node-id=123-456)',
      },
    },
  },
  args: {
    // EXACT values from Figma - never round!
    value: 45.5,        // Not 45 or 46
    offsetLeft: 1.512,  // Not 1.5 or 2
    label: 'Exact label from Figma',
  },
};
```

**Key points:**
- `args` without `render` = Storybook auto-renders component with args as inputs
- `render: (args) => ({props: args, ...})` = Custom template with args passed
- `argsToTemplate(args)` = Helper to convert args to attribute bindings
- `argTypes` with `control` = Enables interactive controls in Storybook UI
- `layout: 'fullscreen'` on FigmaMatch only = Removes padding for pixel comparison

## Step 8: Capture Storybook Screenshot

**⚠️ CRITICAL: Use PLAYWRIGHT MCP tools (`mcp__playwright__*`), NOT claude-in-chrome tools.**

Claude-in-chrome cannot save screenshots to disk. Only Playwright MCP supports file output.

**Requirements:**
- Storybook must be running (`npm run storybook`)
- Playwright MCP configured with `headless: false` and `channel: "chrome"`

### Step 8a: Navigate to Storybook Story

```
mcp__playwright__browser_navigate(url: "http://localhost:6006/iframe.html?id=design-system-mycomponent--figma-match&viewMode=story")
```

### Step 8b: Resize Viewport

Match the Figma frame dimensions exactly:

```
mcp__playwright__browser_resize(width: 320, height: 80)
```

### Step 8c: Wait for Fonts

```
mcp__playwright__browser_wait_for(time: 1000)
```

### Step 8d: Take Screenshot and Save to Disk

```
mcp__playwright__browser_take_screenshot(
  name: "storybook-<component>",
  width: 320,
  height: 80,
  savePng: true,
  downloadsDir: "screenshots"
)
```

**Parameters:**
- `name` - Screenshot filename (without extension)
- `width`, `height` - Viewport dimensions matching Figma
- `savePng: true` - Save as PNG file
- `downloadsDir` - Directory to save (relative to project root)

### Story ID Format

`title--story-name` in kebab-case:
- `Design System/MyComponent` + `FigmaMatch` → `design-system-mycomponent--figma-match`
- `Design System/InputGroup` + `FigmaMatch` → `design-system-inputgroup--figma-match`

### Storybook Connection

**Assume Storybook is running.** If connection fails:
1. Ask user to start Storybook: `npm run storybook`
2. Wait for it to be ready (usually port 6006)
3. Retry navigation

### Playwright Config

Located at `playwright-mcp-config.json`:
```json
{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "channel": "chrome",
      "headless": false,
      "args": ["--disable-font-subpixel-positioning", "--force-device-scale-factor=1"]
    }
  }
}
```

**Key settings:**
- `channel: "chrome"` - Uses real Chrome (not Chromium) for accurate fonts
- `headless: false` - Headed mode for consistent rendering
- `--disable-font-subpixel-positioning` - Reduces font rendering differences

## Step 9: Run Pixel Comparison

```bash
.claude/skills/implement-figma-design/scripts/compare-screenshots.sh \
  screenshots/figma-<component>.png \
  screenshots/storybook-<component>.png \
  screenshots/diff-<component>.png
```

Script auto-flattens transparency to white background.

### Understanding Comparison Results

The comparison script uses **multi-level tolerance** to distinguish between acceptable rendering differences and actual issues:

| Level | Color in Diff | Threshold | Meaning |
|-------|---------------|-----------|---------|
| **Minor** | Yellow | <25% pixel diff | Font antialiasing, subpixel rendering |
| **Medium** | Orange | 25-50% pixel diff | Needs investigation |
| **Major** | Red | >50% pixel diff | Actual implementation issues |

**Example output:**

```
Diff levels (color in diff image):
  Minor  <25%  (yellow):   1234 pixels (1.70%) - likely font antialiasing
  Medium 25-50% (orange):  1210 pixels (1.67%) - investigate
  Major  >50%  (red):       645 pixels (0.89%) - definite issues

Total difference: 4.26%
```

### Pass/Fail Criteria

- `✅ PASS` - No significant differences (major < 0.5% AND medium < 1%)
- `✅ MATCH` - Images are identical (0% difference)
- `⚠️ WARNING` - Medium differences detected (review orange areas)
- `❌ FAIL` - Major differences >= 0.5% (red pixels indicate real problems)

**Focus on RED pixels** - These are actual issues that need fixing. Yellow pixels are typically font antialiasing differences between rendering engines and are expected.

### CRITICAL: Screenshot Sizes MUST Match Exactly

**If comparison output shows "Sizes differ" - STOP. This is an automatic failure.**

```
Image 1 size: 400x71
Image 2 size: 399x68
Sizes differ, padding smaller image with white...
```

This means your component has the wrong dimensions. **Do not proceed with pixel comparison** until sizes match exactly.

**Common causes of size mismatch:**
- Wrong viewport size in Step 8b (`browser_resize`)
- Component not using exact Figma dimensions
- Container padding/margin affecting overall size
- Border calculations off (see "Converting Figma Strokes to CSS Borders")
- `box-sizing` mismatch

**Fix process:**
1. Check Figma frame dimensions from Step 1/2 metadata
2. Ensure `browser_resize(width, height)` matches exactly
3. If sizes still differ, the component CSS is wrong - fix width/height/padding/border
4. Re-screenshot and verify sizes match before comparing pixels

### Interpreting the Diff Image

When analyzing `screenshots/diff-<component>.png`:

1. **Red areas** = Implementation bugs - fix these first
   - Wrong colors, sizes, positions
   - Missing elements or extra elements
   - Border/padding/margin errors

2. **Orange areas** = Investigate
   - Could be subtle color differences
   - Slight position offsets
   - May or may not need fixing

3. **Yellow areas** = Usually acceptable
   - Font antialiasing (expected)
   - Subpixel rendering differences
   - Transparency blending variations

4. **Grey areas** = Perfect match
   - No action needed

## Step 10: Fix Mismatches and Iterate

If comparison fails (major >= 0.5%):

1. Open `screenshots/diff-<component>.png` - focus on RED pixels
2. Identify the issue (border? size? position? color?)
3. Fix component CSS or story args
4. Re-screenshot (Step 8) and re-compare (Step 9)
5. **Repeat until major < 0.5%**

**Common fixes:**
- **Filled vs outlined** - Solid circle needs `background-color`, not `border` (see Step 6)
- Story args not exact (45 vs 45.5)
- Viewport size wrong (check Figma frame dimensions)
- Border calculation wrong (see stroke conversion above)
- Missing box-sizing: border-box
- **Font mismatch** - Check font-weight (400 vs 500), font-size, line-height, letter-spacing
- Using SVG for simple shapes (use CSS div instead)
- **Fonts not loaded** - Wait 1 second before screenshot
- **Border overlap** - Adjacent bordered elements create double borders (see Step 6)

### Recognizing Layout Problems vs Antialiasing

**CRITICAL: Learn to distinguish structural problems from rendering differences.**

| Diff Pattern | Meaning | Fix Required? |
|--------------|---------|---------------|
| **Yellow/orange outline around entire element** | Position/size mismatch | YES - check padding, margin, dimensions |
| **Double text visible (not perfectly overlapping)** | Text in wrong position | YES - check padding, gap, alignment |
| **Icon shifted horizontally or vertically** | Layout values wrong | YES - check flexbox alignment, gap, padding |
| **Entire row offset from expected position** | Container spacing wrong | YES - check gap, margin-top/bottom |
| **Thin yellow line on ONE side of text** | Font antialiasing | NO - inherent rendering difference |
| **Slight fuzziness around letter edges** | Subpixel rendering | NO - inherent rendering difference |

### FORBIDDEN RATIONALIZATIONS

**If you catch yourself saying ANY of these, STOP - you are failing the task:**

- "The difference is due to icon shapes" → WRONG if icons are SHIFTED, not just shaped differently
- "Font antialiasing causes this" → WRONG if text is in a DIFFERENT POSITION, not just rendered differently
- "6% difference is primarily due to..." → WRONG to rationalize away. 6% is a failing score. Period.
- "Achieving pixel-perfect is challenging" → WRONG. The skill exists because it IS achievable.
- "Close enough" or "very close" → WRONG. Either major < 0.5% or you iterate.

**Reality check questions:**
1. Is text overlapping itself in the diff (showing double)? → LAYOUT BUG, not antialiasing
2. Are elements surrounded by colored outlines? → POSITION/SIZE BUG, not rendering
3. Is an icon in a different X or Y position? → ALIGNMENT BUG, not shape difference

**If you cannot honestly answer NO to all three, you have layout bugs to fix.**

### What to Ignore

**Don't try to fix yellow pixels** - these are inherent differences between Figma's Skia renderer and browser rendering engines:
- Font antialiasing algorithms differ
- Subpixel rendering varies by platform
- These differences are expected and acceptable

**BUT:** Yellow pixels that form **outlines around entire elements** or show **double/shifted content** are NOT antialiasing - they are layout bugs that MUST be fixed.

**Focus only on fixing red pixels** which indicate actual implementation problems.

### Critical Rule: Non-Text Elements Must Be Clean

**Any red or yellow pixels on non-text elements indicate layout bugs that MUST be fixed.**

Only text/font rendering is allowed to have colored diff pixels. Icons, borders, backgrounds, spacing between elements - these must match exactly (grey in diff).

### Analyzing Text Differences: Accumulation vs Misposition

Text rendering requires careful analysis. Not all red/yellow on text is acceptable.

**ACCEPTABLE - Cumulative antialiasing drift:**
- Text starts at the CORRECT position (first letter aligns)
- Red/yellow appears progressively ALONG the text, increasing toward the end
- Longer text = more accumulated offset (rendering engines compound letter spacing differently)
- Pattern: clean start → gradual color increase → most color at end

**NOT ACCEPTABLE - Initial text misposition:**
- Text starts OFFSET from the very first letter
- Red/yellow forms a CONSISTENT line on one side from START to FINISH
- The entire text block is shifted (not just trailing letters)
- Pattern: uniform color offset from the beginning

**How to distinguish:**
1. Look at the FIRST letter - is it aligned or shifted?
2. Is the colored area uniform along the text, or does it grow?
3. Check the container/padding - is the text starting position correct?

**Example analysis:**
```
"Submit" button text:
- "S" aligns perfectly, "ubmit" shows increasing yellow toward "t" → ACCEPTABLE (drift)
- "S" is 2px left of expected, entire "Submit" has yellow on right → NOT ACCEPTABLE (misposition)
```

If text is mispositioned from the start, fix the layout (padding, alignment, gap) - don't dismiss it as "font rendering".