dss/docs/principles/ATOMIC_HIERARCHY.md

# DSS Atomic Hierarchy

> **The 5-level composition model for building design systems**

---

## Overview

The atomic hierarchy defines how design system elements compose from simple to complex. Each level builds upon the previous, creating a predictable structure.

```
Level 1: Tokens      → Raw design values
Level 2: Primitives  → Indivisible UI elements
Level 3: Components  → Composite UI elements
Level 4: Layouts     → Page structure patterns
Level 5: Views       → Complete screens
```

---

## Level 1: Tokens

**Definition**: Design variables representing raw values.

Tokens are the foundation - the smallest unit of design decisions. They have no visual representation on their own.

### Categories

| Category | Purpose | Examples |
|----------|---------|----------|
| Colors | Color palette | `--color-primary-500`, `--color-neutral-100` |
| Typography | Font properties | `--font-size-md`, `--font-weight-bold` |
| Spacing | Whitespace scale | `--spacing-4`, `--spacing-8` |
| Sizing | Dimension values | `--size-button-height`, `--size-icon-md` |
| Borders | Border properties | `--border-radius-sm`, `--border-width-1` |
| Shadows | Elevation effects | `--shadow-sm`, `--shadow-lg` |
| Motion | Animation values | `--duration-fast`, `--easing-default` |

### Token Tiers

```
Primitive Tokens (raw values)
    ↓
Semantic Tokens (meaningful names)
    ↓
Component Tokens (scoped to components)
```

**Example**:
```css
/* Primitive */
--color-blue-500: #3b82f6;

/* Semantic */
--color-primary: var(--color-blue-500);

/* Component */
--button-background: var(--color-primary);
```

---

## Level 2: Primitives

**Definition**: Base UI elements that cannot be broken down further.

Primitives are the atoms of the design system. They implement tokens and provide the building blocks for components.

### Core Primitives

| Primitive | Description | Token Usage |
|-----------|-------------|-------------|
| Button | Clickable action trigger | colors, spacing, typography |
| Input | Text entry field | colors, spacing, borders |
| Label | Text descriptor | typography, colors |
| Icon | Visual symbol | sizing, colors |
| Badge | Status indicator | colors, typography, spacing |
| Divider | Visual separator | colors, spacing |
| Avatar | User representation | sizing, borders |
| Spinner | Loading indicator | sizing, colors, motion |

### Rules for Primitives

1. **Single responsibility** - One purpose per primitive
2. **Token-only styling** - No hardcoded values
3. **Stateless by default** - State managed externally
4. **Composable** - Designed for combination
5. **Accessible** - ARIA support built-in

---

## Level 3: Components

**Definition**: Composite UI elements combining multiple primitives.

Components solve specific UI problems by composing primitives into reusable patterns.

### Core Components

| Component | Primitives Used | Purpose |
|-----------|-----------------|---------|
| FormField | Label + Input + Icon | Complete form input |
| Card | Container + primitives | Content grouping |
| Modal | Container + Button + Icon | Overlay dialog |
| Dropdown | Button + List + Icon | Selection menu |
| Tabs | Button + Container | Content switching |
| Toast | Container + Icon + Button | Notifications |
| Tooltip | Container + Text | Contextual info |

### Component Patterns

**Compound Components**:
```jsx
<Card>
  <Card.Header>Title</Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>
    <Button>Action</Button>
  </Card.Footer>
</Card>
```

**Slot-based Components**:
```jsx
<FormField
  label="Email"
  input={<Input type="email" />}
  error="Invalid email"
/>
```

### Rules for Components

1. **Compose primitives** - Never skip to tokens
2. **Define clear API** - Props, slots, events
3. **Handle state** - Internal state management
4. **Provide variants** - Size, color, style options
5. **Document usage** - Storybook stories required

---

## Level 4: Layouts

**Definition**: Page structure patterns that organize components.

Layouts define the spatial relationships and responsive behavior of page sections.

### Core Layouts

| Layout | Purpose | Components Used |
|--------|---------|-----------------|
| PageShell | App wrapper | Header, Sidebar, Content |
| DashboardGrid | Data display | Cards, Charts, Tables |
| FormLayout | Form organization | FormFields, Buttons |
| ListLayout | Item collections | Cards, Pagination |
| SplitView | Side-by-side | Panels, Dividers |

### Layout Primitives

```
Box      → Basic container with spacing/sizing
Stack    → Vertical arrangement with gap
Inline   → Horizontal arrangement with gap
Grid     → 2D arrangement with columns/rows
Cluster  → Flexible wrapping arrangement
```

### Responsive Patterns

```css
/* Mobile-first breakpoints */
--breakpoint-sm: 640px;   /* Phones */
--breakpoint-md: 768px;   /* Tablets */
--breakpoint-lg: 1024px;  /* Laptops */
--breakpoint-xl: 1280px;  /* Desktops */
```

---

## Level 5: Views

**Definition**: Complete screens with content and functionality.

Views are the final composition - full pages that users interact with.

### DSS Admin Views

| View | Purpose | Layouts Used |
|------|---------|--------------|
| TokenExplorer | Browse/edit tokens | DashboardGrid |
| FigmaSync | Import from Figma | FormLayout |
| ComponentAudit | Review components | ListLayout |
| ThemeEditor | Customize themes | SplitView |
| Documentation | View docs | PageShell |

### View Responsibilities

1. **Data fetching** - API calls, state loading
2. **Route handling** - URL parameters, navigation
3. **Layout composition** - Arranging layouts
4. **Business logic** - Domain-specific rules
5. **Error boundaries** - Graceful failure handling

---

## Composition Rules

### The Golden Rule

> **Each level only references the level immediately below.**

```
Views      → use Layouts (never tokens directly)
Layouts    → use Components (never tokens directly)
Components → use Primitives (never tokens directly)
Primitives → use Tokens
Tokens     → are the foundation
```

### Anti-Patterns

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Token in View | Skips 4 levels | Use component with variant |
| Component in Token | Circular dependency | Tokens are values only |
| Layout without Components | Missing abstraction | Create component first |
| Primitive with business logic | Wrong responsibility | Move logic to component |

### Decision Tree

```
Need a design value?
  → Use a TOKEN

Need a single UI element?
  → Use a PRIMITIVE

Need a reusable UI pattern?
  → Create a COMPONENT

Need page structure?
  → Create a LAYOUT

Need a full screen?
  → Create a VIEW
```

---

## Implementation Examples

### Token → Primitive → Component → Layout → View

```
Token:
  --color-primary: #3b82f6;
  --spacing-4: 1rem;

Primitive:
  <Button variant="primary">Click</Button>
  (uses --color-primary, --spacing-4)

Component:
  <FormField>
    <Label>Email</Label>
    <Input type="email" />
    <Button type="submit">Send</Button>
  </FormField>

Layout:
  <FormLayout>
    <FormField ... />
    <FormField ... />
    <FormField ... />
  </FormLayout>

View:
  <ContactPage>
    <PageShell>
      <FormLayout>
        ...
      </FormLayout>
    </PageShell>
  </ContactPage>
```

---

## See Also

- [First Principles](./FIRST_PRINCIPLES.md) - Foundational truths
- [Glossary](../GLOSSARY.md) - Corporate terminology
- [Architecture Overview](../architecture/OVERVIEW.md) - 7-layer system