Metadata Schema Generator

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 (where the team supplies it) business context — in a format that does not require natural language parsing.

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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 is the pack's one extraction of component facts. It generates structured JSON metadata for tooling — not human-readable documentation (usage-guidelines, pattern-documentation) or LLM-facing prose (ai-component-description); those two read .ai/metadata/ when it exists and render from it, so the props and accessibility contract are derived once. If the system has no component inventory yet, run codebase-index first. If no component source is in reach, stop and ask for it: metadata can't be extracted from a description. If the team has no consumer for the files yet (no AGENTS.md pointing at them, no MCP server, no lint integration), say so and suggest agent-instructions as the first consumer rather than generating files nothing reads.

Configuration

If .ds-ops-config.yml exists, follow the configuration-and-recurring knowledge note (../../knowledge-notes/configuration-and-recurring.md) for loading, integration fallbacks and recurring runs. This skill reads:

• system.framework — determines prop extraction approach (React, Vue, Svelte, etc.)
• system.component_paths — directs scanning to component source files
• integrations.* — component data (see below)
• metadata.schema_version — locks the output schema version for compatibility
• metadata.output_directory — overrides default output location
• metadata.include_business_context — toggles the business context layer (default: false; see Step 4)

Auto-pull integrations

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

Source (always attempted, with the tool that fits):

• React with TypeScript: react-docgen-typescript gives name, type, required, default and description per prop; hand-read only what it can't resolve (complex generics), and say so
• Vue: vue-component-meta
• Web Components: the Custom Elements Manifest (npx custom-elements-manifest analyze, or an existing custom-elements.json)
• Anything else: read the interfaces, PropTypes and JSDoc by hand, and note under Scope that extraction was manual

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:

Step 2: Generate the base schema from source

For each component, extract the prop layer automatically from TypeScript or equivalent:

Illustrative Button (a real run uses the component's actual source):

{
  "$schema": "./schema.json",
  "component": "Button",
  "version": "1.0.0",
  "status": "stable",
  "props": [
    {
      "name": "variant",
      "type": "enum",
      "values": ["primary", "secondary", "ghost"],
      "default": "primary",
      "required": false,
      "description": "Visual weight of the button",
      "semantic": {
        "primary": "Use for the single most important action on the page or in a section",
        "secondary": "Use for supporting actions alongside a primary action",
        "ghost": "Use for tertiary actions or actions within dense UI"
      }
    },
    {
      "name": "size",
      "type": "enum",
      "values": ["sm", "md", "lg"],
      "default": "md",
      "required": false,
      "description": "Controls button height and text size"
    },
    {
      "name": "disabled",
      "type": "boolean",
      "default": false,
      "required": false,
      "description": "Prevents interaction and applies disabled styling"
    },
    {
      "name": "loading",
      "type": "boolean",
      "default": false,
      "required": false,
      "description": "Shows a spinner in place of the label and prevents interaction"
    },
    {
      "name": "aria-label",
      "type": "string",
      "required": false,
      "description": "Accessible name when the button has no visible text"
    },
    {
      "name": "children",
      "type": "ReactNode",
      "required": true,
      "description": "Button label content"
    }
  ]
}

Build on the standard, don't invent one. For Web Components the metadata file is the Custom Elements Manifest with a dsops object added to each declaration for the semantic layers (CEM allows additional properties, and every CEM consumer keeps reading it). For React and Vue, the props array keeps docgen's field names (name, type, required, defaultValue, description) so anything that reads docgen output reads this too, and the semantic layers sit beside it.

Extraction rules:

• Every prop in the TypeScript interface must appear in the schema
• Keep the raw type string in type.raw; add type.kind normalised to string, number, boolean, enum, ReactNode, function, object, array, so generics and non-literal unions aren't lost
• Enum values must be listed explicitly, not as a type reference
• Take default from the source's declared default. Omit default when source declares none
• If a prop has JSDoc, use it as the description. If not, flag the prop for manual description.
• Per-value semantic text comes from JSDoc or the team's docs. If neither has it, leave semantic out and flag the prop rather than writing plausible guidance

Step 3: Add the semantic layer

The semantic layer encodes meaning that TypeScript types cannot express. For each component, add the three blocks below.

Provenance rule. Every behaviour, composition and accessibility block carries a provenance value: source (read from the component code), docs (from the team's documentation or the user), or proposed (anything not traced to either). A block that mixes sources takes the weakest. Never present a proposed rule as the system's actual behaviour or policy: tools and agents read this file as ground truth. See "Every figure and fact needs a source" in the output-discipline knowledge note.

The examples below continue the illustrative Button.