stack/docs/design/design-system.md

Mosaic Stack Design System

Overview

The Mosaic Stack design system provides a unified visual language across the dashboard application. It uses CSS custom properties for theming, inline styles for packages/ui components, and a dark-first approach with light theme support.

Design Tokens

All tokens are defined in apps/web/src/app/globals.css as CSS custom properties on :root (dark default) and [data-theme="light"].

Color Palette

Token	Dark Value	Purpose
--ms-blue-400	#4d94ff	Primary accent, active states
--ms-blue-500	#2f80ff	Primary brand color
--ms-teal-400	#2dd4bf	Success, positive metrics
--ms-teal-500	#14b8a6	Success emphasis
--ms-purple-400	#a78bfa	Orchestrator, secondary accent
--ms-purple-500	#8b5cf6	Purple emphasis
--ms-amber-400	#fbbf24	Warnings, caution
--ms-red-400	#f87171	Errors, danger
--ms-cyan-500	#06b6d4	Info, neutral accent

Semantic Tokens

Token	Dark Value	Purpose
--bg	#0a0e17	Page background
--bg-mid	#111827	Card/panel background
--bg-deep	#060a12	Terminal/deep surfaces
--surface	#151c2c	Card surfaces
--surface-2	#1e2940	Hover/active surfaces
--border	#1e2940	Default borders
--text	#e8ecf4	Primary text
--text-2	#94a3b8	Secondary text
--muted	#64748b	Muted/label text
--primary	var(--ms-blue-500)	Primary action
--success	var(--ms-teal-500)	Success state
--danger	var(--ms-red-400)	Error state
--warn	var(--ms-amber-400)	Warning state

Typography

Token	Value	Purpose
--font	Inter, system-ui, sans-serif	Body text
--mono	JetBrains Mono, monospace	Code, metrics, timestamps

Spacing & Radii

Token	Value	Purpose
--r-sm	4px	Small radius (buttons, inputs)
--r	8px	Default radius (cards, panels)
--r-lg	12px	Large radius (sections, modals)

App Shell Layout

The dashboard uses a CSS Grid layout:

grid-template-columns: var(--sidebar-w) 1fr;
grid-template-rows: var(--topbar-h) 1fr;

• Header spans full width (grid-column: 1 / -1)
• Sidebar width: 240px (expanded) / 60px (collapsed)
• Topbar height: 52px

Responsive Breakpoints

Breakpoint	Behavior
< 768px (Mobile)	Single column, sidebar as overlay with backdrop
768-1023px (Tablet)	Sidebar toggleable, hidden by default
>= 1024px (Desktop)	Sidebar always visible

Shared Components (packages/ui)

All packages/ui components use inline styles with CSS custom properties since the package is built with tsc only (no CSS processing).

Button

Variants: primary (blue), secondary (transparent), ghost, danger (red), success (teal)

Badge

Variants: badge-teal, badge-amber, badge-red, badge-blue, badge-muted, badge-purple, badge-pulse

Pill shape with monospace font. badge-pulse includes an animated dot.

Card

Flat design with var(--surface) background, var(--border) border, var(--r-lg) border-radius. Header and footer slots available.

Dot

Status indicator (7x7px circle with glow). Variants: teal, blue, amber, red, muted.

MetricsStrip

Grid of metric cells with colored top borders, hover state, and optional trend indicators. Each cell: value (large mono), label (small muted), trend (colored directional text).

ProgressBar

4px track with fill animation. Variants: blue, teal, purple, amber. Full ARIA progressbar semantics.

FilterTabs

Segmented control with active/hover states.

SectionHeader

Flex row with title/subtitle on left, action slot on right.

DataTable

Generic typed table with column render functions, row hover, and row click support.

LogLine

3-column grid (timestamp, level, message) with color-coded log levels.

Dashboard Page Layout

The dashboard page uses:

1. MetricsStrip (full width, 6 cells)
2. Two-column grid (1fr 320px):
   • Main: OrchestratorSessions + QuickActions
   • Sidebar: ActivityFeed + TokenBudget

Terminal Panel

Bottom drawer component (apps/web/src/components/terminal/TerminalPanel.tsx) with:

• Height animation (0 → 280px)
• Tab bar (main, build, logs)
• Color-coded output lines (prompt, command, output, error, warning, success)
• Blinking cursor animation