tas/Codewalkers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b11cae998c883d689260721452f12ecb5b9b2fcb
Codewalkers/docs/frontend.md
Lukas May 04c212da92 feat: Implement v2 design system with indigo brand, dark mode, and status tokens 
Complete frontend design overhaul replacing achromatic shadcn/ui defaults with
an indigo-branded (#6366F1), status-aware, dark-mode-enabled token system.

Phase 1 — Theme Foundation:
- Replace all CSS tokens in index.css with v2 light/dark mode values
- Add 24 status tokens (6 statuses × 4 variants), 22 terminal tokens,
  7 diff tokens, 5 shadow tokens, 9 transition/animation tokens,
  10 z-index tokens, 10-step extended indigo scale
- Install Geist Sans/Mono variable fonts (public/fonts/)
- Extend tailwind.config.ts with all new token utilities
- Add dark mode flash-prevention script in index.html
- Add status-pulse and shimmer keyframe animations
- Add global focus-visible styles and reduced-motion media query

Phase 2 — ThemeProvider + Toggle:
- ThemeProvider context with system preference listener
- 3-state ThemeToggle (Sun/Monitor/Moon)
- Radix tooltip primitive for tooltips
- localStorage persistence with 'cw-theme' key

Phase 3 — Shared Components + Token Migration:
- StatusDot: mapEntityStatus() maps raw statuses to 6 semantic variants
- StatusBadge: uses status token bg/fg/border classes
- Badge: 6 new status variants + xs size
- EmptyState, ErrorState, SaveIndicator shared patterns
- CommandPalette: Cmd+K search with fuzzy matching, keyboard nav
- Skeleton with shimmer animation + SkeletonCard composite layouts
- KeyboardShortcutHint, NavBadge, enhanced Sonner config
- Migrate ALL hardcoded Tailwind colors to token classes across
  AgentOutputViewer, review/*, ProgressBar, AccountCard,
  InitiativeHeader, DependencyIndicator, PipelineTaskCard,
  PreviewPanel, ChangeSetBanner, MessageCard, PhaseDetailPanel

Phase 4 — App Layout Overhaul:
- Single 48px row header with CW logo, nav with NavBadge counts,
  Cmd+K search button, ThemeToggle, HealthDot
- Remove max-w-7xl from header/main; pages control own widths
- ConnectionBanner for offline/reconnecting states
- BrowserTitleUpdater with running/questions counts
- useGlobalKeyboard (1-4 nav, Cmd+K), useConnectionStatus hooks
- Per-page width wrappers (initiatives max-w-6xl, settings max-w-4xl)

Phase 5 — Page-Level Token Migration:
- ReviewSidebar: all hardcoded green/orange/red → status/diff tokens
- CommentThread: resolved state → status-success tokens
- Settings health: green → status-success-dot
2026-03-03 11:43:09 +01:00

176 lines
7.4 KiB
Markdown
Raw Blame History

# Frontend
`apps/web/` — React web UI for managing initiatives, agents, and content.
## Tech Stack
| Technology | Purpose |
|-----------|---------|
| React 19 | UI framework |
| TanStack Router | File-based routing |
| tRPC React Query | Type-safe API client with caching |
| Tailwind CSS | Utility-first styling |
| shadcn/ui | Component library (button, card, dialog, dropdown, input, label, textarea, badge, sonner, tooltip) |
| Tiptap | Rich text editor (ProseMirror-based) |
| Lucide | Icon library |
| Geist Sans/Mono | Typography (variable fonts in `public/fonts/`) |
## Design System (v2)
Theme spec: `docs/wireframes/v2/theme.md`
- **Brand**: Indigo (#6366F1) — `--primary` is indigo, not black
- **Dark mode**: 3-state toggle (light/system/dark), persisted in `localStorage('cw-theme')`
- **Status tokens**: 6 semantic statuses (active/success/warning/error/neutral/urgent) with bg/fg/border/dot variants. Use `bg-status-{status}-bg`, `text-status-{status}-fg`, etc.
- **Terminal tokens**: Always-dark surface for agent output. Use `bg-terminal`, `text-terminal-fg`, etc.
- **Diff tokens**: `bg-diff-add-bg`, `text-diff-remove-fg`, etc.
- **Shadows**: 5-level system (xs-xl). Dark mode uses inset highlights + ambient glow.
- **Transitions**: `duration-fast`, `duration-normal`, `ease-default`, `ease-spring`
- **Z-index**: Named scale from `z-base` to `z-tooltip`
- **Radius**: 6px base (down from 8px)
- **Flash prevention**: Inline `<script>` in `index.html` reads theme before paint
### Status-to-Entity Mapping
Use `mapEntityStatus(rawStatus)` from `StatusDot.tsx` to convert raw entity statuses to semantic tokens. `StatusDot` and `StatusBadge` both use this automatically.
## Path Alias
`@/*` maps to `./src/*` (configured in `tsconfig.app.json`).
## Routes
| Route | Component | Purpose |
|-------|-----------|---------|
| `/` | `routes/index.tsx` | Dashboard / initiative list |
| `/initiatives/$id` | `routes/initiatives/$initiativeId.tsx` | Initiative detail (tabbed) |
| `/settings` | `routes/settings/index.tsx` | Settings page |
## Initiative Detail Tabs
The initiative detail page has three tabs managed via local state (not URL params):
1. **Content Tab** — Page tree + Tiptap editor, proposal review
2. **Execution Tab** — Pipeline visualization, phase management, task dispatch
3. **Review Tab** — Pending proposals from agents
## Component Inventory (73 components)
### Core Components (`src/components/`)
| Component | Purpose |
|-----------|---------|
| `InitiativeHeader` | Initiative name, project badges, inline-editable execution mode & branch |
| `InitiativeContent` | Content tab with page tree + editor |
| `StatusDot` | Small colored dot using status tokens, with pulse animation |
| `StatusBadge` | Colored badge using status tokens |
| `TaskRow` | Task list item with status, priority, category |
| `QuestionForm` | Agent question form with options |
| `InboxDetailPanel` | Agent message detail + response form |
| `ProjectPicker` | Checkbox list for project selection |
| `RegisterProjectDialog` | Dialog to register new git project |
| `Skeleton` | Loading placeholder with shimmer animation |
| `SkeletonCard` | Composite skeleton layouts (agent-card, initiative-card, etc.) |
| `EmptyState` | Shared empty state with icon, title, description, action |
| `ErrorState` | Shared error state with retry |
| `SaveIndicator` | Saving/saved/error status indicator |
| `CommandPalette` | Cmd+K search palette (initiatives, agents, navigation) |
| `ThemeToggle` | 3-state theme toggle (Sun/Monitor/Moon) |
| `NavBadge` | Numeric badge for nav items |
| `KeyboardShortcutHint` | Formatted keyboard shortcut display |
| `ConnectionBanner` | Offline/reconnecting state banner |
| `HealthDot` | Server health indicator with tooltip |
| `BrowserTitleUpdater` | Dynamic document.title with agent counts |
### Editor Components (`src/components/editor/`)
| Component | Purpose |
|-----------|---------|
| `TiptapEditor` | Core rich text editor wrapper |
| `PageEditor` | Page content editor with auto-save |
| `PhaseContentEditor` | Phase content editor |
| `ContentProposalReview` | Accept/dismiss proposals from agents |
| `SlashCommandMenu` | Slash command popup in editor |
### Execution Components (`src/components/execution/`)
| Component | Purpose |
|-----------|---------|
| `ExecutionTab` | Main execution view container |
| `ExecutionContext` | React context for execution state |
| `PhaseDetailPanel` | Phase detail with tasks, dependencies, plan |
| `PhaseSidebar` | Phase list sidebar |
| `TaskDetailPanel` | Task detail with agent status, output |
### Pipeline Components (`src/components/pipeline/`)
| Component | Purpose |
|-----------|---------|
| `PipelineVisualization` | DAG visualization of phase pipeline |
| `PipelineNode` | Individual phase node in pipeline |
| `PipelineEdge` | Dependency edge between nodes |
### Review Components (`src/components/review/`)
| Component | Purpose |
|-----------|---------|
| `ReviewTab` | Review tab container with diff viewer and preview integration |
| `ReviewSidebar` | Review info, actions, file list, comment summary |
| `DiffViewer` | Unified diff renderer with inline comments |
| `PreviewPanel` | Docker preview status: building/running/failed with start/stop |
| `ProposalCard` | Individual proposal display |
### UI Primitives (`src/components/ui/`)
shadcn/ui components: badge (6 status variants + xs size), button, card, dialog, dropdown-menu, input, label, select, sonner, textarea, tooltip.
## Custom Hooks (`src/hooks/`)
| Hook | Purpose |
|------|---------|
| `useRefineAgent` | Manages refine agent lifecycle for initiative |
| `useDetailAgent` | Manages detail agent for phase planning |
| `useAgentOutput` | Subscribes to live agent output stream |
| `useConnectionStatus` | Tracks online/offline/reconnecting state |
| `useGlobalKeyboard` | Global keyboard shortcuts (1-4 nav, Cmd+K) |
## Theme (`src/lib/theme.tsx`)
`ThemeProvider` wraps the app root. `useTheme()` returns `{ theme, setTheme, isDark }`. The provider listens for OS `prefers-color-scheme` changes when in `system` mode.
## tRPC Client
Configured in `src/lib/trpc.ts`. Uses `@trpc/react-query` with TanStack Query for caching and optimistic updates.
## Key User Flows
### Creating an Initiative
1. Dashboard → "New Initiative" → enter name, select projects
2. `createInitiative` mutation → auto-creates root page
3. Navigate to initiative detail
### Managing Content (Pages)
1. Content tab → page tree sidebar
2. Click page → Tiptap editor loads content
3. Edit → auto-saves via `updatePage` mutation
4. Use slash commands for formatting
### Refining Content with AI
1. Content tab → "Refine" button
2. `spawnArchitectRefine` mutation → agent analyzes pages
3. Agent creates proposals (page edits, new phases, tasks)
4. Proposals appear in review section → accept/dismiss each
### Pipeline Visualization
1. Execution tab → pipeline DAG shows phases as nodes
2. Drag to add dependencies between phases
3. Approve phases → queue for dispatch
4. Tasks auto-queued when phase starts
### Detailing Phases
1. Select phase → "Detail" button
2. `spawnArchitectDetail` mutation → agent creates task proposals
3. Accept proposals → tasks created under phase
4. View tasks in phase detail panel
## Shared Package
`packages/shared/` exports:
- `sortByPriorityAndQueueTime()` — priority-based task sorting
- `topologicalSort()` / `groupByPipelineColumn()` — phase DAG layout
- Shared type re-exports from `packages/shared/src/types.ts` (which re-exports from `apps/server/`)
Reference in New Issue View Git Blame Copy Permalink