# ADR-003: Design System Approach

**Status:** Accepted **Date:** 2026-02-21

## Context

The OSHUN web app serves multiple domains (Tara, Veritas, Nyx, Arete), each with
its own accent color and content type. We needed a design system that provides
visual consistency across domains while allowing domain-specific theming, and
that is accessible and performant.

## Decision

We built a **custom design system** with semantic tokens, domain-aware
components, and CSS-in-JS styling via inline styles driven by a token object.

### Token Architecture (`src/design-system/tokens.ts`)

- **Semantic color tokens**: `tokens.semantic.text.*`, `surface.*`, `accent.*`,
  `status.*` — never raw hex values
- **Domain accent palettes**: Full tint/shade scales (50-950) for each domain
  (Tara cyan, Arete emerald, Veritas sky, Nyx indigo)
- **Typography scale**: display, heading-1 through heading-4, body variants,
  caption, overline, label — with font-size, line-height, weight, spacing
- **Spacing**: 4px grid system (0-64 scale)
- **Motion**: Duration (instant/fast/normal/slow) and easing (standard/
  decelerate/accelerate/spring)
- **Z-index layers**: base, sticky, dropdown, overlay, modal, toast, tooltip

### Component Library (`src/design-system/components/`)

Built-from-scratch components rather than wrapping a third-party library:

- **Button** — Primary/secondary/ghost/destructive/domain variants with loading
  states
- **IconButton** — Icon-only with built-in tooltip and aria-label
- **Tabs** — Roving tabindex, animated indicator, domain accent support
- **Dropdown** — Full keyboard navigation, ARIA menu pattern
- **SearchInput** — Type=search, clear button, shortcut hints
- **OverlaySheet** — Focus trap, scroll lock, body restore
- **Toast** — Auto-dismiss, screen reader announcements, action buttons

### Icon System (`src/design-system/icons.ts`)

Lucide React for tree-shakable, MIT-licensed icons. Domain-specific icon sets
exported for consistent usage.

## Rationale

### Why custom components instead of Radix/shadcn/Chakra?

- **Domain theming**: We need deep control over accent colors per domain. Most
  libraries make this awkward with CSS variable overrides.
- **Bundle size**: Custom components include only what we use. No unused
  component code ships to production.
- **Accessibility control**: We implement ARIA patterns directly rather than
  depending on library internals. This makes accessibility auditable.
- **Learning**: The team understands every line of the design system.

### Why semantic tokens instead of utility classes (Tailwind)?

- Tokens enforce visual consistency — developers pick from a constrained palette
  rather than arbitrary values
- Domain accent switching works at the token level without class rewrites
- Tokens are typed — TypeScript catches invalid color/spacing usage
- Easier to maintain dark mode (change token values, not class lists)

### Why Lucide over Heroicons/Phosphor?

- MIT license (no attribution required)
- Tree-shakable (only imported icons ship)
- Consistent 24px grid with 1.5px stroke
- Large icon set covering all domain needs

## Consequences

- More upfront work than adopting a component library
- Team must maintain accessibility patterns themselves (tested with 87 unit
  tests)
- No Storybook yet (planned) — component docs live in `docs/design-system.md`
- Adding new components requires implementing ARIA patterns from scratch
- Token object is imported in every component — tree-shaking keeps this
  efficient
