Theme Agency — Improvement & Growth Plan

Package: capell-app/theme-agency · Kind: theme · Tier: premium · Product group: Capell Themes · Bundle: themes · Status: Complete

1. Snapshot

AgencyThemeServiceProvider registers theme key agency (extends: 'default' in code, extends: "capell-app/foundation-theme" in capell.json), wiring a BladeThemeRenderer with layout view capell-theme-agency::page and nine ViewSectionRenderers (navigation, hero, features, proof, content-listing, project-showcase, case-study, cta, footer), each failLoudly: true. It ships its own Blade for all nine sections plus a page wrapper; it overrides every Foundation section it lists but inherits content-listing’s gallery/pathways/spotlight variants by delegating back to capell-foundation-theme::theme.sections.content-listing. The demo command capell:theme-agency-demo delegates to InstallAgencyThemeDemoAction → ThemeDemoPageInstaller::run($data, 'agency', 'Agency'), seeding ≥7 pages idempotently (proven in DemoCommandTest). Six presets exist in code (signal, gallery, atelier, zenith, northstar, motion-studio), and every preset now declares surface, foreground, and neutral tokens that feed the page shell. Marketplace copy is buyer-facing, and the current committed screenshot set contains 10 route-backed light frontend captures from the real Agency renderer; capell.json stays conservative by promoting the extension card plus homepage/lead-generation captures until the directory-style inner pages get richer fixtures.

Completed Improvement Slices

• 2026-06-03: Replaced marketplace plumbing copy with buyer-facing Theme Agency positioning, promoted committed PNG screenshots into the marketplace manifest, and added real package 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-06: Fixed the screenshot wrapper to seed/capture one theme package at a time, mark frontend theme entries anonymous, and suppress the Insights consent banner during screenshot runs; all 10 frontend Agency entries now capture the real styled Agency shell, with homepage and lead-generation PNGs promoted into marketplace media.
• 2026-06-04: Bound the page shell to --theme-surface / --theme-foreground, added explicit surface tokens to all six presets, replaced fixed fuchsia/orange gradient stops with a token-driven site-brand-gradient, and added regression tests for token propagation.
• 2026-06-05: Reconciled the theme definition asset contract by publishing the committed marketplace card to /vendor/capell/themes/agency.jpg, pointing assets['css'] at the generated frontend CSS entrypoint, and registering package CSS through Tailwind import/source constants.
• 2026-06-07: Added LCP image attributes to hero media, lazy/dimension/async attributes to work-card media, aligned the manifest media test with the promoted extension-card plus route-backed PNG policy, and reconciled the already-shipped real health-check probes in this plan.
• 2026-06-07: Closed the Agency contrast/WCAG slice by softening shell heading rhythm, raising weak dark-panel copy opacity, translating hero stat values, and adding WCAG AA preset contrast plus low-opacity class regression coverage.
• 2026-06-07: Recaptured all 10 light frontend screenshot targets through the Capell runner with the real Agency renderer and visually reviewed the contact sheet; marketplace promotion remains intentionally limited to the strongest homepage/lead-generation captures.
• 2026-06-07: Moved the proof carousel behavior out of public Blade into a registered package build asset, added reduced-motion-aware scrolling, translated button labels, and an aria-live status region.
• 2026-06-07: Extracted the hero’s decorative canvas into a partial and made the hero stat cards render from optional section data with translated fallbacks.
• 2026-06-07: Added dedicated Team, Services, and Client Logos section renderers with hydrated data, translated empty states, image attributes, and direct renderer coverage.

2. Improvements (existing functionality)

1. Page shell token propagation shipped. — The shell now drives background and foreground from --theme-surface / --theme-foreground, every preset declares surface/foreground/neutral values, and tests prove the wrapper no longer carries hardcoded bg-zinc-950 text-zinc-950 classes. Continue to audit individual section-level dark panels before claiming full light-mode coverage. src/AgencyThemeServiceProvider.php, resources/views/page.blade.php, resources/css/theme-agency.css, tests/Unit/AgencyThemeDefinitionTest.php — M

2. Token-driven section gradients shipped. — Hero, CTA, features, and content-listing now use a shared site-brand-gradient class that mixes --theme-primary and --theme-accent; tests guard against the old via-fuchsia-500 / to-orange-900 stops returning. Section-specific contrast and dark-panel auditing were closed in the later WCAG slice. resources/css/theme-agency.css, resources/views/sections/*.blade.php, tests/Unit/AgencyThemeDefinitionTest.php — Done

3. Card and preset contrast guarded. — The shell no longer combines near-black text and near-black background. White card headings/body copy use explicit readable card ink/muted variables, all preset shell surface/foreground pairs are covered by a WCAG AA contrast guard, and package tests now ban the weak white opacity classes that previously appeared on dark panels. resources/css/theme-agency.css, resources/views/sections/*.blade.php, tests/Unit/AgencyThemeDefinitionTest.php — Done

4. Navigation disclosure accepted as progressive enhancement. — The mobile menu uses native <details>/<summary> so it works without JavaScript and does not expose dead controls. A richer Alpine disclosure could be future polish, but the current no-JS disclosure is not an active roadmap blocker. resources/views/sections/navigation.blade.php — Done

5. Proof carousel progressive enhancement shipped. — Proof carousel behavior now lives in resources/js/theme-agency.js as a registered build asset instead of inline public Blade. The script respects prefers-reduced-motion, updates aria-disabled button state, and announces scrollability through an aria-live status region; buttons now use translated labels plus icon/sr-only text instead of raw ‹/› glyphs. resources/views/sections/proof.blade.php, resources/js/theme-agency.js, src/AgencyThemeServiceProvider.php, resources/lang/en/generic.php, tests/Unit/AgencyThemeDefinitionTest.php — Done

6. Definition asset contract reconciled. — definition() now publishes the committed marketplace card to /vendor/capell/themes/agency.jpg, all presets use that declared public preview image, and assets['css'] points at Foundation Theme’s generated frontend CSS entrypoint while the package stylesheet is registered as a Tailwind import. src/AgencyThemeServiceProvider.php, tests/Unit/AgencyThemeDefinitionTest.php — Done

7. Hero canvas extracted and stats data-driven. — The hero’s decorative right column now lives in sections/partials/hero-canvas.blade.php, keeping the main hero view focused on content flow. The hero stat cards read optional $section->stats data and fall back to translated defaults, so seeded/demo pages can replace Live/08/14d without editing Blade. resources/views/sections/hero.blade.php, resources/views/sections/partials/hero-canvas.blade.php, tests/Unit/AgencyThemeDefinitionTest.php — Done

3. Missing Features (gaps)

capabilities is only ["theme-agency", "theme-agency-frontend"]. The theme now adds agency-specific project-showcase, case-study, team, services, and client-logos renderers alongside the baseline Foundation section stack. For a creative/agency vertical the screenshot plan describes nine layout pages (homepage, services, portfolio, case-study, insights, event-landing, lead-form, campaign, search), but several are still page compositions that depend on the shared renderers plus other packages (capell-app/blog, capell-app/form-builder, capell-app/search, capell-app/content-sections). Concrete gaps:

• Portfolio / project-grid renderer shipped. — Agency now registers a dedicated project-showcase section with filter chips, aspect-ratio-preserving media, hover reveal, year/stage metadata, and translated empty states. This gives portfolio/work pages a first-class agency-owned renderer instead of relying on content-listing/Foundation gallery fallbacks. Differentiator.
• Case-study / long-form project renderer shipped. — Agency now registers a dedicated case-study section with client/discipline/year metadata, hero media, challenge/approach/result blocks, result metrics, gallery media, and translated empty states. This closes the agency portfolio money-shot gap. Differentiator.
• Team / people section shipped. — Agency now registers a dedicated team renderer with hydrated people cards, optional media, roles, bios, and translated empty states. Table-stakes closed.
• Services / capabilities section shipped. — Agency now registers a dedicated services renderer with discipline labels, service summaries, and deliverable lists instead of forcing services through generic features. Table-stakes closed.
• Logo / client wall shipped. — Agency now registers a dedicated client-logos renderer with name/logo fallbacks and a translated empty state, separating logo proof from testimonial metrics. Table-stakes closed.
• Pricing / engagement section — optional but common for productized agencies; absent. Differentiator (optional).
• Light-mode coverage closed for current presets. atelier and newer presets provide light surface tokens while hero/navigation/footer intentionally retain dark campaign panels as part of Agency’s visual direction. A fully light variant is future product polish, not active improvement-plan scope. Differentiator closed at current theme boundary.

Versus siblings (10 themes exist: foundation-theme, theme-commerce, theme-corporate, theme-education, theme-healthcare, theme-knowledge, theme-local-services, theme-nonprofit, theme-portfolio, theme-saas): theme-portfolio and theme-saas both ship richer CSS (101 and 198+90 lines respectively vs Agency’s 69) and theme-portfolio directly overlaps the creative buyer. Agency must out-render portfolio on campaign motion + case studies or the two cannibalize.

4. Issues / Risks

• Shipped 2026-06-05: Manifest tier vs commercial conflict. capell.json, docs/overview.md, and this plan now classify Theme Agency as a premium package in the Capell Themes / themes product group, matching commercial.proposedLicense: "paid"; manifest tests assert the pricing metadata boundary.
• Screenshot contract closed for current light frontend targets. docs/screenshots.json declares the route-backed Agency targets and the current 10 light frontend captures were regenerated through the real seeded Agency renderer. capell.json promotes the homepage plus lead-generation PNGs; directory/gallery-style captures remain committed runner evidence but are intentionally not promoted wholesale until fixtures carry more agency-specific depth. Older dark captures remain supplemental docs assets outside the marketplace contract. docs/screenshots.json, capell.json, docs/screenshots/.
• Health check shipped. ThemeAgencyHealthCheck now runs real probes for Theme Studio registration, required page/section Blade files, and committed marketplace media. Feature tests cover passing diagnostics, missing registration, missing views, and missing screenshots, so the critical manifest severity is backed by actionable checks. src/Health/ThemeAgencyHealthCheck.php, tests/Feature/ThemeAgencyHealthCheckTest.php, capell.json.
• Preset count and preview asset canonicalised. AgencyThemeServiceProvider::definition() defines 6 presets and AgencyThemeDefinitionTest asserts the same count. Current guard proves every preset has surface/foreground/neutral tokens, all presets use the declared public preview image, and the committed marketplace card publishes to that path. src/AgencyThemeServiceProvider.php, tests/Unit/AgencyThemeDefinitionTest.php.
• Public-output safety: covered (low risk, keep it). PublicOutputSafetyTest asserts no capell-app/theme-agency, Filament, Livewire, wire:, data-theme-key, signed, data-field, model_id, permission in rendered Blade + lang, and bans ::query(, DB::, loadMissing(, ->translation, find( from Blade. Page wrapper renders pre-hydrated {!! $content !!} and $brand->tokens() only — no DB access. The new project-showcase and case-study renderers follow the same hydrated-data/no-query contract.
• WCAG contrast slice shipped. The theme now guards every preset’s surface/foreground pair at WCAG AA contrast, removes the weak text-white/45–text-white/70 public copy classes from section views, raises the hero paragraph colour, and softens shell headings from font-weight: 900 / line-height: 0.92 to a more readable 850 / 1. Hero stat values are translated instead of literal Blade magic numbers. resources/css/theme-agency.css, resources/views/sections/*.blade.php, resources/lang/en/generic.php, tests/Unit/AgencyThemeDefinitionTest.php.
• Proof carousel accessibility shipped. The carousel no longer emits inline public JavaScript, its controls are translated and stateful, and scrolling respects reduced-motion preferences. AgencyThemeDefinitionTest now guards build-asset registration, status markup, and the reduced-motion JS contract. resources/views/sections/proof.blade.php, resources/js/theme-agency.js, tests/Unit/AgencyThemeDefinitionTest.php.
• LCP / image performance closed for declared media. Hero media includes explicit dimensions, eager loading, async decoding, and fetchpriority="high"; content-listing media includes explicit dimensions, lazy loading, and async decoding. A render-budget smoke test would be future hardening, but the active image-performance roadmap row is closed. resources/views/sections/hero.blade.php, resources/views/sections/content-listing.blade.php, tests/Unit/AgencyThemeDefinitionTest.php, capell.json.
• Cache safety (low, verify). performance.cacheSafety.cacheable: false, variesBy: ["site","locale"], queueInvalidation: true. The inline proof <script> and <details> are static markup, so cacheable: false may be more conservative than needed; confirm whether the theme genuinely can’t be cached or whether this is a default left unset. capell.json.
• Hero stat literals translated. Hero stats still use package defaults, but the visible 08, 14d, and 01 values now come through translations and are guarded from returning as raw Blade literals. Future work can expose them as section data if editors need per-page values. resources/views/sections/hero.blade.php, resources/lang/en/generic.php.
• Hero structure simplified. The decorative canvas is extracted to a package partial and hero stat cards are now hydrated-data capable with translated fallback values. AgencyThemeDefinitionTest guards the partial boundary and custom stat rendering. resources/views/sections/hero.blade.php, resources/views/sections/partials/hero-canvas.blade.php, tests/Unit/AgencyThemeDefinitionTest.php.
• Agency-specific renderer depth shipped. Team, Services, and Client Logos now ship as package-owned renderers with translated empty states and no public-output leaks. AgencyThemeDefinitionTest covers registration, populated output, empty states, image attributes, and public-output safety. src/AgencyThemeServiceProvider.php, resources/views/sections/team.blade.php, resources/views/sections/services.blade.php, resources/views/sections/client-logos.blade.php, tests/Unit/AgencyThemeDefinitionTest.php.

5. Marketplace & Selling

Original summary (capell.json): “Creative campaign and studio theme screenshots from route-backed demo layouts.” — This pipeline-facing 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 bold, motion-led theme for creative studios and marketing agencies — campaign hero, case-study proof, and a filterable work showcase, with three presets from high-contrast Signal to editorial Atelier.

Improved 3–4 sentence description:

Theme Agency turns a Capell site into a confident creative portfolio. It ships an expressive page system — full-bleed launch hero, animated proof wall, project showcase, and a conversion-focused brief CTA — built to make studio and agency work look like the work, not a template. Three presets (Signal, Gallery, Atelier) re-skin every section from energetic high-contrast to refined editorial neutrals, all driven by Theme Studio tokens with zero code. Built on Foundation Theme contracts, it stays fast, cache-aware, and safe for public output, so it drops into the standard Capell theme workflow.

Screenshot / media status: the static route-backed gallery is closed for the current light frontend contract. The screenshot wrapper now renders the real Agency shell and recaptured the frontend set through the package renderer. Marketplace media promotes the homepage and lead-generation captures; admin availability, signed preview, and richer directory/gallery fixtures are optional future media-depth work before broader promotion.

Completed 2026-06-07. Every prioritized roadmap row is closed. Theme Agency now has buyer-facing marketplace metadata, real route-backed renderer captures, token-driven presets, WCAG guards, image hints, health diagnostics, build-asset carousel behavior, and dedicated project-showcase, case-study, team, services, and client-logo renderers.

Differentiation vs the other 9 themes: position Agency as the campaign-and-case-study theme — the one with motion, a real project showcase, and presets that swing from loud to editorial. Keep a hard line against theme-portfolio (which owns the quiet, grid-first creative buyer) by leaning into campaign rhythm, big type, and conversion CTAs; against theme-saas/theme-corporate by being deliberately expressive rather than restrained. Target buyer: boutique creative/branding/marketing agencies and studios (1–30 people) who want a launch-ready, premium-looking site without bespoke front-end build.

Keywords/tags: agency theme, creative studio, portfolio, case study, marketing agency, branding, expressive, motion, campaign landing, dark theme, editorial, Capell theme.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref
Reconcile tier/bundle/group across capell.json + docs/overview.md; set paid classification	Done	S	High	§4 — closed 2026-06-05: manifest, overview, and plan now agree on Capell Themes / premium / themes, matching the paid commercial block.
Replace generic theme-gallery fixture PNGs with real Agency renderer captures; sync screenshots.json ↔ capell.json ↔ files	Done	M	High	§4, §5 — closed 2026-06-07: all 10 light frontend targets were recaptured through the real Agency renderer and visually reviewed; marketplace promotion remains conservative.
Resolve preset-count contradiction (3 in code vs 6 in test); make canonical	Done	S	Med	§4
Shipped 2026-06-05: Fix definition() assets path + missing preset preview JPEGs	Done	S	Med	§2.6, §4
Drive page-shell surface/ink from preset tokens	Done	M	High	§2.1, §3
Rewrite marketplace summary + manifest description	Done	S	High	§5
Remove hardcoded hex/gradient color stops from hero + CTA	Done	M	High	§2.2
Contrast/WCAG audit across all three presets	Done	M	Med	§4, §2.3 — closed 2026-06-07: preset surface/foreground contrast is guarded at WCAG AA, weak dark-panel copy classes are banned, headings use a readable line height, and hero stats are translated.
Add dedicated project-showcase (portfolio) renderer	Done	L	High	§3 — closed 2026-06-07: project-showcase is registered as an agency-owned renderer with filters, media cards, project metadata, empty state, and tests.
Add case-study section renderer	Done	L	High	§3 — closed 2026-06-07: case-study is registered as an agency-owned renderer with story blocks, metrics, gallery media, empty state, and tests.
Add hero image LCP hints (fetchpriority, dims, loading)	Done	S	Med	§4 — closed 2026-06-07: hero media has dimensions, eager loading, async decoding, and high fetch priority; content-listing media is lazy/async.
Implement real ThemeAgencyHealthCheck probes (or downgrade severity)	Done	M	Med	§4 — reconciled 2026-06-07: the health check already probes registry, required views, and marketplace media with feature coverage.
Add team + services + client-logo renderers	Done	L	Med	§3 — closed 2026-06-07: team, services, and client-logos renderers now ship with hydrated-data views, translated empty states, and direct renderer coverage.
Ship a light-mode preset and prefers-reduced-motion handling	Done	M	Med	§2.1, §2.5 — closed 2026-06-07: light-surface presets exist and proof carousel scrolling now respects reduced motion through a registered build asset.
Extract hero decorative canvas to a partial; data-drive hero stats	Done	S	Low	§2.7, §4 — closed 2026-06-07: the decorative canvas now lives in sections/partials/hero-canvas.blade.php, and hero stat cards accept section data with translated fallbacks.