Skip to main content

​
Best practices

​
Component documentation

Good documentation helps the AI understand not only what your components do, but when to use them.
Listing props alone is not enough. The AI needs context about when to pick one component or variant over another.

​
Usage guidance

For each component, cover:
  • Purpose: what problem the component solves
  • When to use: which scenarios should lead to this component
  • When not to use: anti-patterns or wrong fits
  • Variants: when each variant is appropriate

​
Example: button documentation

/**
 * Button component for user actions.
 *
 * @usage
 * - Use `primary` variant for the main call-to-action on a page
 * - Use `secondary` variant for less important actions
 * - Use `destructive` variant only for delete/remove actions
 * - Use `ghost` variant for tertiary actions or in toolbars
 *
 * @when-not-to-use
 * - Do not use Button for navigation; use Link instead
 * - Do not use multiple primary buttons in the same section
 */
export const Button = ({ variant, size, children, ...props }) => {
  // ...
}

​
Import paths, imports, and exports

A clear import and export layout helps the AI emit correct code.

​
Barrel exports

Create index.ts files that re-export components: 
// src/components/index.ts
export { Button } from './Button'
export { Card } from './Card'
export { Dialog } from './Dialog'

​
Document import paths

In Storybook or other docs, show the import path callers should use: 
// Good: shows the import path users should rely on
import { Button } from '@mycompany/design-system'

// Avoid: deep internal paths that may change
import { Button } from '@mycompany/design-system/src/components/Button/Button'

Overview

How we import documentation and component code.

Component code

Package layout and how to provide access.

Multiple packages

Monorepos, tokens, and cross-package imports.