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:

/* 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:

<Card>
  <Card.Header>Title</Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>
    <Button>Action</Button>
  </Card.Footer>
</Card>

Slot-based Components:

<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

/* 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 - Foundational truths
• Glossary - Corporate terminology
• Architecture Overview - 7-layer system