marketplaces/docs/Catalog-UX-Architecture.md

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