Filament Themes Laravel Package

Product Decisions This Supports

• Ship a personalisation feature without owning the design-system work. Six curated themes, light/dark preview cards, primary colour swatches and a free #rrggbb picker give us a user-facing appearance setting in a sprint rather than a quarter.
• Build vs buy. An in-house switcher typically means a theme contract, a storage migration, per-panel scoping, a permission gate, an admin UI and translations. This package ships all of that plus contrast tests — the piece teams almost never write for themselves.
• Accessibility as a product decision, not a design promise. WCAG AA contrast is guaranteed by tests for the six built-in themes, which de-risks VPAT / EN 301 549 questions and public-sector procurement. Caveat for the PM: the guarantee is bounded to the built-ins — the free-form #rrggbb input can produce non-compliant combinations, so decide whether to restrict or warn on custom colours for regulated tenants.
• Multi-panel / multi-audience roadmap. Per-panel theme lists plus per-user vs panel-wide choice let one deployment present different branding to admins and to customers without a fork.
• Storage decision is a real product trade-off. theme_settings table vs user model columns: choose the table when themes are shared and the user table is already wide; choose columns when you want no extra join on every request.
• Monetisation lever. canChangeTheme maps directly to entitlement — e.g. custom themes for paid tiers, Default-only for free users. Treat it as packaging, not a boolean.
• Extensibility as content, not engineering. Custom themes are plain PHP classes implementing the hasnayeen/themes contract, so a brand theme becomes a class plus swatches that the design team can own.
• Localisation roadmap. 10 languages out of the box removes the settings-page i18n item from the backlog (verify our locale is actually among them).

When to Consider This Package

Consider it when:

• You're on Laravel and, most likely, Filament panels, and need a theme selector that already includes UI, persistence, gating and translations.
• You need per-user and per-panel theming in the same application.
• Contrast/accessibility is a requirement or a recurring sales objection.
• A small curated set of themes is acceptable — you don't need a full design-token engine.
• You want brand themes authored by your own team as PHP classes rather than configured through a CMS.

Look elsewhere when:

• You need runtime, non-developer theme authoring (a live theme builder with save/publish).
• Your needs are token-level — spacing, radius, typography scales, component variants — rather than palette plus light/dark.
• You're not on Filament/panels, or the "panel" concept doesn't map to your architecture.
• You need per-tenant arbitrary CSS, theming of emails/PDFs, or CSS variable injection at scale.
• Themes are business-critical and you can't accept the risk of a v1.0.0 first release with a single maintainer and no proven upgrade path — budget for a fork, a wrapper, or escrow.
• You require contrast guarantees on arbitrary user-chosen colours; you'll have to constrain the free #rrggbb path yourself.

Adoption checklist: pin the version, review the theme_settings migration, confirm the canChangeTheme hook point, verify the 10 locales include ours, and run the package's contrast tests in our CI alongside our own tokens.

How to Pitch It (Stakeholders)

Executives: A small, finished feature we would otherwise build. Customers get six professionally designed themes, per user or per panel, with accessibility contrast enforced by automated tests — one less compliance risk and one less custom build. It also gives us a clean paywall hook (canChangeTheme) to reserve custom branding for higher tiers. The cost is a package dependency, not a project.

Engineering: v1.0.0 ships the Themes page (preview cards, light/dark, primary colour swatches, free hex), six built-in themes with WCAG AA tests, per-user and panel-wide scope, per-panel theme lists, a permission gate, a PHP-class theme contract, two storage strategies, and 10 locales. It replaces the homegrown switcher we'd otherwise maintain. Known risks: first release, single maintainer, and free-form hex can break contrast — so we pin the version and constrain the picker.