--- title: "Documenting Components" subtitle: "How to write component documentation for humans and AI" description: "Standard structure and rules for writing component markdown files that serve both human developers and AI tools." author: "Studio" section: "Docs" layer: "app" subsection: "Code Standards" order: 4 status: "published" access: "team" client: "internal" --- ## Purpose Component docs serve two audiences: 1. **Humans** — designers and developers who need to know how to USE the component: what variants exist, what HTML to write, what combinations work, accessibility rules 2. **AI tools** — reading `llms-full.txt` and need to know how the component is BUILT: what CSS properties it uses, what tokens it references, what selectors exist The docs lead with human usage and end with CSS implementation. This standard defines the section order, what goes in each, and when sections are required. --- ## Section order Every component markdown file follows this structure: ``` --- frontmatter --- # Component Name REQUIRED ## Anatomy IF has data-* axes ## Basic usage REQUIRED ## [Variants / Features] IF has variants ## [Composition / Grouping] IF has group pattern ## [Semantic guidance] IF element choice matters ## JavaScript IF requires JS ## Accessibility REQUIRED ## Usage rules REQUIRED ## CSS reference REQUIRED ``` --- ## What goes in each section ### Intro (no heading — paragraph after `# Component Name`) One paragraph: what the component is, when to use it, what base class is required. - Always mention the base class: "The `.badge` class is required." - If the component has no custom class (bare HTML elements like `code`, `mark`), say so. - If the component uses `data-*` attributes, name them here. ### Anatomy Required for components with more than one axis of variation. Include a table: | Axis | Mechanism | Example | |---|---|---| | Colour | `data-color` | `data-color="success"` | | Type | `data-type` | `data-type="info"` | Below the table, one sentence stating whether the component uses component tokens or references system tokens directly. Omit for simple components with no variation axes (breadcrumb, code, table, mark). ### Basic usage One demo preview + one HTML code block showing the simplest valid instance. If the component requires a wrapper (`