agentleFS
plugin87plugin87/full-stack-design-skills/.claude/skills/design-to-code-workflow/SKILL.md

design-to-code-workflow

Skill10 starsChanged 4 months agoMITView on GitHub

Bridge the gap between design and development for seamless component creation. Use this skill for design-to-code processes, component specification documentation, developer handoff, component generation strategies, design system implementation in code, Figma → React workflows, automated component generation, design tokens integration, and development team collaboration. Triggers include: converting Figma designs to React components, specifying components for developers, automating component generation, design system implementation, design-to-code handoff documentation, component creation workflows, and bridging designer-developer workflows. Essential for teams implementing design systems and automating the design-to-development pipeline.

  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 14 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before writing code, developers need:

    line 44
  2. Distinctive:

    When should it be used?

    line 48
  3. Distinctive:

    Read Figma components and variants

    line 204
  4. Distinctive:

    Add tests (unit, visual, accessibility)

    line 299
  5. Distinctive:

    Document in design system

    line 313
  6. Distinctive:

    When API changes (new required prop, removed prop):

    line 329
  7. Distinctive:

    Use Figma as single source of truth

    line 389
  8. Distinctive:

    Use composition for complex UIs

    line 410
  9. Distinctive:

    Keep related props together

    line 411
  10. Distinctive:

    Document when to use variations

    line 412
  11. Distinctive:

    Keep Figma components organized

    line 420
  12. Distinctive:

    Use variants for all states

    line 421
  13. Distinctive:

    Follow design specs exactly

    line 428
  14. Distinctive:

    Test all states/variants

    line 432

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design to Code Workflow

Bridging design systems and development: from Figma specifications to production React components.

The gap between design and code is where friction happens. A smooth design-to-code workflow means designers can specify components once, developers implement them accurately, and updates propagate automatically. This skill focuses on processes, tools, and patterns that eliminate this friction.


Core Principle: Single Source of Truth

The Design-to-Code Pipeline

Figma Design System
       ↓
Design Tokens (colors, spacing, typography)
       ↓
Component Specifications (props, states, variants)
       ↓
Code Generation (or manual implementation)
       ↓
Component Library (Storybook)
       ↓
Production Applications

Goal: Changes in Figma automatically propagate to:

  • Design tokens in code
  • Component props and defaults
  • Component documentation
  • Type definitions (TypeScript)

Stage 1: Design Specification

What Developers Need

Before writing code, developers need:

  1. Component Purpose
    • What problem does this component solve?
    • When should it be used?
  2. Component Specifications
    • Visual design (colors, sizes, spacing)
    • Interaction states (hover, focus, active, disabled)
    • Responsive behavior
    • Accessibility requirements
  3. Props & Variants
    • What props does component accept?
    • What values for each prop?
    • Default values?
    • Type definitions (TypeScript)?
  4. Content & Copy
    • Labels, helper text, error messages
    • Placeholder text
    • Call-to-action buttons
  5. Examples
    • Primary use cases
    • Edge cases
    • Common variations

Figma as Single Source

Figma should contain:

  • Components with variants (primary/secondary, size variants, states)
  • Design tokens in Figma Variables (colors, spacing, typography)
  • Component documentation (description in component properties)
  • Interaction examples (prototypes showing states)

Example: Button Component in Figma

Button (component)
├── Variants
│   ├── Variant: type (primary, secondary, ghost)
│   ├── Variant: size (sm, md, lg)
│   ├── Variant: state (default, hover, focus, active, disabled)
│   └── Variant: icon (with icon, without icon)
├── Properties
│   ├── Label (text)
│   ├── Icon (boolean)
│   └── Loading (boolean)
└── Documentation
    └── "Primary action button. Use for main CTAs."

Stage 2: Component Specification Document

Creating Developer-Friendly Specs

Component Spec Template:

# Button Component

## Purpose
Primary action button for user interactions.

## Variants
- **Type:** primary (blue), secondary (gray), ghost (transparent)
- **Size:** sm (12px font), md (14px font), lg (16px font)
- **State:** default, hover, focus, active, disabled, loading
- **Icon:** with/without leading/trailing icon

## Props
```typescript
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
  type?: 'button' | 'submit' | 'reset';
}

States

  • Default: Normal appearance
  • Hover: Background darkens by 10%
  • Focus: 2px solid blue outline, 2px offset
  • Active: Darker background, slightly inset
  • Disabled: 50% opacity, no cursor pointer
  • Loading: Spinner replaces icon, disabled

Accessibility

  • Focus indicator visible (2px outline)
  • Icon has aria-label if icon-only button
  • Disabled buttons announce status
  • Color not sole indicator (icon + color)

Examples

  • Submit button (primary, md)
  • Cancel button (secondary, md)
  • Delete button (danger, md, loading state)

---

## Stage 3: Component Implementation

### Option A: Manual Implementation (Reliable)

**Button.tsx:**
```jsx
import React from 'react';
import styles from './Button.module.css';

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
  type?: 'button' | 'submit' | 'reset';
}

export function Button({
  variant = 'primary',
  size = 'md',
  disabled = false,
  loading = false,
  icon,
  children,
  onClick,
  type = 'button',
}: ButtonProps) {
  const className = `${styles.button} ${styles[`button--${variant}`]} ${styles[`button--${size}`]}`;

  return (
    <button
      className={className}
      disabled={disabled || loading}
      onClick={onClick}
      type={type}
      aria-busy={loading}
    >
      {loading ? <Spinner /> : icon}
      {children}
    </button>
  );
}

Option B: Automated Generation (Faster)

From Figma components → code:

Tools like Penpot, Figma plugins, or custom scripts can:

  1. Read Figma components and variants
  2. Generate React component with props
  3. Generate TypeScript types
  4. Generate Storybook stories
  5. Generate CSS/styled-components

Generated Output:

Button.tsx (component)
Button.types.ts (TypeScript interfaces)
Button.stories.tsx (Storybook)
Button.module.css (styles)

Trade-off:

  • Manual: Reliable, customizable, slower to update
  • Automated: Fast, consistent, less flexible

Best approach: Automated with manual refinement.


Stage 4: Design Tokens Sync

Tokens Flow

Figma Variables (colors, spacing, typography)
         ↓
Token Export (JSON, CSS, TypeScript)
         ↓
Code Integration (CSS, Tailwind config, design system)
         ↓
Component Usage

Example: Color Tokens

Figma Variables:

Colors/
  Primary/
    50: #eff6ff
    500: #2563eb
    900: #1e3a8a
  Neutral/
    50: #f9fafb
    900: #111827

Exported to tokens.json:

{
  "color": {
    "primary": {
      "50": { "value": "#eff6ff" },
      "500": { "value": "#2563eb" },
      "900": { "value": "#1e3a8a" }
    }
  }
}

Used in code:

import { tokens } from '@design-system/tokens';

const Button = styled.button`
  background-color: ${tokens.color.primary[500]};
  
  &:hover {
    background-color: ${tokens.color.primary[900]};
  }
`;

Stage 5: Developer Handoff

Before Implementation

Design team provides:

  • ✅ Figma file with components
  • ✅ Design tokens exported
  • ✅ Component specifications (props, states)
  • ✅ Figma → Code handoff document
  • ✅ Storybook examples of each variant

During Implementation

Developers:

  • Implement component following spec
  • Add TypeScript types
  • Write Storybook stories
  • Add tests (unit, visual, accessibility)
  • Update component documentation

After Implementation

Design team reviews:

  • Does component match Figma?
  • Are all states covered?
  • Is accessibility correct?
  • Performance acceptable?

Deploy:

  • Publish component to npm
  • Update Storybook
  • Document in design system

Stage 6: Updates & Versioning

When Design Changes

  1. Designer updates Figma
  2. Export new tokens (if applicable)
  3. Developer updates component
  4. Version bump (major/minor/patch)
  5. Apps update to new version

Breaking Changes

When API changes (new required prop, removed prop):

  • Major version bump (1.0.0 → 2.0.0)
  • Document migration guide
  • Consider deprecation period

Non-Breaking Changes

When visual-only changes:

  • Patch version bump (1.0.0 → 1.0.1)
  • Apps auto-update

Tools & Technologies

Design-to-Code Tools

Figma Plugins:

  • Figma to React (generates React components)
  • HTML Export (generates HTML/CSS)
  • Component Generator (creates component boilerplate)

Design Token Tools:

  • Tokens Studio for Figma
  • Style Dictionary (token transformation)
  • Theo (design tokens)

Code Generation:

  • Penpot (design tool with code export)
  • Framer (design tool, exports React)
  • Storybook (component documentation)

Workflow Automation

GitHub Actions:

name: Token Update
on: [push]
jobs:
  update-tokens:
    runs-on: ubuntu-latest
    steps:
      - name: Export tokens from Figma
        run: npm run export:tokens
      - name: Commit and push
        run: |
          git add tokens/
          git commit -m "Update design tokens"
          git push

Common Challenges

❌ Designer-Developer Gap

Problem: Designers and developers work independently, updates don't sync.

Solution:

  • Use Figma as single source of truth
  • Automate token export
  • Regular design system reviews
  • Shared documentation

❌ Stale Documentation

Problem: Figma doesn't match component in code.

Solution:

  • Automate component generation
  • CI/CD checks (compare Figma to code)
  • Regular audits
  • Version control for components

❌ Prop Explosion

Problem: Component has too many props, becomes unmaintainable.

Solution:

  • Limit variants (3-4 per prop max)
  • Use composition for complex UIs
  • Keep related props together
  • Document when to use variations

Best Practices

For Designers

  • Keep Figma components organized
  • Use variants for all states
  • Document component usage
  • Export tokens regularly
  • Review code implementations

For Developers

  • Follow design specs exactly
  • Implement TypeScript types
  • Create Storybook stories
  • Write accessible code
  • Test all states/variants
  • Keep documentation current

For Teams

  • Regular sync meetings (design + dev)
  • Shared design system documentation
  • Automated token export
  • Version management strategy
  • Migration guides for breaking changes

When to Use This Skill

✅ Do use for:

  • Design-to-code workflows
  • Component specification and handoff
  • Design tokens sync and integration
  • Component generation strategies
  • Design system implementation
  • Figma → React component conversion
  • Automation and CI/CD for design systems
  • Designer-developer collaboration
  • Version management for components

❌ Don't use for:

  • Figma basics (see figma-expert-workflows)
  • CSS styling (see css-styling-pixel-perfect)
  • React component patterns (see frontend-framework-guide)
  • Design system architecture (see design-systems-architecture)
  • Component documentation (see component-library-mastery)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.