design-to-code

Design-to-Code Agent Skill

Translate UI/UX designs into production-ready, accessible, responsive frontend code. This skill turns an agent into a design-aware implementation engine that extracts design tokens, maps component hierarchies, applies accessibility standards, and produces framework-appropriate code — not just a design export.

Quick Reference

Quality Tiers:

• 💎 Production — Accessible, responsive, tested, framework-native, token-driven
• 🥈 MVP — Functional across breakpoints, basic accessibility, inline styles OK for speed
• 🥉 Prototype — Single viewport, minimal accessibility, rapid iteration

When to Use This Skill

Activate this skill when the user asks you to:

• "Turn this Figma design into code" / "Convert this mockup to React/Vue/Svelte"
• "Implement this design" / "Build this UI from this screenshot"
• "Extract design tokens from this Figma file" / "Create a design system from these specs"
• "Make this design responsive" / "Add responsive breakpoints to this layout"
• "Make this component accessible" / "Ensure WCAG 2.1 AA compliance"
• "Set up a component from this Sketch/XD design"
• "Create a pixel-perfect implementation of this design"
• "Integrate this design with our existing design system"
• "Set up visual regression tests for these components"
• Any request containing "design" + "code", "implement", "build", "convert", or "translate"

Additionally, activate proactively when a conversation includes a design artifact (Figma link, screenshot, design spec) and the user's intent is implementation.

Do NOT Activate For

The following inputs are near-miss negatives — they mention design or code language but are not design-to-code tasks:

• Pure code generation without a design: "Write a React form component" — no visual design input, so plain coding.
• Design critique/review: "What do you think of this design?" — opinion, not implementation.
• Pure accessibility audit without implementation: "Audit this page for accessibility" — audit, not design-to-code.
• Design tool usage questions: "How do I create an auto-layout in Figma?" — tool instruction, not code generation.
• Backend/styling-less code: "Build a REST API for user management" — no visual design involved.
• Pure CSS framework questions: "What's better, Tailwind or CSS Modules?" — opinion, not implementation.
• Animating existing components: "Add a fade-in animation to this button" — micro-interaction on existing code, not a full design translation.
• Logo/brand asset generation: "Create an SVG logo based on this brief" — graphic design output, not frontend implementation.
• Design token management without code: "Organize our design tokens in Figma" — design tool work, not code.

When in doubt, ask: "Do you have a design you want me to translate into code, or are you asking me to work directly with code/design concepts?"

Common Pitfalls & Anti-Patterns

❌ Implementer Anti-Patterns

1. Skipping the design analysis phase — Jumping straight to code without

understanding the design's intent, hierarchy, and reusable patterns. Always ingest and analyze before you code.

1. Hardcoding design values — Using raw pixel values (color: #3B82F6)

instead of design tokens (color: var(--color-primary-500)). Token-driven code is maintainable; hardcoded values rot.

1. Accessibility as an afterthought — Adding ARIA at the end rather than

building accessible from the start. Retrofit accessibility is always incomplete.

1. Responsive as a second pass — Implementing desktop-first then

"making it responsive" leads to fragile media-query spaghetti. Plan breakpoints and layout strategy before writing a single rule.

1. Div-soup markup — Nesting <div> inside <div> rather than using

semantic HTML (<nav>, <main>, <section>, <article>, <aside>). Semantic elements are free accessibility and SEO wins.

1. Over-engineering the component tree — Creating 12 components for a

simple card because "atomic design says so." Map hierarchy to what the design actually calls for, not an ideology.

1. Copying Figma auto-layout directly — Figma's stacking model doesn't

always map 1:1 to CSS Flexbox/Grid. Translate the intent, not the implementation.

1. Ignoring existing design system tokens — Using colors/spacing that

diverge from the project's token set. "Close enough" values accumulate into an inconsistent codebase.

1. Testing only one viewport — Verifying at 1440px and calling it done.

Every breakpoint, every browser, every component state needs verification.

1. Skipping visual regression testing — Assuming your implementation

matches the design because it "looks right." Screenshot diffs catch what the human eye misses.

✅ Implementation Quality Checklist

Before declaring a design-to-code task complete, verify:

• [ ] All design sources were ingested and analyzed
• [ ] Design tokens are extracted and referenced as CSS custom properties or token variables
• [ ] Component hierarchy matches the design's visual hierarchy
• [ ] All defined breakpoints have been implemented and tested
• [ ] WCAG 2.1 AA compliance verified (contrast, focus, labels, semantics)
• [ ] Framework conventions followed (component structure, styling approach)
• [ ] No hardcoded design values — all through tokens
• [ ] Visual regression baselines captured and tests pass
• [ ] Component states accounted for (hover, focus, active, disabled, loading, empty, error)
• [ ] Keyboard navigation works end-to-end
• [ ] Screen reader announcement is meaningful
• [ ] Dark mode / theme variants considered (if applicable)

Workflow

Phase 1: Ingest the Design Source

1. Identify the design source type:

• Figma: Extract via Figma API, Figma plugin export, or screenshot +

manual annotation. For API access, use the Figma file key and node IDs.

     # Extract Figma file as JSON
     curl -H "X-Figma-Token: $FIGMA_TOKEN" \
       "https://api.figma.com/v1/files/FILE_KEY"

• Sketch: Parse .sketch files (they are ZIP archives with JSON inside).

Extract via unzip and read document.json + pages/.

• Adobe XD: Export via XD plugin or Adobe's Design Automation API.
• Screenshots / image files: Use image analysis (vision model) to

identify layout, colors, typography, spacing, and components. If a screenshot is the only input, acknowledge the precision limitation.

• Design specs / redlines: Parse spec documents for explicit

measurements, colors, and type scales.

1. Normalize the design data. Regardless of source, produce:

• Color palette — all named colors with hex/RGB/HSL values
• Typography scale — font families, sizes, weights, line heights,

letter spacing per text style

• Spacing scale — consistent spacing units (4px/8px base recommended)
• Shadow definitions — box-shadow values per elevation level
• Border radii — consistent corner radius tokens
• Component inventory — every distinct UI element, its states, and

how it repeats

1. If the design source is incomplete (screenshot, rough mockup), ask the

user for clarification on:

• Exact color values (approximated from a screenshot may be off)
• Font family names (not guessable from a screenshot)
• Interactive states not visible in a static image
• Responsive behaviour at different breakpoints

Phase 2: Extract and Define Design Tokens

Extract a structured token system. Use CSS custom properties as the canonical format and derive framework-specific versions.

:root {
  /* Colors — Primary */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-200: #bfdbfe;
  --color-primary-300: #93c5fd;
  --color-primary-400: #60a5fa;
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-primary-800: #1e40af;
  --color-primary-900: #1e3a8a;

  /* Colors — Neutral */
  --color-neutral-50: #fafafa;
  --color-neutral-100: #f5f5f5;
  /* ...through 900 */

  /* Typography */
  --font-family-sans: 'Inter', system-ui, -apple-system, sans-serif;
  --font-family-mono: 'JetBrains Mono', 'Fira Code', monospace;

  --font-size-xs: 0.75rem;    /* 12px */
  --font-size-sm: 0.875rem;   /* 14px */
  --font-size-base: 1rem;     /* 16px */
  --font-size-lg: 1.125rem;   /* 18px */
  --font-size-xl: 1.25rem;    /* 20px */
  --font-size-2xl: 1.5rem;    /* 24px */
  --font-size-3xl: 1.875rem;  /* 30px */
  --font-size-4xl: 2.25rem;   /* 36px */

  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;

  --line-height-tight: 1.25;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.75;

  /* Spacing — 4px base scale */
  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-3: 0.75rem;   /* 12px */
  --space-4: 1rem;      /* 16px */
  --space-5: 1.25rem;   /* 20px */
  --space-6: 1.5rem;    /* 24px */
  --space-8: 2rem;      /* 32px */
  --space-10: 2.5rem;   /* 40px */
  --space-12: 3rem;     /* 48px */
  --space-16: 4rem;     /* 64px */
  --space-20: 5rem;     /* 80px */

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);

  /* Border Radius */
  --radius-sm: 0.125rem;   /* 2px */
  --radius-md: 0.375rem;   /* 6px */
  --radius-lg: 0.5rem;     /* 8px */
  --radius-xl: 0.75rem;    /* 12px */
  --radius-2xl: 1rem;      /* 16px */
  --radius-full: 9999px;
}

Token naming conventions:

• Use the W3C Design Tokens Community Group format

where possible: color.primary.500, spacing.md, typography.heading.lg.

• In CSS custom properties, use kebab-case dot-separated or dash-separated:

--color-primary-500 or --typography-heading-lg.

• For framework-specific code (Tailwind config, Theme UI, styled-system),

derive the token structure from the CSS custom properties.

Token validation checklist:

• [ ] All colors have a 50–900 scale (or a documented reason not to)
• [ ] Font sizes use relative units (rem) for accessibility
• [ ] Spacing uses a consistent base unit (4px or 8px)
• [ ] No raw values in component code — only token references
• [ ] Dark mode tokens defined if the design supports it

See references/design-tokens-guide.md for the full W3C DTCG token specification and advanced patterns.

Phase 3: Map the Component Hierarchy

1. Identify the top-level layout structure:

• Header, main content area, sidebar, footer
• Page-level grid or layout container

1. Decompose into component tree:

   Page
   ├── Header
   │   ├── Logo
   │   ├── Navigation
   │   │   └── NavItem (repeating)
   │   └── UserMenu
   │       ├── Avatar
   │       └── Dropdown
   ├── MainContent
   │   ├── HeroBanner
   │   │   ├── Heading
   │   │   ├── Subheading
   │   │   └── CTAButton
   │   ├── FeatureGrid
   │   │   └── FeatureCard (repeating)
   │   │       ├── Icon
   │   │       ├── Title
   │   │       └── Description
   │   └── TestimonialCarousel
   │       └── TestimonialCard (repeating)
   └── Footer
       ├── FooterLinks
       └── SocialIcons

1. For each component, define:

• Props/interface — what data flows in
• States — default, hover, focus, active, disabled, loading, empty,

error (list all that apply)

• Variants — primary/secondary for buttons, compact/default/expanded

for cards, etc.

• Slots/children — where does content get injected
• Responsive behaviour — how does it change at each breakpoint

1. Identify shared/reusable patterns:

• Buttons, inputs, cards, avatars — extract as base components
• Layout primitives — Container, Grid, Stack, Flex
• Typography components — Heading, Text, Caption

1. For each reusable component, check if an equivalent exists in the

project's design system. If yes, extend it rather than creating a new one.

Phase 4: Define Responsive Breakpoint Strategy

1. Choose a breakpoint system:

• Mobile-first (recommended): Start at the smallest viewport and add

complexity as screen size increases. Use min-width media queries.

• Desktop-first: Start at the largest viewport and simplify for

smaller screens. Use max-width media queries. Less common but valid for desktop-heavy applications.

1. Define breakpoint values. Common breakpoints:

1. For each breakpoint, document layout changes:

1. Implement responsive utilities. Create CSS custom properties or

utility classes for media queries. For Tailwind, use the built-in breakpoint prefixes (sm:, md:, lg:, xl:).

1. Test at every breakpoint. Do not trust that a component will work at

intermediate sizes. 720px can expose layout bugs that 640px and 768px hide.

Phase 5: Accessibility-First Implementation

Minimum standard: WCAG 2.1 Level AA. If the user's project requires AAA, escalate accordingly.

5.1 Semantic HTML

Use the correct HTML element for every piece of content. This is the single highest-impact accessibility decision.

5.2 ARIA — Use Only When HTML Isn't Enough

First rule of ARIA: don't use ARIA if native HTML can do it. ARIA adds complexity and is easy to get wrong.

When ARIA is necessary:

5.3 Color and Contrast

• Text contrast ratio: 4.5:1 minimum for normal text, 3:1 for large text

(18px+ bold or 24px+ regular). WCAG AA requirement.

• Non-text contrast: 3:1 minimum for UI components and graphical objects

(button borders, input borders, icons).

• Never use color alone to convey information. Error states need both

red color AND an icon/text indicator. Links need underlines (not just color change).

• Focus indicators: Every interactive element must have a visible focus

style. Default outline is fine; custom focus rings must have 3:1 contrast against adjacent colors. :focus-visible is preferred over :focus for mouse users.

/* Good focus indicator */
:focus-visible {
  outline: 3px solid var(--color-primary-500);
  outline-offset: 2px;
}

/* Avoid — removes focus entirely */
*:focus { outline: none; }

5.4 Keyboard Navigation

• Tab order must follow visual order. Avoid positive tabindex values;

use tabindex="0" to add to the natural order or tabindex="-1" for programmatic focus only.

• Interactive elements must be reachable and operable via keyboard:

buttons, links, form controls, custom widgets.

• Skip links: Provide a "Skip to main content" link as the first

focusable element.

• Modals: Trap focus inside the modal while open. Restore focus to the

trigger element on close.

• Dropdown/Menus: Arrow keys navigate items. Escape closes. Enter/Space

selects.

5.5 Screen Reader Considerations

• Descriptive link text: "Learn more about pricing" not "Click here".
• Image alt text: Describe what the image communicates, not what it is.

"Golden retriever fetching a ball in a park" not "Photo of dog".

• Form labels: Every input must have an associated <label>. Use

aria-label or aria-labelledby only when a visible label is not possible.

• Dynamic content: Use aria-live regions for content that updates

without page reload (search results, chat messages, notifications).

• Heading hierarchy: One <h1> per page. Headings should form a logical

outline without skipping levels (no <h1> to <h3> without <h2>).

5.6 Accessibility Audit Checklist

Before shipping, verify:

• [ ] Page has a unique, descriptive <title>
• [ ] <html> has a lang attribute
• [ ] All images have appropriate alt text
• [ ] Color contrast meets WCAG AA minimums (use a checker tool)
• [ ] Focus order is logical and visible
• [ ] Skip link is present and functional
• [ ] Forms have associated labels and error messages
• [ ] Page is navigable by keyboard alone (try tabbing through)
• [ ] ARIA roles, states, and properties are valid (use axe DevTools or

Lighthouse)

• [ ] Dynamic content updates are announced to screen readers

Phase 6: Framework-Agnostic Implementation Patterns

Produce code appropriate to the project's framework. This skill does not favor one framework — adapt to what the project uses.

6.1 React (with TypeScript)

// Button component — React + CSS Modules
import styles from './Button.module.css';
import { type ComponentPropsWithoutRef, forwardRef } from 'react';

type ButtonVariant = 'primary' | 'secondary' | 'ghost';
type ButtonSize = 'sm' | 'md' | 'lg';

interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', isLoading, children, disabled, className, ...props }, ref) => {
    const classes = [
      styles.button,
      styles[variant],
      styles[size],
      isLoading && styles.loading,
      className,
    ].filter(Boolean).join(' ');

    return (
      <button
        ref={ref}
        className={classes}
        disabled={disabled || isLoading}
        aria-busy={isLoading}
        {...props}
      >
        {isLoading ? <Spinner size={size} /> : children}
      </button>
    );
  }
);

Button.displayName = 'Button';

6.2 Vue 3 (Composition API)

<script setup lang="ts">
import { computed } from 'vue';

type ButtonVariant = 'primary' | 'secondary' | 'ghost';
type ButtonSize = 'sm' | 'md' | 'lg';

const props = withDefaults(defineProps<{
  variant?: ButtonVariant;
  size?: ButtonSize;
  loading?: boolean;
  disabled?: boolean;
}>(), {
  variant: 'primary',
  size: 'md',
  loading: false,
  disabled: false,
});

const classes = computed(() => [
  `btn btn--${props.variant}`,
  `btn--${props.size}`,
  { 'btn--loading': props.loading },
]);
</script>

<template>
  <button
    :class="classes"
    :disabled="disabled || loading"
    :aria-busy="loading"
  >
    <Spinner v-if="loading" :size="size" />
    <slot v-else />
  </button>
</template>

6.3 Svelte

<script lang="ts">
  export let variant: 'primary' | 'secondary' | 'ghost' = 'primary';
  export let size: 'sm' | 'md' | 'lg' = 'md';
  export let loading = false;
  export let disabled = false;
</script>

<button
  class="btn btn--{variant} btn--{size}"
  class:btn--loading={loading}
  {disabled}
  aria-busy={loading}
  on:click
  {...$$restProps}
>
  {#if loading}
    <Spinner {size} />
  {:else}
    <slot />
  {/if}
</button>

6.4 Plain HTML/CSS (Web Components)

<!-- Usage -->
<ds-button variant="primary" size="md">Click me</ds-button>

<script>
class DsButton extends HTMLElement {
  static observedAttributes = ['variant', 'size', 'loading', 'disabled'];

  connectedCallback() {
    this.render();
  }

  attributeChangedCallback() {
    this.render();
  }

  render() {
    const variant = this.getAttribute('variant') || 'primary';
    const size = this.getAttribute('size') || 'md';
    const loading = this.hasAttribute('loading');
    const disabled = this.hasAttribute('disabled');

    this.setAttribute('role', 'button');
    this.setAttribute('tabindex', disabled ? '-1' : '0');
    this.setAttribute('aria-busy', String(loading));
    this.className = `ds-button ds-button--${variant} ds-button--${size} ${loading ? 'ds-button--loading' : ''}`;

    if (loading) {
      const spinner = document.createElement('ds-spinner');
      spinner.setAttribute('size', size);
      this.replaceChildren(spinner);
    } else {
      this.replaceChildren(document.createElement('slot'));
    }
  }
}

customElements.define('ds-button', DsButton);
</script>

Phase 7: CSS Architecture Selection

Choose and apply the appropriate CSS strategy based on the project context.

Decision matrix:

1. If the project already uses a CSS approach, match it. Consistency > personal preference.
2. If starting fresh and speed matters, Tailwind CSS or plain CSS custom properties.
3. If building a design system, CSS custom properties + CSS Modules for components.
4. If heavy runtime theming is needed, styled-components or Theme UI.

Phase 8: Visual Regression Testing Strategy

1. Set up a visual testing tool — Chromatic (Storybook), Percy, Playwright

screenshot comparison, or BackstopJS.

1. Define test scenarios:

• Every component in every meaningful state (default, hover, focus, etc.)
• Every breakpoint
• Every theme variant (light/dark)
• Edge cases: very long text, missing images, empty states, error states

1. Capture baselines from the initial implementation and compare against

design references (Figma exports, design screenshots).

1. Establish a regression workflow:

   Implement → Capture baseline → Compare to design → Fix diffs → Re-capture

1. Example Playwright visual test:

   import { test, expect } from '@playwright/test';

   test('Button component matches design', async ({ page }) => {
     await page.goto('/components/button');
     await expect(page.locator('[data-testid="button-primary"]')).toHaveScreenshot(
       'button-primary.png',
       { maxDiffPixelRatio: 0.01 }
     );
   });

1. Acceptable diff thresholds:

• Pixel-perfect: 0% diff (brand pages, landing pages, core UI)
• Near-perfect: <0.5% diff (internal tools, dashboards)
• Tolerance: <2% diff (rapid prototyping, early-stage products)

Phase 9: Design System Integration

When the project has an existing design system, integrate without disruption.

1. Audit the existing system — what tokens, components, and patterns

already exist?

1. Map new design elements to existing tokens:

• If the design uses a color that matches --color-primary-500, use it.
• If the design introduces a new color not in the system, flag it:

"This design specifies #7C3AED which is not in our design system. The closest existing token is --color-secondary-600 (#7C3AED is an exact match to our secondary-600 — recommend using it)."

1. Extend components rather than creating duplicates. If a Card

component exists but the design needs a slightly different variant, add a prop rather than creating SpecialCard.

1. If the design contradicts the design system, flag the discrepancy

and ask whether the design should change or the design system should be updated.

1. Token synchronization — If the project has a token pipeline (e.g.,

Style Dictionary → CSS + JS + Tailwind config), update the source of truth, not the generated files.

Safety Rules

ABSOLUTE RULES — never violate these:

1. Respect intellectual property. Never reproduce copyrighted designs,

illustrations, logos, or brand assets without explicit permission or license. If a user provides a design from Dribbble, Behance, or a competitor's website and asks you to clone it, refuse: "I cannot reproduce this design because it appears to be copyrighted/owned by [entity]. I can help you create an original design inspired by UI patterns but not a direct copy."

1. Never ship hardcoded secrets. If a design includes API keys,

tokens, or credentials in code examples, flag them and strip them. Use environment variables.

1. Always use HTTPS for external assets (fonts, images, CDN resources).

Mixed content is a security risk.

1. Respect user privacy. Don't add third-party trackers, analytics,

or telemetry to generated code without the user's explicit request. Screen readers and accessibility tools must not be blocked.

1. Be honest about fidelity. When working from a screenshot (not a

design file), preface output with: "I'm working from a screenshot, so colors and exact measurements are approximate. Please verify the following values against your design spec."

1. Don't silently replace the design intent. If the design has a

complex interaction that would be expensive to implement, don't simplify it without asking. Say: "This carousel pattern would take ~4 hours to implement with full accessibility. A simpler tabbed layout would take ~1 hour. Which do you prefer?"

1. Accessibility is non-negotiable. Every implementation must meet

WCAG 2.1 AA at minimum. If the user explicitly asks to skip accessibility, warn them but comply with the caveat noted.

1. Don't generate inaccessibly. Never produce code with outline: none

without a replacement focus indicator. Never use tabindex values greater than 0. Never skip heading levels or use non-semantic markup where semantic elements exist.

Platform Compatibility Notes

This skill is designed to work across AI coding platforms with minor adaptations:

Platform-Specific Adjustments

• If Figma API token is unavailable: ask the user to export the design as

SVG/PNG or paste a design spec document. Screenshot analysis is the fallback.

• If image/vision analysis is not available: ask the user to describe the

design in text (layout, colors, typography, spacing). Work from description.

• If a specific framework is not specified: default to the framework the

project already uses. If no project exists, ask the user.

• For Discord/Slack delivery: use bullet lists, not markdown tables. Split

large code blocks across multiple messages. Wrap links in <>.

• For platforms without file system access: inline tokens and styles

directly in generated output rather than referencing external files.

References

• references/design-tokens-guide.md — W3C Design Tokens Community Group

specification and implementation guide

• WCAG 2.1 Quick Reference —

Official WCAG 2.1 guidelines

• WAI-ARIA Authoring Practices —

ARIA design patterns and widget examples

• Figma API Documentation —

Figma REST API reference

• Style Dictionary —

Design token transformation tool

• WebAIM Contrast Checker —

Color contrast verification

• axe DevTools — Automated accessibility testing
• Chromatic — Visual regression testing for

Storybook