diff --git a/docs/UI-COMPOSITION-REVIEW.md b/docs/UI-COMPOSITION-REVIEW.md new file mode 100644 index 0000000..6c9eb6b --- /dev/null +++ b/docs/UI-COMPOSITION-REVIEW.md @@ -0,0 +1,79 @@ +# UI Composition Review — RC-Visual-02 Page Composition Audit + +Audit of every live page against the finished design system. No redesign, no business-logic changes, no new features — layout/spacing/hierarchy/alignment/state-composition fixes only, reusing existing shared components (`src/app/shared/ui/*`). + +Executed as four sequential commits on branch `B2B` (not pushed): + +| Commit | Scope | +|---|---| +| `2e31e80` | Storefront | +| `4ebc15f` | Builder / Project Editor | +| `712a7b4` | Backoffice: Dashboard, Products, Categories, Orders | +| `63c9cee` | Backoffice: Transactions, Customers, Moderation (Reviews/Reports), Users, Monitoring, Analytics | + +`npm run build` verified green after every commit. Baseline warning (pre-existing, unrelated to this work) remains: initial bundle 768.57 kB vs 700 kB budget. + +## Pages audited + +**Storefront** — Home, Catalog, Search, Product Details, Cart, Compare, Favorites/Wishlist, Static Pages (public renderer). + +**Builder** — General, Branding, Theme, Homepage, Widgets, Navigation, Languages, Features, Preview, Static Pages/Content tab, Media Library, Save bar. + +**Backoffice** — Dashboard, Products, Categories, Orders, Transactions, Customers (list + detail), Reviews/Moderation (list + reports queue + detail), Users, Monitoring, Analytics. + +**Not built / out of scope** (confirmed via `app.routes.ts`, not assumed from stale docs): +- **Settings** — no `path: 'settings'` exists anywhere under the backoffice route block. Genuinely missing, not a placeholder page to polish. +- **Diagnostics** — exists as `__diagnostics`, excluded from production builds (`environment.production` guard), not a backoffice/admin page. Skipped. +- Note: `docs/ADMIN.md` (Sprint 19) is stale — it labels Transactions/Customers/Orders/Media as "coming soon" placeholders. All are actually live-routed to real, built components as of the current branch. Audited as real pages, not noted as placeholders. +- `src/app/features/backoffice/{categories,customers,inventory,orders,products,settings}` is dead/unrouted duplicate code, superseded by `src/app/features/admin/*`. Not deleted (deletion is a separate call), flagged for follow-up cleanup. + +## Recurring problems found (same category, repeated across all three passes) + +1. **Undefined CSS theme variables** — `var(--x, #hexFallback)` referencing variable names that don't exist anywhere in `src/styles.scss` or theme files (`--danger-color`, `--brand-primary`, `--color-primary`, `--border-subtle`, `--surface-muted`, `--text-muted`, `--text-tertiary`). These silently resolved to their hardcoded hex fallback and never responded to tenant theming — the actual RC-relevant bug, not cosmetic. Fixed by remapping to real tokens (`--error-color`, `--primary-color`, `--border-color`, `--bg-tertiary`, `--text-secondary`, `--text-light`). +2. **Hand-rolled skeletons/spinners** instead of `app-skeleton`. +3. **Hand-rolled empty states** (`h1`/`h2`/`p`/`a`) instead of `app-empty-state`. +4. **Legacy global `.btn`/`.btn-primary`/`.btn-ghost`** (from `src/styles.scss`) running as a second parallel button system alongside `app-button`. +5. **Bare `` with no `scope="col"`**, breaking screen-reader table navigation. +6. **Dead CSS** — most notably an entire unused `.alt` cart theme (~530 lines, never applied by the template) in `cart.component.scss`, which was the direct cause of that file's pre-existing 40kB budget overrun. + +## Fixes applied by area + +### Storefront (`2e31e80`) +- Catalog, Product Details, Static Pages: replaced hand-rolled loading/error/empty markup with `app-skeleton` / `app-empty-state` / `app-button`; moved hardcoded hex to theme vars. +- Cart: removed dead `.alt` theme CSS (2242 → 1157 lines); cart chunk 89.49 kB → 59.39 kB; budget warning eliminated; empty-cart state componentized. +- Compare, Wishlist: legacy `.btn` classes → `app-button`; hand-rolled empty states → `app-empty-state`. +- Product Details loading: added a gallery+info skeleton layout with `sr-only` status text (previously a bare CSS spinner with no accessible label). + +### Builder (`4ebc15f`) +- Homepage/Widgets sections: added `app-empty-state` branches for the zero-content case (previously rendered nothing at all, no explanation). +- Navigation: added `aria-label` to icon-only move-up/move-down buttons. +- Static Pages tab: was using a dead CSS class (`.editor-section-card`, removed from the shared stylesheet after all other sections migrated to `app-section-card`) — silently missing all card chrome. Migrated to `app-section-card`. +- Save bar: every color was wired to nonexistent CSS variables (`--surface`, `--border`, `--warning`, `--danger`, `--muted-foreground`, `--info-bg`, `--info`) — fully disconnected from the theme. Remapped to real tokens. +- "Reset section" button: the one action button in the editor shell bypassing `app-button` — converted to ``, dead custom CSS removed. +- `section.shared.scss` + 3 section files: bare hex / undefined `--danger-color` → real theme vars. + +### Backoffice — Dashboard/Products/Categories/Orders (`712a7b4`) +- Confirmed `features/admin/*` is the live-routed implementation; `features/backoffice/*` (except `media` and `shared`) is dead duplicate code. +- 13 files: undefined theme vars → real tokens; `scope="col"` added to product/category/order tables. +- SEO-preview widget colors (Google SERP mimicry) and pill-radius fallback deliberately left as-is — intentional, not theme drift. + +### Backoffice — Transactions/Customers/Moderation/Users/Monitoring/Analytics (`63c9cee`) +- Same undefined-var remap pattern across 9 more files, most notably `admin-analytics-page.component.scss` (`--color-primary` used repeatedly for tabs, chart bars, focus rings — never defined). +- `scope="col"` added across ~35 more `` elements spanning transactions, customers, reviews, reports, users (2 tables), monitoring (2 tables), analytics (4 mini-tables). +- Confirmed no Settings route exists. + +## Remaining recommendations (not applied — flagged for follow-up, not composition bugs) + +- **Detail-page pattern inconsistency**: Order/Customer/Review detail pages all share the same pattern — hand-rolled `.card` divs and a plain `

{{ 'common.loading' | translate }}

` instead of `app-card`/`app-skeleton`. Left unchanged everywhere for consistency (fixing one would make it the odd one out among its siblings); recommend a single follow-up pass across all three detail pages together. +- **Bare `