224 lines
14 KiB
Markdown
224 lines
14 KiB
Markdown
# CC Sesija D — Waggle apps/web UI Alignment sa Claude Design Prototype
|
||
|
||
**Datum:** 2026-05-01
|
||
**Autor:** PM
|
||
**Status:** AUTHORED — awaiting Marko ratifikacija → CC kickoff
|
||
**Authority:** Track A iz `decisions/2026-04-30-pre-launch-sprint-consolidation-LOCKED.md` + Pass 1 review `strategy/ui-ux/2026-04-30-track-a-uiux-review-pass-1.md` + Claude Design overnight completes `project_overnight_2026_04_30_claude_design_completes.md`
|
||
**Branch policy:** Kreirati `feature/sesija-D-ui-alignment` iz main HEAD-a (NE iz feature/sesija-A — taj branch je za Tauri/backend integration, paralelan stream)
|
||
**Cost cap:** $40 hard / $30 halt / $10-20 expected — UI iteracije sa screenshot verifications mogu biti tokens-heavy
|
||
|
||
---
|
||
|
||
## §0 — Pre-flight gates (BLOCKING — CC mora da prođe pre §1 kickoff)
|
||
|
||
### Gate G0.1 — Branch state verifikacija
|
||
|
||
CC izvršava i prijavljuje:
|
||
- `git fetch origin && git status` — clean working tree
|
||
- `git log --oneline -5 origin/main` — verify HEAD je production-ready
|
||
- `git checkout -b feature/sesija-D-ui-alignment origin/main` — create branch
|
||
- `npm install --workspace=apps/web` — verify dependencies clean
|
||
|
||
**PASS uslovi:** clean checkout, npm install zero errors, dev server može da krene (`npm run dev --workspace=apps/web` opens at localhost:5173 ili sl.)
|
||
**FAIL handling:** halt + PM ratifikacija pre nastavka
|
||
|
||
### Gate G0.2 — Test baseline establish
|
||
|
||
CC izvršava i prijavljuje:
|
||
- `npm test --workspace=apps/web` — full vitest run
|
||
- `npm run lint --workspace=apps/web` — ESLint clean
|
||
- `npm run typecheck --workspace=apps/web` — TypeScript clean
|
||
|
||
Capture full test count (X passed / Y skipped / Z failed). To je baseline — svaki commit u Sesija D mora održavati ili poboljšati taj broj. Zero new failures.
|
||
|
||
### Gate G0.3 — Visual reference acquisition
|
||
|
||
CC pristupa Claude Design "waggle app" project (URL: `https://claude.ai/design/p/019dd700-75a0-7127-872a-3ce5e162d11f?file=Waggle+Workspace+OS.html`) za pixel-level reference. Ako CC nema browser access, alternativa je da PM autoring pripremi screenshot folder u `D:\Projects\PM-Waggle-OS\strategy\ui-ux\reference-screenshots\` sa po-state screenshots (Tweaks closed/open, dark/light theme, simple/professional/power tier) — koje CC koristi kao spec.
|
||
|
||
**PASS uslovi:** CC dobio access do reference (browser ili screenshot folder).
|
||
**FAIL handling:** PM dostavlja screenshot bundle za 30 min, kickoff resume.
|
||
|
||
---
|
||
|
||
## §1 — Scope declaration
|
||
|
||
### Šta ulazi u Sesija D
|
||
|
||
Strukturni UI alignment apps/web/src/components/os/ existing React/TypeScript codebase sa Claude Design visual spec-om iz overnight Pass 1 fix iteracije + Waggle Landing.html visual tokens. Sedam Pass 1 fix-eva already done in Claude Design moraju biti reflected u waggle-os apps/web/ React komponentama.
|
||
|
||
Konkretno: Desktop.tsx + Dock.tsx + StatusBar.tsx + AppWindow.tsx + ContextRail (overlays/) + MemoryApp.tsx (filter pills) + Settings/Tweaks UI + Welcome callout system. Plus dark theme color tokens, typography (Inter + JetBrains Mono), spacing tokens.
|
||
|
||
### Šta NE ulazi u Sesija D
|
||
|
||
- Backend code (services/, hive-mind packages, MCP servers) — touched 0 lines
|
||
- Business logic unutar apps (npr. MemoryApp logic, ChatApp message flow, AgentsApp agent execution) — UI/UX prezentacioni sloj only
|
||
- 25 apps individual feature work — only shell + Memory + Chat + Cockpit polish u Sesija D
|
||
- Tauri/.msi packaging — to je Sesija A scope, ne diramo
|
||
- Landing site (apps/www ako postoji) — separate stream
|
||
- Test infrastructure changes — postojeći vitest + playwright ostaje
|
||
- New dependencies — koristimo postojeće (shadcn/ui + Tailwind + react-query + react-router)
|
||
|
||
---
|
||
|
||
## §2 — Mapping table (Claude Design → waggle-os apps/web)
|
||
|
||
| Claude Design component / state | waggle-os target file | Akcija | Priority |
|
||
|---|---|---|---|
|
||
| Dock global position (fixed, bottom 14px, viewport-centered) | `apps/web/src/components/os/Dock.tsx` | Refactor outer wrapper iz `left:0; right:0; flex-center` u `position: fixed; bottom: 14px; left: 50%; transform: translateX(-50%)` na dock pill itself; verify ne pomera kad Tweaks panel toggle | P0 |
|
||
| Top menu bar (Waggle/File/Edit/View/Window/Help) sa View shortcuts ⌘1 Cockpit / ⌘2 Memory / ⌘3 Chat | `apps/web/src/components/os/StatusBar.tsx` (ili novi `MenuBar.tsx`) | Add macOS-style menu bar component sa keyboard shortcuts; bind shortcuts u global handler | P0 |
|
||
| Workspace selector "Q1 Strategy Review" (replaceable) | `apps/web/src/components/os/WorkspaceBriefing.tsx` ili StatusBar | Update default placeholder text + interaction popover | P1 |
|
||
| Model selector dropdown "qwen3.6-35b-thinking" sa interactive popover | `apps/web/src/components/os/ModelSelector.tsx` | Update default model + ensure popover trigger working + Phase 5 LOCKED scope only (Claude Opus + qwen-thinking, ne GPT/Llama/Gemini) | P0 |
|
||
| Memory app filter pills "all/decision/fact/insight/task/event" | `apps/web/src/components/os/apps/MemoryApp.tsx` | Add "event" pill to filter pills component | P1 |
|
||
| Welcome callout cards (Back/Next + "Don't show again", 3-card swipeable format) | New component `apps/web/src/components/os/WelcomeCards.tsx` | Implement card-based onboarding flow, replace any existing single-callout | P1 |
|
||
| Tweaks panel — Dock position dropdown sa default "Bottom" | `apps/web/src/components/os/apps/SettingsApp.tsx` ili novi `TweaksPanel.tsx` | Implement dropdown sa working state mgmt (bottom/top/left/right) | P2 |
|
||
| Tweaks panel — Billing Tier dropdown sa default "Pro" | Same Tweaks panel | Implement dropdown bound na user tier system | P2 |
|
||
| Z-order focus dim (0.7 opacity overlay za unfocused windows) | `apps/web/src/components/os/AppWindow.tsx` | Add focus state + dim CSS na non-focused windows | P1 |
|
||
| Cockpit window default state ("3 agents · 1 running · 1 queued") | `apps/web/src/components/os/apps/CockpitApp.tsx` | Update default mock state za prototype-friendly demo | P2 |
|
||
| Chat window persona ("Researcher · Deep investigation, multi-source synthesis") | `apps/web/src/components/os/apps/ChatApp.tsx` ili ChatWindowInstance | Update default persona display + add persona switcher hook | P2 |
|
||
| Color tokens — dark navy #0A0E1A bg, warm beige #F5E6D3 text, orange #ED915C primary CTA | `apps/web/tailwind.config.js` ili `apps/web/src/index.css` | Update theme tokens to match Claude Design palette | P0 |
|
||
| Typography — Inter (body) + JetBrains Mono (tags/numerals) | Same tailwind config + globals.css | Add font-family tokens, ensure web fonts loaded | P1 |
|
||
|
||
### Mapping discovery uslovi
|
||
|
||
CC mora prvo da read postojeće Dock.tsx, StatusBar.tsx, AppWindow.tsx files i prijavi PM-u **diff-aware mapping** — šta već postoji u kodu, šta treba dodati, šta menjati. Ne implement before reporting current state. PM ratifikuje mapping pre §3 implementation kickoff.
|
||
|
||
---
|
||
|
||
## §3 — Implementation phases
|
||
|
||
### §3.1 — Phase 1: Color + Typography tokens (P0, 1 dan)
|
||
|
||
Update tailwind config + globals.css sa Claude Design palette. Verify svi postojeći komponenti i dalje render-uju (visual regression check kroz Playwright snapshot tests). Zero functional change — samo theme refresh.
|
||
|
||
**Deliverable:** PR commit "feat(theme): align tokens sa Claude Design — dark navy + warm beige + orange CTA". Screenshot diff (before/after) attached.
|
||
|
||
### §3.2 — Phase 2: Dock + StatusBar + MenuBar P0 (1-2 dana)
|
||
|
||
Three P0 fixes:
|
||
1. Dock global position refactor (postojeći Dock.tsx) — exact CSS spec primenjen
|
||
2. Top MenuBar implementacija sa keyboard shortcuts ⌘1/⌘2/⌘3 (i ⌘P workspace switcher, ⌘K spotlight)
|
||
3. ModelSelector update sa Phase 5 LOCKED scope + interactive popover
|
||
|
||
**Deliverable:** PR commit per fix sa Playwright screenshot test koji verifikuje state. Test suite green.
|
||
|
||
### §3.3 — Phase 3: Memory app filter pills + Welcome cards (P1, 1 dan)
|
||
|
||
Add "event" pill u MemoryApp filter component. Implement WelcomeCards component sa Back/Next + "Don't show again" + first-launch detection.
|
||
|
||
**Deliverable:** PR commits + visual regression tests + e2e test za welcome flow first-launch.
|
||
|
||
### §3.4 — Phase 4: Z-order focus dim + AppWindow polish (P1, 1 dan)
|
||
|
||
AppWindow component dobija focus state, unfocused windows dim na 0.7 opacity. Window switching kroz ⌘` (cmd+backtick) implementiran.
|
||
|
||
**Deliverable:** PR commit sa interactive demo screenshots multi-window state pre/posle focus change.
|
||
|
||
### §3.5 — Phase 5: Tweaks panel dropdowns (P2, 1-2 dana)
|
||
|
||
SettingsApp ili novi TweaksPanel komponenta dobija dva working dropdowns: Dock position (bottom/top/left/right) + Billing Tier (free/trial/pro/teams/enterprise). Real state management, ne dead UI. Billing Tier toggling menja Approvals chip visibility u dock + Team Governance access.
|
||
|
||
**Deliverable:** PR commit sa interactive demo, full test coverage.
|
||
|
||
### §3.6 — Phase 6: Cockpit + Chat default states (P2, 0.5 dana)
|
||
|
||
CockpitApp dobija prototype-friendly default mock state. ChatApp dobija default persona display + persona switcher. Niska kompleksnost, kosmetičko poboljšanje za demo screenshots.
|
||
|
||
**Deliverable:** PR commit sa screenshot updates.
|
||
|
||
---
|
||
|
||
## §4 — Visual reference assets (PM dostavlja)
|
||
|
||
PM autoring sa overnight Computer Use:
|
||
- `D:\Projects\PM-Waggle-OS\strategy\ui-ux\reference-screenshots\` folder sa pre-named PNG-ovima:
|
||
- `dock-fixed-tweaks-closed.png` (Claude Design verified output)
|
||
- `dock-fixed-tweaks-open.png` (Claude Design verified output)
|
||
- `welcome-callout-cards.png`
|
||
- `tweaks-panel-dropdowns.png`
|
||
- `view-menu-shortcuts.png`
|
||
- `memory-filter-pills-event.png`
|
||
- `model-selector-popover.png`
|
||
- `multi-window-focus-dim.png`
|
||
- `landing-hero.png` (color reference)
|
||
|
||
Plus reference fajlovi:
|
||
- `landing-v3.1-refreshed-overnight.md` — color tokens + typography spec source-of-truth
|
||
- `track-a-uiux-review-pass-1.md` — original Pass 1 diagnostic
|
||
- `project_overnight_2026_04_30_claude_design_completes.md` — accepted fix decisions
|
||
|
||
CC fetch-uje ove fajlove kao input pre §3.1 phase kickoff.
|
||
|
||
---
|
||
|
||
## §5 — Acceptance criteria
|
||
|
||
CC Sesija D je COMPLETE kad svih 6 phases zatvoren PR-ovima na `feature/sesija-D-ui-alignment` branch sa:
|
||
|
||
1. **Test posture:** vitest + playwright + tsc + ESLint zero new failures vs G0.2 baseline
|
||
2. **Visual diff:** Screenshot diff before/after za svaki phase, embedded u PR description
|
||
3. **Pixel match:** Dock pill x-position centered na viewport midpoint kad Tweaks closed AND open (per overnight spec)
|
||
4. **Functional:** ⌘1/⌘2/⌘3/⌘`/⌘K/⌘P shortcuts sve work, popovers open na click, dropdowns store state
|
||
5. **Branch state:** sve commits pushed na origin, branch ready za review (NE merge — Marko ratifikuje pre merge u main)
|
||
6. **Documentation:** Update apps/web/README.md (ako postoji) sa novim color tokens + shortcut list
|
||
|
||
PM Pass 2 review (ja kroz Computer Use ili manual screenshots verification) na branch HEAD-u pre merge u main.
|
||
|
||
---
|
||
|
||
## §6 — Cost projection (real-anchored)
|
||
|
||
Baseline procena per phase:
|
||
- Phase 1 (tokens): ~5K LLM tokens — color tokens su deterministic, mali file diff
|
||
- Phase 2 (dock+menubar+modelselector): ~30K — Dock.tsx ~200-400 LOC menjati, MenuBar od nule ~150-300 LOC, ModelSelector ~50-100 LOC
|
||
- Phase 3 (filter pills + welcome): ~15K
|
||
- Phase 4 (focus dim): ~10K
|
||
- Phase 5 (tweaks dropdowns): ~25K — dva interactive dropdowns sa state mgmt + tests
|
||
- Phase 6 (cockpit+chat): ~10K
|
||
|
||
**Total estimate:** ~95K tokens × Sonnet 4.6 cost = ~$15-20 per single pass. Cap $40 hard / $30 halt allows for 1-2 retry passes ako bilo koji phase fail QA.
|
||
|
||
**Halt triggers:**
|
||
- Cumulative spend > $30 → halt + PM review
|
||
- Any phase requires > 5 retry iteracija → halt + PM diagnostic
|
||
- Test suite breaks i ne može vratiti zelenom unutar 1h → halt + PM rollback decision
|
||
- TypeScript errors koji nisu auto-fixable unutar 30 min → halt + PM scope decision
|
||
|
||
---
|
||
|
||
## §7 — Out of scope (eksplicitno isključeno)
|
||
|
||
- Backend integration (services/, hive-mind packages)
|
||
- New apps (sve od 25 postojećih ostaju, samo shell + 3 core polished)
|
||
- BootScreen redesign — Day 1 polish, ne pre-launch
|
||
- Animation polish (motion design) — Day 1 polish, ne pre-launch
|
||
- Accessibility audit (WCAG full pass) — separate stream Sesija E ako prioritet
|
||
- i18n / lokalizacija — Day 1 polish
|
||
- Performance optimization (bundle size, code splitting) — Day 1 polish
|
||
- Tauri-specific behavior (resize, traffic lights, system tray) — Sesija A scope
|
||
|
||
---
|
||
|
||
## §8 — Audit trail anchors
|
||
|
||
- Pre-launch sprint consolidation: `decisions/2026-04-30-pre-launch-sprint-consolidation-LOCKED.md` Track A
|
||
- Pass 1 review (input): `strategy/ui-ux/2026-04-30-track-a-uiux-review-pass-1.md`
|
||
- Overnight Claude Design completes (fix evidence): `project_overnight_2026_04_30_claude_design_completes.md`
|
||
- Landing v3.1 (color/typography source): `strategy/landing/2026-04-30-landing-v3.1-refreshed-overnight.md`
|
||
- Memory systems coexistence (cross-stream context): `feedback_memory_systems_coexistence.md`
|
||
- This brief: `briefs/2026-05-01-cc-sesija-D-apps-web-ui-alignment.md`
|
||
|
||
---
|
||
|
||
## §9 — Marko ratifikacija decisions (4 odluke)
|
||
|
||
Pre nego što CC krene, treba 4 ratifikacije:
|
||
|
||
1. **Branch baseline** — `origin/main` HEAD ili `feature/sesija-A` ako Marko želi da Sesija D radi povrh A za smoother merge?
|
||
2. **Visual reference dostava** — PM pravi screenshot bundle (1h Computer Use) ili CC samostalno fetch-uje Claude Design URL (rizik: Claude Design account cookie)?
|
||
3. **Cost cap** — $40 hard cap OK ili menjamo? Probe-validated $35-45 reality nije relevantna ovde (drugi tip rada od Phase 5 production deployment), $40 ima headroom za 1-2 retry passes.
|
||
4. **Branch merge policy** — CC otvara PR ka main i čeka Marko ratifikaciju, ili ja PM mergujem posle Pass 2 review u njegovo ime?
|
||
|
||
---
|
||
|
||
**End of brief. Awaiting Marko ratifikacija na 4 odluke iz §9 → CC kickoff.**
|