Overview

A concise 1-3 sentence description of this component and its primary purpose.

• Purpose: Explain why this component exists in the design system and what user/business needs it addresses
• When to Use: Describe use cases, scenarios, and the context in which this component is most effective.

Visual documentation

1. Anatomy
2. Variants
3. States

Anatomy

A labeled visual breakdown of the component's parts and structure.

Purpose: It provides an apparent reference for designers and developers to understand each component's structure and naming conventions.

• Diagram & Labels:
• Title or Header
• Icon or Chevron (if applicable)
• Body / Content Area
• Visual Examples: Include annotated images or Figma embeds.

Composition

• Structure: Explain how the component is built (container, subcomponents, nesting).
• Alignment: Explain how elements are aligned within the component.

Variants

List and describe the different variations of the components available in the system.

Purpose: Documents the flexibility of the component and helps teams select the right variant for their use case.

Usage guidelines

1. When to Use
2. Best Practices
3. Content Guidelines

When to use

Provide clear guidance on when, where, and how to use the component.

Purpose: Helps teams use components consistently and appropriately, preventing misuse and ensuring a cohesive user experience.

Best practices

• Do’s:
• Use the component for [specific use case].
• Keep labels concise and consistent.
• Don’ts:
• Avoid overcrowding the component with too much content.
• Don’t use the component when a full-page scroll is more appropriate.

Content guidelines

• Briefly explain the content writing practice with a link to related pages from our guidelines.

Technical documentation

1. Interaction & behavior
2. Properties
3. Modifiers

Interaction & behavior

• Transitions/Motion: Include details on easing functions, durations, and animation (e.g., “Use --motion-duration-quick-1 for smooth transitions”).
• Keyboard & Mouse Interactions: Explain how users interact via clicks, keyboard navigation, and focus management.

Best practice: Clearly document interactive behaviors and states so developers can reproduce consistent interactions across platforms.

Properties

Document the customizable options, props (React), or parameters available for the component.

Purpose: As a technical reference for developers implementing the component, ensuring proper usage and customization.

Modifiers

• Style:
• Alternate color schemes or icon alignments.
• Size variations (e.g., small, medium, large).
• Overrides:
• Additional states include error, loading, or focused.
• Usage Examples:
• Provide annotated examples showing how a modifier changes appearance or behavior.

Accessibility

Document accessibility considerations and requirements.

Purpose: To ensure the component is accessible to everyone, including people with disabilities, and meets legal and ethical accessibility standards.

References

• Link for the external article that can explain any part of the component more deeply.

Related components

List and briefly describe components that are related or can be used in conjunction with this one.

Purpose: Helps teams understand the component ecosystem and decide which components to use together.