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

feat(web): MS15 Phase 1 — Design System & App Shell #451

Merged
jason.woltje merged 6 commits from feat/ms15-design-system into main 2026-02-22 20:57:06 +00:00
Conversation 0 Commits 6 Files Changed 15 +327
3 changed files with 327 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 2a6d02b46b - Show all commits

233
docs/PRD.md Normal file
View File

@@ -0,0 +1,233 @@
# PRD: Mosaic Stack Dashboard & Platform Implementation
## Metadata
- Owner: Jason Woltje
- Date: 2026-02-22
- Status: in-progress
- Best-Guess Mode: true
## Problem Statement
The Mosaic Stack web UI has a basic navigation and simple widget-based dashboard that doesn't match the production-ready design vision. The reference design (dashboard.html) defines a comprehensive command center UI with sidebar navigation, topbar, terminal panel, and multiple page layouts. The current implementation uses mismatched design tokens (raw Tailwind colors vs CSS variables), has no collapsible sidebar, no global terminal, and lacks the polished design system from the reference.
## Objectives
1. Implement the dashboard.html reference design as the production UI foundation
2. Establish a consistent CSS design token system that supports multiple themes
3. Build a responsive, accessible app shell with collapsible sidebar and full-width header
4. Create a theme system supporting installable theme packages
5. Build all dashboard pages (Dashboard, Projects, Workspace, Kanban, Files, Logs, Settings, Profile)
6. Implement real backend integration (no mock data)
7. Support multi-tenant configuration with RBAC
8. Implement federation (master-master and master-slave)
9. Build global terminal, project chat, and master chat session
10. Configure telemetry with opt-out support
## Scope
### In Scope (Milestone 0.0.15 — Dashboard Shell & Design System)
1. CSS design token system overhaul (colors, fonts, spacing, radii from dashboard.html)
2. App shell layout: sidebar + full-width header + main content area
3. Full-width header with logo, search, system status, terminal toggle, notifications, theme toggle, user avatar dropdown
4. Collapsible sidebar with nav groups, icons, badges, active states, collapse/expand button
5. Responsive layout with hamburger button at small breakpoints, sidebar hidden by default at mobile
6. Light/dark theme matching the reference design
7. Mosaic logo icon as global loading spinner
8. Shared component updates in packages/ui (Card, Badge, Button, Dot, MetricsStrip, ProgressBar, FilterTabs, SectionHeader, Table, LogLine, Terminal panel)
9. Dashboard page: metrics strip, active orchestrator sessions, quick actions, activity feed, token budget
10. Grain overlay texture from reference design
### In Scope (Future Milestones — Documented for Planning)
11. Additional pages: Projects, Workspace, Kanban, File Manager, Logs & Telemetry, Settings, Profile
12. Theme system with installable theme packages
13. Widget system with installable widget packages, customizable sizes
14. Global terminal (project/orchestrator level, smart)
15. Project-level orchestrator chat
16. Master chat session (collapsible sidebar/slideout, always available)
17. Settings page for ALL environment variables, dynamically configurable via webUI
18. Multi-tenant configuration with admin user management
19. Team management with shared data spaces and chat rooms
20. RBAC for file access, resources, models
21. Federation: master-master and master-slave with key exchange
22. Federation testing: 3 instances on Coolify (woltje.com domain)
23. Agent task mapping configuration (system-level defaults, user-level overrides)
24. Telemetry: opt-out, customizable endpoint, sanitized data
25. File manager with WYSIWYG editing (system/user/project levels)
26. User-level and project-level Kanban with filtering
27. Break-glass authentication user
28. Playwright E2E tests for all pages
29. API documentation via Swagger
30. Backend endpoints for all dashboard data
### Out of Scope
1. Mobile native app
2. Third-party marketplace for themes/widgets (initial implementation is local package management only)
3. Production deployment to non-Coolify targets
4. Calendar system redesign (existing calendar implementation is retained)
## User/Stakeholder Requirements
1. The `jarvis` user must be able to log into mosaic.woltje.com via Authentik as administrator with access to all pages
2. A standard `jarvis-user` must operate at a lower permission level
3. A break-glass user must have access without Authentik authentication
4. All pages must be navigable without errors
5. Light and dark themes must work across all pages and components
6. Sidebar must be collapsible with open/close button; hidden by default at small breakpoints
7. Hamburger button visible at lower breakpoints for sidebar control
8. The Mosaic Stack logo icon must be the site-wide loading spinner
9. No mock data — all data pulled from backend APIs
## Functional Requirements
### FR-001: Design Token System
- CSS custom properties for all colors, spacing, typography, radii
- Dark theme as default (`:root`), light theme via `[data-theme="light"]`
- Fonts: Outfit (body), Fira Code (monospace)
- All components must use design tokens, never hardcoded colors
### FR-002: App Shell Layout
- CSS Grid: sidebar column + header row + main content
- Full-width header spanning above sidebar and content
- ASSUMPTION: Header spans full width including above sidebar area. The logo is in the header, not the sidebar. Rationale: User explicitly stated "The logo will NOT be part of the sidebar."
### FR-003: Sidebar Navigation
- Nav groups: Overview (Dashboard), Workspace (Projects, Project Workspace, Kanban, File Manager), Operations (Logs & Telemetry, Terminal), System (Settings)
- Collapsible: icon-only mode when collapsed
- Active state indicator (left border accent)
- User card in footer with avatar, name, role, online status
- ASSUMPTION: Sidebar footer user card navigates to Profile page. Rationale: Matches reference design behavior.
### FR-004: Header/Topbar
- Logo + brand wordmark (left)
- Search bar with keyboard shortcut hint
- System status indicator
- Terminal toggle button
- Notification bell with badge
- Theme toggle (sun/moon icon)
- User avatar button with dropdown (Profile, Account Settings, Sign Out)
### FR-005: Responsive Design
- Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
- Below md: sidebar hidden, hamburger button in header
- md-lg: sidebar can be toggled
- lg+: sidebar visible by default
### FR-006: Dashboard Page
- 6-cell metrics strip with colored top borders and trend indicators
- Active Orchestrator Sessions card with agent nodes
- Quick Actions 2x2 grid
- Activity Feed sidebar card
- Token Budget sidebar card with progress bars
### FR-007: Loading Spinner
- Mosaic logo icon (4 corner squares + center circle) with CSS rotation animation
- Used as global loading indicator across all pages
- Available as a shared component
### FR-008: Theme System (Future Milestone)
- Support multiple themes beyond default dark/light
- Themes are installable packages from Mosaic Stack repo
- Theme installation and selection from Settings page
- ASSUMPTION: Initial implementation supports dark/light from reference design. Multi-theme package system is a future milestone. Rationale: Foundation must be solid before extensibility.
### FR-009: Terminal Panel (Future Milestone)
- Bottom drawer panel, toggleable from header and sidebar
- Multiple tabs (Orchestrator, Shell, Build)
- Smart terminal operating at project/orchestrator level
- Global terminal for system interaction
### FR-010: Settings Page (Future Milestone)
- All environment variables configurable via UI
- Minimal launch env vars, rest configurable dynamically
- Settings stored in DB with RLS
- Theme selection, widget management, federation config, telemetry config
## Non-Functional Requirements
1. Security: All API endpoints require authentication. RBAC enforced. No PII in telemetry. Secrets never hardcoded.
2. Performance: Dashboard loads in <2s. No layout shift during theme toggle. Sidebar toggle is instant (<100ms animation).
3. Reliability: Break-glass auth ensures access when Authentik is down.
4. Observability: Telemetry with opt-out support. Wide-event logging. Customizable telemetry endpoint.
## Acceptance Criteria
### Milestone 0.0.15
1. Design tokens from dashboard.html are implemented in globals.css
2. App shell shows full-width header with logo, collapsible sidebar, main content area
3. Sidebar has all nav groups with icons, collapses to icon-only mode
4. Hamburger button appears at mobile breakpoints, sidebar hidden by default
5. Light/dark theme toggle works across all components
6. Mosaic logo spinner is used as site-wide loading indicator
7. Dashboard page shows metrics strip, orchestrator sessions, quick actions, activity feed, token budget
8. All shared components in packages/ui use design tokens (no hardcoded colors)
9. Lint, typecheck, and existing tests pass
10. Grain overlay texture from reference is applied
### Full Project (All Milestones)
11. jarvis user logs in via Authentik, has admin access to all pages
12. jarvis-user has standard access at lower permission level
13. Break-glass user has access without Authentik
14. Three Mosaic Stack instances on Coolify with federation testing
15. Playwright tests confirm all pages, functions, theming work
16. No errors during site navigation
17. API documented via Swagger with proper auth gating
18. Telemetry working locally with wide-event logging
19. Mosaic Telemetry properly reporting to telemetry endpoint
## Constraints and Dependencies
1. Next.js 16 with App Router — all pages use server/client component patterns
2. Tailwind CSS 3.4 — design tokens must integrate with Tailwind's utility class system
3. BetterAuth for authentication — must maintain existing auth flow
4. Authentik as IdP at auth.diversecanvas.com — must remain operational
5. PostgreSQL 17 with Prisma — all settings stored in DB
6. Coolify for deployment — 3 instances needed for federation testing
7. packages/ui is shared across apps — changes affect all consumers
## Risks and Open Questions
1. **Risk**: Changing globals.css design tokens may break existing pages (login, knowledge, calendar). Mitigation: Thorough regression testing.
2. **Risk**: packages/ui uses hardcoded Tailwind colors — migration to CSS variables needs care. Mitigation: Phase the migration, test each component.
3. **Open**: Exact federation protocol details for master-master vs master-slave data sync.
4. **Open**: Specific telemetry data points to collect.
5. **Open**: Agent task mapping configuration schema (informed by OpenClaw research).
## Testing and Verification
1. Baseline: `pnpm lint && pnpm build` must pass
2. Situational: Visual verification at sm/md/lg/xl breakpoints
3. Situational: Theme toggle across all pages
4. Situational: Sidebar collapse/expand at all breakpoints
5. E2E: Playwright tests for all page navigation
6. E2E: Auth flow with Authentik
7. Federation: Master-master and master-slave data access tests
## Delivery/Milestone Intent
| Milestone | Version | Focus |
| ----------------------- | ------- | ----------------------------------------------------------------- |
| MS15-DashboardShell | 0.0.15 | Design system + app shell + dashboard page |
| MS16-Pages | 0.0.16 | Projects, Workspace, Kanban, Settings, Profile, Files, Logs pages |
| MS17-BackendIntegration | 0.0.17 | API endpoints, real data, Swagger docs |
| MS18-ThemeWidgets | 0.0.18 | Theme package system, widget registry, dashboard customization |
| MS19-ChatTerminal | 0.0.19 | Global terminal, project chat, master chat session |
| MS20-MultiTenant | 0.0.20 | Multi-tenant, teams, RBAC, RLS enforcement, break-glass auth |
| MS21-Federation | 0.0.21 | Federation (M-M, M-S), 3 instances, key exchange, data separation |
| MS22-AgentTelemetry | 0.0.22 | Agent task mapping, telemetry, wide-event logging |
| MS23-Testing | 0.0.23 | Playwright E2E, federation tests, documentation finalization |

63
docs/scratchpads/ms15-dashboard-shell.md Normal file
View File

@@ -0,0 +1,63 @@
# MS15 — Dashboard Shell & Design System
## Objective
Implement the dashboard.html reference design across the Mosaic Stack web app. Establish the design token system, app shell layout, shared components, and dashboard page.
## Design Reference
`/home/jwoltje/src/mosaic-stack-website/docs/designs/round-5/claude/01/dashboard.html`
## Key Architectural Decisions
1. **Theme approach**: CSS custom properties via `:root` + `[data-theme="light"]`. Tailwind configured to use these variables. ThemeProvider updated to set `data-theme` attribute on `<html>`.
2. **Logo placement**: Logo in full-width header (topbar), NOT in sidebar. User spec overrides reference design.
3. **Sidebar collapse**: Collapsible with icon-only mode. Hidden by default at mobile breakpoints. Hamburger button for small screens.
4. **Fonts**: Outfit (body) + Fira Code (mono). Loaded via `next/font/google`.
5. **Loading spinner**: Mosaic logo icon component with CSS rotation animation.
6. **Grain overlay**: Subtle noise texture via CSS pseudo-element, same as reference.
7. **Per-phase branches**: `feat/ms15-design-system`, `feat/ms15-shared-components`, `feat/ms15-dashboard-page`.
## Phases
### Phase 1: Foundation (Design System & App Shell)
- MS15-FE-001: Design token system overhaul
- MS15-FE-002: App shell grid layout
- MS15-FE-003: Sidebar component
- MS15-FE-004: Topbar/Header component
- MS15-FE-005: Responsive breakpoints
- MS15-FE-006: Loading spinner (Mosaic logo)
### Phase 2: Shared Components
- MS15-UI-001: packages/ui token alignment
- MS15-UI-002: Card, Badge, Button, Dot updates
- MS15-UI-003: MetricsStrip, ProgressBar, FilterTabs
- MS15-UI-004: SectionHeader, Table, LogLine
- MS15-UI-005: Terminal panel component
### Phase 3: Dashboard Page
- MS15-DASH-001: Metrics strip
- MS15-DASH-002: Active Orchestrator Sessions
- MS15-DASH-003: Quick Actions
- MS15-DASH-004: Activity Feed
- MS15-DASH-005: Token Budget
### Phase 4: Quality
- MS15-QA-001: Baseline tests
- MS15-QA-002: Situational tests
- MS15-DOC-001: Documentation
## Progress Log
- Session started: 2026-02-22
- Status: Bootstrap phase
## Risks
- Large surface area: globals.css change affects all existing pages
- packages/ui color system mismatch requires careful migration
- Existing pages (login, auth) may need adjustment after token changes

31
docs/tasks.md
View File

@@ -1,5 +1,36 @@
# Tasks
## MS15-DashboardShell (0.0.15) — Dashboard Shell & Design System
**Orchestrator:** Claude Code (Opus 4.6)
**Started:** 2026-02-22
**Branch:** feat/ms15-design-system (Phase 1), feat/ms15-shared-components (Phase 2), feat/ms15-dashboard-page (Phase 3)
**Milestone:** MS15-DashboardShell (0.0.15)
**PRD:** docs/PRD.md
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
| ------------- | ----------- | -------------------------------------------------------------------------------------------- | ----- | ---- | --------------------------- | ----------------------- | ----------------------------------------------- | ----- | ---------- | ------------ | -------- | ---- | ----- |
| MS15-FE-001 | not-started | 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 | | | | 25K | | |
| MS15-FE-002 | not-started | 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 | | | | 20K | | |
| MS15-FE-003 | not-started | Sidebar component (collapsible, nav groups, icons, badges, user card footer) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | | | | 25K | | |
| MS15-FE-004 | not-started | Topbar/Header component (logo, search, status, notifications, theme toggle, avatar dropdown) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | | | | 25K | | |
| MS15-FE-005 | not-started | Responsive layout (breakpoints, hamburger, sidebar auto-hide at mobile) | #448 | web | feat/ms15-design-system | MS15-FE-003,MS15-FE-004 | MS15-QA-001 | | | | 20K | | |
| MS15-FE-006 | not-started | Loading spinner (Mosaic logo icon with rotation animation, site-wide) | #448 | web | feat/ms15-design-system | MS15-FE-001 | | | | | 10K | | |
| MS15-UI-001 | not-started | 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 | | | | 20K | | |
| MS15-UI-002 | not-started | Update Card, Badge, Button, Dot component variants to match reference | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | | | | 25K | | |
| MS15-UI-003 | not-started | Create MetricsStrip, ProgressBar, FilterTabs shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | | | | 20K | | |
| MS15-UI-004 | not-started | Create SectionHeader, Table, LogLine shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-002 | | | | 15K | | |
| MS15-UI-005 | not-started | Create Terminal panel component (bottom drawer, tabs, output) | #449 | web | feat/ms15-shared-components | MS15-UI-001 | | | | | 20K | | |
| MS15-DASH-001 | not-started | Dashboard metrics strip (6 cells, colored borders, values, trends) | #450 | web | feat/ms15-dashboard-page | MS15-UI-002,MS15-UI-003 | | | | | 15K | | |
| MS15-DASH-002 | not-started | Active Orchestrator Sessions card with agent nodes | #450 | web | feat/ms15-dashboard-page | MS15-UI-004 | | | | | 20K | | |
| MS15-DASH-003 | not-started | Quick Actions 2x2 grid | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | | | | 10K | | |
| MS15-DASH-004 | not-started | Activity Feed sidebar card | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | | | | 15K | | |
| MS15-DASH-005 | not-started | Token Budget sidebar card with progress bars | #450 | web | feat/ms15-dashboard-page | MS15-UI-003 | | | | | 10K | | |
| MS15-QA-001 | not-started | Baseline tests (lint, typecheck, build) and situational tests (responsive, themes) | #448 | web | feat/ms15-design-system | MS15-FE-005 | | | | | 15K | | |
| MS15-DOC-001 | not-started | Documentation: design system reference, component docs | #448 | docs | feat/ms15-design-system | MS15-QA-001 | | | | | 10K | | |
---
## M10-Telemetry (0.0.10) — Telemetry Integration
**Orchestrator:** Claude Code