# Theme Healthcare — Improvement & Growth Plan > Package: capell-app/theme-healthcare · Kind: theme · Tier: premium · Product group: Capell Themes · Bundle: themes · Status: Complete ## 1. Snapshot Theme Healthcare is a renderer-only Capell theme that registers the `healthcare` theme key (`HealthcareThemeServiceProvider::THEME_KEY`) and an appointment-led clinical direction for clinics. It ships a `BladeThemeRenderer` with the page wrapper `capell-theme-healthcare::page` and 22 declared `includedSections`. Of those, 19 are bespoke Blade views under `resources/views/sections/` (utility-bar, navigation, hero, service-finder, services, care-pathway, clinicians, clinician-profile, conditions-directory, booking, emergency-escalation, locations, insurance-trust, events, comparison, proof, blog-teaser, contact, cta, footer); `features` reuses the local `services` view and `content-listing` reuses the `blog-teaser` renderer. Three sections (`content-listing`/`blog-teaser`, `booking`, `events`) use bespoke `SectionRenderer` classes that inject optional `blogAvailable`/`formBuilderAvailable`/`eventsAvailable` flags before Blade renders. It inherits all runtime data contracts, `ThemeSection` data, and the foundation `content-listing` partial (`blog-teaser.blade.php` `@include`s `capell-foundation-theme::theme.sections.content-listing` for gallery/pathways/spotlight variants) from Foundation Theme; it overrides every section's visual treatment plus a 200-line scoped CSS file (`resources/css/theme-healthcare.css`). The demo command `capell:theme-healthcare-demo` exists (`src/Console/Commands/DemoCommand.php`) and delegates to `InstallHealthcareThemeDemoAction` → `ThemeDemoPageInstaller::run(..., 'healthcare', 'Healthcare')`. Marketplace and Composer copy are buyer-facing, and `capell.json` now promotes the extension card plus five styled, route-backed Healthcare PNGs captured through the Capell screenshot runner. The older generic `theme-gallery`, admin-list, and signed-preview fixture targets are no longer part of the screenshot contract because this renderer-only package has no package-owned admin surface; Theme Studio/admin preview proof belongs to the core theme-management runner once that fixture exists. `docs/screenshots.json` points frontend entries at real seeded routes (`/theme-healthcare`, `/theme-healthcare-directory`, `/theme-healthcare-detail`, `/theme-healthcare-contact`) and marks those entries as anonymous captures. ## Completed Improvement Slices - **2026-06-03:** Added buyer-facing marketplace and Composer copy, replaced the stub Diagnostics health check with real theme registration/view/vendor-asset probes, and limited marketplace screenshots to committed preview assets. - **2026-06-06:** Captured all 8 `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:** Added a real `main-content` skip-link target, added image dimensions/loading/decoding/fetch-priority attributes, translated visible events carousel button text, and added tests for those public rendering contracts. - **2026-06-07:** Converted the booking panel from decorative chips into a hydrated-form/strong-CTA branch, removed the events inline script in favour of shared carousel markers, added empty states to item-driven sections, rendered address/hours/click-to-call/map fields for locations/contact cards, and covered the contracts with Pest. - **2026-06-07:** Added a dedicated hydrated emergency/urgent-care escalation section with safe `tel:` output, translated fallback steps, and public-output coverage; also added a direct 20 ms public render-budget test with a no-query assertion. - **2026-06-07:** Added Healthcare dark-mode support through `.dark .healthcare-shell`, `.healthcare-shell.dark`, and `prefers-color-scheme: dark` token layers, including surface/text/border/shadow normalization and WCAG AA dark-token contrast coverage. - **2026-06-07:** Added dedicated hydrated `clinician-profile` and `conditions-directory` surfaces for credentials, specialties, languages, accepting-patients status, and condition/treatment-to-service routing, with empty states and anonymous-safe tests. - **2026-06-07:** Closed the stale screenshot roadmap row: `docs/screenshots.json` now keeps only real seeded Healthcare frontend route captures, `capell.json` promotes only committed runner-backed Healthcare PNGs, and unowned Theme Studio/admin preview targets are intentionally left to the core theme-management screenshot contract. ## 2. Improvements (existing functionality) Prioritized. Effort: S = <0.5d, M = ~1–2d, L = >2d. 1. **Image performance attributes added.** — Hero images now include explicit dimensions, async decoding, and `fetchpriority="high"`; clinician, service, and resource-card images include explicit dimensions, lazy loading, and async decoding. — `resources/views/sections/hero.blade.php`, `resources/views/sections/clinicians.blade.php`, `resources/views/sections/services.blade.php`, `resources/views/sections/partials/resource-card-media.blade.php`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **S** 2. **Booking panel converted to a real conversion surface.** — `sections/booking.blade.php` now renders a hydrated `formHtml`/`formMarkup` branch when the optional form package is available and the section data supplies markup, and otherwise exposes a prominent appointment/contact CTA plus click-to-call fallback from hydrated section data. No package names or authoring details are emitted publicly, and the renderer still performs no queries. — `resources/views/sections/booking.blade.php`, `src/Rendering/BookingSectionRenderer.php`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **M** 3. **Event carousel button text translated.** — `sections/events.blade.php` now uses the existing `capell-theme-healthcare::generic.carousel_previous|next` keys for visible button text and aria labels. — `resources/views/sections/events.blade.php`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **S** 4. **Events carousel now uses shared carousel markers.** — `sections/events.blade.php` no longer emits an inline IIFE; it uses the same `data-carousel`, `data-carousel-track`, `data-carousel-prev`, and `data-carousel-next` markers as the other theme carousels. Public-output safety tests now guard against inline scripts. — `resources/views/sections/events.blade.php`, `tests/Unit/HealthcareThemeDefinitionTest.php`, `tests/Unit/PublicOutputSafetyTest.php` — **M** 5. **No-items empty states added to item-driven sections.** — `services`, `clinicians`, `contact`, `events`, and `service-finder` now render translated dashed placeholder cards instead of bare headings when authors leave the section empty. — `resources/views/sections/services.blade.php`, `clinicians.blade.php`, `contact.blade.php`, `events.blade.php`, `service-finder.blade.php`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **M** 6. **Healthcare palette tokenized.** — Section and blog templates now route the recurring ink, primary, accent, link, line, and surface colours through `--healthcare-*` CSS custom properties instead of hard-coded Tailwind hex utilities, so Theme Studio presets can recolour the public renderer. The token guard asserts section/blog Blade files stay free of literal hex. — `resources/views/sections/*.blade.php`, `resources/views/blog/*.blade.php`, `resources/css/theme-healthcare.css`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **L** 7. **Dark-mode support shipped.** — Healthcare now supports `.dark .healthcare-shell`, `.healthcare-shell.dark`, and `prefers-color-scheme: dark` token layers. Dark mode remaps ink, muted, line, primary, link, accent, and surface tokens, normalizes common white/stone utilities under the shell, darkens shadows, and has WCAG AA contrast coverage for the default dark token pairings. — `resources/css/theme-healthcare.css`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **L** 8. **Heading scale and weights softened.** — The Healthcare shell now uses calmer heading clamps and lower `h1`/`h2` weights, avoiding the previous ultra-heavy clinical tone while retaining utility-class override safety. — `resources/css/theme-healthcare.css`, `tests/Unit/HealthcareThemeDefinitionTest.php` — **S** ## 3. Missing Features (gaps) `capabilities[]` currently declares only `theme-healthcare` and `theme-healthcare-frontend` — generic placeholders that say nothing about healthcare capability. Against what a real clinic/medical site needs: - **Booking-ready conversion surface shipped.** The booking panel now supports a hydrated live-form branch and a static appointment/contact CTA without querying in Blade. A dedicated Bookings/scheduling package can later hydrate availability, locations, staff, and appointment request models into the existing branch. — differentiator closed at theme boundary. - **Practitioner/clinician profile detail shipped.** Healthcare now registers `clinician-profile`, rendering hydrated name/bio/image, credentials, specialties, languages, availability, and accepting-new-patients status without querying public Blade. — table-stakes closed at theme boundary. - **Locations with hours, address, phone, and map shipped.** — `locations` and `contact` now render hydrated address, hours/opening-hours, click-to-call, and map links, with coverage for the visible fields and sanitized `tel:` output. A future enhancement could add embedded maps, but the table-stakes public details are now present. — table-stakes. - **Conditions / treatments directory shipped.** Healthcare now registers `conditions-directory`, rendering hydrated condition/treatment cards with summaries and cross-links to services or pathways. A future taxonomy package can hydrate richer relationships, but the theme now owns the public directory surface. — differentiator closed at theme boundary. - **Insurance / patient information surface accepted for theme scope.** `insurance-trust` renders hydrated trust/patient-info cards and can carry insurer, self-pay, and patient-rights copy supplied by the page data. Dedicated insurer logos, fee transparency models, and medical-record workflows are future package depth. — differentiator deferred beyond renderer scope. - **Emergency / urgent-care escalation banner shipped.** Healthcare now registers an `emergency-escalation` section that renders hydrated urgent-contact copy, sanitized `tel:` links, optional urgent-care actions, and translated fallback steps. This keeps duty-of-care messaging in public presentation data without exposing package/admin details. — differentiator closed at theme boundary. - **Trust/accreditation signals can be hydrated today.** Proof and insurance/trust cards can render healthcare-specific trust copy from section data; formal CQC/GMC/accreditation models remain future product depth. Versus siblings: most of the 9 other themes share the same generic section skeleton; healthcare currently differentiates only by colour and copy, not by clinical capability. The booking cross-sell is the single biggest opportunity to make it genuinely vertical. ## 4. Issues / Risks 1. **Dual `extends` meaning documented.** — `ThemeDefinitionData(extends: 'default')` records runtime theme-key inheritance while manifest `"extends": "capell-app/foundation-theme"` records package inheritance; the service provider comment documents this distinction. Add an explicit test if this keeps regressing in future theme work. — `src/HealthcareThemeServiceProvider.php`, `capell.json`. 2. **Health check shipped.** — `ThemeHealthcareHealthCheck` now probes Theme Studio registration, required views, and vendor asset registration; tests cover passing diagnostics and an unregistered theme failure. — `src/Health/ThemeHealthcareHealthCheck.php`, `tests/Unit/ThemeHealthcareHealthCheckTest.php`. 3. **Screenshot contract closed for Healthcare-owned surfaces.** — The package screenshot wrapper now injects selected package CSS into the screenshot app frontend build, runs preflight before package demo commands, and then captures seeded package routes with `--skip-build`; Healthcare frontend captures use the styled `healthcare` shell instead of generic `theme-gallery` output. `capell.json` promotes the clean desktop homepage, mobile homepage, services listing, detail, and contact PNGs. The previous generic `theme-gallery`, admin-list, and signed-preview fixture targets are no longer declared here because Healthcare is renderer-only and does not own those admin surfaces. — `docs/screenshots.json`, `capell.json`, `docs/screenshots/`, `scripts/run-package-screenshots.js`. 4. **Inline script risk closed.** — `sections/events.blade.php` now relies on shared carousel markers instead of emitting raw JavaScript to anonymous visitors, and `PublicOutputSafetyTest` asserts public Blade stays free of inline scripts. — `resources/views/sections/events.blade.php`, `tests/Unit/PublicOutputSafetyTest.php`. 5. **WCAG / accessibility guard shipped.** — Positives: a skip-link with a real `#main-content` target, `:focus-visible` outlines, translated carousel button labels, `aria-label`s on carousel buttons, and `aria-hidden` on decorative placeholders are present. The default ink, muted, primary, link, accent-on-ink, and white-on-ink token pairings now meet WCAG AA contrast thresholds in tests, and the heaviest shell heading weights were softened. Remaining visual QA is a consistency pass over decorative hero/card placeholder blocks. — `resources/views/page.blade.php`, `resources/css/theme-healthcare.css`, `resources/views/sections/events.blade.php`, `tests/Unit/HealthcareThemeDefinitionTest.php`. 6. **Token wiring closed.** — Section and blog templates now use `var(--healthcare-*)` classes for recurring palette values, and a package test prevents hard-coded hex from returning to those public views. Theme Studio preset values in `definition()` now flow through the public page palette instead of only the gradient/focus ring. — all `resources/views/sections/*.blade.php`, `resources/views/blog/*.blade.php`. 7. **Performance budget covered.** — A focused Pest test renders a representative Healthcare public page under the manifest's 20 ms `frontendRenderBudgetMs` and asserts no database queries during the render phase. `cacheable:false` remains conservative for now, but the renderer budget is no longer undocumented or untested. — `capell.json`, `tests/Unit/HealthcareThemeDefinitionTest.php`. 8. **No public DB-query risk found (good)** — `PublicOutputSafetyTest` asserts Blade contains no `DB::`, `::query(`, `loadMissing(`, `Frontend::`, `find(`, etc., and the renderers pass hydrated `toViewData()` only. Section renderers correctly take availability booleans rather than querying. This invariant holds; keep the guard test when adding the booking form (§2.2) so a live form doesn't introduce a query in Blade. 9. **Test coverage reconciled.** — Covered: theme definition shape, section-renderer key list, install-gating, vendor asset registration, leak-token safety on full-page + individual sections, CSS specificity, skip-link target, image loading attributes, translated event controls, optional Form Builder / Events / Blog availability datasets, booking live/static branches, emergency escalation rendering/fallbacks, clinician profile and conditions directory rendering/empty states, locations/contact field output, empty-section rendering, no-inline-script safety, no-DB-query assertion, render-budget evidence, tokenized palette guards, WCAG AA default token contrast, health diagnostics, demo command delegation + idempotency. Final visual review of decorative placeholders is optional visual QA, not active plan scope. — `tests/Unit/`, `tests/Feature/`. 10. **`composer.json` PHP floor vs platform** — `composer.json` requires `php: ^8.3` while the monorepo/Boost context targets PHP 8.4 and the source uses typed class constants (`public const string THEME_KEY`). Confirm the `^8.3` floor is intentional. — `composer.json`. ## 5. Marketplace & Selling Marketplace and Composer copy now use the buyer-facing positioning below, and composer keywords include healthcare, clinic, medical, appointments, booking, clinicians, patient acquisition, care pathways, accessibility, and WCAG terms. **Improved 1-sentence summary:** > A premium, appointment-led theme for private clinics and healthcare groups — service discovery, clinician profiles, care pathways, locations, and a booking-ready enquiry panel, all WCAG-minded and brand-tunable in Theme Studio. **Improved 3–4 sentence description:** > Theme Healthcare turns Capell into a conversion-focused clinical website. It ships nineteen care-oriented sections — an appointment hero, service finder, clinician carousel, care-pathway guidance, insurance/trust signals, locations, events, and a booking panel — that route patients toward the right enquiry with calm, clinical styling. The booking, events, and resource sections light up automatically when Capell Bookings/Form Builder, Events, and Blog are installed, with no theme reconfiguration. Built on Foundation Theme with accessible focus states and a skip link, it activates from the Themes screen and seeds a full demo via `capell:theme-healthcare-demo`. (Note: the description can now claim "booking-ready" because §2.2 ships a hydrated form branch plus static appointment/contact CTA. Avoid claiming live availability until a dedicated bookings/scheduling package supplies that data.) **Screenshot / media gaps:** Healthcare-owned frontend route media is closed. The Capell screenshot runner captures styled seeded Healthcare routes and `capell.json` promotes the desktop homepage, mobile homepage, services listing, detail, and contact route PNGs. The generic `frontend-page-rendered-with-healthcare-theme` capture remains unpromoted as runner evidence, while Theme Studio/admin preview screenshots are intentionally out of scope for this renderer-only package until the core theme-management runner owns that fixture. Completed 2026-06-07. Every prioritized roadmap row is closed. Theme Healthcare now ships buyer-facing marketplace copy, real route-backed Healthcare captures, health diagnostics, tokenized/dark styling, booking live/static branches, no-inline-script carousel output, empty states, locations/contact fields, emergency escalation, clinician profile, conditions directory, public-output/no-query guards, WCAG contrast coverage, and render-budget evidence. **Differentiation vs the other 9 Capell themes** (agency, commerce, corporate, education, knowledge, local-services, nonprofit, portfolio, saas): today healthcare differs only by palette (deep teal + amber) and copy. Its defensible niche is **clinical conversion + compliance**: a real booking/enquiry flow, clinician credentials, insurance transparency, emergency escalation, and demonstrable WCAG AA. Lean the marketing into "the only Capell theme built for patient acquisition and accessibility compliance." **Target buyer:** private clinics, specialist/consultant practices, multi-site healthcare groups, dental/physio/aesthetic practices, and agencies building patient-acquisition sites for medical clients. **Keywords / tags (8–12):** Composer keywords now include `healthcare`, `clinic`, `medical`, `appointments`, `booking`, `clinicians`, `patient acquisition`, `care pathways`, `accessibility`, `WCAG`, `dental physiotherapy`, and `Capell theme`; `definition()` tags are still only `Healthcare`, `Appointments`, and `Services`. ## 6. Prioritized Roadmap | Item | Bucket | Effort | Impact | Section ref | | ------------------------------------------------------------------------------------------ | ------ | ------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Replace generic `theme-gallery` fixture PNGs with real Healthcare renderer captures | Done | M | High | §4.3, §5 — closed 2026-06-07: Healthcare now keeps only real seeded frontend route captures in `docs/screenshots.json`, promotes five styled runner-backed PNGs in `capell.json`, and leaves unowned Theme Studio/admin preview proof to the core theme-management screenshot contract. | | Add an explicit test documenting runtime `extends: default` vs manifest package dependency | Done | S | Med | §4.1, §4.9 — closed 2026-06-05: the definition contract test now asserts runtime inheritance uses `default` while the manifest package dependency remains `capell-app/foundation-theme`. | | Make booking panel a live form / strong CTA (Form Builder + Bookings) | Done | M | High | §2.2, §3 — closed 2026-06-07: the booking section renders hydrated form markup when supplied and otherwise falls back to appointment/contact and phone CTAs without public package leakage. | | Wire hardcoded hex to brand tokens so presets recolour the page | Done | L | High | §2.6, §4.6 — closed 2026-06-07: section/blog views use healthcare CSS variables for recurring palette values, with a no-hex Blade guard. | | Add empty-state fallbacks to item-driven sections | Done | M | Med | §2.5 — closed 2026-06-07: services, clinicians, contact, events, and service-finder render translated empty-state cards with coverage. | | Extract / unify the inline events `