{"slug":"murphytrueman-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.","long_description":"---\nname: ai-component-description\ndescription: \"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.\"\nreferences:\n - ../../knowledge-notes/ai-readiness.md\n - ../../knowledge-notes/component-bestiary-reference.md\n - ../../knowledge-notes/mcp-setup-guide.md\n---\n\n# AI component description\n\nA 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.\n\n## Context\n\nThis 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.\n\nThe 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.\n\nThe 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.\n\n---\n\n## Configuration\n\nBefore producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:\n- `integrations.figma` — if enabled, auto-pull component data from Figma (see below)\n- `integrations.storybook` — if enabled, pull prop definitions and story context\n- `integrations.documentation` — if enabled, cross-reference existing documentation for accuracy\n\n## Auto-pull integrations\n\n**Figma MCP** (`integrations.figma.enabled: true`):\n- Read the component node, its variants, layer structure, and existing description text from `integrations.figma.file_key`\n- Extract: component name, variant names and values, layer hierarchy (for composition rules), and any existing description\n- Use this as the primary source for Step 1 — skip the manual \"ask for component information\" step if Figma data is comprehensive\n- Do not assume existing description text is accurate — it is a starting point, not a source of truth\n\n**Storybook** (`integrations.storybook.enabled: true`):\n- Fetch the component's story from `integrations.storybook.url`\n- Extract: prop types, default values, and arg types from the story metadata\n- Use this to validate and complete the Props section — Storybook's auto-generated prop tables are usually accurate for types and defaults\n\n**GitHub** (`integrations.github.enabled: true`):\n- Pull the component source file to read prop definitions directly from TypeScript interfaces or PropTypes\n- Cross-reference with the Figma and Storybook data to ensure all three sources agree on the component's API\n\nIf an integration fails, log it and proceed with manual input.\n\n## Step 0: Check data sources and existing description\n\nThis skill works best with a Figma MCP connection but does not require one. Before proceeding, check what data sources are available:\n\n1. **Figma MCP available:** Read the component directly from Figma (preferred path — skip most manual questions in Step 1)\n2. **Storybook / GitHub available:** Read prop definitions and source code (good alternative for the Props and Accessibility sections)\n3. **Neither available:** Ask the user for component information manually — the skill still produces a complete description from user-provided input\n\nIf 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.\n\n**Check for an existing description first.** When reading from Figma, always check whether the component already has a description. If it does:\n- **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?\"\n- Do not claim \"there is no description\" unless the description field is genuinely empty (null, empty string, or whitespace only)\n- Do not silently discard an existing description and offer to \"add\" one — the user wrote that text and deserves to see it acknowledged\n\nIf 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?\"\n\n---\n\n## Step 1: Gather component information\n\nAsk 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:\n\n- Component name\n- Component category (e.g. navigation, feedback, form, layout, data display)\n- Available props/variants and their accepted values\n- Default state\n- Any composition relationships (what it contains, what it can be placed inside)\n- Accessibility requirements already defined for the component\n- Known misuse patterns observed in production (if any)\n\nIf pulling directly from Figma via MCP: read the component node, its variants, layer structure, and any existing description text. If description text exists, show it to the user (see Step 0). Do not assume existing description text is accurate — it is a starting point, not a source of truth. But do not ignore it either — existing descriptions often contain institutional knowledge that should be preserved in the rewrite.\n\n## Step 2: Write the six-section description\n\nWrite each section in plain prose. No bullet lists inside the description itself — AI agents parse prose better than nested lists in this context. Each section should be dense but not padded.\n\n---\n\n### Section 1: Purpose\n\nOne to two sentences. What does this component do, and when should it be used? Write this as a contract statement, not a marketing line.\n\nBad: \"A flexible card component for displaying content in a visually appealing way.\"\nGood: \"A surface container for grouping related content that belongs together but does not require its own page. Use when content needs visual separation from surrounding context without implying navigational hierarchy.\"\n\n### Section 2: Props\n\nDocument every configurable prop. For each:\n- Prop name (exact, as it appears in the component API)\n- Accepted values (enumerated where finite, typed where variable)\n- Default value\n- One-sentence description of what the prop controls\n\nFormat: prop-name | type | default | description\n\nDo not skip props because they seem obvious. LLMs cannot infer defaults.\n\nExample:\n```\nvariant | \"primary\" | \"secondary\" | \"ghost\" | \"destructive\" | \"primary\" | Controls visual weight and colour treatment\nsize | \"sm\" | \"md\" | \"lg\" | \"md\" | Adjusts padding, font size, and min-touch-target\ndisabled | boolean | false | Prevents interaction and applies reduced-opacity treatment\nloading | boolean | false | Replaces label with loading indicator and prevents further clicks\n```\n\n### Section 3: Anti-patterns\n\nWhat should an AI agent NOT do with this component? List the three to five most common misuse patterns, each as a one-sentence prohibition with a brief reason.\n\nThese anti-patterns should be specific to this component, not generic design system guidance. Write them based on actual misuse patterns if known, or inferred from the component's structure and common analogues.\n\nExample (Button):\n- Do not use the destructive variant for actions that are reversible. Destructive implies permanent data loss or deletion.\n- Do not use ghost variant as the primary action in a flow. Ghost is for secondary or tertiary actions where a button is needed but should not compete with a primary.\n- Do not place more than one primary variant button in the same visual context.\n- Do not use size lg in dense form layouts. It creates disproportionate vertical rhythm.\n\n#### Anti-pattern inference guide\n\nIf observed misuse patterns are not available from production data, infer likely anti-patterns from the component's API structure:\n\n- **Components with a `variant` prop that includes \"destructive\" or \"danger\":** Likely misuse — using the destructive variant for reversible actions, or using it as a visual emphasis tool rather than a semantic signal.\n- **Components with a `size` prop:** Likely misuse — using large sizes in dense layouts, or mixing sizes inconsistently within the same context.\n- **Components with a boolean `disabled` prop:** Likely misuse — using disabled state to hide functionality rather than communicating why it is unavailable (missing `aria-disabled` with explanation).\n- **Container components (Card, Modal, Drawer):** Likely misuse — nesting containers inside other containers without semantic justification, or using a container for visual grouping when a simpler layout element would suffice.\n- **Components with an `icon` or `iconOnly` prop:** Likely misuse — using icon-only variants without providing an accessible label, or choosing icons based on aesthetics rather than meaning.\n- **Components with `onClick` or action props:** Likely misuse — using a button-like component for navigation (should be a link), or attaching actions to non-interactive elements.\n\nUse these inferences as starting points. Mark inferred anti-patterns as \"anticipated\" in the description — they should be validated against real usage and upgraded to \"observed\" once confirmed.\n\n### Section 4: Composition rules\n\nHow does this component relate to others? Document:\n- What this component can contain (if it is a container)\n- What this component can be placed inside\n- What other components are typically used alongside it\n- Any hard constraints on nesting or ordering\n\nBe specific. \"Can be used in cards\" is not useful. \"Can be placed inside Card as an action — always as the last child of Card.Footer, never inside Card.Body\" is useful.\n\n### Section 5: Accessibility\n\nDocument the accessibility contract for this component:\n- ARIA role(s) applied\n- Keyboard interaction pattern (Tab, Enter, Space, Arrow keys, Escape — state which apply)\n- Focus management behaviour (where does focus go on open/close/activate)\n- Required aria attributes and their expected values\n- Screen reader announcement pattern\n\nThis is not a WCAG checklist. It is the specific accessibility behaviour of this specific component.\n\n**Why this section requires extra rigour.** Accessibility is where AI-generated components fail most often. LLMs understand accessibility theory but routinely produce code that fails basic testing — missing keyboard handlers, incomplete ARIA attributes, focus management that traps or loses focus. The description must be prescriptive enough that an AI agent generating from it produces accessible output without additional guidance.\n\nSpecific requirements:\n- Specify semantic HTML elements, not just ARIA roles. If the component should render as a `