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)

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).