Design System
Principles, conventions, and architecture.
Overview
Design principles, token architecture, and key conventions.
Othelia's design system is documented in docs/specs/DESIGN-SYSTEM.md and implemented across src/styles/globals.css (tokens) and src/components/ui/ (components). This page renders the real tokens and components from the codebase — when something changes in code, it changes here automatically.
Design Principles
- Content density over decoration — every visual element must earn its space. Prefer showing more content over adding chrome.
- Tool, not toy — the UI should feel like a capable instrument, not a consumer app. Prefer patterns that present information clearly.
- Icons carry type, color carries meaning — use icons to distinguish categories, reserve color for status, authority level, or identity.
- Earn every element — before adding a visual element, ask: does this convey information the user needs at this level?
Token Architecture
Two layers, not three:
- Primitives (sand, neutral, red, etc.) — raw colour values defined in
globals.css - Semantic (flat tokens +
surface-*+ status scales) — purpose-driven names that components use
Components are the mapping layer — Button knows it uses bg-primary. No component-token indirection needed.
Key Conventions
| Convention | Rule |
|---|---|
| Body text | text-sm (14px) default |
| Font | Inter only, self-hosted via next/font |
| Radius | rounded-lg for interactive, rounded-xl for containers |
| Shadows | Always with borders, not instead of |
| Dark mode | .dark class on root, sand → neutral swap |
| Status colors | Translucent fills (bg-warning-200/70), not solid |
| Icons in buttons | Sized by the Button component, don't add size classes |
| Memoization | Don't use useMemo/useCallback — React Compiler handles it |
File Structure
| Path | Purpose |
|---|---|
src/styles/globals.css | Token definitions, theme overrides, franchise theming |
src/components/ui/ | UI primitives (shadcn/ui + Radix) |
src/components/providers/ThemeProvider.tsx | Dark/light/system theme management |
src/lib/utils.ts | cn() helper (clsx + tailwind-merge) |
docs/specs/DESIGN-SYSTEM.md | Full specification document |