Back to Details

ai-component-metadata

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AI Component Metadata Generator

AI 组件元数据生成器

Generate structured, AI-consumable metadata for design system components to enable intelligent UI generation and component usage.
为设计系统组件生成结构化、可被AI调用的元数据，以实现智能UI生成和组件合理使用。

Quick Start

快速开始

When analyzing a component, use the metadata schema template in 
scripts/generate_metadata.py
or follow the manual process below:
bash
undefined
分析组件时，可使用 
scripts/generate_metadata.py
中的元数据模板，或遵循以下手动流程：
bash
undefined

Automatic generation (reads component file)

自动生成（读取组件文件）

python scripts/generate_metadata.py path/to/Component.tsx
python scripts/generate_metadata.py path/to/Component.tsx

Or use the template directly

或直接使用模板

cp assets/metadata-template.tsx your-component-metadata.tsx
undefined
cp assets/metadata-template.tsx your-component-metadata.tsx
undefined

Core Workflow

核心流程

1. Analyze Component Structure

1. 分析组件结构

Identify:
  • Component composition (slots, children)
  • Available variants and states
  • Props and their types
  • Accessibility attributes
识别：
  • 组件组成（插槽、子元素）
  • 可用变体和状态
  • 属性（Props）及其类型
  • 无障碍访问属性

2. Generate Metadata

2. 生成元数据

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"
  }
}
按照以下 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

3. 验证元数据

  • Test with AI generation tasks
  • Verify in Storybook
  • Ensure examples are runnable
  • 通过AI生成任务进行测试
  • 在Storybook中验证
  • 确保示例代码可运行

Component Categories

组件分类

  • atoms: Basic building blocks (Button, Text, Input)
  • molecules: Simple combinations (Card, Chip, FormField)
  • organisms: Complex components (Header, Table, Form)
  • atoms：基础构建块（Button、Text、Input）
  • molecules：简单组合组件（Card、Chip、FormField）
  • organisms：复杂组件（Header、Table、Form）

Advanced Features

高级功能

For complex scenarios, see:
  • Nested components: NESTED.md
  • Integration patterns: INTEGRATION.md
  • Testing strategies: TESTING.md
针对复杂场景，请参考：
  • 嵌套组件：NESTED.md
  • 集成模式：INTEGRATION.md
  • 测试策略：TESTING.md

Working with Figma

与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
结合Figma MCP使用时：
javascript
// Figma提供视觉上下文
const figmaContext = await Figma.get_design_context();

// 你的元数据提供行为上下文
const componentMetadata = components.Button.metadata;

// AI结合两者以获得完整理解

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
  1. 使用真实示例 - 采用可运行的实际代码
  2. 聚焦使用模式 - 记录常见使用模式
  3. 包含反模式 - 帮助AI避免错误
  4. 通过使用验证 - 结合实际AI生成任务进行测试

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
当你的元数据满足以下条件时，即为有效：
  • AI使用现有组件而非重新创建
  • 根据上下文选择正确的组件变体
  • 生成的代码保持无障碍访问性
  • AI输出的模式保持一致