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

5.7 KiB

Raw Blame History

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.

5.7 KiB Raw Blame History Unescape Escape