/metadata-schema-generator

name: metadata-schema-generator
description: "Generate structured JSON metadata schemas for design system components — machine-readable constraint definitions that encode props, behavioural rules, composition constraints, prohibited combinations, and accessibility contracts as programmatic data. This produces JSON files for tooling (MCP servers, linters, code generators, test frameworks), NOT text descriptions for humans or Figma. Trigger when someone says: generate metadata schema, JSON schema for components, component contract as JSON, structured metadata for tooling, prop constraints as data, machine-readable component rules, or anything about producing JSON/structured data that tools consume programmatically. Do NOT trigger for Figma descriptions, component documentation, or AI-readable text — use ai-component-description for those."
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md

Metadata schema generator

A skill for generating structured JSON metadata schemas for design system components. These schemas encode everything an AI agent, MCP server, code generator, or testing framework needs to work with a component programmatically — props, behavioural rules, composition constraints, accessibility contracts, and business context — in a format that does not require natural language parsing.

Context

Component documentation serves humans. Component metadata serves machines. The distinction matters because the information needs are different, the format requirements are different, and the failure modes are different.

A human reading a component's documentation can infer that "this button triggers the primary action" means it should be visually prominent and placed in the expected location. A code generation agent reading that same string cannot infer any of that — it needs explicit data: `{ "role": "primary_action", "visual_weight": "high", "placement": ["form_footer", "dialog_footer", "page_header"] }`.

Most design systems have one layer of machine-readable data: TypeScript interfaces or PropTypes declarations that define prop names and types. This is necessary but insufficient. A TypeScript interface tells a tool that a Button accepts a `variant` prop of type `"primary" | "secondary" | "ghost"` — but it does not tell the tool when to use `primary` vs `secondary`, which combinations of props are prohibited, where the component can be placed in a layout, or what accessibility contract it must honour.

Structured metadata fills this gap. It encodes the knowledge layer between "what the component accepts" (TypeScript) and "how the component should be used" (documentation) as machine-readable data that tooling consumes directly.

The `ai-component-description` skill produces text descriptions optimised for LLM consumption. This skill produces structured data optimised for programmatic consumption. Together they serve the two modes of AI interaction: conversational (descriptions) and deterministic (metadata).

Boundaries

This skill generates structured JSON metadata schemas for tooling consumption — not human-readable documentation (use `usage-guidelines` or `pattern-documentation` for that) or LLM-facing descriptions (use `ai-component-description`). If the system has no component inventory yet, run `component-audit` or `codebase-index` first. If the team has no current need for machine-readable metadata (no MCP server, no code generation, no linting integration), this skill adds overhead without value — discuss the use case before generating.

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `system.framework` — determines prop extraction approach (React, Vue, Svelte, etc.)
• `system.component_paths` — directs scanning to component source files
• `integrations.*` — enables auto-pull for component data
• `metadata.schema_version` — locks the output schema version for compatibility
• `metadata.output_directory` — overrides default output location
• `metadata.include_business_context` — toggles the business intelligence section (default: true)

Auto-pull integrations

If integrations are configured in `.ds-ops-config.yml`, pull data automatically:

**Figma MCP** (`integrations.figma.enabled: true`):

• Read component properties, variant structures, and descriptions from `integrations.figma.file_key`
• Cross-reference Figma component properties against code props to detect mismatches
• Extract accessibility annotations if present

**Storybook** (`integrations.storybook.enabled: true`):

• Fetch prop tables and arg types from story metadata
• Extract documented states and control definitions
• Pull interaction test definitions if available

**TypeScript/Source** (always attempted):

• Parse TypeScript interfaces or PropTypes from component source files
• Extract JSDoc/TSDoc annotations for prop descriptions
• Identify generic type parameters for polymorphic components

If an integration fails, log it and proceed with available sources.

---

Step 1: Select components and assess existing metadata

Ask for or confirm (skip questions already answered by auto-pull):

• Which components need metadata schemas? (Specific components, a category, or the full library)
• Where do component source files live?
• Is there existing structured metadata in any format (JSON, YAML, Custom Elements Manifest)?

For each component, scan for existing metadata sources:

• TypeScript interface or PropTypes declaration
• JSDoc/TSDoc annotations
• Storybook arg types and controls
• Existing metadata files (`.metadata.json`, `.metadata.ts`)
• Figma component description

Produce a source assessment per component:

| Component | TS interface | JSDoc | Storybook | Figma | Existing metadata | Gaps | |---|---|---|---|---|---|---| | Button | complete | partial | complete | yes | none | composition, behaviour | | Card | complete | none | partial | yes | none | all se