Components
Documentation Standard

Component Documentation Standard

Every component page should be usable by a product team without Slack. This standard defines the minimum structure for enterprise-grade documentation.

Required Sections

  • Summary: What the component is and when to use it.
  • Anatomy: Named parts of the component with a diagram or list.
  • Variants: Visual and behavioral variants with examples.
  • States: Hover, active, disabled, loading, error, empty.
  • Accessibility: Keyboard behavior, ARIA, focus management, contrast notes.
  • Design Tokens: Tokens used for color, spacing, typography, and radius.
  • Usage Guidelines: Do / Don’t guidance in plain language.
  • Examples: At least 2 canonical use cases.
  • API Reference: Props and types with defaults.

Status Model

Each component must declare one of these states at the top of the page:

  • Stable — safe for production and long-term support.
  • Beta — API may change, use with caution.
  • Deprecated — avoid in new work; will be removed.

If a status badge is missing, treat the component as Stable by default.

Minimum Example Block

import { Button } from '@gtcx/ui';
 
<Button variant="primary">Save</Button>

Accessibility Checklist

  • Keyboard focusable and operable
  • Visible focus ring
  • Proper roles and labels
  • 4.5:1 contrast on text
  • No information conveyed by color alone

Review Checklist

  • Content matches current API
  • Storybook story exists and is linked
  • Tokens are referenced where relevant
  • Status is set and justified
Status RegistryTemplates