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

8.0 KiB

Raw Blame History

UI Composition Review — RC-Visual-02 Page Composition Audit

Audit of every live page against the finished design system. No redesign, no business-logic changes, no new features — layout/spacing/hierarchy/alignment/state-composition fixes only, reusing existing shared components (src/app/shared/ui/*).

Executed as four sequential commits on branch B2B (not pushed):

Commit	Scope
`2e31e80`	Storefront
`4ebc15f`	Builder / Project Editor
`712a7b4`	Backoffice: Dashboard, Products, Categories, Orders
`63c9cee`	Backoffice: Transactions, Customers, Moderation (Reviews/Reports), Users, Monitoring, Analytics

npm run build verified green after every commit. Baseline warning (pre-existing, unrelated to this work) remains: initial bundle 768.57 kB vs 700 kB budget.

Pages audited

Storefront — Home, Catalog, Search, Product Details, Cart, Compare, Favorites/Wishlist, Static Pages (public renderer).

Builder — General, Branding, Theme, Homepage, Widgets, Navigation, Languages, Features, Preview, Static Pages/Content tab, Media Library, Save bar.

Backoffice — Dashboard, Products, Categories, Orders, Transactions, Customers (list + detail), Reviews/Moderation (list + reports queue + detail), Users, Monitoring, Analytics.

Not built / out of scope (confirmed via app.routes.ts, not assumed from stale docs):

Settings — no path: 'settings' exists anywhere under the backoffice route block. Genuinely missing, not a placeholder page to polish.
Diagnostics — exists as __diagnostics, excluded from production builds (environment.production guard), not a backoffice/admin page. Skipped.
Note: docs/ADMIN.md (Sprint 19) is stale — it labels Transactions/Customers/Orders/Media as "coming soon" placeholders. All are actually live-routed to real, built components as of the current branch. Audited as real pages, not noted as placeholders.
src/app/features/backoffice/{categories,customers,inventory,orders,products,settings} is dead/unrouted duplicate code, superseded by src/app/features/admin/*. Not deleted (deletion is a separate call), flagged for follow-up cleanup.

Recurring problems found (same category, repeated across all three passes)

Undefined CSS theme variables — var(--x, #hexFallback) referencing variable names that don't exist anywhere in src/styles.scss or theme files (--danger-color, --brand-primary, --color-primary, --border-subtle, --surface-muted, --text-muted, --text-tertiary). These silently resolved to their hardcoded hex fallback and never responded to tenant theming — the actual RC-relevant bug, not cosmetic. Fixed by remapping to real tokens (--error-color, --primary-color, --border-color, --bg-tertiary, --text-secondary, --text-light).
Hand-rolled skeletons/spinners instead of app-skeleton.
Hand-rolled empty states (h1/h2/p/a) instead of app-empty-state.
Legacy global .btn/.btn-primary/.btn-ghost (from src/styles.scss) running as a second parallel button system alongside app-button.
Bare <th> with no scope="col", breaking screen-reader table navigation.
Dead CSS — most notably an entire unused .alt cart theme (~530 lines, never applied by the template) in cart.component.scss, which was the direct cause of that file's pre-existing 40kB budget overrun.

Fixes applied by area

Storefront (`2e31e80`)

Catalog, Product Details, Static Pages: replaced hand-rolled loading/error/empty markup with app-skeleton / app-empty-state / app-button; moved hardcoded hex to theme vars.
Cart: removed dead .alt theme CSS (2242 → 1157 lines); cart chunk 89.49 kB → 59.39 kB; budget warning eliminated; empty-cart state componentized.
Compare, Wishlist: legacy .btn classes → app-button; hand-rolled empty states → app-empty-state.
Product Details loading: added a gallery+info skeleton layout with sr-only status text (previously a bare CSS spinner with no accessible label).

Builder (`4ebc15f`)

Homepage/Widgets sections: added app-empty-state branches for the zero-content case (previously rendered nothing at all, no explanation).
Navigation: added aria-label to icon-only move-up/move-down buttons.
Static Pages tab: was using a dead CSS class (.editor-section-card, removed from the shared stylesheet after all other sections migrated to app-section-card) — silently missing all card chrome. Migrated to app-section-card.
Save bar: every color was wired to nonexistent CSS variables (--surface, --border, --warning, --danger, --muted-foreground, --info-bg, --info) — fully disconnected from the theme. Remapped to real tokens.
"Reset section" button: the one action button in the editor shell bypassing app-button — converted to <app-button variant="danger" size="sm">, dead custom CSS removed.
section.shared.scss + 3 section files: bare hex / undefined --danger-color → real theme vars.

Backoffice — Dashboard/Products/Categories/Orders (`712a7b4`)

Confirmed features/admin/* is the live-routed implementation; features/backoffice/* (except media and shared) is dead duplicate code.
13 files: undefined theme vars → real tokens; scope="col" added to product/category/order tables.
SEO-preview widget colors (Google SERP mimicry) and pill-radius fallback deliberately left as-is — intentional, not theme drift.

Backoffice — Transactions/Customers/Moderation/Users/Monitoring/Analytics (`63c9cee`)

Same undefined-var remap pattern across 9 more files, most notably admin-analytics-page.component.scss (--color-primary used repeatedly for tabs, chart bars, focus rings — never defined).
scope="col" added across ~35 more <th> elements spanning transactions, customers, reviews, reports, users (2 tables), monitoring (2 tables), analytics (4 mini-tables).
Confirmed no Settings route exists.

Remaining recommendations (not applied — flagged for follow-up, not composition bugs)

Detail-page pattern inconsistency: Order/Customer/Review detail pages all share the same pattern — hand-rolled .card divs and a plain <p>{{ 'common.loading' | translate }}</p> instead of app-card/app-skeleton. Left unchanged everywhere for consistency (fixing one would make it the odd one out among its siblings); recommend a single follow-up pass across all three detail pages together.
Bare <select> filters (category/status/stock/sort/role/scope pickers) across Products, Orders, Users are not migrated to app-select. This was already a reviewed, deliberate decision per docs/ADMIN.md's Sprint 28 notes (aria-labels present) — left as-is.
Catalog toolbar buttons (.catalog-reset-btn, .catalog-save-search-btn, sort/grid sheet buttons) still hand-styled rather than app-button — carry active/selected-state styling not trivially portable; flagged as a larger follow-up.
Analytics lowStockProducts table has no loading-skeleton branch while topProducts (same facade signal) does — minor inconsistency, not fixed to keep the diff surgical.
SearchEmptyResultsComponent (src/app/features/search/components/empty-results/) is dead code, defined but never referenced — flagged for cleanup, not deleted (deletion is a separate decision).
features/backoffice/* dead duplicate code (categories, customers, inventory, orders, products, settings subfolders) — superseded by features/admin/*, candidate for removal in a dedicated cleanup pass.
Responsive breakpoints: all three passes worked from SCSS only, no browser available. Recommend a visual pass at mobile/tablet widths, particularly catalog's filter drawer/mobile toolbar and cart's swipe-to-delete interaction.
Payment modal spinners (.spinner-large/.spinner-small in cart) intentionally left as CSS spinners rather than app-skeleton — appropriate for an in-progress action state, not a content-loading placeholder.

Not audited

Settings — no page exists to audit.
Diagnostics — dev-only, excluded from production.

8.0 KiB Raw Blame History