Description
Design System Theming is the visual contract shared by Dots applications and reusable UI. A single token source defines surface, ink, border, DIIICE category, signal state, personal accent, typography, spacing, radius, shadow, breakpoint, and motion values. CSS consumers resolve those variables at runtime, while TypeScript exports cover the smaller set needed by component APIs that require numeric or structured values.
The user’s color mode and accent stamp apply at the document root so derived focus rings, glows, and component states update consistently. Reduced-motion handling collapses interaction timing through shared utilities, and signal colors remain separate from DIIICE content classification. This makes visual customization a controlled product capability rather than a collection of unrelated component props.
Selling Points
- Keeps every module visually coherent, so users experience one recognizable product across complex workflows.
- Makes light, dark, accent, contrast, and reduced-motion behavior systemic instead of requiring per-feature fixes.
- Gives developers semantic tokens that express intent and remain safe when the palette evolves.
- Separates content categories from status signals, preserving meaning for users who rely on repeated visual cues.
- Reduces accessibility drift by centralizing contrast-critical surfaces, focus treatment, and motion timing.
User Story
A developer builds a new settings panel using surface, ink, spacing, and signal tokens rather than selecting raw colors. A user switches to dark mode and a gold personal accent, and the new panel changes in step with the shell, focus rings, charts, and overlays without module-specific theme code.
Extension Surface
The feature is configurable. packages/ui/src/styles/tokens.css is the authoritative token catalog, and apps/web/src/modules/shell/settings/tabs/ThemeSection.tsx exposes supported user theme choices. Consumers can compose with the published semantic variables, but users and plugins cannot redefine the locked DIIICE taxonomy or inject arbitrary runtime styles.
Capabilities & Limits
- Supplies semantic tokens for color, type, spacing, motion, surfaces, borders, shadows, and interaction states.
- Supports light and dark modes, personal accent, reduced motion, and accessibility-aware focus treatment.
- Exposes CSS and TypeScript token surfaces for component consumers.
- Limit: customization is bounded to sanctioned tokens and choices; raw palettes, per-module accent systems, and arbitrary theme packages are outside the contract.
Implementation Map
packages/ui/src/styles/tokens.csspackages/ui/src/tokens.tsapps/web/src/modules/shell/settings/tabs/ThemeSection.tsxpackages/ui/src/lib/useReducedMotion.ts