marketplaces/docs/UI-DESIGN-REVIEW.md

UI Design System Finalization — RC Final Polish

Scope: token infrastructure + mechanical, value-preserving normalization of typography/radius/spacing across storefront, builder, and backoffice. Architecture, routing, facades, providers, and business logic were left untouched, per instructions. This pass builds on the icon standardization work (see docs/UI-ICON-AUDIT.md) and the earlier storefront/admin polish passes (docs/STORE_FRONT_REVIEW.md, docs/ADMIN_REVIEW.md) — it does not redo that work.

No docs/DESIGN.md exists in this repo (confirmed in docs/STORE_FRONT_REVIEW.md); impeccable hook findings referencing it were treated as inapplicable noise throughout, same precedent as the prior pass.

Before

• src/styles.scss had a color/shadow/radius/spacing token set (--primary-color, --radius-sm..xl, --space-xs..xl, --shadow-sm..lg) but no typography scale at all — no font-size, font-weight, or line-height tokens.
• Font sizes were hand-written per component. A repo-wide scan found 24 distinct font-size values in simultaneous use for what was clearly the same handful of intended sizes: 0.7/0.72/0.75/0.78/0.8/0.8125/0.85/0.875/ 0.9/0.9375/0.95/1/1.05/1.1/1.125/1.15/1.2/1.25/1.3/1.35/1.4/1.5/1.75/2rem (plus a handful of raw px values), spread across 104 of 136 component SCSS files.
• Font-weight was always a raw literal (400/500/600/700), never a token.
• border-radius had the same drift: 72 of 136 files used raw px values instead of the existing --radius-* tokens; two "shape" values in constant use — 4px (small chips/badges) and 999px (pills/toggles) — had no token at all, so every pill/chip component reinvented 999px by hand (41 occurrences) or 4px (9 occurrences).
• src/app/shared/ui/* — the actual shared component library used across admin/builder/backoffice (button, input, select, badge, card, table, dialog, etc.) — was already internally consistent (button and input both used a matching 32/40/48px sm/md/lg scale with 0.8125/0.9375/1rem font sizes) but expressed every value as a hand-written literal rather than a token, and one file (section-card.component.scss) had drifted from its sibling card.component.scss (16px/18px/14px raw vs. --radius-lg/ --space-*).
• code-editor.component.scss's focus state used a hardcoded #497671 (the dexar tenant's primary color) instead of var(--primary-color) — it would not have adapted if a tenant switched to the lavero or novo theme.

After

Tokens introduced (src/styles.scss)

--font-size-xs: 0.75rem     (12px)
--font-size-sm: 0.8125rem   (13px)
--font-size-base: 0.875rem  (14px)
--font-size-md: 0.9375rem   (15px)
--font-size-lg: 1rem        (16px)
--font-size-xl: 1.125rem    (18px)
--font-size-2xl: 1.25rem    (20px)
--font-size-3xl: 1.5rem     (24px)
--font-size-4xl: 2rem       (32px)

--font-weight-normal: 400
--font-weight-medium: 500
--font-weight-semibold: 600
--font-weight-bold: 700

--line-height-tight: 1.2
--line-height-normal: 1.5
--line-height-relaxed: 1.6

--space-2xl: 48px   (new, extends the existing xs/sm/md/lg/xl scale)
--space-3xl: 64px   (new)

Tokens added to all three theme files (src/styles/themes/*.theme.scss)

--radius-xs: 4px      (dexar/lavero/novo — chip/badge corner radius)
--radius-full: 999px  (dexar/lavero/novo — pill/toggle shape)

The scale steps were chosen to match sizes already in wide use (button/input sm|md|lg already used 0.8125/0.9375/1rem) so most components could adopt the tokens by direct substitution rather than a visual redesign.

Files touched, by phase

Global base (src/styles.scss) — body, h1–h6, p, small, the .btn/.mt-*/.mb-*/.p-* utility classes, and the shared .item-badge/.item-tag/.item-simple-desc classes now reference the new tokens instead of literals.

Shared component library (18 files, hand-reviewed, not mechanical) — src/app/shared/ui/{button,input,select,badge,card,section-card,table,dialog, empty-state,form-field,pagination,toggle,image-field,key-value-editor, locale-tabs,color-picker,code-editor,skeleton}/*.component.scss. Fixes made along the way:

• code-editor.component.scss: hardcoded #497671 focus color → var(--primary-color) — now adapts correctly across tenant themes.
• section-card.component.scss: raw 16px/18px/14px radius/padding → var(--radius-lg)/var(--space-*), matching the sibling card component.
• toggle/badge/item-tag: raw 999px → the new --radius-full token.

App-wide mechanical rollout (89 files touched across storefront, builder, and backoffice) — three scripted, value-preserving sweeps:

1. font-size: <literal>; → var(--font-size-STEP, <same-or-nearest-step>); for every literal that matched (or was within ~0.03rem/1px of) one of the 9 scale steps. Values within that tolerance were snapped to the nearest step to consolidate near-duplicates (e.g. 0.85rem and 0.8rem both → --font-size-sm/0.8125rem).
2. border-radius: <literal>; → token, but only for the 5 values that exactly match a token everywhere (4px, 8px, 12px, 13px, 999px). 20px/16px/10px/6px/3px/2px/14px/24px/19px were deliberately left alone (see Remaining issues).
3. font-weight: <literal>; → token (400/500/600/700), value-preserving.

Each sweep was applied with sed, spot-checked against git diff for correctness, then verified with a full ng build --configuration=production (exit 0) before committing. Five commits total, one per phase/sweep, each independently buildable and revertable.

Remaining issues (deferred, not fixed in this pass)

• Spacing (margin/padding) was not mechanically swept. The existing --space-xs..3xl scale covers gaps and simple paddings, but margin/padding shorthand comes in 1/2/3/4-value forms that aren't safe to regex-replace without risking silently changing box models on components that use asymmetric shorthand. This needs a manual, component-by-component pass — recommended as the next follow-up, using the same --space-* scale already established.
• border-radius values with no exact token match (20px × 9, 16px × 7, 10px × 38, 6px × 9, 3px × 4, 2px × 3, 14px, 24px, 19px) were intentionally left as literals. Several of these (10px, 6px) are common enough that a --radius-2xs/intermediate step might be warranted, but adding one now without a design call would be inventing a new shape rather than normalizing existing ones — flagged for the design owner rather than decided unilaterally.
• Phases 5–9 (cards, tables, status system, animations, accessibility) were not addressed as dedicated passes in this session. The shared/ui card, table, dialog, badge, and skeleton components are already reasonably unified (see "After" above) since they're single shared components consumed everywhere, but a full per-surface audit (storefront product cards, admin dashboard cards, builder panel cards; every table's sticky-header/hover/selection/density behavior; a single status-badge language for success/warning/error/draft/published/archived/pending) was out of reach in this pass and should be scoped as its own follow-up.
• Status system: no unified success/warning/error/draft/published/etc. visual language audit was performed. The app-badge component has --neutral/primary/success/warning/danger/info variants already, but whether every surface (storefront order status, admin order/review status, builder publish state) actually uses app-badge rather than a hand-rolled span was not verified in this pass.
• Animations: not audited in this pass beyond what already existed (the codebase already has a global prefers-reduced-motion neutralizer in src/styles.scss and per-component reduced-motion overrides in most shared/ui components — this predates this session).
• Accessibility: not audited in this pass; the prior STORE_FRONT_REVIEW.md and UI-ICON-AUDIT.md passes already covered a a11y pass on the storefront and icon-only buttons respectively. No new a11y work was done here.
• cart.component.scss now sits ~771 bytes over its anyComponentStyle budget warning (40kB) due to the added var(...) string length from the font-weight sweep. This is a maximumWarning, not maximumError (angular.json budgets: initial 700kB warn / 1.5MB error, component style 40kB warn / 50kB error), so the build still exits 0 — but it's worth either trimming the file or bumping its allotment slightly in a follow-up.
• Tenant brand colors (src/styles/themes/{dexar,lavero,novo}.theme.scss) and badge accent colors (.item-badge.badge-new/sale/exclusive/... and code-editor syntax-highlight colors .cm-*) were intentionally left untouched — these are per-tenant palettes / syntax-token colors, not design-system drift.

Recommendations

1. Next pass: spacing. Do a manual, per-surface sweep of margin/padding using the existing --space-xs..3xl scale, prioritizing the same high-traffic files already touched here (shared/ui, then catalog/product-details/cart on storefront, then admin dashboard/list pages).
2. Decide on the missing radius steps (10px, 6px) with the design owner — either add --radius-2xs/an intermediate token, or confirm they should collapse into --radius-xs/--radius-sm and re-run the same mechanical sweep pattern used in this session (sed + ng build + commit per phase).
3. Status system audit: grep for hand-rolled status spans/badges outside app-badge across admin (orders, reviews, moderation) and storefront (order tracking) and consolidate onto the existing app-badge variants.
4. Cards/tables surface audit: now that card/section-card/table are internally token-consistent, verify every page-level "card" and "table" actually composes these shared components rather than hand-rolling similar-looking markup — this is the highest-leverage next step for phases 5–6 since the primitives are already unified.