Eve library

ADR-003: Design System Approach

ADR

Revision 1

On this page

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