go-htmx-gsd #1

Merged
arthur merged 558 commits from go-htmx-gsd into main 2026-05-23 15:16:44 +00:00
7 changed files with 454 additions and 188 deletions
Showing only changes of commit c2d191bd4b - Show all commits

View file

@ -1,5 +1,32 @@
# Project Milestones: Xtablo
## v3.0 Design System & Visual Polish (Shipped: 2026-05-17)
**Delivered:** Full design system ported from go-backend and applied to every product surface — auth pages, app shell, tablo list, tablo detail, chat, and planning.
**Phases completed:** 13-17 (5 phases, 16 plans)
**Key accomplishments:**
- Built a complete CSS token vocabulary and typed templ component library (11 types: button, badge, card, modal, empty-state, table, icon-button, input, textarea, select, form-field) with a build-tag-gated `/ui-catalog` visual verification page.
- Restyled auth pages (login/signup) with gradient animated background, centered auth-card, brand logo, and Google Material Design sign-in button with Roboto font.
- Implemented app shell: sidebar with brand section, icon nav items, tablo list section, and user footer; tablo list with project-card grid, color avatars, and action controls.
- Restyled tablo detail: project-card-top header, tasks-section kanban, etapes section, and files table using `@ui.Table` with `@ui.EmptyState` fallback.
- Added own-vs-others chat bubbles with brand-tint right-alignment and planning day-separator event list using overview-section layout.
**Stats:**
- 150 files changed, +23,505 / 993 lines across v3.0 git range
- 5 phases, 16 plans
- 2 days (2026-05-16 → 2026-05-17)
- Go backend: ~18,600 non-test LOC + ~3,400 templ LOC
**Git range:** `3b9bd62``fa48d81`
**Known deferred items at close:** 6 acknowledged open artifact items (all pre-existing from v1.0/v2.0). See `.planning/STATE.md` Deferred Items.
---
Entries are listed newest first.
## v2.0 Collaboration, Planning, and Social Sign-in (Shipped: 2026-05-16)

View file

@ -2,7 +2,7 @@
## What This Is
A Go + HTMX version of Xtablo centered on tablos as collaborative workspaces. v1 established the authenticated Tablos workflow with tasks, files, worker, and deploy scaffolding; v2 added collaboration, messaging, etapes, events, planning, and Google sign-in; v3 replaces the minimal backend UI with a full design system that makes the product look like the existing JS app.
A Go + HTMX version of Xtablo centered on tablos as collaborative workspaces. v1 established the authenticated Tablos workflow (tasks, files, worker, deploy); v2 added collaboration, messaging, etapes, events, planning, and Google sign-in; v3 ported the full design system from the reference JS app — CSS token vocabulary, typed templ component library, and a visual reskin of every surface.
Built for a developer who wants a simpler, durable product stack: one Go server, Postgres, server-rendered UI, and no managed chat provider.
@ -12,16 +12,9 @@ Built for a developer who wants a simpler, durable product stack: one Go server,
If everything else fails, this must work end-to-end on a single Go binary backed by Postgres and an S3-compatible bucket.
## Current Milestone: v3.0 Design System & Visual Polish
## Shipped: v3.0 Design System & Visual Polish (2026-05-17)
**Goal:** Replace the minimal backend UI layer with a full design system ported from `go-backend/internal/web/ui`, then apply it to every surface using the JS app as the visual reference.
**Target features:**
- Design system foundation: port CSS tokens and component library (button, input, card, badge, modal, select, textarea, table, empty-state) into `backend/internal/web/ui`
- Auth pages (login/signup) restyled to match the JS product visual
- Dashboard & Tablos (sidebar, tablo list, project cards) restyled
- Tablo detail (tasks/kanban, etapes, files) restyled
- Chat & Planning pages restyled
**Delivered:** Full CSS token vocabulary and typed templ component library (11 types) applied to every surface — auth pages, app shell sidebar, tablo list, tablo detail, chat, and planning. Build-tag-gated `/ui-catalog` visual verification page included.
## Requirements
@ -39,16 +32,20 @@ If everything else fails, this must work end-to-end on a single Go binary backed
- ✓ Tablo events with CRUD — Phase 10 (v2.0)
- ✓ Individual planning view (`/planning`) — Phase 11 (v2.0)
- ✓ Native per-tablo chat with real-time SSE — Phase 12 (v2.0)
- ✓ CSS design token vocabulary + typed templ component library (11 types) in `backend/internal/web/ui` — Phase 13 (v3.0)
- ✓ Auth pages (login/signup) match JS app visual — Phase 14 (v3.0)
- ✓ App shell sidebar + project-card tablo grid — Phase 15 (v3.0)
- ✓ Tablo detail (tasks, etapes, files) restyled with design system components — Phase 16 (v3.0)
- ✓ Chat and planning views visually consistent with app shell — Phase 17 (v3.0)
### Active
<!-- v3.0 hypotheses. See REQUIREMENTS.md for the canonical list with REQ-IDs. -->
<!-- v4.0 candidates — to be refined in /gsd-new-milestone -->
- [ ] A full design system (tokens + component library) lives in `backend/internal/web/ui` and can be used by all templates
- [ ] Auth pages look visually equivalent to the JS app (login/signup)
- [ ] Dashboard and tablo list match the sidebar + project-card layout from the JS app
- [ ] Tablo detail (tasks, etapes, files) matches the JS app's visual treatment
- [x] Chat and planning views have consistent, polished styling — Phase 17
- [ ] Responsive layout: sidebar collapses on small screens, kanban board scrolls horizontally on mobile
- [ ] Dark mode: CSS tokens gain `prefers-color-scheme` counterparts or a class-toggle variant
- [ ] Status field on tablos (e.g., active/archived) with UI indicator on project cards
- [ ] Task completion percentage on tablo detail header (progress bar wiring)
### Out of Scope
@ -69,10 +66,10 @@ If everything else fails, this must work end-to-end on a single Go binary backed
- The JS monorepo (this repository) is the source of truth for product behavior and is fully mapped in `.planning/codebase/` (ARCHITECTURE, STACK, STRUCTURE, INTEGRATIONS, CONVENTIONS, CONCERNS, TESTING). Use these to derive expected behavior — but the rewrite is free to simplify both schema and visuals.
- The DB schema **will change** during the rewrite — the JS version's Supabase schema is a reference, not a constraint. The user wants to be in the loop on schema decisions for each domain (users/sessions, tablos, tasks, files).
- Visuals will also change — no requirement to mirror the existing UI; Tailwind + HTMX patterns drive the new look.
- `go-backend/` already contains real scaffolding (router, sqlc, air, tailwind input). It is *not* the foundation — a fresh `backend/` package will be created.
- v3.0 shipped the full design system and visual reskin. `backend/internal/web/ui` now has: CSS token vocabulary, 11 typed templ components, an app shell, and surface-specific CSS (auth, dashboard, tablo detail, chat, planning).
- Current backend source footprint: ~18,600 non-test Go LOC + ~3,400 templ LOC.
- Developer is comfortable in Go and wants a low-dependency, server-rendered stack going forward.
- v2 shipped functional and plain UI for collaboration and planning. v3 is the visual pass that ports the richer design system and applies it across product surfaces.
- Known stubs shipped in v3.0: tablo status field hardcoded as "En cours", progress bar hardcoded at 0% — both require a DB schema extension to wire properly.
## Constraints
@ -101,6 +98,10 @@ If everything else fails, this must work end-to-end on a single Go binary backed
| Google/Apple are identity providers only | Preserve server-owned users/sessions while allowing social sign-in | ✓ Google validated; Apple disabled for now |
| Etapes are one-level wrappers around tasks | Matches the requested mental model and avoids recursive planning complexity | ✓ Validated |
| Planning is individual, events remain tablo-scoped | Lets users see their schedule while preserving tablos as the source of work context | ✓ Validated |
| Design system lives in `backend/internal/web/ui` (not go-backend) | Keep all production code in `backend/`; go-backend is scratch/reference only | ✓ Validated — all 11 components + token CSS in backend/ |
| Build-tag-gated `/ui-catalog` route for design system verification | Catalog must not ship in production; build tags are the idiomatic Go mechanism | ✓ Validated — production build passes, catalog isolated |
| Tablo status + progress bar shipped as visual stubs | DB schema extension needed; unblocking is lower value than shipping the visual design | ⚠️ Revisit — stub needs wiring in v4.0 |
| Air config extended to watch .css files and run Tailwind CLI on rebuild | CSS edits require Tailwind rebuild; air restarts on template changes but not CSS without this | ✓ Validated |
## Evolution
@ -127,4 +128,5 @@ This document evolves at phase transitions and milestone boundaries.
- **Milestone v2.0 shipped: Collaboration, planning, and social sign-in** — Shipped 2026-05-16. Delivered Google sign-in, etapes, events, individual planning, and native SSE-backed tablo discussions. Closed with 7 acknowledged deferred artifact items; see `.planning/milestones/v2.0-MILESTONE-AUDIT.md`.
---
*Last updated: 2026-05-17 — Phase 17 complete (discussion view and planning page restyled with design system components; IsOwn bubble alignment, day separators, HTMX tab fix, discussion max-height with auto-scroll)*
---
*Last updated: 2026-05-17 after v3.0 milestone — design system shipped, all 17 phases complete through v1.0v3.0*

View file

@ -47,6 +47,59 @@ A living document updated after each milestone. Lessons feed forward into future
---
## Milestone: v3.0 — Design System & Visual Polish
**Shipped:** 2026-05-17
**Phases:** 5 (13-17) | **Plans:** 16
### What Was Built
- Full CSS token vocabulary in `base.css` (colors, spacing, typography, shadows, gradients)
- 11 typed templ components: button, badge, card, modal, empty-state, table, icon-button, input, textarea, select, form-field
- Build-tag-gated `/ui-catalog` visual verification page for the design system
- Auth pages (login/signup) with gradient animated background, auth-card layout, Google Material Design sign-in button
- App shell sidebar with brand section, nav icons, tablo list section, user footer
- Project-card tablo grid with color avatars, creation date, action controls
- Tablo detail: project-card-top header, tasks-section kanban, etapes section, files `@ui.Table` with `@ui.EmptyState`
- Chat view: own-vs-others message bubbles with brand-tint right-alignment
- Planning view: day-separator event list using overview-section layout
### What Worked
- Building the design system foundation (Phase 13) before any surface work paid off — phases 14-17 moved fast because components were ready
- Build-tag catalog (`just catalog`) made visual verification frictionless between phases
- Air CSS watching (added in Phase 14) eliminated manual restart friction for the rest of the milestone
- TDD for view model logic (planning view, chat IsOwn) caught integration bugs before browser verify
### What Was Inefficient
- REQUIREMENTS.md checkboxes for DASH-01/02/03 were not ticked even after Phase 15 completed — stale data discovered only at milestone close
- Phase 13 summary one-liners were raw "Task 1 —" prefixes from the executor rather than human-readable accomplishments — cleaned manually at close
- Some ROADMAP.md phase entries had stale "1/2 plans executed" counts that didn't reflect actual SUMMARY.md files
### Patterns Established
- Design system → auth surface → dashboard → detail → auxiliary (chat/planning) is the right reskin order
- `@ui.Table` + `@ui.EmptyState` as a pair for any list view
- `@AppLayout` wraps all authenticated pages; `@AuthLayout` wraps auth pages — switching is done by changing the outer template
- Build tags (`//go:build catalog` + `//go:build !catalog` stub) as the idiom for dev-only routes
### Key Lessons
- Validate REQUIREMENTS.md checkboxes during phase completion, not at milestone close
- Phase SUMMARY.md one-liners should be written by the executor in final form; raw task names create cleanup work at milestone close
- CSS dev-watch in air is non-negotiable for any CSS-heavy phase — add it at project start, not mid-milestone
- Catalog-first is worthwhile for design systems: visual inventory before any surface application prevents design drift
### Cost Observations
- 2-day milestone (2026-05-16 → 2026-05-17)
- 150 files, +23,505/993 lines across 128 commits
- Most expensive phase: Phase 14 (auth pages) — auth_components + auth_layout from scratch took iteration
- Fastest phase: Phase 13 Plan 05 (catalog) — 3 minutes once components existed
---
## Cross-Milestone Trends
### Process Evolution
@ -54,15 +107,20 @@ A living document updated after each milestone. Lessons feed forward into future
| Milestone | Sessions | Phases | Key Change |
|-----------|----------|--------|------------|
| v2.0 | multiple | 5 | Collaboration, scheduling, and realtime work stayed inside Go + HTMX; artifact hygiene needs tighter close discipline. |
| v3.0 | multiple | 5 | Design-system-first approach validated; surface reskins moved fast. Stale requirement checkboxes and raw summary one-liners are recurring close-time friction. |
### Cumulative Quality
| Milestone | Tests | Coverage | Zero-Dep Additions |
|-----------|-------|----------|-------------------|
| v2.0 | Go handler/DB suites plus browser UAT | Strong behavior coverage; some archive artifacts deferred | Native SSE chat, server-owned sessions, Postgres-backed planning |
| v3.0 | TDD for view models (planning, chat IsOwn); browser verify checkpoints | Visual correctness tested via catalog + human UAT; unit coverage on behavior helpers | Design system (no new runtime deps); build-tag-gated catalog route |
### Top Lessons
1. Close phase validation and verification artifacts before running milestone audit.
2. Keep milestone archival before next-milestone initialization when possible.
3. Preserve browser UAT for HTMX interaction behavior.
4. Check REQUIREMENTS.md checkboxes during phase execution, not at milestone close — stale checkboxes create friction.
5. Design-system-first pays dividends: build the component library, verify in catalog, then apply to surfaces.
6. Add CSS dev-watch (Air) at project start — it's always needed for CSS-heavy work.

View file

@ -1,169 +1,66 @@
# Roadmap: Xtablo v3.0 Design System & Visual Polish
# Roadmap: Xtablo Go + HTMX Rewrite
**Created:** 2026-05-16
**Project mode:** Brownfield milestone on existing Go+HTMX backend
**Milestone:** v3.0 — Design System & Visual Polish
## Milestones
5 phases, sequential. Phase numbering continues from v2.0, so v3.0 starts at Phase 13.
- ✅ **v1.0 MVP** — Phases 1-7 (shipped 2026-05-15). Archive: [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md)
- ✅ **v2.0 Collaboration, Planning, and Social Sign-in** — Phases 8-12 (shipped 2026-05-16). Archive: [`milestones/v2.0-ROADMAP.md`](milestones/v2.0-ROADMAP.md)
- ✅ **v3.0 Design System & Visual Polish** — Phases 13-17 (shipped 2026-05-17). Archive: [`milestones/v3.0-ROADMAP.md`](milestones/v3.0-ROADMAP.md)
---
## Phases
## Previous Milestones
<details>
<summary>✅ v1.0 MVP (Phases 1-7) — SHIPPED 2026-05-15</summary>
- [x] **v2.0 Collaboration, Planning, and Social Sign-in** — Phases 8-12, shipped 2026-05-16. Archive: [`milestones/v2.0-ROADMAP.md`](milestones/v2.0-ROADMAP.md)
- [x] Phase 1: Foundation — completed 2026-05-14
- [x] Phase 2: Authentication — completed 2026-05-15
- [x] Phase 3: Tablos CRUD — completed 2026-05-15
- [x] Phase 4: Tasks Kanban — completed 2026-05-15
- [x] Phase 5: File Attachments — completed 2026-05-15
- [x] Phase 6: Background Worker — completed 2026-05-15
- [x] Phase 7: Deploy v1 — completed 2026-05-15
---
</details>
## Phase Summary
<details>
<summary>✅ v2.0 Collaboration, Planning, and Social Sign-in (Phases 8-12) — SHIPPED 2026-05-16</summary>
| # | Phase | Goal | Requirements |
|---|-------|------|--------------|
| 13 | 5/5 | Complete | 2026-05-16 |
| 14 | 1/2 | In Progress| |
| 15 | 3/3 | Complete | 2026-05-16 |
| 16 | 4/4 | Complete | 2026-05-16 |
| 17 | 2/2 | Complete | 2026-05-17 |
- [x] Phase 8: Social Sign-in (5/5 plans) — completed 2026-05-15
- [x] Phase 9: Etapes (4/4 plans) — completed 2026-05-15
- [x] Phase 10: Events (3/3 plans) — completed 2026-05-16
- [x] Phase 11: Individual Planning (2/2 plans) — completed 2026-05-16
- [x] Phase 12: Native Tablo Chat (3/3 plans) — completed 2026-05-16
---
</details>
## Phase Details
<details>
<summary>✅ v3.0 Design System & Visual Polish (Phases 13-17) — SHIPPED 2026-05-17</summary>
### Phase 13: Design System Foundation
**Goal:** Replace the minimal `backend/internal/web/ui` with a full design system ported from `go-backend/internal/web/ui` — tokens, components, and Tailwind integration — so every subsequent phase has a stable component library to consume.
**Mode:** mvp
**Status:** Pending
**Requirements:** DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-09
**Plans:** 5/5 plans complete
**Success Criteria:**
1. `backend/internal/web/ui/base.css` defines all CSS custom properties (color, spacing, typography, shadows, gradients) matching the go-backend token vocabulary
2. All component types are implemented as templ components: button, input, textarea, select, card, badge, modal, empty-state, table, icon-button
3. `backend/tailwind.input.css` imports all component CSS files and the app shell CSS
4. A component catalog page (`/ui-catalog`, dev-only) renders all components for visual verification
5. All existing templates compile and unit tests pass with no regressions
- [x] Phase 13: Design System Foundation (5/5 plans) — completed 2026-05-16
- [x] Phase 14: Auth Pages (2/2 plans) — completed 2026-05-16
- [x] Phase 15: Dashboard & Tablos (3/3 plans) — completed 2026-05-16
- [x] Phase 16: Tablo Detail (4/4 plans) — completed 2026-05-17
- [x] Phase 17: Chat & Planning (2/2 plans) — completed 2026-05-17
Plans:
**Wave 1**
- [x] 13-01-PLAN.md — Token vocabulary + enum/helper foundation (base.css, auth.css extraction, variants.go, helpers.go)
</details>
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 13-02-PLAN.md — Migrate existing components to go-backend API (button multi-class, badge pill, card typed API, template hardcodes)
## Progress
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 13-03-PLAN.md — Port form-input components: input, textarea, select, form-field (CSS + templ + tests)
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 13-04-PLAN.md — Port surface components: modal, empty-state, table, icon-button, space + tailwind.input.css manifest
**Wave 5** *(blocked on Wave 4 completion)*
- [x] 13-05-PLAN.md — Catalog route (build-tag gated) + visual sign-off checkpoint
**User-in-loop:** Review the catalog page before proceeding to per-view application phases. Confirm token choices (brand color, radius, shadow levels) match what you want the product to look like.
### Phase 14: Auth Pages
**Goal:** Restyle login and signup pages to match the JS app's auth-card layout using the design system from Phase 13.
**Mode:** mvp
**Status:** Pending
**Requirements:** AUTH-UI-01, AUTH-UI-02, AUTH-UI-03
**Plans:** 1/2 plans executed
**Success Criteria:**
1. Login page has gradient background with animated background layer, centered auth card with brand logo, and status banner using design tokens
2. Signup page matches the same visual treatment as login
3. Google sign-in button uses the Material Design button style from the go-backend design
4. All existing auth handler tests pass unchanged
5. Browser walkthrough of login and signup matches the go-backend app.css auth-card design
Plans:
**Wave 1**
- [x] 14-01-PLAN.md — Auth foundation: logo assets + auth.css replacement + auth_components.templ + auth_layout.templ
**Wave 2** *(blocked on Wave 1 completion)*
- [ ] 14-02-PLAN.md — Page migration: update auth_login.templ and auth_signup.templ to use AuthLayout + FormField inputs + nav links + browser verify checkpoint
**User-in-loop:** Browser walkthrough checkpoint in Plan 02 — approve visual result before considering the phase complete.
### Phase 15: Dashboard & Tablos
**Goal:** Restyle the layout shell (sidebar + main) and tablo list/dashboard to match the JS app's sidebar + project-card layout.
**Mode:** mvp
**Status:** Pending
**Requirements:** DASH-01, DASH-02, DASH-03
**Plans:** 3/3 plans complete
**Success Criteria:**
1. Sidebar has brand section, nav items with icons, tablo list section, and user/account footer using sidebar-nav-shell classes
2. Tablo list uses project-card layout with color avatars, creation date, and action controls
3. Dashboard empty state uses the empty-state component
4. All existing tablo CRUD handler tests pass unchanged
5. Browser walkthrough of tablos list matches the go-backend project-card / sidebar design
Plans:
**Wave 0**
- [x] 15-01-PLAN.md — Wave 0 test stubs: TestTablosDashboard_Sidebar, TestTablosDashboard_ProjectCards, TestTablosDashboard_EmptyState (RED baseline for DASH-01/02/03)
**Wave 1** *(blocked on Wave 0 completion)*
- [x] 15-02-PLAN.md — CSS foundation + AppLayout: app.css ported from go-backend, tailwind.input.css updated, app_layout.templ + app_layout_helpers.go created
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 15-03-PLAN.md — Dashboard wiring: tablos.templ restyled (project-card grid, ui.EmptyState), handlers updated, planning + account_providers switched to AppLayout, browser verify checkpoint
**User-in-loop:** Approve sidebar shape (nav items, tablo list section) and tablo card layout before implementation.
### Phase 16: Tablo Detail
**Goal:** Restyle the tablo detail view — header, task kanban, etapes, and files — using design system components.
**Mode:** mvp
**Status:** Pending
**Requirements:** DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04
**Plans:** 4/4 plans complete
**Success Criteria:**
1. Tablo detail header uses project-card-top layout with title, avatar, and action controls
2. Task kanban uses tasks-section design: section header with add button, task rows with checkbox and meta
3. Etapes section uses the same card/section visual pattern as tasks
4. Files section uses the table component with consistent row actions
5. All existing task, etape, and file handler tests pass unchanged
Plans:
**Wave 1**
- [x] 16-01-PLAN.md — CSS foundation + icons: append CSS Sections 1925 to app.css; add download + chat icon cases to UIIcon switch
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 16-02-PLAN.md — Header + tab nav + overview tab: restyle TabloDetailPage header (project-card-top), metadata row, tab nav (design token classes), move desc to overview tab, remove EtapeStrip call from TasksTabFragment
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 16-03-PLAN.md — Kanban + etape grouping: groupTasksByEtape helper, restyled KanbanBoard/Column/TaskCard, EtapeStrip OOB removal, handlers_tasks.go call sites updated
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 16-04-PLAN.md — Files section: @ui.Table, @ui.EmptyState, FileListRow as tr, FileDeleteConfirmFragment as tr, browser verify checkpoint
**User-in-loop:** Browser verify checkpoint in Plan 04 — approve visual result before considering the phase complete.
### Phase 17: Chat & Planning
**Goal:** Restyle the discussion view and planning page using design system components to make them visually consistent with the rest of the app.
**Mode:** mvp
**Status:** Pending
**Requirements:** CHAT-UI-01, PLAN-UI-01
**Plans:** 2/2 plans complete
**Success Criteria:**
1. Discussion view uses card/surface design; own messages vs. others are visually differentiated
2. Planning page uses overview-section layout with chronological event list
3. All existing chat and planning handler tests pass unchanged
4. Browser walkthrough confirms both views look consistent with the Phase 1516 restyled surfaces
Plans:
**Wave 1** *(both plans parallel — no shared files)*
- [x] 17-01-PLAN.md — Discussion view: CSS message-bubble classes + DiscussionTabData view model + ChatMainContent() component + handler wiring + browser verify
- [x] 17-02-PLAN.md — Planning view: h1 selector fix + PlanningTabData view model + PlanningShowDaySeparator + PlanningMainContent() component + handler wiring + browser verify
**User-in-loop:** Browser verify checkpoints in both plans — approve visual result before considering the phase complete.
---
## Coverage
**21 requirements mapped across 5 phases**
| Phase | Requirements | Count |
|-------|-------------|-------|
| 13 | DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-09 | 9 |
| 14 | AUTH-UI-01, AUTH-UI-02, AUTH-UI-03 | 3 |
| 15 | DASH-01, DASH-02, DASH-03 | 3 |
| 16 | DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04 | 4 |
| 17 | CHAT-UI-01, PLAN-UI-01 | 2 |
| **Total** | | **21 / 21 ✓** |
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|---------------|----------|------------|
| 1. Foundation | v1.0 | — | Complete | 2026-05-14 |
| 2. Authentication | v1.0 | 7/7 | Complete | 2026-05-15 |
| 3. Tablos CRUD | v1.0 | 3/3 | Complete | 2026-05-15 |
| 4. Tasks Kanban | v1.0 | 3/3 | Complete | 2026-05-15 |
| 5. File Attachments | v1.0 | — | Complete | 2026-05-15 |
| 6. Background Worker | v1.0 | 2/2 | Complete | 2026-05-15 |
| 7. Deploy v1 | v1.0 | — | Complete | 2026-05-15 |
| 8. Social Sign-in | v2.0 | 5/5 | Complete | 2026-05-15 |
| 9. Etapes | v2.0 | 4/4 | Complete | 2026-05-15 |
| 10. Events | v2.0 | 3/3 | Complete | 2026-05-16 |
| 11. Individual Planning | v2.0 | 2/2 | Complete | 2026-05-16 |
| 12. Native Tablo Chat | v2.0 | 3/3 | Complete | 2026-05-16 |
| 13. Design System Foundation | v3.0 | 5/5 | Complete | 2026-05-16 |
| 14. Auth Pages | v3.0 | 2/2 | Complete | 2026-05-16 |
| 15. Dashboard & Tablos | v3.0 | 3/3 | Complete | 2026-05-16 |
| 16. Tablo Detail | v3.0 | 4/4 | Complete | 2026-05-17 |
| 17. Chat & Planning | v3.0 | 2/2 | Complete | 2026-05-17 |

View file

@ -2,15 +2,15 @@
gsd_state_version: 1.0
milestone: v3.0
milestone_name: Design System & Visual Polish
status: milestone_complete
last_updated: "2026-05-17T08:36:32.223Z"
last_activity: 2026-05-17
status: Awaiting next milestone
last_updated: "2026-05-17T12:09:43.643Z"
last_activity: 2026-05-17 — Milestone v3.0 completed and archived
progress:
total_phases: 5
completed_phases: 6
completed_phases: 5
total_plans: 16
completed_plans: 16
percent: 120
percent: 100
---
# STATE
@ -21,17 +21,17 @@ progress:
## Project Reference
See: `.planning/PROJECT.md` (updated 2026-05-16)
See: `.planning/PROJECT.md` (updated 2026-05-17)
**Core value:** A user can sign in and run the Tablos workflow — organize work, attach files, discuss, and plan scheduled events — without a JS framework or managed chat provider.
**Current focus:** Phase 17 — Chat & Planning
**Current focus:** Planning next milestone (v4.0)
## Current Position
Phase: 17
Plan: Not started
Status: Milestone complete
Last activity: 2026-05-17
Phase: Milestone v3.0 complete
Plan:
Status: Awaiting next milestone
Last activity: 2026-05-17 — Milestone v3.0 completed and archived
## Previous Milestone Status
@ -53,11 +53,10 @@ Last activity: 2026-05-17
## Deferred Items
Items acknowledged and deferred at milestone close on 2026-05-16:
Items acknowledged and deferred at v3.0 milestone close on 2026-05-17 (all pre-existing from v1.0/v2.0):
| Category | Item | Status |
|----------|------|--------|
| uat_gap | Phase 01: 01-HUMAN-UAT.md | resolved; 0 pending scenarios |
| uat_gap | Phase 05: 05-HUMAN-UAT.md | partial; 6 pending scenarios |
| uat_gap | Phase 07: 07-HUMAN-UAT.md | partial; 3 pending scenarios |
| verification_gap | Phase 03: 03-VERIFICATION.md | human_needed |
@ -203,3 +202,7 @@ Items acknowledged and deferred at milestone close on 2026-05-16:
---
*Last updated: 2026-05-16 after Phase 14 Plan 02 execution complete*
## Operator Next Steps
- Start the next milestone with /gsd-new-milestone

View file

@ -0,0 +1,110 @@
# Requirements Archive: v3.0 Design System & Visual Polish
**Archived:** 2026-05-17
**Status:** SHIPPED
For current requirements, see `.planning/REQUIREMENTS.md`.
---
# Requirements: Xtablo v3.0 Design System & Visual Polish
**Defined:** 2026-05-16
**Core Value:** A user can sign in and run the Tablos workflow — organize work, attach files, discuss, and plan scheduled events — without a JS framework or managed chat provider.
## v3.0 Requirements
Requirements for milestone v3.0. Each maps to exactly one roadmap phase.
### Design System
- [x] **DS-01**: CSS design tokens (colors, spacing, typography, shadows, gradients) are defined in `backend/internal/web/ui/base.css` matching the go-backend token vocabulary
- [x] **DS-02**: Button component with primary, secondary, ghost, and danger variants
- [x] **DS-03**: Input, Textarea, and Select form field components replace inline raw HTML in all templates
- [x] **DS-04**: Card component is used across tablo list, detail, and content views
- [x] **DS-05**: Badge component supports semantic tones (primary, warning, success, danger)
- [x] **DS-06**: Modal component is available for create/edit dialogs
- [x] **DS-07**: Empty-state component is available for zero-data views
- [x] **DS-08**: Table component is available for list views (files, events)
- [x] **DS-09**: Icon-button component replaces inline icon-button patterns across templates
### Auth Views
- [x] **AUTH-UI-01**: Login page matches the JS app's auth-card layout (gradient background, centered card, brand logo, status banner)
- [x] **AUTH-UI-02**: Signup page matches the same visual treatment as login
- [x] **AUTH-UI-03**: Google sign-in button uses the Material Design button style
### Dashboard & Tablos
- [ ] **DASH-01**: Sidebar uses the go-backend sidebar design (brand section, nav items with icons, tablo list, user/account footer)
- [ ] **DASH-02**: Tablo list uses project-card layout with color accents, creation date, and action controls
- [ ] **DASH-03**: Dashboard empty state uses the empty-state component
### Tablo Detail
- [x] **DETAIL-01**: Tablo detail header area matches the project-card-top design
- [x] **DETAIL-02**: Task kanban board uses the tasks-section design (section header, task rows, add control)
- [x] **DETAIL-03**: Etapes section is visually consistent with the task section
- [x] **DETAIL-04**: Files section uses the table component
### Chat & Planning
- [x] **CHAT-UI-01**: Discussion view uses consistent card/surface design with message bubbles distinguishing own vs. others
- [x] **PLAN-UI-01**: Planning page uses the overview-section layout for event aggregation
## Future Requirements
### Responsive / Mobile
- **RESP-01**: Sidebar collapses on small screens (hamburger or bottom-nav pattern)
- **RESP-02**: Kanban board scrolls horizontally on mobile
- **RESP-03**: Auth pages adapt gracefully to narrow viewports
### Dark Mode
- **DARK-01**: All CSS tokens have dark-mode counterparts via `prefers-color-scheme` or a class toggle
## Out of Scope
| Feature | Reason |
|---------|--------|
| New pages or features | v3.0 is purely visual — no new routes or data models |
| Billing / Stripe | Deferred from v1.0, still out of scope |
| Client portal / Admin | Deferred from v1.0, still out of scope |
| Mobile app | Out of scope for this rewrite milestone |
| Dark mode | Future requirement — tokens will be structured to enable it, not implement it |
## Traceability
| Requirement | Phase | Status |
|-------------|-------|--------|
| DS-01 | Phase 13 | Complete |
| DS-02 | Phase 13 | Complete |
| DS-03 | Phase 13 | Complete |
| DS-04 | Phase 13 | Complete |
| DS-05 | Phase 13 | Complete |
| DS-06 | Phase 13 | Complete |
| DS-07 | Phase 13 | Complete |
| DS-08 | Phase 13 | Complete |
| DS-09 | Phase 13 | Complete |
| AUTH-UI-01 | Phase 14 | Complete |
| AUTH-UI-02 | Phase 14 | Complete |
| AUTH-UI-03 | Phase 14 | Complete |
| DASH-01 | Phase 15 | Pending |
| DASH-02 | Phase 15 | Pending |
| DASH-03 | Phase 15 | Pending |
| DETAIL-01 | Phase 16 | Complete |
| DETAIL-02 | Phase 16 | Complete |
| DETAIL-03 | Phase 16 | Complete |
| DETAIL-04 | Phase 16 | Complete |
| CHAT-UI-01 | Phase 17 | Complete |
| PLAN-UI-01 | Phase 17 | Complete |
**Coverage:**
- v3.0 requirements: 21 total
- Mapped to phases: 21
- Unmapped: 0 ✓
---
*Requirements defined: 2026-05-16*
*Last updated: 2026-05-16 after initial definition*

View file

@ -0,0 +1,169 @@
# Roadmap: Xtablo v3.0 Design System & Visual Polish
**Created:** 2026-05-16
**Project mode:** Brownfield milestone on existing Go+HTMX backend
**Milestone:** v3.0 — Design System & Visual Polish
5 phases, sequential. Phase numbering continues from v2.0, so v3.0 starts at Phase 13.
---
## Previous Milestones
- [x] **v2.0 Collaboration, Planning, and Social Sign-in** — Phases 8-12, shipped 2026-05-16. Archive: [`milestones/v2.0-ROADMAP.md`](milestones/v2.0-ROADMAP.md)
---
## Phase Summary
| # | Phase | Goal | Requirements |
|---|-------|------|--------------|
| 13 | 5/5 | Complete | 2026-05-16 |
| 14 | 1/2 | In Progress| |
| 15 | 3/3 | Complete | 2026-05-16 |
| 16 | 4/4 | Complete | 2026-05-16 |
| 17 | 2/2 | Complete | 2026-05-17 |
---
## Phase Details
### Phase 13: Design System Foundation
**Goal:** Replace the minimal `backend/internal/web/ui` with a full design system ported from `go-backend/internal/web/ui` — tokens, components, and Tailwind integration — so every subsequent phase has a stable component library to consume.
**Mode:** mvp
**Status:** Pending
**Requirements:** DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-09
**Plans:** 5/5 plans complete
**Success Criteria:**
1. `backend/internal/web/ui/base.css` defines all CSS custom properties (color, spacing, typography, shadows, gradients) matching the go-backend token vocabulary
2. All component types are implemented as templ components: button, input, textarea, select, card, badge, modal, empty-state, table, icon-button
3. `backend/tailwind.input.css` imports all component CSS files and the app shell CSS
4. A component catalog page (`/ui-catalog`, dev-only) renders all components for visual verification
5. All existing templates compile and unit tests pass with no regressions
Plans:
**Wave 1**
- [x] 13-01-PLAN.md — Token vocabulary + enum/helper foundation (base.css, auth.css extraction, variants.go, helpers.go)
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 13-02-PLAN.md — Migrate existing components to go-backend API (button multi-class, badge pill, card typed API, template hardcodes)
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 13-03-PLAN.md — Port form-input components: input, textarea, select, form-field (CSS + templ + tests)
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 13-04-PLAN.md — Port surface components: modal, empty-state, table, icon-button, space + tailwind.input.css manifest
**Wave 5** *(blocked on Wave 4 completion)*
- [x] 13-05-PLAN.md — Catalog route (build-tag gated) + visual sign-off checkpoint
**User-in-loop:** Review the catalog page before proceeding to per-view application phases. Confirm token choices (brand color, radius, shadow levels) match what you want the product to look like.
### Phase 14: Auth Pages
**Goal:** Restyle login and signup pages to match the JS app's auth-card layout using the design system from Phase 13.
**Mode:** mvp
**Status:** Pending
**Requirements:** AUTH-UI-01, AUTH-UI-02, AUTH-UI-03
**Plans:** 1/2 plans executed
**Success Criteria:**
1. Login page has gradient background with animated background layer, centered auth card with brand logo, and status banner using design tokens
2. Signup page matches the same visual treatment as login
3. Google sign-in button uses the Material Design button style from the go-backend design
4. All existing auth handler tests pass unchanged
5. Browser walkthrough of login and signup matches the go-backend app.css auth-card design
Plans:
**Wave 1**
- [x] 14-01-PLAN.md — Auth foundation: logo assets + auth.css replacement + auth_components.templ + auth_layout.templ
**Wave 2** *(blocked on Wave 1 completion)*
- [ ] 14-02-PLAN.md — Page migration: update auth_login.templ and auth_signup.templ to use AuthLayout + FormField inputs + nav links + browser verify checkpoint
**User-in-loop:** Browser walkthrough checkpoint in Plan 02 — approve visual result before considering the phase complete.
### Phase 15: Dashboard & Tablos
**Goal:** Restyle the layout shell (sidebar + main) and tablo list/dashboard to match the JS app's sidebar + project-card layout.
**Mode:** mvp
**Status:** Pending
**Requirements:** DASH-01, DASH-02, DASH-03
**Plans:** 3/3 plans complete
**Success Criteria:**
1. Sidebar has brand section, nav items with icons, tablo list section, and user/account footer using sidebar-nav-shell classes
2. Tablo list uses project-card layout with color avatars, creation date, and action controls
3. Dashboard empty state uses the empty-state component
4. All existing tablo CRUD handler tests pass unchanged
5. Browser walkthrough of tablos list matches the go-backend project-card / sidebar design
Plans:
**Wave 0**
- [x] 15-01-PLAN.md — Wave 0 test stubs: TestTablosDashboard_Sidebar, TestTablosDashboard_ProjectCards, TestTablosDashboard_EmptyState (RED baseline for DASH-01/02/03)
**Wave 1** *(blocked on Wave 0 completion)*
- [x] 15-02-PLAN.md — CSS foundation + AppLayout: app.css ported from go-backend, tailwind.input.css updated, app_layout.templ + app_layout_helpers.go created
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 15-03-PLAN.md — Dashboard wiring: tablos.templ restyled (project-card grid, ui.EmptyState), handlers updated, planning + account_providers switched to AppLayout, browser verify checkpoint
**User-in-loop:** Approve sidebar shape (nav items, tablo list section) and tablo card layout before implementation.
### Phase 16: Tablo Detail
**Goal:** Restyle the tablo detail view — header, task kanban, etapes, and files — using design system components.
**Mode:** mvp
**Status:** Pending
**Requirements:** DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04
**Plans:** 4/4 plans complete
**Success Criteria:**
1. Tablo detail header uses project-card-top layout with title, avatar, and action controls
2. Task kanban uses tasks-section design: section header with add button, task rows with checkbox and meta
3. Etapes section uses the same card/section visual pattern as tasks
4. Files section uses the table component with consistent row actions
5. All existing task, etape, and file handler tests pass unchanged
Plans:
**Wave 1**
- [x] 16-01-PLAN.md — CSS foundation + icons: append CSS Sections 1925 to app.css; add download + chat icon cases to UIIcon switch
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 16-02-PLAN.md — Header + tab nav + overview tab: restyle TabloDetailPage header (project-card-top), metadata row, tab nav (design token classes), move desc to overview tab, remove EtapeStrip call from TasksTabFragment
**Wave 3** *(blocked on Wave 2 completion)*
- [x] 16-03-PLAN.md — Kanban + etape grouping: groupTasksByEtape helper, restyled KanbanBoard/Column/TaskCard, EtapeStrip OOB removal, handlers_tasks.go call sites updated
**Wave 4** *(blocked on Wave 3 completion)*
- [x] 16-04-PLAN.md — Files section: @ui.Table, @ui.EmptyState, FileListRow as tr, FileDeleteConfirmFragment as tr, browser verify checkpoint
**User-in-loop:** Browser verify checkpoint in Plan 04 — approve visual result before considering the phase complete.
### Phase 17: Chat & Planning
**Goal:** Restyle the discussion view and planning page using design system components to make them visually consistent with the rest of the app.
**Mode:** mvp
**Status:** Pending
**Requirements:** CHAT-UI-01, PLAN-UI-01
**Plans:** 2/2 plans complete
**Success Criteria:**
1. Discussion view uses card/surface design; own messages vs. others are visually differentiated
2. Planning page uses overview-section layout with chronological event list
3. All existing chat and planning handler tests pass unchanged
4. Browser walkthrough confirms both views look consistent with the Phase 1516 restyled surfaces
Plans:
**Wave 1** *(both plans parallel — no shared files)*
- [x] 17-01-PLAN.md — Discussion view: CSS message-bubble classes + DiscussionTabData view model + ChatMainContent() component + handler wiring + browser verify
- [x] 17-02-PLAN.md — Planning view: h1 selector fix + PlanningTabData view model + PlanningShowDaySeparator + PlanningMainContent() component + handler wiring + browser verify
**User-in-loop:** Browser verify checkpoints in both plans — approve visual result before considering the phase complete.
---
## Coverage
**21 requirements mapped across 5 phases**
| Phase | Requirements | Count |
|-------|-------------|-------|
| 13 | DS-01, DS-02, DS-03, DS-04, DS-05, DS-06, DS-07, DS-08, DS-09 | 9 |
| 14 | AUTH-UI-01, AUTH-UI-02, AUTH-UI-03 | 3 |
| 15 | DASH-01, DASH-02, DASH-03 | 3 |
| 16 | DETAIL-01, DETAIL-02, DETAIL-03, DETAIL-04 | 4 |
| 17 | CHAT-UI-01, PLAN-UI-01 | 2 |
| **Total** | | **21 / 21 ✓** |