Agentic Figma Components via Claude Code Metadata

Three Pillars of Agentic Components

Every agent-ready component requires props, relationships, and tokens. Props define properties like states (false, true, primary, hover, press, disabled) and variants (appearance axes, size, density). Relationships specify parent-child hierarchies, common contexts (forms, text boxes), and usage frequency. Tokens reference design variables, with semantic names like 'emphasis', 'default', 'subtle' preferred over technical ones like 'primary', 'secondary'; each token needs descriptions (e.g., 'active items and emphasizing', 'hovers on items subtle raising').

Anti-patterns prove as critical as patterns; agents need explicit instructions on prohibited uses, such as avoiding two primary buttons side-by-side or using buttons for navigation.

Metadata Structure for AI Readability

Metadata follows four decisions: (1) states, implied tokens, and variants (primary, secondary, ghost, destructive; loading, disabled booleans; leading icon, onClick); (2) accessibility and relationships (purpose, fit in hierarchy); (3) semantic purpose descriptions ('interactive trigger a single decisive action', 'most common interactive primitive'); (4) anti-patterns and rules ('use exactly one per intent', 'let visual variant signal hierarchy').

Example metadata for a button:

• Category: atom
• Purpose: interactive trigger a single decisive action
• Variants: primary (main CTA), secondary (supporting), minimal, destructive (irreversible)
• Props: loading (boolean), disabled (boolean), leadingIcon (boolean), onClick
• Relationships: common in forms, dialogues, toolbars
• Tokens: spacing, core gray 200
• AI hints: common patterns (destructive as submit); anti-patterns (two primaries side-by-side, navigation, disabled misuse)

Semantic naming aids AI comprehension, aligning with 'AI language is English'.

Workflow: Figma to Storybook via Claude Code

Install the AI Component Metadata skill: npx claude skill from https://github.com/cris-achiardi/claude-skills/tree/main/skills/ai-component-metadata. Create a sibling UI package (e.g., in cal.com repo branch 'agentic-design-systems'). Define schema, copy templates for components.

Spin up Storybook. In Figma, ensure components expose states (type, state, size, icons) and described tokens. Paste Figma MCP console link into Claude Code prompt: 'Using the Figma MCP console and knowledge of defined schema, take the button component in Figma and turn it into a Storybook component.' Claude generates: CSS tokens, component code, metadata.md, stories, index, tests.

Review output in Storybook; iterate (e.g., fix font inheritance from repo, adjust loading state, add anti-patterns). Refine processes into reusable skills.

Iteration and Living System

Agents hallucinate without metadata; humans read docs, agents query structure. Validate in Storybook as source of truth. Update metadata iteratively: deepen anti-patterns product-specifically, ensure token pulls, add descriptions everywhere. Scale to icon buttons, pages; agents then select components contextually (e.g., 'build a page' respects metadata rules). This creates 10x faster design-to-code loops.