From d5c9cf1927a00fa767353769acb694f884754edf Mon Sep 17 00:00:00 2001
From: "bert.hausmans" <bert@hausmans.nl>
Date: Mon, 11 May 2026 01:16:13 +0200
Subject: [PATCH] docs(rfc): correct AD-2/AD-5 and Appendix B to reflect
 ecosystem state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three RFC drift corrections discovered during F3 implementation:

1. AD-5 icon rendering: corrected from "<i :class='i-tabler-X'>"
   utility-class pattern (which would require UnoCSS, not installed)
   to "@iconify/vue's <Icon> component with name='tabler-X' prop"
   (existing Crewli pattern producing real SVG output). The thin wrapper
   shipped in F3 B6 as apps/app/src/components/Icon.vue accordingly.

2. AD-2 theme architecture: corrected package reference from
   @primevue/themes@^4.5 (deprecated by PrimeFaces) to
   @primeuix/themes@^2 (the path now prescribed by PrimeVue 4's
   official install docs at primevue.org/vite/). Same maintainers,
   same API surface (definePreset, Aura preset, semantic tokens).
   F3 commit B1 already uses the corrected package.

3. Appendix B Aura theme token plan: updated import-path examples to
   @primeuix/themes and @primeuix/themes/aura accordingly.

Also updated:
- §6 F3 deliverables list: dependency line now reads @primeuix/themes@^2
  with a footnote linking to the B1 rationale.
- Appendix C Version Pinning Policy: separated @primeuix/themes from
  the primevue/^primevue/forms lockstep pin (independent release cadence).
- dev-docs/PRIMEVUE_COMPONENTS.md §3 (Data display): VIcon row updated
  to <Icon name="tabler-..." />; surrounding migration-spirit paragraph
  rewritten; §10 external-resources link relabeled to @primeuix/themes.

These are RFC drift corrections — the implementation in F3 (commits
B1, B2, B6 of this sprint) already uses the corrected packages and
import paths. This commit aligns the spec with reality so future
contributors don't reach for the deprecated/inaccurate documentation.

.claude-sync/ regenerates automatically post-commit via lefthook.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 dev-docs/PRIMEVUE_COMPONENTS.md      | 16 ++++++++++------
 dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md | 21 +++++++++++++++------
 2 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/dev-docs/PRIMEVUE_COMPONENTS.md b/dev-docs/PRIMEVUE_COMPONENTS.md
index 8f1aef0a..e3f13ae1 100644
--- a/dev-docs/PRIMEVUE_COMPONENTS.md
+++ b/dev-docs/PRIMEVUE_COMPONENTS.md
@@ -129,17 +129,21 @@ replaces `VSheet`, `VSpacer`, and most uses of `VContainer`.
 | `VChip` | `Tag` (preferred) or `Chip` | https://primevue.org/tag/ | `Tag` for status badges; `Chip` for removable filters |
 | `VAvatar` | `Avatar` | https://primevue.org/avatar/ | `variant='tonal'` → `:style="{ background, color }"` (no built-in tonal) |
 | `VImg` | `<img>` (native) | — | No wrapper needed; use `loading="lazy"` |
-| `VIcon` | `<i class="i-tabler-..." />` | — | **Iconify-Tabler retained** per [RFC AD-5](./RFC-WS-FRONTEND-PRIMEVUE.md#ad-5-icons--iconify-tabler-retained-primeicons-not-installed); PrimeIcons is **not installed** |
+| `VIcon` | `<Icon name="tabler-..." />` | — | **Iconify-Tabler retained** per [RFC AD-5](./RFC-WS-FRONTEND-PRIMEVUE.md#ad-5-icons--iconify-tabler-retained-primeicons-not-installed); thin wrapper at `apps/app/src/components/Icon.vue` over `@iconify/vue`'s `<Icon>`. PrimeIcons is **not installed** |
 | `VLabel` | `<label>` (native) or `<FormField label="...">` | — | |
 | `VTimeline` / `VTimelineItem` | `Timeline` | https://primevue.org/timeline/ | |
 | `VBadge` (1 use) | `Badge` or `OverlayBadge` | https://primevue.org/badge/ | |
 
 **Migration spirit.** `VIcon` is the most widespread component (267 uses)
 and it does **not** become a PrimeVue component. The Iconify-Tabler
-class-based pattern (`<i class="i-tabler-arrow-right" />`) is
-stack-agnostic and survives the migration intact. PrimeIcons is not
-installed; do not introduce `pi pi-*` icon classes during F4 — they will
-not render. Lists are the most context-dependent area: a selection list
+naming convention survives intact: call-sites use the existing
+`tabler-*` string identifiers (e.g. `tabler-arrow-right`) and the new
+`apps/app/src/components/Icon.vue` wrapper renders them through
+`@iconify/vue` as real `<svg>` markup. UnoCSS-style `i-tabler-*` utility
+classes were considered but not adopted (UnoCSS is not in the stack);
+the wrapper preserves Crewli continuity. PrimeIcons is not installed;
+do not introduce `pi pi-*` icon classes during F4 — they will not
+render. Lists are the most context-dependent area: a selection list
 uses `Listbox`, a card grid uses `DataView`, a navigation list uses
 `MenuItem`/`PanelMenu`, and a generic display list is just `<ul><li>`.
 
@@ -369,7 +373,7 @@ External (PrimeVue ecosystem):
 
 - PrimeVue components: https://primevue.org/
 - `@primevue/forms` (form layer): https://primevue.org/forms/
-- `@primevue/themes` (Aura preset): https://primevue.org/theming/styled/
+- `@primeuix/themes` (Aura preset, the maintained successor to `@primevue/themes`): https://primevue.org/theming/styled/
 - `tailwindcss-primeui` (token bridge): https://github.com/primefaces/tailwindcss-primeui
 
 Internal (Crewli docs):
diff --git a/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md b/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md
index 9fe1cd88..d748400f 100644
--- a/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md
+++ b/dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md
@@ -105,7 +105,9 @@ The current `<VForm>` ref + per-field `:rules` array pattern is replaced by `<Fo
 
 ### AD-2: Theme = Aura preset, Crewli teal primary, dark mode preserved
 
-The Aura preset is configured via `@primevue/themes` `definePreset(Aura, { semantic: { primary: { ... } } })`. The Crewli teal (`#0D9394` light, `#0B7F80` dark) maps to `primary.500` and `primary.600` semantic tokens. Surface, success, info, warning, error tokens use Aura defaults unless explicit Crewli equivalents exist. Dark mode is wired via PrimeVue's `darkModeSelector: '.dark'` config, integrated with the existing `@core/composable/useSkins.ts` until F6 cleanup.
+The Aura preset is configured via `@primeuix/themes` `definePreset(Aura, { semantic: { primary: { ... } } })`. The Crewli teal (`#0D9394` light, `#0B7F80` dark) maps to `primary.500` and `primary.600` semantic tokens. Surface, success, info, warning, error tokens use Aura defaults unless explicit Crewli equivalents exist. Dark mode is wired via PrimeVue's `darkModeSelector: '.dark'` config, integrated with the existing `@core/composable/useSkins.ts` until F6 cleanup.
+
+> **Drift correction (F3 B9):** RFC v1.0 referenced `@primevue/themes@^4.5`. That package was deprecated by its maintainers (PrimeFaces) during the F3 sprint with explicit guidance to migrate to `@primeuix/themes`. PrimeVue 4's official install documentation at primevue.org/vite/ now specifies `@primeuix/themes` as the theme package. Same maintainers, same API surface (Aura preset, `definePreset`, semantic tokens). F3 commit B1 installed `@primeuix/themes@^2` directly; this paragraph and Appendix B are aligned with that ecosystem state.
 
 **Per-tenant overrides:** primary color and logo only (per project-level decision). Implementation: a Pinia computed reads `useOrganisationStore().branding.primaryColor` and patches the active preset via `usePrimeVue().config.theme.preset` at organisation-switch time. Full white-labeling is explicitly out of scope.
 
@@ -125,7 +127,9 @@ The Aura preset is configured via `@primevue/themes` `definePreset(Aura, { seman
 
 ### AD-5: Icons = Iconify-Tabler retained, PrimeIcons not installed
 
-The 593 `tabler-*` icon references in templates remain unchanged. PrimeVue's components accept any element in icon slots and `:icon` props can render arbitrary class names. The custom Vuetify icon component in `apps/app/src/plugins/vuetify/icons.ts` is replaced by a tiny generic `<Icon>` component that renders `<i :class="...">` for Iconify class strings — or, where call-sites already use `<VIcon icon="tabler-X">`, the migration substitutes `<i class="iconify tabler-X">` directly. The 5 SVG checkbox/radio overrides in `@images/svg/` become unused (PrimeVue's Checkbox/RadioButton ship their own styling) and are deleted in F6.
+The 593 `tabler-*` icon references in templates remain unchanged. PrimeVue's components accept any element in icon slots and `:icon` props can render arbitrary content. The custom Vuetify icon adapter in `apps/app/src/plugins/vuetify/icons.ts` is replaced by a tiny generic `<Icon>` component (at `apps/app/src/components/Icon.vue`) that wraps `@iconify/vue`'s `<Icon>` component and emits real `<svg>` markup. Call-site migration substitutes `<VIcon icon="tabler-X" />` with `<Icon name="tabler-X" />`. The 5 SVG checkbox/radio overrides in `@images/svg/` become unused (PrimeVue's Checkbox/RadioButton ship their own styling) and are deleted in F6.
+
+> **Drift correction (F3 B9):** RFC v1.0 described the new `<Icon>` component as rendering `<i :class="i-tabler-X">` utility classes. That approach would require UnoCSS to resolve `i-tabler-*` into real icon output, and UnoCSS is not in the Crewli stack — the project already uses `@iconify/vue` (installed at 4.1.2) for SVG icon rendering through Vuetify's icon adapter. F3 commit B6 implements `Icon.vue` as a thin wrapper around `@iconify/vue` accordingly. The substitution preserves existing icon naming (`tabler-eye`, `tabler-user`, etc.) and produces equivalent SVG output to the current Vuetify path. UnoCSS-style utility-class icon rendering was considered but not adopted; the wrapper retains Crewli's continuity.
 
 **Rationale:** Throwing away 593 icon references is needless cost; PrimeVue does not require its own icon set; the project's Tabler aesthetic is preserved.
 
@@ -195,7 +199,9 @@ Six work packages, executed strictly serially. Each package ends with: (a) all t
 ### F3 — Foundation (2 days)
 
 **Output:**
-- Dependencies installed: `primevue@^4.5`, `@primevue/themes@^4.5`, `@primevue/forms@^4.5`, `primelocale@^1`, `tailwindcss@^4`, `@tailwindcss/vite@^4`.
+- Dependencies installed: `primevue@^4.5`, `@primeuix/themes@^2` [^themes-pkg], `@primevue/forms@^4.5`, `primelocale@^1`, `tailwindcss@^4`, `@tailwindcss/vite@^4`.
+
+[^themes-pkg]: RFC v1.0 specified `@primevue/themes@^4.5`. That package was deprecated during F3 with explicit guidance to migrate to `@primeuix/themes` (same maintainers, same API surface). PrimeVue 4's official install documentation now prescribes `@primeuix/themes`. See F3 commit B1 for the substitution rationale and B9 for the AD-2 + Appendix B alignment.
 - Dependencies retained: `flatpickr`, `vue-flatpickr-component`, `@iconify-json/tabler`, `@iconify-json/mdi`, `@iconify-json/fa`, all Pinia/TanStack/Vue Query/Zod packages.
 - New: `apps/app/src/plugins/primevue/index.ts` — registers PrimeVue plugin with Aura preset, theme tokens, nl-NL locale.
 - New: `apps/app/src/plugins/primevue/theme.ts` — Aura `definePreset` with Crewli teal semantic tokens.
@@ -510,8 +516,10 @@ const onSubmit = async ({ valid, values }: any) => {
 
 ```ts
 // apps/app/src/plugins/primevue/theme.ts
-import Aura from '@primevue/themes/aura'
-import { definePreset } from '@primevue/themes'
+// Drift correction (F3 B9): imports use @primeuix/themes (the
+// maintained successor that PrimeVue 4's install docs now prescribe).
+import { definePreset } from '@primeuix/themes'
+import Aura from '@primeuix/themes/aura'
 
 export const CrewliPreset = definePreset(Aura, {
   semantic: {
@@ -549,7 +557,8 @@ Component-level overrides use the `pt` (PassThrough) prop globally configured in
 
 PrimeVue moves fast (4.5.0 → 4.5.5 in Oct–Dec 2025). Sprint pins:
 
-- `primevue` and `@primevue/themes` and `@primevue/forms`: pin to **same exact patch version** (e.g., `4.5.5`) in F3. They must always upgrade together to avoid token-mismatch bugs.
+- `primevue` and `@primevue/forms`: pin to **same exact patch version** (e.g., `4.5.5`) in F3. They must always upgrade together to avoid token-mismatch bugs.
+- `@primeuix/themes`: pin to `^2` (own release cadence, decoupled from PrimeVue's 4.x patch line — same maintainers, separate package per the F3 B9 drift correction).
 - `tailwindcss` and `@tailwindcss/vite`: pin to same exact version.
 - `primelocale`: caret range fine (`^1`).