ai-component-metadata

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:

# 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:

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)