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 <details> 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.

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
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
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
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
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
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
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
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.