Files

sdarbinyan 5374401257 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

7.2 KiB

Raw Blame History

Storefront Premium UX Review — RC-Premium-01

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).

7.2 KiB Raw Blame History