Standard Structure
Every component file should follow this exact order:
# ComponentName
## Import
[Copy-paste ready imports]
---
## Variants
[Table of variants with use cases]
### Choosing a Variant
[Decision guidance]
---
## Sizes (if applicable)
[Table of sizes]
---
## Styling / Structure
[Design tokens table - use "Structure" for composite components, "Styling" for simple ones]
---
## States
[Table of all interactive states]
---
## Icons (if component uses icons)
[Icon specs and usage]
---
## Common Patterns
[2-4 copy-paste code examples]
---
## Accessibility
[Component-specific a11y requirements]
---
## Gotchas
[Problem/Solution table]
---
## Figma Reference
[Link to Figma Dev Mode]
---
*Last updated: [Date]*
Section Templates
Import Section
## Import
\`\`\`tsx
import { ComponentName } from "@timelycare/helix-ui"
\`\`\`
Do Not Write a Props Section
Props are a structured fact, owned by packages/helix-ui/src/metadata/<component>.metadata.ts. The viewer renders that metadata as a props table automatically, so a hand-written ## Props block in markdown would only duplicate it — and drift from it.
If a prop is missing or wrong, fix the metadata file. Use the prose here for what metadata cannot carry: rationale, gotchas, and patterns.
Formatting Rules
- Tables: Use pipe-delimited markdown tables
- Code blocks: Use tsx syntax highlighting
- Tokens: Reference Tailwind classes, not raw values
- Links: Use relative paths within system/ (e.g., Colors)
- Dates: Format as "Month DD, YYYY" (e.g., January 16, 2026)
This template last updated: January 29, 2026