Design Tokens & Styling
Relevant source files
The following files were used as context for generating this wiki page:
The Dotorixel design system, internally referred to as the Pebble UI theme, is a "learning-first" visual framework designed for cross-platform consistency between Web (Svelte) and Apple Native (SwiftUI/Metal) environments. It utilizes a unified set of design tokens to establish a warm, earth-toned aesthetic characterized by rounded floating panels and acorn brown accents.
The system is architected to prioritize declarative styling using CSS custom properties (variables) on the web, which are mirrored as static properties in native shells. This ensures visual parity and high cohesion across different device tiers, ranging from compact mobile views to wide desktop layouts.
Sources: CLAUDE.md:154-162, tasks/records/041-design-system-finalization.md:1-5
Design Token Architecture
The styling system is built upon a global CSS variable architecture using the --ds-* namespace. This namespace unified previously disparate systems (like --pebble-* and --color-*) into a single source of truth defined in design-tokens.css.
Visual Hierarchy & Themes
Dotorixel supports both Light and Dark themes via the data-theme="dark" attribute. The system is designed with an "elevated" surface logic where components like panels use background colors that stand out against the base canvas or app background.
The diagram shows how global tokens provide the foundation for all UI components while supporting theme-based overrides.
Sources: src/styles/design-tokens.css:7-104, tasks/records/041-design-system-finalization.md:14-18
Core Token Categories
| Category | Key Tokens | Description |
|---|---|---|
| Surface | --ds-bg-base, --ds-bg-surface, --ds-bg-elevated | Defines the layered background system for the app and panels. |
| Accent | --ds-accent, --ds-accent-text | Primary brand color (Acorn Brown) used for active states and highlights. |
| Typography | --ds-font-heading, --ds-font-body | Custom pixel fonts (Galmuri) for headings and interface text. |
| Spacing | --ds-space-1 to --ds-space-8 | An 8-level scale ranging from 2px to 48px. |
| Shape | --ds-radius-sm to --ds-radius-xl | Corner radii, where sm (6px) is used for buttons and lg (20px) for panels. |
Sources: src/styles/design-tokens.css:7-75, tasks/records/045-design-system-application.md:20-25
Styling Principles & Implementation
Component Styling Strategy
Dotorixel follows a "Vanilla CSS only" rule for the web, avoiding frameworks like Tailwind in favor of Svelte's scoped <style> blocks. Styling logic emphasizes readability and intent:
- Scoped Properties: Prefer component-scoped custom properties for derived values (e.g.,
--depth). - Pure Functions: Use CSS
color-mix()for dynamic variants like hover states (e.g., deriving a darker shade from--ds-accent) rather than adding new tokens. - Native Alignment: Apple native shells mirror these tokens as static
SwiftUI.Colorproperties to maintain parity.
Sources: CLAUDE.md:148-158, tasks/records/045-design-system-application.md:24
Responsive Layout Paradigms
The system employs different layout structures based on screen width breakpoints:
The design system transitions from a "Docked Panel" (CSS Grid) on desktop to a "Tab Navigation" system on mobile/tablet.
Sources: tasks/records/046-editor-layout-restructure.md:11-39
Typography System
Dotorixel uses the Galmuri pixel font family to reinforce its 2D pixel art aesthetic while supporting multiple languages (Korean, English, Japanese).
| Font Token | Typeface | Usage |
|---|---|---|
--ds-font-heading | Galmuri14 | Titles, labels, and primary UI headings. |
--ds-font-body | Galmuri11 | General interface text and proportional body copy. |
--ds-font-mono | GalmuriMono11 | Fixed-width numbers and technical coordinate data. |
Sources: src/styles/design-tokens.css:41-43, src/lib/ui-pixel/DesignTokens.stories.svelte:80-120
Visual Components & Patterns
The design system defines specific patterns for common UI elements:
- Buttons: Use
--ds-radius-sm(6px). Hover states are derived viavar(--ds-bg-hover)orcolor-mix()for accents. - Floating Panels: Feature
backdrop-filter: blurand a semi-transparent background derived from--ds-bg-elevatedat approximately 93% opacity. - Swatches: Standardized at 24x24px for the editor, using
--ds-accentfor selected state outlines. - Touch Targets: A minimum size of 44px (
--ds-touch-target-min) is enforced for mobile/tablet usability.
Sources: src/styles/design-tokens.css:62, tasks/records/045-design-system-application.md:21-36, tasks/records/046-editor-layout-restructure.md:19-21
Conclusion
The Design Tokens & Styling system in Dotorixel provides a robust, themeable foundation that bridges the gap between web and native platforms. By centralizing values in the --ds-* namespace and utilizing platform-agnostic styling principles, the project maintains a consistent "Pebble UI" identity while remaining responsive across a wide range of devices and form factors.
Sources: tasks/records/041-design-system-finalization.md:21-25, CLAUDE.md:154-159