Filament Themes Laravel Package

Technical Evaluation

Architecture fit

• This is a presentation-layer package: it owns theme selection, persistence and a ready-made Themes settings page. It does not touch domain logic, so it slots into an existing Laravel app without reshaping our architecture.
• The hasnayeen/themes contract for custom themes keeps theme definition in plain PHP classes — compatible with our config-driven, code-reviewed deployment model. No DB-stored CSS/HTML blobs, which is a meaningful security and reviewability win.
• Strong fit where we already run Filament panels and need white-label or brand-variant UI per customer/tenant. Weaker fit if our admin UI is not Filament-based; the "panel", "per-panel theme list" and Themes page concepts are Filament-shaped and would need re-implementation.
• Accessibility is a first-class concern here: WCAG AA contrast is asserted by the package's own tests for the six built-in themes. That is unusual and directly reduces our compliance burden — but only for shipped themes, not ours.

Integration feasibility

• Low integration effort: publish config + migration, register the plugin/provider on a panel, optionally enable the user-column storage mode. Expect a 1–3 day spike for a single panel including a look at the Themes page in both light and dark previews.
• Two storage strategies (dedicated theme_settings table vs. columns on the user model) is the main design decision. The table is the safer default; user columns are simpler but couple theme state to our user schema and complicate multi-tenant or guest/anonymous cases.
• canChangeTheme gate plus per-panel theme lists give us the policy levers we need to expose themes to some tiers/tenants and lock others to a single brand theme — enough to support commercial packaging without forking.

Technical risk

• Maturity: v1.0.0 is a first release. No upgrade/regression history, no security track record, unknown maintainer bus factor. Treat as a supply-chain dependency requiring a pin and a review gate.
• Contract coupling: our custom themes inherit hasnayeen/themes. If that contract shifts, our theme classes break. Mitigate with an internal adapter/base class so the blast radius is one file per theme.
• Accessibility gap at the edges: built-ins are test-guaranteed, but a free #rrggbb primary colour lets users pick combinations that fail contrast. Our compliance posture depends on either restricting the free-form input or validating it ourselves.
• Filament version coupling is the most likely breakage vector; a Filament major upgrade could strand the package.
• Runtime theming risks are unproven at our scale: flash of unstyled/default theme on first paint, config/asset caching behaviour, and cache invalidation when an admin changes a panel-wide theme.

Key questions

• Which Filament major versions are supported, and what is the stated support window/policy?
• Is hasnayeen/themes version-constrained, and is it maintained by the same author? What is the semver/deprecation policy for the theme contract?
• Does the free-hex primary colour path perform any contrast validation, or is AA guaranteed strictly for the six shipped themes?
• What are the fallback semantics when a stored theme no longer exists (theme removed from the panel list, custom class deleted)?
• Are the 10 translations complete, including our required locales, and is RTL verified? Who owns translation updates?
• What is the intended upgrade path and changelog discipline for 1.x?
• Any published performance characteristics for resolving the active theme per request (query per request? cached?).

Integration Approach

Stack fit

• Requires Laravel + Filament. Confirm our Laravel and Filament versions are inside the supported matrix before committing; this is the single gating compatibility check.
• Storage choice should align with our tenancy model. For multi-tenant panels, prefer the theme_settings table with a tenant scope over user-model columns, and keep panel-wide defaults in config.
• Accessibility ownership must be explicit: built-in themes = package's problem; our brand theme and any user-selected custom colour = ours.

Migration path

• No upgrade migration exists or is needed — this is an initial release, so we are greenfield adopters with no legacy theme state to convert.
• Adoption path is additive: introduce the package behind a feature flag on one non-critical panel, then migrate other panels by adding them to the per-panel theme list.
• If we currently hard-code brand colours in CSS, plan a short reconciliation step so the package's theme tokens become the single source of truth rather than creating a second, competing palette.

Compatibility

• Hard dependencies: Laravel version, Filament major, PHP version, and the hasnayeen/themes constraint. Pin all four in composer.json and record them in our dependency register.
• Front-end compatibility: verify the Themes page renders correctly under our asset pipeline (Vite), our CSP, and both light and dark modes.
• Locale compatibility: confirm the shipped 10 languages cover our supported set; any gap means we own translations from day one.

Sequencing

1. Compatibility spike: install in a throwaway branch, confirm Filament/PHP/Laravel support, view the Themes page with a custom theme class.
2. Decide storage model (table vs. user columns) and whether users get free-hex control or a curated palette only.
3. Build an internal theme base class + adapter around the vendor contract; author one brand theme and run our own contrast checks in CI.
4. Publish config/migration, wire the gate and per-panel lists, pilot on one panel behind a flag.
5. Accessibility and visual regression pass (light/dark, all supported locales), then expand panel by panel.
6. Defer the free-hex colour input to a later phase, or ship it with validation, until the accessibility story is proven.

Operational Impact

Maintenance

• Ongoing cost is low but non-zero: track package releases, and re-verify on every Filament major upgrade. Budget a recurring half-day per quarter plus a defined check at each framework upgrade.
• Our custom themes become first-class code we own — they need the same review, contrast testing and visual regression coverage as any UI change.
• Translation upkeep is ours for any locale not covered by the package's 10.

Support

• User-facing support load centres on "my theme didn't apply" (cache, stale config, missing row) and "my colours look wrong" (free-hex choices). A short internal runbook on cache clearing and theme resolution order will absorb most tickets.
• Admins need guidance on per-panel theme lists and the gate, otherwise the gate becomes a way to accidentally lock people out of theming.

Scaling

• Theme resolution is per-request and per-user; if it queries theme_settings each request it is a small but universal read. Confirm caching, and plan to cache panel-wide defaults.
• Large user bases with per-user theme rows add a modest row count to an already large table — acceptable, but choose the table approach deliberately rather than by default.
• Custom theme classes should be registered statically, not discovered by scanning, to keep boot cost flat as theme count grows.

Failure modes

• Missing published assets or stale config cache after deploy → default theme with no error; needs a smoke test in the deploy checklist.
• Stored theme no longer in the panel's allowed list → silent fallback or exception depending on implementation; verify and document.
• canChangeTheme misconfiguration → users or admins unable to change their theme; ensure a config-level override so we can always recover.
• Free-hex primary colour breaking contrast on buttons/links → accessibility regression we own; either validate on input or remove the input.
• Vendor contract change or abandoned package → all custom themes break at once; the adapter layer is the mitigation, and it should exist before the second theme is written.
• Flash of default theme on first paint → visible flicker on slow connections; check on a throttled connection during the pilot.

Ramp-up

• Low for any Laravel/Filament developer: config publish, plugin registration, one PHP class per theme. A mid-level engineer is productive in under a day.
• The non-obvious skills are accessibility validation and dark-mode visual QA — assign those explicitly rather than assuming the package's AA guarantee transfers to our custom theme.
• No new infrastructure, no new runtime service, no data platform work: this is a contained front-end/admin concern that a single squad can own end to end.