oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b20b138fe485817e8d69d0c60e376e3c53af149a
waggle-os/docs/briefs/2026-05-01-cc-sesija-D-apps-web-ui-alignment.md
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details
moving
2026-09-02 10:10:29 +02:00

14 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink