Filament Panel Theme Isolation Laravel Package

Product Decisions This Supports

• Multi-panel admin architecture: Directly supports the decision to run more than one Filament panel on a shared domain (e.g. admin for staff, app for customers, partner for resellers) without users' dark/light preference bleeding between panels. If the roadmap includes panel proliferation, this removes a known cosmetic/UX defect class rather than a feature bet.
• Build vs buy: Strong "buy" (adopt) signal for a ~single-concern plugin. The underlying fix is prefixed localStorage keys — trivially describable, but easy to implement inconsistently across panels, custom themes, and future Filament upgrades. Vendoring a maintained package is cheaper than owning that surface area.
• UX consistency as a product requirement: Theme preference is a small but visible trust signal in admin tooling. Supporting per-panel theming lets you keep a light, dense operator console for support staff while a dark, brand-forward panel serves external users — without one overriding the other.
• Roadmap dependency check: Adopting this effectively pins the admin layer to Filament v3. That is a planning input for any Filament v4 migration epic, not just an engineering detail.
• Scope signal: This package does not address per-user theme persistence across devices, per-panel branding, or authorization. Do not let it be sold internally as "multi-tenant theming" — it is narrower than that.

When to Consider This Package

Consider adoption when all of the following hold:

• You run two or more Filament v3 panels on the same domain and users (or the same browser) move between them.
• You have observed, or expect, theme preference leaking between panels — e.g. a user toggles dark mode in one panel and finds another panel unexpectedly dark.
• You are on Laravel 10+ / PHP 8.1+ and have no near-term plan to leave Filament v3.
• Your panels use Filament's standard theme switching rather than a fully bespoke, hand-rolled theme layer — custom implementations may already namespace their own keys and gain nothing here.

Look elsewhere or build in-house when:

• You have a single panel — there is no conflict to isolate, and the package adds a dependency for zero benefit.
• You are mid-migration to Filament v4 or run v2 — compatibility is stated only for v3; confirm support before committing.
• You need theming persisted server-side per user (cross-device, auditable) — this is a client-side localStorage solution, not a preferences backend.
• You require strict supply-chain guarantees: a 1.0.0 initial release from a new package implies a single-maintainer bus factor and no track record. For a purely cosmetic concern that may be acceptable; for anything regulated, weigh it.
• Panels live on separate domains or subdomains — browser storage is already partitioned, so the problem this solves largely does not exist.

Risk note for the adoption decision: the package is small and its failure mode is cosmetic, so the downside of trying it is low and reversible. The real cost is a permanent minor dependency plus an upgrade gate on Filament v4.

How to Pitch It (Stakeholders)

For executives: We run multiple admin interfaces on one domain, and today a user's light/dark preference in one leaks into the others — a small but recurring polish defect that generates support noise and undermines confidence in our internal tools. A focused, low-cost plugin isolates that preference per panel. It is a low-risk adoption: the fix is cosmetic in nature, easy to remove, and requires no changes to our data model or infrastructure. Main caveat: it ties us to Filament v3, so it should be logged as an input to our eventual v4 upgrade planning, not treated as a permanent fixture.

For engineering: This is a single-purpose Filament v3 plugin that namespaces theme preference in localStorage per panel, resolving cross-panel theme bleed. Requirements: Filament v3, Laravel 10+, PHP 8.1+. Integration is negligible — install, register the plugin on the panels that need isolation, verify existing custom themes aren't already prefixing their own keys. Two things to confirm before merge: (1) whether our Filament v4 timeline makes this a short-lived dependency, and (2) that the package's key-prefixing strategy composes cleanly with any bespoke theme JS we've written. If either is unfavorable, the underlying behaviour is small enough to reimplement internally in an afternoon — so treat this as a convenience purchase, not a strategic commitment.