crewli/dev-docs/RFC-WS-GUI-REDESIGN-CREWLI-STARTER.md

# RFC-WS-GUI-REDESIGN-CREWLI-STARTER — crewli-starter as design source

| Field | Value |
|---|---|
| **Status** | Approved (2026-05-16) |
| **Supersedes** | F4a–F4d component-migration sub-packages of RFC-WS-FRONTEND-PRIMEVUE |
| **Design spec** | `dev-docs/superpowers/specs/2026-05-15-crewli-starter-gui-redesign-design.md` |
| **Impl plans** | `dev-docs/superpowers/plans/2026-05-16-gui-redesign-foundation.md` (Plan 1 of 5) |

## Status

| Plan | State | Scope |
|---|---|---|
| Plan 1 — structural foundation | ✅ Done | bootable `/v2/` slice |
| Plan 2 — shell pieces | ✅ Done | AppSidebar/AppTopbar/SidebarNav/WorkspaceSwitcher/RightDrawer/AppDialog |
| Plan 3 — Tier-1 primitives + DraggableBlock + Storybook | ✅ Done (2026-05-18) | `537ec098..0b19e785` on `main`, 16 commits |
| Plan 4 — template layer | Next | List/Form/Detail/Dashboard/StateBlock |
| Plan 5 — catalog + theme/density toolbar | Pending | — |

**Plan 3 closure (2026-05-18).** Per-task SHAs: A1 `1561024e` · A2
`dd45e899` · T1 `20af2ebd` · T2 `9d1fd16f` · T3 `12cff8c0` · T4
`b0d5e961` · T5 `284fdcc4` · T6 `b64b0241` · T7 `79650d0b` · T8
`91d20d0d` · T9 `814d11c8` · T10 `183218ef` · T11 `f03a3f16` ·
T11(b)-fix `237afc89` · T12 `1a66ac6e` · lint-fix `0b19e785`.

- **Tests:** 527 → 564 (+37). `vue-tsc --noEmit` clean; scoped ESLint clean.
- **Bundle:** +35.9 kB raw / +0.82% (gzip overhead negligible) — within §11 "expected small".
- **DEFERRED-HITL (4, by design per AD-G6, not failures):** v2 parity
  baselines for StatusTag, StatCard, PageHead, EnergyDots, EnergyPicker,
  DraggableBlock (static states), TagsInput (criterion: Aura-coherent,
  not pixel), and the AppTopbar `@visual` re-baseline. Per-component
  criteria documented in the Plan 3 plan-doc; these are the human
  parity-check gate.
- **Spawned BACKLOG follow-ups (3):** `FRONTEND-ENERGYDOTS-NAN-ROBUSTNESS`,
  `FRONTEND-DRAGGABLEBLOCK-POINTERCANCEL` (blocked on an A2-contract
  amendment), `A11Y-AD3-MENUBAR-EMPTY-MODEL` — see `dev-docs/BACKLOG.md`
  § Technische schuld.
- Holistic review verdict: sound foundation for Plan 4.

## 1. What changes vs RFC-WS-FRONTEND-PRIMEVUE

The F4a–F4d strategy ("translate legacy Vuetify pages 1:1 to PrimeVue,
preserve UX") is **superseded**. The new strategy: `crewli-starter/` is
the design source of truth; v2 pages are built fresh under `/v2/*`
parallel routes and migrated page-by-page; v1 stays inert until per-page
cutover. All F4 *architectural* decisions (AD-1..AD-12: PrimeVue + Aura +
Tailwind + FormField + DataTable conventions) remain binding.

## 2. Binding architectural decisions (carried from the spec)

- **AD-G1 — Parallel routes.** `pages-v2/` mounts at `/v2/*` via a second
  `routesFolder`; v2 route NAMES are `v2-` prefixed (collision guard).
- **AD-G2 — Layout.** `OrganizerLayoutV2` wraps `AppShellV2`; every
  `pages-v2/**` page declares `definePage({ meta: { layout:
  'OrganizerLayoutV2' } })`, enforced by a custom ESLint rule.
- **AD-G3 — Fidelity.** PrimeVue-first; custom CSS only for genuinely
  bespoke visuals (DraggableBlock layout, WorkspaceSwitcher visual,
  shell chrome). Generic elements accept the PrimeVue look.
- **AD-G4 — State.** No `useWorkspaceStore`. Org/context data reuses
  `useAuthStore`/`useOrganisationStore`. One new `useShellUiStore` holds
  only sidebar/theme/density + right-drawer state. `provide`/`inject`
  from crewli-starter is replaced per-port (no `inject()` survives).
- **AD-G5 — Boundaries.** New `components-v2`/`pages-v2`/`layouts-v2`
  zones; the only v1→v2 bridge is a narrow `components-foundation` zone
  (FormField, Icon). No back-porting (structurally enforced). The v2
  shell layout (`src/layouts/*V2*.vue`, e.g. `OrganizerLayoutV2`) is the
  `layouts-v2` zone — same v2 capability as `pages-v2` (may import
  `components-v2` + `navigation`) so AD-G2's "`OrganizerLayoutV2` wraps
  `AppShellV2`" holds. The v1 `layouts` zone is unchanged and still
  cannot import `components-v2`, so v2 isolation is preserved (only
  top-level `*V2*.vue` layout files gain v2 capability;
  `src/layouts/components/AppShellV2.vue` stays in `layouts` since it
  imports only `stores`). Locked by `tests/unit/boundaries-v2.spec.ts`
  (`layouts-v2 → components-v2` allowed; v1 `layouts → components-v2`
  forbidden).
- **AD-G6 — Testing.** TEST-INFRA-001 (✅ Resolved) Playwright-CT +
  visual foundation is kept as the CI gate; Storybook a11y is
  complementary. v2 visual baselines are captured from the v2 component
  after human parity-check vs crewli-starter. CT specs are standalone
  (no `@storybook/test-runner`).
- **AD-G7 — Portal.** Frontend SPA prefix is `/portal/*` (already true
  in repo); observability binds on `route.meta.context==='portal'`, not
  path; `/api/v1/p/*` is a separate untouched backend layer. Portal v2
  is a later sprint with its own `PortalLayoutV2`.
- **AD-G8 — Cutover.** Per page: move `pages-v2/X`→`pages/X`, rewrite
  links, strip `v2-` name prefix, delete dead v1. Final cutover: folder
  renames + revert router/boundaries config + delete v1 shell + Vuetify.

## 3. Sequencing

Plan 1: RFC + structural foundation (bootable `/v2/` slice).
Plan 2: shell pieces (AppSidebar/AppTopbar/SidebarNav/WorkspaceSwitcher/
RightDrawer/AppDialog).
Plan 3: Tier-1 primitives + DraggableBlock + their Storybook stories.
Plan 4: template layer (List/Form/Detail/Dashboard/StateBlock).
Plan 5: full PrimeVue standard catalog stories + theme/density toolbar.
Then: Smart-Filter sub-sprint → Page-1 (events list) → subsequent trees.

## 4. Out of scope

Backend changes; v1 deletion before cutover; back-porting; domain
modules (Timetable/Cue/SectionBuilder migrate with their owning page);
Flatpickr/vue-i18n/DatePicker (inherit RFC-WS-FRONTEND-PRIMEVUE).