marketplaces/docs/STORE_FRONT_REVIEW.md

# Storefront UI Polish — RC1 Review

Scope: production-ready UI/UX polish pass across the storefront, one page at a time.
Architecture, routing, facades, providers, APIs, and data models were left unchanged
per instructions. No `docs/DESIGN.md` exists in this repo, so `impeccable` design-hook
findings referencing it (font-size/radius/color "outside DESIGN.md") were treated as
inapplicable noise throughout — there's no design system file to violate.

## Pages reviewed

| Page | Commit | Status |
|---|---|---|
| Home | `fix(storefront): polish home` | done |
| Header | `fix(storefront): polish header` | done |
| Footer | `fix(storefront): polish footer` | done |
| Search | `fix(storefront): polish search` | done |
| Catalog | `fix(storefront): polish catalog` | done |
| Product Details | `fix(storefront): polish product-details` | done |
| Compare | `fix(storefront): polish compare` | done |
| Wishlist | — | reviewed, no changes needed |
| Cart | `fix(storefront): polish cart` | done |
| Checkout | — | no separate implementation (see below) |
| Static Pages | `fix(storefront): polish static-pages` | done |

## Improvements made

**Correctness bugs fixed:**
- **Catalog**: `app-catalog-empty-state` self-closed one line early in the
  empty-category state, leaving `(secondaryAction)="goToParentCategory()" />` as an
  orphaned line outside any tag. Angular rendered it as literal text on the page and
  the handler was never wired. Fixed and verified the component's `secondaryAction`
  output exists.
- **Cart**: the payment success checkmark (`✓`) and timeout clock (`⏱`) icons had been
  corrupted to literal `?` glyphs (confirmed via `git log -p` — both were replaced by
  `?` in a prior change). A customer who just paid saw a confusing `?` instead of a
  success indicator. Restored both icons and marked them `aria-hidden` since the
  adjacent heading already conveys the status in text.

**Accessibility:**
- Added `role="status"`/`aria-live="polite"` to loading states and `role="alert"` to
  error states on Home, Search, Product Details, and the CMS static-page loader —
  previously plain text with no announcement to screen readers.
- Added `:focus-visible` states where entirely missing: Footer nav links, Search retry
  button, Catalog empty-state actions/chips, Product Details buying-flow controls
  (add-to-cart/buy-now/wishlist/compare/share buttons, variant colour/size pickers,
  star rating selector), and the static-page 404 back-home link.
- Fixed a real keyboard-accessibility bug in the Header: mobile nav items (catalog,
  static pages) were `<a>` with no `href`, driven only by `(click)` — not reachable
  via Enter/Space and not exposed correctly to assistive tech. Converted to
  `<button type="button">`, matching the existing desktop nav-btn pattern.
- Search input had a placeholder but no accessible label — added `aria-label`.
- Cart icon-only buttons (quantity increase/decrease, mobile delete) had no
  accessible name at all; the desktop remove button relied on a `title` attribute
  only, which screen readers don't reliably announce. Added `aria-label` to all four,
  plus new `cart.increaseQuantity`/`decreaseQuantity` i18n keys (en/ru/hy).
- Compare's remove-from-list button rendered a bare `×` glyph with no label — added
  `ux.removeFromCompare` across all three locales.

**Dead code / duplication removed:**
- Home: ~900 lines of CSS from two superseded redesigns (`.alt-*`, `.platform-*`
  home layout) with zero template references — verified via grep before deletion.
- Header: ~495 lines of dead `.header`/`.alt-header` CSS from earlier redesigns,
  same verification approach. Only the current `.platform-*` classes are live.

**Loading/empty states:**
- Home's hardcoded "Loading homepage..." text replaced with a skeleton layout
  (`app-skeleton`) mimicking the hero + category grid; empty-config state now uses
  the shared `EmptyStateComponent` instead of raw text.

## Remaining issues (not fixed in this pass)

- **Product engagement components** (review-form, question-form, question-card,
  review-card, review-list, question-list, rating-summary, stars, product-tabs,
  product-gallery, product-description, product-specifications, product-warranty,
  related-products, delivery-information) still have **zero `:focus-visible` coverage**.
  This pass fixed the highest-traffic buying-flow controls (actions, variants, star
  selector) given scope/time; the remaining engagement-tab components should get the
  same treatment in a follow-up pass.
- Several icon SVGs in the Header (search icon, cart icon, mobile menu icons, chevrons)
  use hardcoded hex fills (`#576463`, `#1e3c38`, `#497671`, `#697777`, `#677B78`)
  instead of theme CSS custom properties (ADR-008 convention). They'll look correct in
  the current tenant theme but won't adapt if a tenant switches theme/dark mode.
  Recasting them to `currentColor` + a themed wrapper color was judged too broad a
  diff for a single-page polish pass — flagged here for a dedicated icon-theming pass.
- No `docs/DESIGN.md` exists. If the team wants literal design-system enforcement
  (type ramp, radius scale, color palette) going forward, that file needs to be
  authored — the `impeccable` hook is currently flagging pre-existing values against
  a document that was never created.

## Optional future improvements (post backend-integration)

- Cart quantity controls, search-box, and header search box are all separate hand-rolled
  implementations; once the design system stabilizes, consider consolidating around a
  shared input/stepper component to reduce drift.
- Home's skeleton loading state is hand-built to approximate the hero+grid layout;
  once real component boundaries for the dynamic homepage are finalized, this could
  move to per-widget skeleton placeholders resolved by the widget host itself.