Files
marketplaces/docs/archive/STORE_FRONT_UX_REVIEW.md

70 lines
7.2 KiB
Markdown
Raw Normal View History

# Storefront Premium UX Review — RC-Premium-01
docs: consolidate documentation and archive temporary reports Step 1-2 (audit + plan): classified 35 project markdown files into Core/Architecture/ADR/Temporary-audit/Sprint-report/Generated-review/ Duplicate/Obsolete/Historical. Agent-tooling files (.agents/skills/**, .superpowers/**, docs/context/**, CLAUDE.md/GEMINI.md/AGENTS.md/ .github/copilot-instructions.md) explicitly out of scope — intentional per-tool duplication, not documentation debt. Step 3 (merge, no information lost): - docs/PROJECT.md -> docs/PROJECT_INDEX.md, rewritten as the single entry point: system overview, living-doc index, archive pointer, current status, and a critical-finding callout up top. - docs/backend/BACKEND-INTEGRATION.md -> docs/BACKEND_API.md, docs/backend/REMAINING-BACKEND-WORK.md -> docs/BACKEND_API_REMAINING_WORK.md (also folded in a legitimate uncommitted status update that had been sitting unstaged all session: categories marked DONE, order-creation endpoint noted done). - RELEASE-NOTES.md merged into CHANGELOG.md (was a near-duplicate of the same release content in friendlier prose), then deleted. - KNOWN-ISSUES.md: added item 13 (see below) and item 14 (missing canDeactivate on admin/products edit, from the archived PROJECT-STATE audit, re-verified still true); added a correction note to Fixed item 7. - All cross-references to renamed/moved files fixed across every kept doc (grep+sed pass, then verified with a link-existence check across all 58 in-scope markdown files -> 0 broken links). Step 4 (archive, nothing deleted without merging first): created docs/archive/, moved 19 files there (3 root sprint reports, 1 platform report, SPRINT-PLAN.md, and 14 one-off audit/review/report docs). Added correction headers to the 3 archived docs whose conclusions were affected by the finding below, rather than silently leaving them misleading. Step 5: docs/PROJECT_INDEX.md rewritten per the mission brief - someone opening the repo should understand the whole system from it. IMPORTANT FINDING (surfaced during this audit, not the mission's primary goal but too significant to bury): pages/category/*, pages/search/*, pages/item-detail/*, pages/info/**, pages/legal/** (40+ files) are entirely unrouted dead code - app.routes.ts's cmsContentRoutes is a literal empty array, and category/search/product routes redirect to CatalogContainerComponent/ ProductDetailsContainerComponent, not these files. Confirmed against app.routes.ts directly and cross-checked against FRONTEND.md's own routing description. This means several fixes from earlier this cycle (RC-Premium-01, RC STORE-01) and the dead-code cleanup sprint's conclusion that these files were live were all wrong - documented as KNOWN-ISSUES.md item 13, flagged at the top of PROJECT_INDEX.md, and noted on the 3 archived docs whose conclusions it affects. No application code was changed to fix this (out of scope per this session's 'documentation only' constraint) - it needs a wire-it-up-or- delete-it decision first. Verification: tsc --noEmit clean, npm run build green, all markdown links across 58 in-scope files resolve (checked programmatically). No application/Angular/backend code modified. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-25 19:10:49 +04:00
> **Archived, correction (2026-07-25):** the FAQ/legal-page polish below was applied to `pages/info/**`/`pages/legal/**`, which turned out to be unrouted dead code (the CMS static-page renderer serves these routes in production, not these components) — see `docs/KNOWN-ISSUES.md` item 13. Kept here for historical accuracy.
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).