Figma Component Sync Skill

Specialized workflow for translating a Figma node URL into production-ready components and Storybook stories with high visual fidelity.

When to Use

• User shares a Figma URL and asks to implement the UI
• User asks for "Figma to Storybook" or "sync design to code"
• User needs exact visual parity before productization

Required Inputs

• Figma URL with node-id parameter
• Initiative name (or feature name) for artifacts
• Target domain in app (for example chat, navigation, settings)

Codebase Targets

Use the current Elephant AI app layout:

• Components: elephant-ai/apps/web/src/components/
• Storybook config: elephant-ai/apps/web/.storybook/
• Initiative specs: pm-workspace-docs/initiatives/[initiative-name]/

If apps/web is missing, check for legacy web/src paths and adapt.

Workflow

1) Validate and Scope

1. Confirm URL includes node-id.
2. Limit scope to one frame/component set at a time.
3. Define output folder and component names before generating code.

2) Check Existing Components First

Avoid duplicate components. Search for same or similar names/purpose in:

• elephant-ai/apps/web/src/components/
• Exclude generated prototypes unless user asked for prototype-only output

If a matching production component exists, update it instead of creating a duplicate.

3) Extract Design Data via MCP

Use Figma MCP in this order:

1. get_metadata for node inventory and child structure
2. get_design_context for layout/style/component hierarchy
3. get_variable_defs for tokens and variable collections
4. get_screenshot for pixel-parity validation artifact

Use exact extraction mode only when requested:

• forceCode: true (or equivalent exact-mode option)
• Preserve raw generated output in figma-generated/ if needed for comparison

4) Build a Canonical Spec

Create pm-workspace-docs/initiatives/[initiative-name]/figma-spec.json with:

• Source URL and node ID
• Variant/property mapping
• Component states and story args
• Token mapping decisions (existing app tokens first)
• Open parity gaps requiring manual follow-up

5) Generate Components

Create or update files in the chosen component folder:

• [component-name].tsx
• [component-name].stories.tsx
• types.ts (optional, when prop surface is large)
• index.ts export barrel

Implementation rules:

• Prefer existing @/components/ui/* primitives
• Reuse existing chat/navigation/layout patterns from nearby components
• Keep API/data-fetching/business logic out of first scaffold pass
• Match spacing/typography/radius/shadows from app tokens before custom classes

6) Generate Storybook Coverage

Stories must include:

• One story per variant/state extracted from Figma
• Required interactive states (loading, success, error, empty, low-confidence where applicable)
• A visual comparison reference (screenshot-based) for manual parity check

7) Run Fidelity Check

Before handoff, verify:

• Layout hierarchy matches Figma structure
• Typography, spacing, and colors map to app tokens
• Interaction and hover/focus/disabled states are present
• Mobile and desktop breakpoints match intended behavior

Output Contract

Deliver:

• Component file paths
• Storybook story paths
• figma-spec.json path
• Short delta list: what is exact, what is approximate, what needs designer decision

Re-Sync Rules

When design changes:

1. Re-run extraction on the same node URL.
2. Update spec first, then update component + stories.
3. Preserve custom logic/accessibility fixes added after the first sync.
4. Flag breaking prop changes explicitly.