MixAI Design System

Source of truth for how every MixAI surface looks and behaves — web (PWA), MixAI DJ (Tauri), Companion (Electron), native shell (Tauri/Capacitor), TV (Tizen web + Android Compose) and the browser extension. Code lives in packages/design-tokens (data) and packages/ui (components). Progress and decisions: docs/mixai-design-tracker.md.

1. Principles

1. One token source. Colours, radii, motion, breakpoints and theme dimensions are declared once in packages/design-tokens/src/tokens.ts and generated into every format a surface can read. Hand-typed hex values in app code are a bug.
2. Hue is the only thing a user changes about colour. Every role (primary, ring, chart-1, sidebar-primary…) is an OKLCH triple whose hue is var(--accent-h). Lightness/chroma are fixed per mode so any accent — including a user-picked hue or one sampled from cover art — stays accessible.
3. Dimensions, not themes. A theme is the product of independent axes (mode × accent × surface × density × radius × motion). Each axis is a data-* attribute on <html>; CSS reacts to the attributes, never to a "theme name".
4. No flash, ever. prehydrate.js (1 KB, ES2017) runs before first paint on every web-based surface and writes the attributes from localStorage["mixai:prefs:v1"].
5. Skeletons match layout. Every streaming boundary renders a skeleton with the same box geometry as the final content (no CLS). Spinners only for indeterminate sub-second work.
6. Native feel per platform. Mobile: safe areas, bottom tab bar, sheets, 44 px targets. Desktop: keyboard-first, command palette, dense tables. TV: 24 px root, 4 px focus ring, overscan margins, D-pad spatial navigation.
7. Ultra-wide is a first-class viewport. Reading columns cap at --content-lg/xl; lists become multi-column via container queries; the shell centres itself above 240 rem.

2. Brand — "Neon Nocturne"

Neutrals carry a faint indigo bias (hue 285, chroma 0.004–0.02) and dark-mode text is warm ivory (oklch(0.96 0.01 80)), never pure white.

3. Theme dimensions

Persisted shape (ThemePrefs): { mode, accent, surface, density, radius, motion, locale, feedback }. feedback enables haptics + sound cues (useHaptics()).

Migration: theme (web v1), mixai-ui (MixAI DJ zustand blob: flat-pro→flat, studio-metal→solid, minimal→reduced) and the mmo-locale cookie are read once when mixai:prefs:v1 is absent.

4. Generated artefacts

pnpm -C packages/design-tokens build (also pnpm tokens:build at root) writes:

CI (web-ci.yml) fails if the committed output differs from a fresh build.

5. @mmo/ui

Base UI (@base-ui/react) primitives styled with Tailwind v4, shadcn-compatible names so migration from Radix is mechanical. Differences from Radix you will hit:

• asChild → render={<Link href=… />} (Base UI useRender).
• onOpenChange(open, eventDetails), onValueChange(value, eventDetails) — second arg is new.
• State attributes: data-open, data-checked, data-highlighted, data-starting-style, data-ending-style (not data-state=…).

Families: theme (ThemeProvider, useThemePrefs, useTheme legacy shape, applyPrefs, dominantHueFromImage), layout (AppShell, Sidebar*, BottomTabBar, Page, PageHeader, PageSection), feedback (Skeleton*, EmptyState + NotSignedInState / NoCompanionState / ErrorState / NoResultsState, Progress, ProgressJob, Toaster), data (DataTable on TanStack Table 9 with column priority + mobile cards), overlays (Dialog, Sheet, AlertDialog, Popover, Tooltip, DropdownMenu, ContextMenu, CommandDialog, ShortcutsOverlay), forms (Input, Textarea, Select, Checkbox, Switch, Slider, RadioGroup, ToggleGroup, Field*), settings (ThemeSettings, ThemePreview), motion (fade, rise, scale, slideUp, stagger, PageTransition), hooks (useMediaQuery, useIsMobile, useIsUltrawide, useIsStandalone, useSafeArea, useHaptics, useContainerSize), shortcuts (registerShortcut, useRegisterShortcut, formatKeys).

Consumption is via tsconfig paths (repo convention, packages/README.md). Apps must dedupe react, react-dom, motion, @base-ui/react to their own node_modules (see apps/web/next.config.ts turbopack.resolveAlias and vitest.config.ts resolve.dedupe), otherwise hooks fail with "Cannot read properties of null (reading 'useState')".

6. Layout rules

• Content widths: content-sm 40 rem (forms), content-md 56 rem (reading), content-lg 80 rem (dashboards), content-xl 100 rem (dense tables), full (canvases: DAW, mixer, player).
• Breakpoints: Tailwind defaults + 3xl 120 rem, 4xl 160 rem; variant ultrawide: for min-aspect-ratio: 21/9.
• Mobile shell: BottomTabBar (5 slots + "More" sheet) above the mini-player; --shell-bottom-offset exposes the stacked height so pages can pad (pb-safe-*).
• Z-index scale (--z-*): base 0, raised 10, sticky 20, sidebar 30, player 40, overlay 50, modal 60, popover 70, toast 80, tooltip 90.
• TV: overscan utility (5 vw / 4 vh), --focus-ring-w 4 px, --card-scale-focused 1.06.

Media patterns (Media Home, ADR-0010)

• Hero billboard (.media-hero): full-bleed backdrop clamped at 1600 px and centred on ultrawide, two-direction scrim (--background to the bottom and left), content bottom-left ≤ 640 px, TMDB logo treatment or the title in --font-heading 800; dots are role=tab. Decorative motion (24 s Ken Burns drift, staggered entrance) exists only under data-motion="full".
• Media row (.media-row): heading + "See all" + prev/next, an embla viewport with role=list, ←/→ page, Home/End jump, at most 40 slides then a dashed "+N" tile. Slides reuse PosterCard (--watch-poster-w 180 px, 124 px < 48 rem); TVs mirror the layout with the focused card at --card-scale-focused.
• Title page (.media-title): hero backdrop, poster column (11 rem ≥ 48 rem) overlapping by clamp(-8rem, -14vh, -4rem), sections "Play on <server>" (.media-sources), "Where to watch" (.media-offers, one tile per offer, data-preferred, data-deeplink) and the mandatory attribution line (.media-attribution).
• Server chips (.media-chip): pill per paired MMO Server with a --success dot, aria-pressed filter state, data-offline dimming; notices use --warning at 12 %.

7. Motion

Tokens: --dur-fast 120 ms, --dur-base 220 ms, --dur-slow 400 ms, --dur-page 320 ms; --ease-out (0.16,1,0.3,1), --ease-in-out, --ease-spring (linear() spring). All become 0 ms / linear under data-motion="reduced".

• Route changes: React 19.3 <ViewTransition> (Next App Router, no config) with the cross-fade in @mmo/ui/styles.css; mixai/companion use <PageTransition>.
• Entrances: animate-fade-in, animate-rise-in, animate-scale-in utilities or the motion presets; lists use stagger().
• Decorative motion is only in motion-full: and only on hero/NowPlaying surfaces.

8. Accessibility

WCAG 2.2 AA. Every accent hue yields ≥ 4.5:1 for primary-foreground on primary by construction (L 0.62/0.70 vs 0.99/0.14). Focus is always visible (:focus-visible outline in --ring; 4 px on TV). Touch targets ≥ 44 px (checkbox/switch/radio/slider thumbs pad their hit area). Reduced motion honoured. EmptyState tone="error" has role="alert". Native TV Android (2.1.0+): per-profile reduceMotion pref (true / false / "system" = Android animator duration scale), exposed as LocalReducedMotion (ui/components/Motion.kt); headings use the bundled Space Grotesk variable font and body text Inter (ui/components/Typography.kt, OFL in assets/licenses).

9. Adding a surface

1. @import "tailwindcss"; @import "<path>/design-tokens/dist/tokens.css"; @import "<path>/ui/src/styles.css"; @source "<path>/ui/src";
2. Inline or load prehydrate.js in <head>.
3. Wrap the tree in <ThemeProvider>; add <ThemeSettings /> to the settings screen.
4. Add path aliases @mmo/ui, @mmo/design-tokens and the React dedupe.
5. Register the surface in docs/mixai-design-tracker.md.

For non-web surfaces use tokens.plain.css / Tokens.kt and keep the same attribute names.