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

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

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.
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.
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.
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.
WCAG / accessibility guard shipped. — Positives: a skip-link with a real #main-content target, :focus-visible outlines, translated carousel button labels, aria-labels 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.
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.
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.
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.
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/.
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 `<script>` onto carousel markers	Done	M	Med	§2.4, §4.4 — closed 2026-06-07: events uses shared carousel data markers and public-output safety tests prevent inline scripts.
Render locations with hours/address/click-to-call/map	Done	M	High	§3 — closed 2026-06-07: locations/contact render address, hours, sanitized click-to-call links, and map links from hydrated data.
WCAG AA contrast audit of muted greys + heavy weights	Done	M	High	§4.5 — closed 2026-06-07: muted/link/default token pairings meet WCAG AA in tests and shell heading weights are softened.
Add image perf attributes (hero `fetchpriority`+dims; rest `loading=lazy`)	Done	S	High	§2.1, §4.5
Render a real `id="main-content"` target so the skip link works	Done	S	High	§4.5
Translate events carousel “Previous”/“Next” button text	Done	S	Med	§2.3, §4.5
Rewrite marketplace summary + composer description; expand keywords/tags	Done	S	High	§5
Flesh out the critical health check (assert views/renderer/assets)	Done	S	Med	§4.2
Add dark-mode support (CSS vars + `prefers-color-scheme`)	Done	L	Med	§2.7 — closed 2026-06-07: class-based and `prefers-color-scheme` dark token layers now ship with surface/text/border/shadow normalization and contrast coverage.
Add clinician detail + conditions/treatments directory surfaces	Done	L	High	§3 — closed 2026-06-07: `clinician-profile` and `conditions-directory` render hydrated clinical credentials, specialties, languages, accepting-patient status, and service links with tests.
Add emergency/urgent-care escalation banner component	Done	S	Med	§3 — closed 2026-06-07: `emergency-escalation` renders hydrated urgent-contact copy, safe `tel:` links, optional urgent-care action, and fallback steps.
Assert the 20ms render budget + accessibility in tests	Done	M	Med	§4.7, §4.9 — closed 2026-06-07: package tests now render a representative public page inside the 20 ms budget with no DB queries, alongside the existing accessibility guards.