From 18beb7b7a100554ca5084fdbe5676e746231938b Mon Sep 17 00:00:00 2001
From: sdarbinyan <sdarbinyan@4pay.ru>
Date: Thu, 23 Jul 2026 12:08:21 +0400
Subject: [PATCH] docs: add STORE_FRONT_UX_REVIEW.md for RC-Premium-01 audit

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/STORE_FRONT_UX_REVIEW.md | 67 +++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/STORE_FRONT_UX_REVIEW.md

diff --git a/docs/STORE_FRONT_UX_REVIEW.md b/docs/STORE_FRONT_UX_REVIEW.md
new file mode 100644
index 0000000..7b4665e
--- /dev/null
+++ b/docs/STORE_FRONT_UX_REVIEW.md
@@ -0,0 +1,67 @@
+# Storefront Premium UX Review — RC-Premium-01
+
+Follow-up to `docs/UI-COMPOSITION-REVIEW.md` (RC-Visual-02). That sprint fixed *composition* bugs — undefined theme variables, hand-rolled skeletons/empty-states replaced with shared components, missing `scope="col"`. This sprint (RC-Premium-01) is a narrower, purely *visual/interaction* polish pass on top of that clean baseline: hierarchy, spacing, states, motion, accessibility signaling. No redesign, no business-logic changes, no route changes, no new components — reuses `src/app/shared/ui/*` and the existing token set in `src/styles.scss` exclusively.
+
+Executed as four sequential commits on branch `B2B` (not pushed):
+
+| Commit | Scope |
+|---|---|
+| `9ea8c98` | Home, Catalog, Search |
+| `ea1a5d9` | Product Details, Compare, Wishlist |
+| `9956020` | Cart, Checkout |
+| `d5603c2` | Static / Legal / Info pages |
+
+`npm run build` verified green after every commit. Baseline bundle-budget warning (pre-existing, unrelated) persists.
+
+## Pages audited
+
+Home, Catalog (grid, filters, sorting, layout switcher), Search (bar, results, trending, empty state), Product Details (gallery, info, actions, description, specs, warranty, delivery, related products, variant selector, reviews/questions/ratings), Compare, Wishlist, Cart (line items, quantity, summary, payment modal, QR/bank-payment flow), Checkout (no separate route — the payment section within Cart), Static Pages (FAQ, About, Contacts, Delivery, Guarantee, legal pages, CMS-driven static-page renderer).
+
+**Not touched, with reason:**
+- `src/app/pages/item-detail/*` — confirmed dead/unrouted code.
+- Wishlist page and `product-details-container` — already fully composed with shared components from RC-Visual-02, nothing to add.
+- Contacts page — no form exists to polish.
+- About/Delivery/Guarantee/Company-details/Payment-terms/Privacy-policy/Public-offer/Return-policy — already token-clean, no accordion/form elements in scope.
+
+## Recurring theme: color-only signaling
+
+The single most common finding across every area: state was communicated by color alone (selected swatch = border color change only, active tab = background color only, active sort/layout = highlight color only). Fixed everywhere it appeared by pairing color with a second signal — `aria-pressed`, `aria-current`, `aria-selected`, `aria-live`, or a visible checkmark/icon — so the same state is legible to screen readers and to users with color-vision deficiency, not just sighted mouse users.
+
+## Fixes applied by area
+
+### Home, Catalog, Search (`9ea8c98`)
+- Hardcoded hex across `product-card`, `category-grid`, catalog filters/results normalized to design tokens; stock/discount indicators moved to semantic `--success-color`/`--warning-color`/`--error-color`.
+- Color/size/rating filter chips, layout-switcher buttons, mobile sort/grid sheet options get `aria-pressed`/`aria-current`; selected color swatch gets a checkmark + ring instead of border-color-only.
+- Add-to-cart hover, card hover shadow, favorite/compare toggle buttons (`aria-pressed`) polished with existing `--transition-*`/`--shadow-lg` tokens.
+- Home loading/empty spacing converted to `--space-*` tokens.
+
+### Product, Compare, Wishlist (`ea1a5d9`)
+- Hardcoded hex to tokens across gallery, actions, description, related-products, variant-selector, and engagement components (tabs, reviews, questions, star-selector).
+- `aria-pressed` on wishlist/compare toggles and variant buttons; checkmark on selected color swatch; `aria-current`+`aria-label` on active gallery thumbnail; `role="tab"`/`aria-selected` on product tabs; per-star `aria-label` on star-selector (new `starsLabel` i18n key added to en/hy/ru); `aria-expanded` on ask-question disclosure.
+- Hover/focus-visible/active/disabled states added across action buttons, gallery thumbnails/toolbar, pager/load-more, form inputs.
+- Review-list and question-list empty text replaced with shared `app-empty-state`.
+- Compare table: `scope="col"`/`scope="row"`, sticky header + sticky attribute column, polished remove-chip hover/focus.
+
+### Cart, Checkout (`9956020`)
+- Hardcoded hex normalized to tokens across line items, quantity controls, summary, login gate, terms checkbox, payment modal, QR/payment-active screen, bank-payment iframe overlay; deduplicated a repeated `.close-modal-btn` rule.
+- `focus-visible` rings added to every interactive control in the flow (clear-cart, remove-item, quantity stepper, checkout/QR/card buttons, close-modal, retry-payment, copy/open-link, telegram-login).
+- Delivery-required warning now pairs an icon + `role="alert"` with the text; quantity value gets `aria-live="polite"` + `aria-label` so screen readers announce changes.
+- `delivery-selector`: tokens normalized, hover/focus-visible added to the `<select>`, dead `:host-context(.cart-container.alt)` rule removed (orphaned by RC-Visual-02's `.alt` theme deletion).
+
+### Static Pages (`d5603c2`)
+- FAQ entries converted from always-expanded static blocks to native `<details>/<summary>` disclosures, reusing the existing global chevron pattern in `styles.scss` rather than a new accordion component.
+- `shared-legal.scss` (shared by every info/legal page): `transition: all 0.3s ease` sites normalized to `--transition-normal`; prose capped at `max-width: 70ch` for readable line length.
+- CMS-driven static-page renderer (`src/app/pages/static-page/`): spacing moved to `--space-*` tokens, prose capped at 70ch, and real styling added for headings/lists/links/images/blockquote/table — previously only `h2`/`h3` margins were styled for arbitrary `[innerHTML]` CMS content.
+
+## Remaining recommendations (not applied — flagged for follow-up, not this pass's scope)
+
+- **Payment modal / bank-payment iframe** could move to shared `app-dialog`, but it carries custom multi-step state and its own focus-trap already — a composition change, not visual polish.
+- **`clearCart()`'s native `confirm()`** could become a custom confirm-remove dialog, but no existing storefront pattern exists to follow yet — first instance would be an architecture decision.
+- **Cart's `.email-form` block** (post-payment email/phone capture) is dead CSS behind commented-out markup — candidate for deletion in a cleanup pass.
+- **`pages/category` and `pages/search`** still use hand-rolled skeleton markup instead of `app-skeleton` — replacing that is a composition fix (RC-Visual-02 territory), not covered here.
+- **`stars.component` rating glyph color** and a few legacy hex literals in `pages/category`/`pages/search` have no exact token match — left as-is to avoid an unintended visual shift; worth a deliberate token-extension decision later.
+- **Responsive verification**: all four passes worked from source/SCSS with build checks only; no browser was available in this session. Recommend a visual QA pass at mobile/tablet widths, particularly the FAQ accordion, compare table's sticky column, and cart's payment modal.
+
+## Not audited
+
+- Same exclusions as RC-Visual-02: **Settings** (no route exists), **Diagnostics** (dev-only, excluded from production).