Skip to content
Beta Multi-model support (OpenAI, Gemini, and more) launching soon.
RBA RBA Skills

component-doc-writer

Installable Ships in design-system-manager — or copy the raw skill below.
Open Claude.ai

Paste into Claude Code, Claude.ai, the desktop app, or the browser extension — ⌘/Ctrl+V.

ExperimentalNo security review

Component Doc Writer

Generate complete, structured documentation for a design system component. Works from source code analysis, a token file, or a verbal description of the component. Produces Markdown output ready for Storybook MDX, Supernova, zeroheight, or a Starlight documentation site.

Usage

/component-doc-writer <ComponentName> [--source <path>] [--platform sitecore|optimizely|umbraco|headless] [--format storybook|supernova|starlight|zeroheight]

Examples:

  • /component-doc-writer Button --source src/components/Button.tsx — from source file
  • /component-doc-writer Card --platform sitecore --format starlight — with platform notes
  • /component-doc-writer NavigationMenu --source src/components/Navigation/ — directory of files
  • /component-doc-writer Alert — from name only (AI infers based on common patterns)

Phase 1 — Component Discovery

If --source is provided, read the component file(s):

  • Infer: component name, props interface / TypeScript types, exported variants, event handlers.
  • Identify: which design tokens are used (via var(--ds-*) in CSS, tokens.* imports in JS/TS, or className patterns referencing token-backed Tailwind classes).
  • Detect: ARIA roles (role=, aria-* attributes), keyboard handlers (onKeyDown, onKeyUp).
  • Note: forward-ref patterns, compound component exports, context providers.

If no source is provided, infer props and behaviour from the component name and common industry patterns. State assumptions clearly in the generated doc.

Phase 2 — Component Overview Section

Write the opening overview:

# <ComponentName>

<One-sentence purpose statement>. <One sentence on when to use it in a DX context>.

**Status:** Stable | Beta | Deprecated
**Introduced:** v<x.x>
**Figma:** [<ComponentName>](<figma-link-placeholder>)
**Storybook:** [<ComponentName>](<storybook-link-placeholder>)

Include a brief description covering:

  • What the component does
  • The user problem it solves
  • Its role in the design system (foundational / composite / page-level)

Phase 3 — Anatomy Section

Document the component's visual structure using a named-parts diagram (text-based if no image):

## Anatomy

┌─────────────────────────────────────────┐ │ [icon] Label text [trailing] │ └─────────────────────────────────────────┘ 1 2 3


| Part | Name | Description |
|------|------|-------------|
| 1 | Leading icon (optional) | 16×16px icon slot; hidden when no icon prop |
| 2 | Label | Required text content |
| 3 | Trailing slot (optional) | Badge, count, or icon |

Enumerate every visual sub-element. Use clear part names that match the component's prop names and the token names (e.g., if the prop is leadingIcon, the anatomy part is "Leading icon", and the token is component.button.icon-size).

Phase 4 — Props / API Table

Generate a complete props table. Infer from TypeScript types if --source was provided:

## Props

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `children` | `ReactNode` | — | ✅ | Button label; use plain text for accessibility |
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `'primary'` | — | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | — | Controls padding and font-size |
| `disabled` | `boolean` | `false` | — | Disables the button and applies disabled token styles |
| `loading` | `boolean` | `false` | — | Shows a loading spinner; prevents double-submission |
| `leadingIcon` | `ReactNode` | `undefined` | — | Icon rendered before the label |
| `trailingIcon` | `ReactNode` | `undefined` | — | Icon rendered after the label |
| `onClick` | `(event: MouseEvent) => void` | — | — | Click handler; not called when disabled |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | — | HTML button type; always set explicitly in forms |
| `aria-label` | `string` | — | — | Required when button has no visible label text |
| `data-testid` | `string` | — | — | Test selector for automated testing |

For CMS-integrated components (Sitecore, Optimizely, Umbraco), also document rendering parameters / block settings fields as a separate table.

Phase 5 — States and Variants

Document all interactive states with token callouts:

## States

| State | Description | Token change |
|-------|-------------|-------------|
| Default | Resting state | `component.button.primary.background-default` |
| Hover | Mouse over | `component.button.primary.background-hover` |
| Active | Mouse/touch pressed | `component.button.primary.background-active` |
| Focus | Keyboard focus | `component.button.primary.border-focus` (2px ring) |
| Disabled | Not interactive | `component.button.primary.background-disabled`; `cursor: not-allowed` |
| Loading | Async in progress | Spinner replaces leading icon; `aria-busy="true"` applied |

## Variants

Document each variant (primary, secondary, ghost, danger, etc.) with:
- When to use vs. when NOT to use
- Token values that differ from the default variant
- Any additional props specific to this variant

Phase 6 — Design Token Callouts

List every token the component consumes, grouped by tier:

## Design Tokens

### Component tokens (direct)
| Token | Value at default theme | Purpose |
|-------|----------------------|---------|
| `component.button.primary.background-default` | `{semantic.color.action.primary}` | Button fill |
| `component.button.primary.text-default` | `{semantic.color.text.inverse}` | Button label colour |
| `component.button.primary.border-radius` | `{semantic.border-radius.md}` | Corner rounding |
| `component.button.primary.padding-x` | `{semantic.spacing.component-md}` | Horizontal padding |

### Semantic tokens (resolved from component)
| Token | Resolves to (default brand) | Role |
|-------|----------------------------|------|
| `semantic.color.action.primary` | `#3b82f6` | Brand primary action colour |
| `semantic.color.text.inverse` | `#ffffff` | Text on dark background |

To override the button for a brand, update the semantic tier only.

Phase 7 — Accessibility Section

Document accessibility requirements inline (not as a separate audit):

## Accessibility

### ARIA pattern
- Element: `<button>` (native element preferred over `role="button"`)
- When rendered as a link (`href` prop): use `<a>` element, not `<button>`
- Icon-only buttons: **must** have `aria-label` or `aria-labelledby`
- Loading state: add `aria-busy="true"` and `aria-label="Loading..."` to screen-reader span

### Keyboard interaction
| Key | Behaviour |
|-----|-----------|
| `Space` / `Enter` | Activates the button |
| `Tab` | Moves focus to next focusable element |
| `Shift+Tab` | Moves focus to previous focusable element |

### Focus indicator
Focus ring uses `component.button.primary.border-focus` token (2px solid ring with 2px offset).
Do **not** suppress with `outline: none` — this violates WCAG 2.2 SC 2.4.11 (Focus Appearance).
Focus ring colour must achieve 3:1 contrast against adjacent colours.

### Colour contrast
- Primary button: action-primary background vs. inverse-text — must meet 4.5:1 (WCAG AA normal text)
- Disabled state: explicitly exempt from contrast requirements per WCAG 1.4.3 exception
- Loading spinner: must meet 3:1 contrast against button background (SC 1.4.11 — Non-text Contrast)

### Screen reader announcements
- Loading state: announce with a live region: `<span role="status" aria-live="polite">Loading</span>`
- Success/error after async: announce via `aria-live="assertive"` region external to the button

### European Accessibility Act (EAA) — June 2025+
All interactive components shipped by RBA for EU clients must meet WCAG 2.1 AA as a baseline.
Recommend WCAG 2.2 AA to future-proof.

Phase 8 — Usage Guidelines (Do / Don't)

## Usage guidelines

### Do
- Use `variant="primary"` for the single most important action on a page or within a section.
- Use `variant="secondary"` for secondary actions that appear alongside a primary.
- Always set `type="submit"` explicitly on form submit buttons.
- Use `aria-label` when the button contains only an icon.

### Don't
- Don't place two primary buttons of equal weight side-by-side; establish visual hierarchy.
- Don't use buttons for navigation — use `<a>` links or the `LinkButton` composite component.
- Don't disable buttons to indicate unavailability without explanation; consider a tooltip on hover
  that explains why the action is unavailable.
- Don't hard-code colours — always use the component's token layer.

Phase 9 — Platform Notes

Add a section per --platform flag (or all platforms if flag omitted):

## Platform integration

### Sitecore XM Cloud / SXA
- Map this component to an SXA rendering item. Expose `variant` and `size` as rendering parameters.
- In JSS / Next.js: import from the design system package and pass Sitecore field values as props.
- In SXA SCRIBAN: render conditional classes from rendering parameters.

### Optimizely CMS
- Create an Optimizely block type with `[ContentType]` attribute for page-editor placement.
- Expose `Variant` and `Label` as `[Display]`-decorated string properties.

### Umbraco
- Create a Block Editor element type with matching property editors.
- Partial view: `@await Html.PartialAsync("Components/Button", model.Button)`.

### Headless / composable
- Import directly: `import { Button } from '@rba/design-system';`
- Use Storybook Controls to validate all prop combinations before integration.

Phase 10 — Write Output File

Write the completed document to:

  • docs/components/<component-name>.md (default)
  • If --format storybook: src/stories/<ComponentName>.mdx
  • If --format starlight: src/content/docs/components/<component-name>.md with Starlight frontmatter
  • If --format supernova or --format zeroheight: standard Markdown (both platforms accept it)

Print the file path and a short summary of what was generated.

Reference files

  • templates.md — Full component doc template, Storybook MDX frontmatter, Starlight frontmatter, do/don't table format
  • examples.md — Complete generated docs for Button, Card, and Alert as worked examples
Technical details
Plugin
design-system-manager
Author
Dakota Smith
Skill name
component-doc-writer
Maturity
experimental
Security review
No security review
Owners
  • design
  • engineering
Argument hint
<ComponentName> [--source <path/to/Component.tsx>] [--platform sitecore|optimizely|umbraco|headless] [--format storybook|supernova|starlight|zeroheight]
Allowed tools
  • Read
  • Write
  • Glob
  • Bash(ls *)
Source
plugins/design-system-manager/skills/component-doc-writer/SKILL.md

Edit this skill on GitHub — opens GitHub's web editor. No git knowledge needed.