# Theme Commerce — Improvement & Growth Plan > Package: capell-app/theme-commerce · Kind: theme · Tier: premium · Product group: Capell Themes · Bundle: themes · Status: Complete ## 1. Snapshot Theme Commerce ("Editorial Commerce") registers theme key `commerce`, extends `default` (manifest says `capell-app/foundation-theme`), and ships a Blade renderer (`CommerceThemeServiceProvider` → `BladeThemeRenderer` with `page.blade.php` wrapper). It registers **22 section renderers** (`src/CommerceThemeServiceProvider.php` `sectionRenderers()`): navigation, hero, features→product-grid, content-listing→collections, product-finder, collections, product-grid, product-detail, mini-basket, comparison, catalog, lookbook, promotion, campaign, search, store-event, newsletter, buying-guide, proof, blog-teaser, cta, footer — backed by 23 Blade views under `resources/views`. Demo command `capell:theme-commerce-demo` delegates to `InstallCommerceThemeDemoAction` → Foundation `ThemeDemoPageInstaller` (seeds ≥7 pages). It is a **styling theme, not a commerce integration**: it renders content/section data only and never queries products itself. Integration with `shopify-commerce` is now a safe hydrated-data contract: product grid and PDP views accept Shopify-shaped featured image, variant, price/currency, option, handle, and availability arrays, while catalog can render synced product/variant/stock summary data when an upstream presenter provides it. `blog` availability still toggles `blog-teaser.blade.php`; `campaign-studio` and `media-library` availability feed promotion/lookbook views. Marketplace copy is buyer-facing, and the current committed screenshot set contains 10 route-backed light frontend captures from the real Commerce renderer; `capell.json` promotes the extension card plus homepage while deeper search/event/newsletter/campaign captures remain unpromoted page-composition evidence until those dedicated surfaces exist. ## Completed Improvement Slices - **2026-06-03:** Replaced marketplace plumbing copy with premium commerce positioning, limited marketplace screenshots to committed preview assets, declared optional package supports, documented the dual `extends` meaning, and replaced the stub health check with registration/view/vendor-asset diagnostics. - **2026-06-06:** Captured all 12 `docs/screenshots.json` route-backed targets through the Capell runner, then demoted the gallery after verifying the route renders the generic `theme-gallery` fixture rather than the package theme shell. - **2026-06-04:** Moved hero and catalog hard-coded English into translations, made hero trust badges data-driven with translated fallbacks, replaced the catalog carousel's theme-specific public selector with a generic selector, and added tests for those contracts. - **2026-06-07:** Added LCP image attributes to hero media, lazy/dimension/sizes attributes to product-grid media, fixed the mobile `
` marker utility, aligned manifest screenshot expectations with the promoted extension-card/homepage media policy, and added per-section render coverage plus a 20 ms render-budget guard. - **2026-06-07:** Added the dedicated `product-detail` (PDP) renderer with gallery media, pricing/compare-at state, variants, stock proof, basket CTA, recommendations, translated empty state, health-check coverage, and direct renderer tests. - **2026-06-07:** Added the `mini-basket` renderer plus navigation basket affordance, promotion countdown/data-code primitives, and proof ratings/review counts, with registry and public-output coverage. - **2026-06-07:** Routed Commerce Blade palette utilities through `--retail-*` tokens, added secondary warm/panel/deep tokens, and added a regression guard against arbitrary hex colour utilities in views. - **2026-06-07:** Recaptured all 10 light frontend screenshot targets through the Capell runner with the real Commerce renderer and visually reviewed the contact sheet; marketplace promotion remains intentionally limited to the strongest homepage capture. - **2026-06-07:** Added hydrated `search`, `store-event`, `newsletter`, and `campaign` section renderers to match the advertised Commerce layout set, with translated empty states and direct registry coverage. - **2026-06-07:** Added a token-driven dark-mode layer for the Commerce shell, inverting retail surface/panel/deep tokens and normalizing common white/stone utility surfaces under `.dark .retail-shell`. - **2026-06-07:** Rebuilt the comparison section as a real product comparison table and registered a generic Commerce carousel asset so catalog controls are visible, stateful, translated, and reduced-motion aware. - **2026-06-07:** Added Shopify-shaped hydrated render primitives for product cards, PDPs, and catalog sync panels: featured images, handles, variant option labels, price/currency, availability labels, and product/variant/stock counts now render without public Blade querying Shopify models. ## 2. Improvements (existing functionality) Prioritized. 1. **Route theme colours through tokens instead of hard-coded hex.** — Commerce section/blog views now use token-backed utilities (`bg-[var(--retail-ink)]`, `text-[var(--retail-accent)]`, etc.) instead of arbitrary hex colour utilities, with CSS variables for ink, primary, accent, surface, warm, panel, deep, and line colours. A unit guard scans views so the old palette utilities cannot drift back in. — `resources/views/**/*.blade.php`, `resources/css/theme-commerce.css`, `tests/Unit/CommerceThemeDefinitionTest.php` — **Done** 2. **Dark mode shipped through shell tokens.** — Commerce now supports `.dark .retail-shell` / `.retail-shell.dark` by inverting retail ink, muted, line, surface, warm, panel, and deep tokens, then normalizing common white/stone utility surfaces so existing section markup inherits the dark palette without adding per-view `dark:` churn. A unit guard proves the dark shell contract remains in `theme-commerce.css`. — `resources/css/theme-commerce.css`, `tests/Unit/CommerceThemeDefinitionTest.php` — **Done** 3. **Hero/catalog copy translated.** — Hero trust pill fallbacks and the catalog highlights panel now use `capell-theme-commerce::generic.*` translation keys, with regression tests covering the rendered strings. — `resources/views/sections/hero.blade.php`, `resources/views/sections/catalog.blade.php`, `resources/lang/en/generic.php`, `tests/Unit/CommerceThemeDefinitionTest.php` — **S** 4. **Hero trust badges are data-driven.** — The hero reads `$section->badges` when provided and falls back to translated retail badges, so custom page data can replace the stock trust copy without editing Blade. — `resources/views/sections/hero.blade.php` — **M** 5. **Mobile menu marker utility fixed.** — The mobile nav summary now uses `list-none` plus `[&::-webkit-details-marker]:hidden` instead of the invalid `marker:hidden` utility, with direct render coverage for the emitted class. — `resources/views/sections/navigation.blade.php`, `tests/Unit/CommerceThemeDefinitionTest.php` — **S** 6. **Comparison grid shipped.** — `comparison.blade.php` now renders a real table with option columns, feature/spec rows, prices, captions, and fallback summary criteria while preserving the old simple item data path. — `resources/views/sections/comparison.blade.php`, `tests/Unit/CommerceThemeDefinitionTest.php` — **Done** 7. **Catalog "Highlights" panel duplicates the connected/ready panel** — the right `retail-frame` panel and the inner dark panel both restate merchandising messaging with overlapping dark blocks; tighten to one panel or differentiate (e.g. live stock vs. value prop). — `resources/views/sections/catalog.blade.php:55-85` — **S** 8. **Image performance hints added.** — Hero media now includes explicit dimensions, eager loading, async decoding, `fetchpriority="high"`, and responsive `sizes`; product-grid images now include dimensions, lazy loading, async decoding, and responsive `sizes`. — `hero.blade.php`, `product-grid.blade.php`, `tests/Unit/CommerceThemeDefinitionTest.php` — **S** ## 3. Missing Features (gaps) Manifest `capabilities[]` is only `["theme-commerce","theme-commerce-frontend"]` (generic), so gaps are measured against what a retail site needs and against the package's own marketed promises. - **Advertised search/event/newsletter/campaign layouts shipped.** Commerce now registers hydrated `search`, `store-event`, `newsletter`, and `campaign` section renderers with package Blade views, translated empty states, and direct registry tests. They intentionally render supplied data rather than querying optional Search/Events/Newsletter/Campaign Studio packages from public Blade. — **table-stakes closed for advertised layouts.** - **Product-detail (PDP) layout shipped.** Commerce now registers a `product-detail` section/view with gallery media, price and compare-at pricing, variant chips, stock/trust proof, basket CTA, and recommended products. It remains hydrated-data driven rather than querying Shopify directly; deeper `shopify-commerce` model binding is future integration depth, not theme scope. — **differentiator + table-stakes closed.** - **Cart / checkout / mini-basket styling shipped.** Commerce now registers a hydrated `mini-basket` section with line items, media, subtotal, delivery note, and checkout CTA; navigation can also render a basket link/count affordance from render data. Cart drawer behaviour and direct Shopify cart binding are future integration work. — **table-stakes closed for theme rendering.** - **Promo/sale countdown primitives shipped.** `promotion.blade.php` now supports top-level countdown values/arrays and per-offer countdown/code/discount display, so campaign data can render sale urgency without authoring-specific markup. Announcement bars and richer segmented CTAs are future refinements. — **table-stakes closed for theme rendering.** - **Reviews/ratings primitives shipped.** `proof` can render rating and review-count data alongside existing proof metrics, while PDP trust items cover shipping/returns/checkout proof. Dedicated review-card and third-party review integration are future opportunities. — **differentiator closed at theme boundary.** - **Shopify-shaped hydrated rendering shipped.** Product grid and PDP views now consume upstream Shopify-style arrays for featured images, handles, variants/options, `priceAmount`/`priceCurrency` or snake-case equivalents, and `availableForSale`/`available_for_sale` stock states. Catalog can render synced product, variant, available-stock, and timestamp metrics. The theme still intentionally does not query `shopify-commerce` models from public Blade; a consuming presenter/action must hydrate the render data. — **differentiator closed at theme boundary.** - **Empty/zero-state coverage shipped for owned renderers.** Commerce renderers now expose translated empty states or safe placeholders for advertised surfaces, and tests cover the critical optional/static branches. Richer merchandising-specific empty states are future content polish. — **table-stakes closed.** ## 4. Issues / Risks - **Health check shipped.** `ThemeCommerceHealthCheck` now probes Theme Studio registration, required views, and vendor assets, with unit coverage for passing and failing registration states. Remaining opportunity: add a package-specific doctor command if direct console diagnostics become necessary. — `src/Health/ThemeCommerceHealthCheck.php`, `tests/Unit/ThemeCommerceHealthCheckTest.php`. - **Optional dependency metadata aligned.** `capell.json` now lists `blog`, `campaign-studio`, `media-library`, and `shopify-commerce` in `dependencies.supports`, matching the package availability checks in `sectionRenderers()`. — `src/CommerceThemeServiceProvider.php`, `capell.json`. - **Screenshot contract closed for current light frontend targets.** `docs/screenshots.json` declares the route-backed Commerce targets and the current 10 light frontend captures were regenerated through the real seeded Commerce renderer. `commerce-homepage-layout.png` is promoted in `capell.json`; deeper search/event/newsletter/campaign captures remain committed runner evidence but are intentionally not promoted until those package-specific surfaces exist. — `capell.json`, `docs/screenshots.json`. - **Dual `extends` meaning documented.** Manifest `extends: "capell-app/foundation-theme"` records package inheritance; `ThemeDefinitionData.extends = 'default'` records runtime theme-key inheritance, and the provider comment documents that distinction. — `src/CommerceThemeServiceProvider.php`, `capell.json`. - **Cache safety reconciled.** `capell.json` now keeps Commerce theme output non-cacheable, varies by site/locale, has empty invalidation sources, and sets `queueInvalidation: false`, matching the renderer's hydrated-data/no-query boundary. — `capell.json`. - **`frontendRenderBudgetMs: 20` is covered.** A warmed hydrated Commerce page render is now asserted under the manifest's 20 ms frontend budget using package renderers and hydrated section data. — `capell.json`, `tests/Unit/CommerceThemeDefinitionTest.php`. - **Renderer failure policy accepted.** `CatalogSectionRenderer`/`BlogTeaserSectionRenderer` are registered with `failLoudly: true`, so package-owned runtime failures surface during rendering instead of silently blanking sections. Adding logging to the non-loud fallback path would be future hardening. — `src/Rendering/*.php`. - **Public-output safety: covered.** `tests/Unit/PublicOutputSafetyTest.php` asserts no DB calls (`DB::`, `::query(`, `loadMissing(`, `Frontend::`, etc.) and no authoring/leak tokens (`wire:`, `data-field`, `model_id`, `signed`, `permission`, package name) in views+lang. `page.blade.php` renders pre-built `$content` and brand tokens only. This is solid; keep new sections inside the same test. - **WCAG/dark-mode work closed for current roadmap.** Commerce ships focus-visible styles, a skip link, dark token layers, comparison-table semantics, and reduced-motion-aware carousel controls. Further catalog-control polish is future UI depth rather than an open improvement-plan row. — `catalog.blade.php`, `product-grid.blade.php`, `theme-commerce.css`. - **Dark-mode token layer shipped.** The shell now has `.dark` support through retail tokens, including dark surface/panel/deep values, common white/stone utility overrides, frame/input treatment, and package tests guarding the contract. Remaining WCAG work is narrower carousel/control polish rather than absence of a dark rendering strategy. — `resources/css/theme-commerce.css`, `tests/Unit/CommerceThemeDefinitionTest.php`. - **Carousel accessibility slice shipped.** Commerce now registers `resources/js/theme-commerce.js` as a build asset. The script initializes generic `[data-carousel]` regions, respects `prefers-reduced-motion`, updates `aria-disabled`, and writes status text. Catalog controls are visible/stateful with translated labels and an `aria-live` status region instead of hidden raw glyph buttons. — `src/CommerceThemeServiceProvider.php`, `resources/js/theme-commerce.js`, `resources/views/sections/catalog.blade.php`, `tests/Unit/CommerceThemeDefinitionTest.php`. - **Section render coverage widened.** Tests now cover registration, definition keys, demo command, output safety, optional integration branches, catalog/blog-teaser/lookbook/promotion/buying-guide/product-detail, feature/content-listing fallbacks, hero image attributes, product-grid/PDP image attributes, direct navigation/comparison/proof/cta/footer renders, and the 20 ms render-budget guard. Remaining gaps are larger feature surfaces rather than basic renderer coverage. — `tests/Unit/CommerceThemeDefinitionTest.php`, `tests/`. - **Advertised layout coverage shipped.** Tests now cover `search`, `store-event`, `newsletter`, and `campaign` renderer registration, populated output, empty states, image attributes, and public-output safety. — `src/CommerceThemeServiceProvider.php`, `resources/views/sections/{search,store-event,newsletter,campaign}.blade.php`, `tests/Unit/CommerceThemeDefinitionTest.php`. ## 5. Marketplace & Selling **Original `summary` critique:** _"Retail buying-path theme screenshots from route-backed demo layouts."_ — this screenshot-pipeline copy has been replaced with the buyer-facing summary below. The package composer description remains short, but the manifest description and marketplace description now carry the stronger positioning. **Improved 1-sentence summary:** > A premium, conversion-focused retail theme for Capell — image-led catalog, product discovery, social proof, and buying-guide layouts that turn browsing into baskets. **Improved 3–4 sentence description:** > Editorial Commerce is a premium Capell theme built for retail and e-commerce storefronts that need to feel like a buying journey, not a styled brochure. It ships an image-led hero, product finder, collection and product grids, comparison and proof sections, buying-guide editorial, and conversion CTAs — all driven by hydrated render data with zero database access in public Blade. Pair it with Capell Shopify Commerce to light up connected-catalog merchandising panels, and with Blog for buying-guide content that supports purchase decisions. Warm editorial direction (deep ink, forest-green merchandising, coral action accents) and a token-driven design system keep every store on-brand while staying fast and accessible. **Screenshot/media gaps:** the static gallery is closed for the current light frontend contract: all current frontend targets were recaptured through the real Commerce renderer, and the homepage capture is promoted. Future work should deepen fixtures before promoting search/event/newsletter/campaign behaviour that still depends on generic page composition rather than dedicated Commerce renderers (Section 3). Completed 2026-06-07. Every prioritized roadmap row is closed. Theme Commerce now has real health diagnostics, buyer-facing marketplace copy, route-backed renderer captures, tokenized/dark styling, translated/data-driven retail sections, PDP/mini-basket/promotion/review primitives, optional integration branches, render-budget coverage, and Shopify-shaped hydrated rendering without public Blade queries. **Differentiation & bundling:** vs. sibling content themes (Agency, Corporate) this is the only retail/buying-path theme — lean into PDP, cart, promo/countdown, and reviews to make that real. The natural commercial bundle is **theme-commerce + shopify-commerce (+ payments)** sold as a "Capell Storefront" pack; today the Shopify tie is one boolean, so the bundle story is weak until deeper integration lands (Section 3). **Target buyer:** retail/DTC store owners and agencies launching a Capell storefront who want a polished, conversion-oriented design without bespoke front-end work. **Keywords/tags:** ecommerce theme, retail theme, storefront, product grid, catalog, conversion, shopify, buying guide, lookbook, merchandising, collections, premium Capell theme. ## 6. Prioritized Roadmap | Item | Bucket | Effort | Impact | Section ref | | -------------------------------------------------------------------------------------------------------------------------------- | ------ | ------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Implement real `ThemeCommerceHealthCheck` (or downgrade severity) | Done | S | High | 4 | | Replace generic `theme-gallery` fixture PNGs with real Commerce renderer captures; reconcile `capell.json` vs `screenshots.json` | Done | M | High | 4, 5 — closed 2026-06-07: all 10 light frontend targets were recaptured through the real Commerce renderer and visually reviewed; marketplace promotion remains conservative. | | Translate hard-coded hero/catalog English strings | Done | S | Med | 2 | | Rewrite `summary` + manifest description | Done | S | High | 5 | | Declare `campaign-studio` + `media-library` in `capell.json` supports | Done | S | Med | 4 | | Resolve `extends` (`foundation-theme` vs `default`) | Done | S | Med | 4 | | Reconcile cacheSafety contradiction | Done | S | Med | 4 — closed 2026-06-05: the manifest now keeps non-cacheable theme output from queueing invalidation when no invalidation sources are declared, with regression coverage. | | Replace 106 hard-coded hex utilities with theme tokens | Done | L | High | 2 — closed 2026-06-07: Commerce views now route palette utilities through `--retail-*` tokens with a regression guard against arbitrary hex utilities. | | Build product-detail (PDP) section + view | Done | L | High | 3 — closed 2026-06-07: `product-detail` now renders gallery media, pricing, variants, stock/trust proof, basket CTA, recommendations, empty state, and tests. | | Add cart/mini-basket + promo/countdown + reviews/ratings components | Done | L | High | 3 — closed 2026-06-07: `mini-basket`, navigation basket affordance, promotion countdown/code display, and proof ratings/review counts now render from hydrated data. | | Add per-section render tests (hero, nav, comparison, proof, cta, footer) + render-budget test | Done | M | Med | 4 — closed 2026-06-07: direct section render coverage, image-attribute assertions, and a warmed 20 ms page render-budget guard now ship. | | Make hero trust badges data-driven | Done | M | Med | 2 | | Add dark mode variants/tokens | Done | L | Med | 2 — closed 2026-06-07: `.dark .retail-shell` now inverts Commerce tokens and common section utility surfaces, with regression coverage. | | Build search/event/newsletter/campaign sections to match advertised SVGs (or remove SVGs) | Done | L | Med | 3 — closed 2026-06-07: `search`, `store-event`, `newsletter`, and `campaign` renderers now ship with hydrated-data views, translated empty states, and direct tests. | | Deepen `shopify-commerce` integration (price/variant/stock via hydrated data) | Done | L | High | 3 — closed 2026-06-07: product grid, PDP, and catalog now render Shopify-shaped hydrated image, handle, price/currency, variant/option, availability, and sync-summary data without public Blade queries. | | Real multi-column comparison grid + carousel keyboard a11y | Done | M | Med | 2, 4 — closed 2026-06-07: comparison now renders a real table and catalog carousel controls are backed by a generic reduced-motion-aware Commerce asset. |