/ai-component-description

name: ai-component-description
description: "Generate AI-optimised text descriptions for components, formatted for Figma's MCP server and LLM consumption. This produces prose descriptions in a six-section format (purpose, props, anti-patterns, composition, accessibility, examples), NOT JSON schemas or structured data files. Trigger when someone says: write component description for AI, Figma MCP description, write the description for Claude to read, six-section description, describe this component for AI, or anything about writing text that makes components legible to LLMs. Do NOT trigger for JSON metadata schemas, structured constraint files, or programmatic tooling data — use metadata-schema-generator for those."
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/mcp-setup-guide.md

AI component description

A skill for generating structured component descriptions optimised for consumption by LLMs via Figma's MCP server. Output is a six-section description that gives an AI agent the information it needs to understand, compose, and generate from a component accurately — without relying on implicit knowledge, visual inference, or team context.

Context

This is the differentiating skill in Design System Ops. It encodes a methodology built through production use on a real AI-assisted design system and informed by the AI-readiness patterns in the knowledge notes.

The problem it solves: most component descriptions are written for human designers discovering the component for the first time. They use phrases like "use this to show important information" or "works great in cards". These descriptions are not useless — but they are not structured for LLM consumption. An LLM reading a component description needs to know what the component IS, what it takes, what it prohibits, how it relates to other components, and what failure modes look like. Human-readable descriptions skip most of this.

The six-section format is the product of watching AI agents misuse components that had perfectly fine human documentation. The sections are not arbitrary — each one addresses a specific class of LLM error.

---

Configuration

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

• `integrations.figma` — if enabled, auto-pull component data from Figma (see below)
• `integrations.storybook` — if enabled, pull prop definitions and story context
• `integrations.documentation` — if enabled, cross-reference existing documentation for accuracy

Auto-pull integrations

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

• Read the component node, its variants, layer structure, and existing description text from `integrations.figma.file_key`
• Extract: component name, variant names and values, layer hierarchy (for composition rules), and any existing description
• Use this as the primary source for Step 1 — skip the manual "ask for component information" step if Figma data is comprehensive
• Do not assume existing description text is accurate — it is a starting point, not a source of truth

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

• Fetch the component's story from `integrations.storybook.url`
• Extract: prop types, default values, and arg types from the story metadata
• Use this to validate and complete the Props section — Storybook's auto-generated prop tables are usually accurate for types and defaults

**GitHub** (`integrations.github.enabled: true`):

• Pull the component source file to read prop definitions directly from TypeScript interfaces or PropTypes
• Cross-reference with the Figma and Storybook data to ensure all three sources agree on the component's API

If an integration fails, log it and proceed with manual input.

Step 0: Check data sources and existing description

This skill works best with a Figma MCP connection but does not require one. Before proceeding, check what data sources are available:

1. **Figma MCP available:** Read the component directly from Figma (preferred path — skip most manual questions in Step 1) 2. **Storybook / GitHub available:** Read prop definitions and source code (good alternative for the Props and Accessibility sections) 3. **Neither available:** Ask the user for component information manually — the skill still produces a complete description from user-provided input

If Figma tools are configured but fail (connection error, invalid node, nothing selected), note the error and fall back to manual input. Do not retry in a loop.

**Check for an existing description first.** When reading from Figma, always check whether the component already has a description. If it does:

• **Show it to the user** before doing anything else: "This component already has a description: [quote the existing text]. Want me to rewrite it in the six-section format, improve what's there, or start fresh?"
• Do not claim "there is no description" unless the description field is genuinely empty (null, empty string, or whitespace only)
• Do not silently discard an existing description and offer to "add" one — the user wrote that text and deserves to see it acknowledged

If the existing description already follows the six-section format, say so: "This component already has a structured description. Want me to review it for completeness, or is there a specific section you want improved?"

---

Step 1: Gather component information

Ask for or confirm the following (skip if auto-pulled via integrations above). If the component is in a connected Figma file, use the MCP server to read it directly:

• Component name
• Component category (e.g. navigation, feedback, form, layout, data display)
• Available props/variants and their accepted values
• Default state
• Any composition relationships (what it contains, what it can be placed inside)
• Accessibility requirements already defined for the component
• Known misuse patterns observed in