Component Anatomy Standards

Component anatomy breaks down complex components into their core parts, making them easier to understand, document, and maintain. By identifying the essential elements and their relationships, we create a shared vocabulary and enable consistent implementation across teams.

Why Anatomy Matters

Documenting component anatomy provides:

  • Clarity: Clear understanding of what makes up a component
  • Consistency: Standardized terminology across teams
  • Flexibility: Understanding parts enables composition and customization
  • Documentation: Visual and textual reference for implementation

Anatomy Hierarchy

1. Root Element

The outermost container that wraps all component parts:

// Button root element
<button className="button" {...props}>
  {/* All parts contained within */}
</button>

// Card root element
<div className="card">
  {/* Card parts */}
</div>

2. Primary Parts

Essential elements that define the component's purpose:

// Button primary parts
<button className="button">
  <span className="button__icon">{icon}</span> {/* Icon part */}
  <span className="button__text">{children}</span> {/* Text part */}
</button>

// Card primary parts
<div className="card">
  <div className="card__header">{title}</div> {/* Header part */}
  <div className="card__body">{content}</div> {/* Body part */}
  <div className="card__footer">{actions}</div> {/* Footer part */}
</div>

3. Optional Parts

Parts that may or may not be present based on props or state:

// Button optional parts
<button className="button">
  {icon && <span className="button__icon">{icon}</span>} {/* Optional icon */}
  <span className="button__text">{children}</span>
  {loading && <span className="button__spinner" />} {/* Optional spinner */}
</button>

// Card optional parts
<div className="card">
  {image && <div className="card__image">{image}</div>} {/* Optional image */}
  <div className="card__body">{content}</div>
  {actions && <div className="card__footer">{actions}</div>} {/* Optional footer */}
</div>

Naming Conventions

BEM-Style Naming

Use BEM (Block Element Modifier) naming for clarity:

// Block: Component name
.button { }
.card { }

// Element: Part of component
.button__icon { }
.button__text { }
.card__header { }
.card__body { }

// Modifier: Variant or state
.button--primary { }
.button--disabled { }
.card--elevated { }

Semantic Naming

Use semantic names that describe purpose, not appearance:

// ✅ Good: Semantic naming
.card__header { }
.card__body { }
.card__footer { }

// ❌ Bad: Appearance-based naming
.card__top { }
.card__middle { }
.card__bottom { }

Documentation Standards

Required Documentation

Every component anatomy should include:

  • Visual Diagram: Visual representation of parts
  • Part List: List of all parts with descriptions
  • Hierarchy: How parts relate to each other
  • Required vs Optional: Which parts are always present vs conditional
  • Code Examples: How parts map to code structure

Anatomy Structure Format

/**
 * Button Component Anatomy
 * 
 * Root: button.button
 * ├── Icon (optional): span.button__icon
 * ├── Text (required): span.button__text
 * └── Spinner (optional): span.button__spinner
 */
interface ButtonAnatomy {
  root: 'button';
  parts: {
    icon?: 'span.button__icon';
    text: 'span.button__text';
    spinner?: 'span.button__spinner';
  };
}

Layer-Specific Anatomy

Primitives

Primitives have simple anatomy with minimal parts:

// Button (Primitive)
Root: button
Parts:
  - text (required): Button label
  - icon (optional): Leading icon
  
// Simple structure, few parts

Compounds

Compounds coordinate multiple primitives:

// TextField (Compound)
Root: div.field
Parts:
  - label (required): Label element
  - input (required): Input primitive
  - hint (optional): Helper text
  - error (optional): Error message
  
// Coordinates multiple primitives

Composers

Composers have complex anatomy with orchestrated parts:

// Modal (Composer)
Root: div.modal
Parts:
  - overlay (required): Backdrop
  - container (required): Main modal container
    - header (optional): Title area
    - body (required): Content area
    - footer (optional): Action area
      - actions (optional): Button group
  
// Hierarchical structure with nested parts

Visual Documentation

Anatomy Diagrams

Visual diagrams help teams understand component structure:

  • Wireframe Style: Simple outlines showing part locations
  • Labeled Parts: Clear labels connecting visual to code
  • Hierarchy Trees: Tree structure showing relationships

Related Resources