Styling & Design Tokens

Basalt follows strict styling rules to ensure theme flexibility, visual consistency, and accessibility across the desktop workbench.

---

1. The --sat-* Token System (ADR-002)

All colors across the application flow through CSS custom properties prefixed with --sat-*.

:::danger No Hardcoded Colors Using hardcoded hex colors, RGB literals, or arbitrary Tailwind color classes (such as bg-blue-600 or text-gray-400) is strictly prohibited. Every color must reference a --sat-* variable. :::

Token Families

Family	Purpose	Canonical Tokens
Surface	Background planes and elevation layers	--sat-surface-base, --sat-surface-1, --sat-surface-2, --sat-surface-elevated
Text	Hierarchical typography colors	--sat-text-primary, --sat-text-secondary, --sat-text-muted, --sat-text-faint
Accent	Interactive focal points and buttons	--sat-accent-primary, --sat-accent-hover, --sat-accent-subtle
Layout	Structural outlines and separators	--sat-layout-border, --sat-layout-divider, --sat-layout-ring
State	Feedback for user interaction	--sat-state-hover, --sat-state-active, --sat-state-selected
Editor	Prose writing surface elements	--sat-editor-bg, --sat-editor-cursor, --sat-editor-selection

Styling Examples

// ❌ WRONG — Raw Tailwind color or hex code
<div className="bg-[#1e293b] text-white border-gray-700">
  <button className="bg-blue-600 hover:bg-blue-700">Save</button>
</div>

// ✅ CORRECT — CSS custom properties for color, Tailwind for layout
<div className="bg-[var(--sat-surface-1)] text-[var(--sat-text-primary)] border-[var(--sat-layout-border)] p-4 flex gap-2">
  <Button variant="default">Save</Button>
</div>

---

2. Component Policy: shadcn & Radix (ADR-003)

Basalt relies on headless Radix UI primitives styled with Tailwind and exported via packages/ui/:

• Never Hand-Roll Core Primitives: Always use standard components (Button, Dialog, DropdownMenu, Tooltip, Select, Input) from @workspace/ui/components/ui/*.
• Dumb Presentational Rule: Components in packages/ui/ must remain pure presentational elements. They:
  • 🚫 Must NOT import from @tauri-apps/*
  • 🚫 Must NOT invoke backend IPC commands
  • 🚫 Must NOT access business Zustand stores
  • ✅ Receive props, emit DOM callbacks, and manage internal UI state (e.g., open/close, hover) only.

---

3. Themes & Customization

Basalt supports instant, zero-reload theme switching between Dark and Light modes as well as community color palettes (Nord, Solarized, Gruvbox, etc.).

Because all components reference --sat-* tokens, swapping themes merely updates the CSS variable definitions at the document root, causing every editor, panel, and widget to re-skin smoothly without re-rendering the component tree.