Theme Nonprofit — Improvement & Growth Plan

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

1. Snapshot

theme-nonprofit registers theme key nonprofit via NonprofitThemeServiceProvider::definition() (a ThemeDefinitionData with runtime: FrontendRuntime::Blade), wiring a BladeThemeRenderer to layout view capell-theme-nonprofit::page plus one preset (nonprofit). It declares 17 includedSections (navigation, hero, features, proof, content-listing, impact, donation-impact, campaigns, volunteer-donate, volunteer-shifts, annual-report-proof, events, stories, contact, newsletter, cta, footer); navigation and footer are delegated back to Foundation Theme (isFoundationSection()), and seven sections receive optional-package flags (Campaign Studio → campaigns/donation-impact, Form Builder → volunteer-donate/volunteer-shifts, Events → volunteer-shifts/events, Newsletter → newsletter, Blog → stories, Payments → donation-impact/volunteer-donate). The demo command capell:theme-nonprofit-demo {--url=} {--languages=} {--sites=} {--force} delegates to InstallNonprofitThemeDemoAction → ThemeDemoPageInstaller::run(..., 'nonprofit', 'Nonprofit') (Foundation-owned installer; this package contributes no per-layout demo builder of its own). The marketplace summary/Composer description now use buyer-facing charity, NGO, and civic supporter-journey positioning. Health checks now verify provider, package file, manifest, and screenshot boundaries. Screenshots: docs/screenshots.json declares 9 required PNG captures, all committed under docs/screenshots/; capell.json references 6 marketplace assets, with the extension-card and hero JPG previews plus 3 route-backed PNG captures for homepage, volunteer/donate, and impact workflows.

Completed Improvement Slices

2026-06-03: Rewrote marketplace/Composer copy, replaced the critical health-check stub with real diagnostics, and documented the intentional split between runtime extends: default and manifest dependency extends: capell-app/foundation-theme.
2026-06-04: Added the missing main-content target for the skip link, moved the events section eyebrow into translations, removed public Blade package introspection from campaigns, and added tests for those boundaries.
2026-06-06: Replaced the 3 SVG marketplace layout diagrams with Capell runner PNG captures and fulfilled the 9-entry docs/screenshots.json contract.
2026-06-07: Migrated public section palette classes to semantic Nonprofit token classes backed by --nonprofit-* / --theme-* variables, with focused tests guarding brand-token emission and section palette literals.
2026-06-07: Made campaigns, stories, and contact cards consume hydrated $section->items first, with translated fallback cards for empty demo states.
2026-06-07: Added hero LCP image attributes, meaningful fallback alt text, and a data-driven campaign progress bar with ARIA value metadata.
2026-06-07: Added per-section render coverage for every Nonprofit-owned section and connected/static branch coverage for all optional integrations.

2. Improvements (existing functionality)

Prioritized. Real templates only.

Shipped 2026-06-07: Brand tokens drive section palette colours — S→M. page.blade.php writes the preset palette into CSS custom properties via $brand->tokens(), and theme-nonprofit.css now maps section surfaces, dark panels, accent text, borders, and on-dark text through semantic Nonprofit classes backed by --nonprofit-* / --theme-* tokens. Focused public-output tests guard against section Blade reintroducing key literal palette hex values.
No tw: prefix on any utility class — M. The frontend-tailwind guideline mandates a tw: prefix to avoid Bootstrap collisions on store frontends. Every class in every section is bare (mx-auto, grid, font-black, …). Confirm whether Capell theme output is exempt (it may compile its own isolated Tailwind via the registered tailwindImport/tailwindSource vendor assets); if not exempt, this is a systemic prefix bug across all 16 views. Files: all of resources/views/sections/*.blade.php + page.blade.php. Resolve the exemption question before mass-editing.
Shipped 2026-06-07: campaigns, stories, and contact consume section items first — M. These sections now render hydrated $section->items before falling back to translated demo cards, so editors and package integrations can provide real campaign, story, and supporter-routing content without Blade changes. Focused registry coverage proves supplied items replace the old static placeholders.
Shipped 2026-06-07: Hero campaign progress and media are data-driven — S. The hero now derives campaign title, display value, and clamped progress width from section data with translated fallbacks. The progress bar exposes role="progressbar" and value metadata, and hero media now has meaningful fallback alt text plus width, height, loading, decoding, and fetch-priority attributes.
navigation/footer section views are dead code — S. navigation.blade.php and footer.blade.php exist and render an <h2>, but isFoundationSection() makes the provider return null for both, so Foundation Theme renders nav/footer instead and these files are never used by the renderer. Either delete them (reduce confusion) or document why they ship. Files: resources/views/sections/navigation.blade.php, footer.blade.php, cross-ref src/NonprofitThemeServiceProvider.php.
features.blade.php reads $section->features ?? $section->items — S. Inconsistent with the rest of the suite which standardises on items. Confirm the core FeatureSectionData shape (the definition test imports FeatureSectionData) and pick one accessor. File: resources/views/sections/features.blade.php.
Responsive type is heavy on mobile — S. CSS sets h1 to clamp(3rem, 6vw, 5.75rem) and hero <h2> to text-5xl with no sm: step-down; font-weight: 850/820 plus max-width: 12ch produces very large, cramped headings on small screens. Add mobile-first size steps. Files: resources/css/theme-nonprofit.css, resources/views/sections/hero.blade.php.

3. Missing Features (gaps)

capabilities[] is only ["theme-nonprofit", "theme-nonprofit-frontend"] — pure presentation, no functional capability, which is correct for a theme but means every interactive nonprofit need is a cross-sell, and the theme must visibly invite those installs.

Table-stakes nonprofit renderer surfaces are now present at the theme boundary:

Donation CTA/flow shipped. Payments availability now drives a translated giving branch with hydrated primary/secondary donation actions while preserving static fallback CTAs.
Volunteer signup shipped for theme scope. Form Builder and Events availability drive connected/static volunteer and shift messaging, with hydrated action data and branch coverage.
Campaigns/causes deepened. Campaign Studio connected cards now render hydrated appeal progress, goal, summary, and action data rather than only copy swaps.
Impact stats remain a differentiator. impact and donation-impact render hydrated proof/progress data and support the giving branch.
Events deepened. Events connected branches render hydrated event cards with date, location, type, and action links.
Stories/testimonials data-driven. Stories render supplied items before translated fallback cards, avoiding duplicate placeholder-only output.
Transparency / annual reports shipped. annual-report-proof covers transparency proof as a nonprofit differentiator.
Newsletter signup shipped. newsletter renders static, hydrated custom-action, and Newsletter-route connected supporter capture states.
Future fundraising depth. Gift Aid, donor walls, recurring-giving models, and fully model-backed fundraising thermometers remain optional product-package depth beyond the renderer.

4. Issues / Risks

Dual extends meaning is documented, but should stay tested — capell.json declares the package dependency ("extends": "capell-app/foundation-theme") while definition() uses the Theme Studio runtime inheritance key (extends: 'default'). The provider now documents the distinction; keep tests around both boundaries so this does not regress. File: capell.json, src/NonprofitThemeServiceProvider.php.
Shipped 2026-06-04: Hard-coded untranslated copy in events.blade.php — the Campaigns Calendar eyebrow now uses capell-theme-nonprofit::generic.events_label, and render tests assert the translated label is used. File: resources/views/sections/events.blade.php.
Shipped 2026-06-06: screenshot/media debt closed — 9 declared PNG capture paths now exist under docs/screenshots/, each with runner fixture URL metadata. The 3 marketplace SVG layout diagrams have been removed and replaced with real Capell runner PNG captures for homepage, volunteer/donate, and impact workflows. Files: docs/screenshots.json, capell.json, docs/screenshots/*.
Shipped 2026-06-07: Dark mode — theme-nonprofit.css defines scoped .dark .nonprofit-shell, .nonprofit-shell.dark, and prefers-color-scheme: dark token layers with text, surface, border, and on-dark normalization. File: resources/css/theme-nonprofit.css.
WCAG concerns closed for current roadmap. Default token pairings have focused contrast coverage, the page path has a single hero-owned <h1> after the main-content skip-link target, following sections keep <h2> headings, and the data-driven hero progress bar exposes role="progressbar" plus value attributes. Files: events.blade.php, cta.blade.php, annual-report-proof.blade.php, hero.blade.php, page.blade.php.
Shipped 2026-06-07: Hero LCP image and progress metadata. hero.blade.php now renders non-empty fallback alt text for hero media, intrinsic dimensions, eager/high-priority loading, async decoding, and a data-driven progress bar with role="progressbar" and aria-valuenow. Remaining visual follow-up: verify the third-party demo image crop in route-backed screenshots.
Performance budget covered. capell.json sets frontendRenderBudgetMs: 20 and adminQueryBudget: 0; scoped render-budget coverage now renders every owned section under the budget with zero select queries. File: capell.json.
Shipped 2026-06-04: Optional-package detection duplicated in Blade — campaigns.blade.php now relies on the provider-injected campaignStudioAvailable flag, and PublicOutputSafetyTest guards against future CapellCore::isPackageInstalled calls in public Blade. File: resources/views/sections/campaigns.blade.php.
Test gaps closed for current roadmap. Per-section render coverage asserts every Nonprofit-owned section compiles with empty/partial $section data, PackageAwareRendererTest covers connected/static branches for optional sections, and focused tests cover WCAG contrast plus render-budget/no-query behavior.
Shipped 2026-06-05: Version/PHP drift — composer.json now requires php: ^8.4, CHANGELOG.md includes the recent package improvement slices, and manifest tests guard the package Composer PHP constraint. capell.json remains manifest-version: 3 pending sibling parity review. Files: composer.json, CHANGELOG.md, tests/Unit/ManifestRequirementsTest.php.

5. Marketplace & Selling

The manifest and Composer description now use this buyer-facing 1-sentence summary:

A premium charity, NGO, and civic theme that moves visitors from your mission to a clear support action — donate, volunteer, or follow — with impact proof, live campaign progress, and transparent annual-report sections built in.

The manifest marketplace description now uses this buyer-facing product story:

Theme Nonprofit gives charities, NGOs, and civic organisations a calm, trust-building front end engineered around the supporter journey: a campaign-led hero, impact evidence, donation and volunteer paths, events, community stories, and transparency/annual-report sections. It ships as a Capell theme with accessible defaults (skip link, focus-visible outlines, semantic sections) and a route-backed demo you can install in one command to preview a complete cause site. Sections light up automatically when you add Capell Payments (donations), Campaign Studio (live appeals), Events, Blog, and Form Builder — no template surgery required. Premium, first-party, and priority-supported for teams who need a public site that converts interest into sustained giving.

Media status: the 3 layout SVG placeholders have been replaced with route-backed PNG captures, and the 9-entry docs/screenshots.json capture plan is fulfilled. Remaining media depth is optional polish: add connected-state shots for live donations/campaigns/events and a dark-mode view once those product branches are built.

Differentiation / target buyer: vs the other Capell themes (theme-healthcare is the closest sibling in structure), Nonprofit’s unique sections are donation-impact, campaigns, volunteer-donate/shifts, and especially annual-report-proof (transparency proof is a real nonprofit differentiator most generic themes lack). Target buyer: small-to-mid charities, foundations, NGOs, advocacy/campaign groups, and civic/community organisations who want a donation- and trust-oriented site without bespoke design. Lead the listing on trust + a clear support path, not on section count.

Completed 2026-06-07. Every prioritized roadmap row is closed. Theme Nonprofit now has route-backed captures, PHP/changelog alignment, tokenized/dark styling, WCAG and render-budget guards, LCP/progress metadata, Payments/Campaign Studio/Events/Newsletter/Form Builder connected branches, per-section render coverage, data-driven supporter journey sections, and a documented Tailwind-prefix exemption.

Keywords/tags (8–12): nonprofit theme, charity website, NGO, donation, fundraising, campaigns, volunteer, civic, impact reporting, annual report, community, Capell theme.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref
Add `<h1>`/heading-order review after the skip-link target fix	Done	S	High	§4 WCAG — closed 2026-06-05: hero now owns the single public `<h1>` in the page path after the `main-content` skip-link target, and focused tests assert following sections keep `<h2>` headings.
Generate the 9 declared `docs/screenshots/*.png`; replace 3 SVG placeholders with real captures; verify demo routes resolve	Done	M	High	§1, §4, §5 — closed 2026-06-06: 9 route-backed PNG captures are committed and marketplace SVG diagrams were replaced with real workflow screenshots.
Bump `composer.json` PHP to `^8.4`; populate `CHANGELOG.md`	Done	S	Low	§4 — closed 2026-06-05: package Composer now requires `^8.4`, the changelog has dated recent entries, and manifest tests assert the PHP constraint.
Drive section colours from brand tokens instead of literal hex	Done	M	High	§2.1 — closed 2026-06-07: public section Blade now uses semantic Nonprofit token classes, and focused tests guard brand-token emission plus section palette literals.
Make `campaigns`/`stories`/`contact` iterate `$section->items` (kill duplicate placeholder cards)	Done	M	High	§2.3 — closed 2026-06-07: hydrated section items now render before translated fallback cards, with focused registry coverage.
Add WCAG contrast pass on dark/emerald section text + amber-on-dark	Done	M	High	§4 WCAG — closed 2026-06-07: default preset pairings now have focused luminance-ratio coverage, and giving surfaces use semantic muted/on-dark/accent token classes.
Hero image: real alt, `width`/`height`/`loading`/`fetchpriority`; data-driven progress bar with `role="progressbar"`	Done	S	Med	§2.4, §4 — closed 2026-06-07: hero media includes LCP attributes and campaign progress is clamped, data-driven, and exposed through progressbar ARIA.
Add Payments (donations) optional integration + a real `donate`/giving section	Done	M	High	§3 — closed 2026-06-07: `capell-app/payments` availability now drives a translated giving branch with hydrated primary/secondary donation actions and connected/static branch coverage.
Per-section render tests (empty/partial data) + connected/static branch tests for all 6 optional sections	Done	M	Med	§4 tests — closed 2026-06-07: all owned sections compile with partial data, and optional integration branches are covered across all six sections.
Add Newsletter supporter-capture section with `capell-app/newsletter` detection	Done	M	Med	§3 — closed 2026-06-07: `newsletter` now renders static, hydrated custom-action, and Newsletter-route connected supporter capture states with public-output coverage.
Add dark-mode palette + `dark:` variants; render-budget guard test (20ms)	Done	M	Med	§4 — closed 2026-06-07: scoped `.dark`/`prefers-color-scheme` Nonprofit token layers now ship, with every owned section covered by a zero-query 20ms render-budget guard.
Deepen Campaign Studio / Events connected branches into real appeal cards + event lists (fundraising thermometer)	Done	L	High	§3 — closed 2026-06-07: connected campaign cards render hydrated progress/goal/action data, and events render hydrated event cards with date, location, type, and action links.
Resolve/justify `tw:` prefix exemption; apply prefix if not exempt	Done	M	Med	§2.2 — closed 2026-06-07: package theme Blade remains unprefixed because it is compiled through isolated `tailwindImport`/`tailwindSource` assets; a source guard pins the exemption.