fixes

docs/Catalog-UX-Architecture.md

@@ -0,0 +1,104 @@
+# Catalog UX, Navigation and Loading Strategies - Sprint 16
+
+## Scope
+
+Sprint 16 improves catalog UX without introducing marketplace-specific logic.
+
+Areas covered:
+- empty category behavior
+- root navigation consistency
+- multiple loading strategies
+- grid selector completion
+- mobile catalog behavior
+- future slug routing preparation
+- reusable catalog states
+- centralized feature flags
+- project skills documentation
+
+## Empty Category Behavior
+
+Catalog now distinguishes three category outcomes:
+- subcategories exist: show category browser
+- products exist: show product list
+- neither exist: show dedicated catalog empty state
+
+Empty category state belongs to catalog surface, not product grid.
+
+## Root Navigation
+
+`All Categories` always routes to `/catalog` and shows category browser.
+
+Continue-browsing restoration no longer hijacks this root navigation path.
+
+## Loading Strategies
+
+Configured via `catalog.loadingStrategy`:
+- `pagination`
+- `loadMore`
+- `infiniteScroll`
+
+Single product list component remains source of truth. Strategy changes only affect controls and page-windowing.
+
+## Grid System
+
+Supported layouts:
+- `grid-2`
+- `grid-3`
+- `grid-4`
+- `list`
+- `compact`
+
+User preference persists locally. Bootstrap default still seeds first render.
+
+Legacy layout aliases normalize to new modes for backward compatibility.
+
+## Mobile Behavior
+
+Mobile catalog uses:
+- filter drawer
+- sort popup sheet
+- grid popup sheet
+
+Inline filter density is avoided.
+
+## Breadcrumb and Slug Preparation
+
+Current URLs remain ID-based.
+
+Routing layer now tolerates future slug-like category tokens by resolving them to internal IDs without changing current public contract.
+
+## Centralized Features
+
+`bootstrap.features` is new central toggle surface for UI features such as:
+- wishlist
+- compare
+- reviews
+- comments
+- questions
+- recommendations
+- recentlyViewed
+- searchHistory
+- recentlySearched
+- ratings
+- share
+- brands
+- manufacturers
+- availability
+- discounts
+- badges
+
+Feature resolver falls back to older config surfaces to preserve behavior.
+
+## Project Skills
+
+Added repo skills:
+- `.agents/skills/marketplace-architecture/SKILL.md`
+- `.agents/skills/ui-standards/SKILL.md`
+- `.agents/skills/backend-contract/SKILL.md`
+
+## Future Work
+
+- true backend paging for load-more/infinite strategies
+- offline-aware cached catalog data
+- explicit slug field on categories
+- admin editing surface for centralized feature toggles