mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: design system reference and task completion (MS15-DOC-001) (#454)

Browse Source 
Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>
This commit was merged in pull request #454.
This commit is contained in:
Jason Woltje
2026-02-22 21:20:28 +00:00
committed by jason.woltje
parent b43e860c40
commit d218902cb0
2 changed files with 161 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
docs/design/design-system.md Normal file
View File

@@ -0,0 +1,141 @@
# 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

40
docs/tasks.md
View File

@@ -8,26 +8,26 @@
**Milestone:** MS15-DashboardShell (0.0.15) **Milestone:** MS15-DashboardShell (0.0.15)
**PRD:** docs/PRD.md **PRD:** docs/PRD.md
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes | | id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
| ------------- | ----------- | -------------------------------------------------------------------------------------------- | ----- | ---- | --------------------------- | ----------------------- | ----------------------------------------------- | ----- | ----------------- | ----------------- | -------- | ---- | --------------------------------------------------------------- | | ------------- | ------ | -------------------------------------------------------------------------------------------- | ----- | ---- | --------------------------- | ----------------------- | ----------------------------------------------- | ----- | ----------------- | ----------------- | -------- | ---- | --------------------------------------------------------------- |
| MS15-FE-001 | done | Design token system overhaul (globals.css → dashboard.html tokens, dark/light, fonts) | #448 | web | feat/ms15-design-system | | MS15-FE-002,MS15-FE-003,MS15-FE-004,MS15-UI-001 | w-1 | 2026-02-22T14:30Z | 2026-02-22T15:00Z | 25K | 18K | Combined with FE-002. Commit e615fa8. Build passes. | | MS15-FE-001 | done | Design token system overhaul (globals.css → dashboard.html tokens, dark/light, fonts) | #448 | web | feat/ms15-design-system | | MS15-FE-002,MS15-FE-003,MS15-FE-004,MS15-UI-001 | w-1 | 2026-02-22T14:30Z | 2026-02-22T15:00Z | 25K | 18K | Combined with FE-002. Commit e615fa8. Build passes. |
| MS15-FE-002 | done | App shell grid layout (sidebar + full-width header + main content) | #448 | web | feat/ms15-design-system | MS15-FE-001 | MS15-FE-003,MS15-FE-004,MS15-FE-005 | w-1 | 2026-02-22T14:30Z | 2026-02-22T15:00Z | 20K | 0K | Combined with FE-001 (same commit). | | MS15-FE-002 | done | App shell grid layout (sidebar + full-width header + main content) | #448 | web | feat/ms15-design-system | MS15-FE-001 | MS15-FE-003,MS15-FE-004,MS15-FE-005 | w-1 | 2026-02-22T14:30Z | 2026-02-22T15:00Z | 20K | 0K | Combined with FE-001 (same commit). |
| MS15-FE-003 | done | Sidebar component (collapsible, nav groups, icons, badges, user card footer) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | w-3 | 2026-02-22T15:30Z | 2026-02-22T16:00Z | 25K | 67K | 4 nav groups, SidebarContext, collapse toggle. Commit 04f9918. | | MS15-FE-003 | done | Sidebar component (collapsible, nav groups, icons, badges, user card footer) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | w-3 | 2026-02-22T15:30Z | 2026-02-22T16:00Z | 25K | 67K | 4 nav groups, SidebarContext, collapse toggle. Commit 04f9918. |
| MS15-FE-004 | done | Topbar/Header component (logo, search, status, notifications, theme toggle, avatar dropdown) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | w-4 | 2026-02-22T15:30Z | 2026-02-22T16:00Z | 25K | 44K | Search, status, notifications, avatar dropdown. Commit 04f9918. | | MS15-FE-004 | done | Topbar/Header component (logo, search, status, notifications, theme toggle, avatar dropdown) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | w-4 | 2026-02-22T15:30Z | 2026-02-22T16:00Z | 25K | 44K | Search, status, notifications, avatar dropdown. Commit 04f9918. |
| MS15-FE-005 | done | Responsive layout (breakpoints, hamburger, sidebar auto-hide at mobile) | #448 | web | feat/ms15-design-system | MS15-FE-003,MS15-FE-004 | MS15-QA-001 | w-5 | 2026-02-22T16:00Z | 2026-02-22T16:30Z | 20K | 57K | Mobile overlay, hamburger, matchMedia. Commit 28620b2. | | MS15-FE-005 | done | Responsive layout (breakpoints, hamburger, sidebar auto-hide at mobile) | #448 | web | feat/ms15-design-system | MS15-FE-003,MS15-FE-004 | MS15-QA-001 | w-5 | 2026-02-22T16:00Z | 2026-02-22T16:30Z | 20K | 57K | Mobile overlay, hamburger, matchMedia. Commit 28620b2. |
| MS15-FE-006 | done | Loading spinner (Mosaic logo icon with rotation animation, site-wide) | #448 | web | feat/ms15-design-system | MS15-FE-001 | | w-2 | 2026-02-22T14:30Z | 2026-02-22T15:00Z | 10K | 8K | MosaicLogo + MosaicSpinner components. Same commit e615fa8. | | MS15-FE-006 | done | Loading spinner (Mosaic logo icon with rotation animation, site-wide) | #448 | web | feat/ms15-design-system | MS15-FE-001 | | w-2 | 2026-02-22T14:30Z | 2026-02-22T15:00Z | 10K | 8K | MosaicLogo + MosaicSpinner components. Same commit e615fa8. |
| MS15-UI-001 | done | Align packages/ui tokens with new CSS variable design system | #449 | ui | feat/ms15-shared-components | MS15-FE-001 | MS15-UI-002,MS15-UI-003,MS15-UI-004 | w-6 | 2026-02-22T17:00Z | 2026-02-22T17:30Z | 20K | 35K | Combined with UI-002. Commit 44011f4. Build passes. | | MS15-UI-001 | done | Align packages/ui tokens with new CSS variable design system | #449 | ui | feat/ms15-shared-components | MS15-FE-001 | MS15-UI-002,MS15-UI-003,MS15-UI-004 | w-6 | 2026-02-22T17:00Z | 2026-02-22T17:30Z | 20K | 35K | Combined with UI-002. Commit 44011f4. Build passes. |
| MS15-UI-002 | done | Update Card, Badge, Button, Dot component variants to match reference | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | w-6 | 2026-02-22T17:00Z | 2026-02-22T17:30Z | 25K | 0K | Combined with UI-001 (same commit 44011f4). | | MS15-UI-002 | done | Update Card, Badge, Button, Dot component variants to match reference | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | w-6 | 2026-02-22T17:00Z | 2026-02-22T17:30Z | 25K | 0K | Combined with UI-001 (same commit 44011f4). |
| MS15-UI-003 | done | Create MetricsStrip, ProgressBar, FilterTabs shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | w-7 | 2026-02-22T17:30Z | 2026-02-22T18:00Z | 20K | 30K | Commit 9b0445c. Build passes. | | MS15-UI-003 | done | Create MetricsStrip, ProgressBar, FilterTabs shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | w-7 | 2026-02-22T17:30Z | 2026-02-22T18:00Z | 20K | 30K | Commit 9b0445c. Build passes. |
| MS15-UI-004 | done | Create SectionHeader, Table, LogLine shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-002 | w-8 | 2026-02-22T17:30Z | 2026-02-22T18:00Z | 15K | 25K | Commit 9b0445c. Build passes. | | MS15-UI-004 | done | Create SectionHeader, Table, LogLine shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-002 | w-8 | 2026-02-22T17:30Z | 2026-02-22T18:00Z | 15K | 25K | Commit 9b0445c. Build passes. |
| MS15-UI-005 | done | Create Terminal panel component (bottom drawer, tabs, output) | #449 | web | feat/ms15-shared-components | MS15-UI-001 | | w-9 | 2026-02-22T17:30Z | 2026-02-22T18:00Z | 20K | 30K | Commit 9b0445c. Build passes. | | MS15-UI-005 | done | Create Terminal panel component (bottom drawer, tabs, output) | #449 | web | feat/ms15-shared-components | MS15-UI-001 | | w-9 | 2026-02-22T17:30Z | 2026-02-22T18:00Z | 20K | 30K | Commit 9b0445c. Build passes. |
| MS15-DASH-001 | done | Dashboard metrics strip (6 cells, colored borders, values, trends) | #450 | web | feat/ms15-dashboard-page | MS15-UI-002,MS15-UI-003 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 15K | 12K | DashboardMetrics.tsx. Commit 4500f80. Build passes. | | MS15-DASH-001 | done | Dashboard metrics strip (6 cells, colored borders, values, trends) | #450 | web | feat/ms15-dashboard-page | MS15-UI-002,MS15-UI-003 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 15K | 12K | DashboardMetrics.tsx. Commit 4500f80. Build passes. |
| MS15-DASH-002 | done | Active Orchestrator Sessions card with agent nodes | #450 | web | feat/ms15-dashboard-page | MS15-UI-004 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 20K | 15K | OrchestratorSessions.tsx. Commit 4500f80. | | MS15-DASH-002 | done | Active Orchestrator Sessions card with agent nodes | #450 | web | feat/ms15-dashboard-page | MS15-UI-004 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 20K | 15K | OrchestratorSessions.tsx. Commit 4500f80. |
| MS15-DASH-003 | done | Quick Actions 2x2 grid | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 10K | 8K | QuickActions.tsx. Commit 4500f80. | | MS15-DASH-003 | done | Quick Actions 2x2 grid | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 10K | 8K | QuickActions.tsx. Commit 4500f80. |
| MS15-DASH-004 | done | Activity Feed sidebar card | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 15K | 10K | ActivityFeed.tsx. Commit 4500f80. | | MS15-DASH-004 | done | Activity Feed sidebar card | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 15K | 10K | ActivityFeed.tsx. Commit 4500f80. |
| MS15-DASH-005 | done | Token Budget sidebar card with progress bars | #450 | web | feat/ms15-dashboard-page | MS15-UI-003 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 10K | 8K | TokenBudget.tsx. Commit 4500f80. | | MS15-DASH-005 | done | Token Budget sidebar card with progress bars | #450 | web | feat/ms15-dashboard-page | MS15-UI-003 | | w-10 | 2026-02-22T19:00Z | 2026-02-22T19:30Z | 10K | 8K | TokenBudget.tsx. Commit 4500f80. |
| MS15-QA-001 | done | Baseline tests (lint, typecheck, build) and situational tests (responsive, themes) | #448 | web | feat/ms15-design-system | MS15-FE-005 | | orch | 2026-02-22T16:30Z | 2026-02-22T16:35Z | 15K | 2K | lint 0 errors, typecheck clean, build passes. All caches hit. | | MS15-QA-001 | done | Baseline tests (lint, typecheck, build) and situational tests (responsive, themes) | #448 | web | feat/ms15-design-system | MS15-FE-005 | | orch | 2026-02-22T16:30Z | 2026-02-22T16:35Z | 15K | 2K | lint 0 errors, typecheck clean, build passes. All caches hit. |
| MS15-DOC-001 | not-started | Documentation: design system reference, component docs | #448 | docs | feat/ms15-design-system | MS15-QA-001 | | | | | 10K | | | | MS15-DOC-001 | done | Documentation: design system reference, component docs | #448 | docs | feat/ms15-docs | MS15-QA-001 | | orch | 2026-02-22T19:40Z | 2026-02-22T19:45Z | 10K | 3K | docs/design/design-system.md. Commit a7a2708. |
--- ---