# 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 `ViewSectionRenderer`s (`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.                       |