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