Skip to main content
skill CX Codex

ai-component-metadata — Claude Code skill: component metadata

The ai-component-metadata Claude Code skill creates structured metadata for design system components used in AI-generated interfaces. It runs during component analysis and records how each component should be composed and used.

MIT ★ 107 updated 2026-11-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-code
Open on GitHub

What ai-component-metadata does

The skill examines a component’s structure, including its slots, child elements, variants, states, prop types, and accessibility attributes. It turns those findings into metadata covering usage patterns, composition constraints, behavior, and guidance for AI.

For automatic generation, scripts/generate_metadata.py reads a component file and runs with python. Alternatively, copy assets/metadata-template.tsx and fill it in manually. The skill recommends testing the metadata with generation tasks and in Storybook, using runnable code examples.

What it helps with

  • document a component’s props, variants, and states
  • record common usage patterns and anti-patterns
  • describe how components fit together
  • preserve accessibility details for generated interfaces

Example prompts for the agent

  • Create metadata for Button.tsx, including its props, states, and accessibility details.
  • Analyze FormField.tsx and document common patterns and anti-patterns.
  • Write metadata for these design system components using the provided schema.

How to install ai-component-metadata

1Skills CLI (Vercel)

npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-code

2Manually: put the files in place

~/.claude/skills/ai-component-metadata/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ai-component-metadata/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ai-component-metadata

How do I install ai-component-metadata in Claude Code?

Run npx skills add thedesignproject/agent-skills --skill ai-component-metadata -a claude-code. The skill file is located at ~/.claude/skills/ai-component-metadata/SKILL.md.

What does ai-component-metadata do?

It analyzes component structure and creates metadata about usage, composition, behavior, and accessibility. AI can use that information to select and apply design system components during interface generation.

Can ai-component-metadata be used with Figma MCP?

Yes. Figma MCP can supply visual design context, while the component metadata describes behavior; AI can combine both.

Source text

SKILL.md · MIT
---
name: ai-component-metadata
version: 1.0.0
description: Generate AI-ready metadata for design system components to enable intelligent UI generation. Analyzes component structure and generates structured metadata that helps AI understand when and how to use components correctly. Useful for teams building AI-consumable design systems.
---

# AI Component Metadata Generator

Generate structured, AI-consumable metadata for design system components to enable intelligent UI generation and component usage.

## Quick Start

When analyzing a component, use the metadata schema template in `scripts/generate_metadata.py` or follow the manual process below:

```bash
# Automatic generation (reads component file)
python scripts/generate_metadata.py path/to/Component.tsx

# Or use the template directly
cp assets/metadata-template.tsx your-component-metadata.tsx
```

## Core Workflow

### 1. Analyze Component Structure
Identify:
- Component composition (slots, children)
- Available variants and states
- Props and their types
- Accessibility attributes

### 2. Generate Metadata
Create metadata following this schema:

```javascript
export const componentMetadata = {
  component: {
    name: "ComponentName",
    category: "atoms|molecules|organisms",
    description: "Brief description",
    type: "interactive|display|container|input|navigation"
  },
  
  usage: {
    useCases: ["primary-use", "secondary-use"],
    requiredProps: [],
    commonPatterns: [
      {
        name: "pattern-name",
        description: "When to use",
        composition: "JSX example"
      }
    ],
    antiPatterns: [
      {
        scenario: "what-not-to-do",
        reason: "why",
        alternative: "what-instead"
      }
    ]
  },
  
  composition: {
    slots: {},
    nestedComponents: [],
    commonPartners: [],
    parentConstraints: []
  },
  
  behavior: {
    states: [],
    interactions: {},
    responsive: {}
  },
  
  accessibility: {
    role: "ARIA role",
    keyboardSupport: "description",
    screenReader: "behavior",
    focusManagement: "strategy",
    wcag: "AA"
  },
  
  aiHints: {
    priority: "high|medium|low",
    keywords: [],
    context: "when to use"
  }
}
```

### 3. Validate Metadata
- Test with AI generation tasks
- Verify in Storybook
- Ensure examples are runnable

## Component Categories

- **atoms**: Basic building blocks (Button, Text, Input)
- **molecules**: Simple combinations (Card, Chip, FormField)
- **organisms**: Complex components (Header, Table, Form)

## Advanced Features

For complex scenarios, see:
- **Nested components**: [NESTED.md](references/NESTED.md)
- **Integration patterns**: [INTEGRATION.md](references/INTEGRATION.md)
- **Testing strategies**: [TESTING.md](references/TESTING.md)

## Working with Figma

When combining with Figma MCP:

```javascript
// Figma provides visual context
const figmaContext = await Figma.get_design_context();

// Your metadata provides behavioral context
const componentMetadata = components.Button.metadata;

// AI combines both for complete understanding
```

## Best Practices

1. **Keep examples real** - Use actual, runnable code
2. **Focus on patterns** - Document common usage patterns
3. **Include anti-patterns** - Help AI avoid mistakes
4. **Validate through usage** - Test with actual AI generation

## Success Metrics

Your metadata is effective when:
- AI uses existing components instead of recreating
- Correct variants are selected based on context
- Accessibility is maintained in generated code
- Patterns are consistent across AI outputs

© thedesignproject · MIT · thedesignproject/agent-skills

Similar skills

All skills for Design →

From the same set13

The whole set →
performance-review-self-assessment The performance-review-self-assessment Claude Code skill guides employees through a quarterly self-assessment. It covers accomplishments, challenges, leadership principles, and progress on development goals. CX Codex +1 ★ 107repo stars performance-review-manager The performance-review-manager Claude Code skill guides a manager through a quarterly employee review. It gathers peer feedback and helps assess performance, potential, and development. CX Codex +1 ★ 107repo stars performance-review-360-peer The performance-review-360-peer Claude Code skill guides a colleague through peer feedback using Nonviolent Communication. It asks about strengths, growth areas, leadership principles, and future collaboration. CX Codex +1 ★ 107repo stars create-skill This Claude Code skill helps create Cursor skills and explains the structure of SKILL.md. It applies to requests for a new skill or questions about its instruction file. CX Codex +1 ★ 107repo stars create-prd create-prd is a Claude Code skill that turns a feature request or transcript into a PRD. It examines the codebase and can create a Linear project with issues. CX Codex +1 ★ 107repo stars business-kickoff-workshop The business-kickoff-workshop Claude Code skill prepares a Business Model Canvas workshop and turns call notes into a completed canvas. It activates for kickoff planning, customer discovery questions, or post-call canvas work. CX Codex +1 ★ 107repo stars build-my-designer-brain The build-my-designer-brain Claude Code skill builds a designer’s personal collection of methods, preferences, and lessons. It runs to create or revise that collection, or to apply it while working on a feature. CX Codex +1 ★ 107repo stars agentic-design-systems The agentic-design-systems Claude Code skill guides the design and review of component libraries built for AI agents. It activates for AI-readable design systems, component metadata work, and library audits. CX Codex +1 ★ 107repo stars

Project sponsors

Companies that keep this analytics open