Filament Nitpick Laravel Package

Technical Evaluation

Architecture fit packstub/filament-nitpick is a Filament panel plugin (Laravel/PHP) that layers runtime theme switching onto a Filament 5.x application. Architecturally it sits in the panel-configuration phase: it mutates the Panel object per request, registers a user-menu entry and/or Appearance page, and persists the selection. This release deepens that coupling deliberately — themes can now configure the panel directly (Theme::make()->panel(fn (Panel $panel) => ...), or a ConfiguresPanel theme class) and can attach their own Filament plugin while active (Theme::make()->plugin()). That is the right shape for a multi-theme product: theme behaviour travels with the theme rather than being re-declared by the host app.

The important structural constraint is now explicit: pages, resources and widgets added via the panel callback are not applied, because their routes are resolved before the request. Nitpick reports them instead of silently dropping them. This confirms themes are a presentation-layer concern only — if your product roadmap includes per-theme routes or navigation shapes, that is out of scope and needs a different mechanism.

Integration feasibility Integration is a composer install plus NitpickPlugin::make() on the panel, then defining themes. The public surface has consolidated nicely in this release: ->picker(fn (ThemePicker $picker) => ..., condition:, modal:, userMenuItem:, page:, transition:) is a single entry point with additive semantics (omitted options retain earlier values), and there is a documented theme-author path (docs/theme-authors.md) plus a convention for auto-joining the picker when both packages are present. For teams consuming third-party Filament themes rather than authoring their own, this is close to drop-in.

Technical risk

• Beta API churn is real, not theoretical. userSelectable() / appearancePage() (and their getters) are deprecated in this release and removed in 1.0. Any code written against beta.1 needs touching. Budget for one more breaking pass at 1.0 GA.
• Behavioural break in plugin(). Themes that previously relied on getStylesheets() / getColors() returning a bundled plugin's assets will now get neither; the plugin is instead mounted on the panel only while active. This is a correctness improvement (assets and global render hooks no longer leak onto every panel and every theme) but it is a silent-ish change for anyone who consumed those methods.
• Reload-based application. Themes that ship a plugin can no longer preview live — picking or leaving one triggers a full page reload. This is honest engineering given route/asset bootstrapping, but it is a UX regression against the advertised live preview and will surface as a product question, especially for users mid-form.
• State and mode persistence. Fixed here for Filament 5.10.2+ (filament:theme:mode, dual-written with legacy theme), which tells you the framework's own persistence contract moves under this package. Assume further churn across Filament minors.
• Third-party theme fragility. The modal-clipping fix works by stripping backdrop-filter/filter/transform from the topbar while a modal is open — a workaround aimed at one specific theme (Mia). Expect a class of CSS-interaction bugs that are theme-specific and hard to generalise.
• Octane correctness is addressed (panel restored at request end), which is a good signal, but any per-request panel mutation deserves an Octane/queue-worker regression test in your own suite.

Key questions

1. Which Filament, Laravel and PHP version ranges are supported and tested in CI, and what is the maintainer's stated 1.0 timeline?
2. What is the deprecation-to-removal window for userSelectable() / appearancePage() — is 1.0 imminent or a quarter out?
3. How are excluded pages/resources/widgets "reported" — log channel, debug UI, exception? Can it fail the build in CI?
4. Is the 2.5 s cover-lift cap tunable, and what does the panel look like when it times out on a slow connection?
5. For themes that force reloads, is partial-form state preserved, or do we need to warn users?
6. Does the picker honour per-user permissions/conditions (condition:) in a way that composes with our existing authorisation model?
7. What is the accessibility posture beyond prefers-reduced-motion — keyboard traversal of the modal, focus return, contrast of swatches?

Integration Approach

Stack fit Assumes a Filament 5.x panel on Laravel with Livewire; Tailwind-built theme plugins are explicitly supported without extra build steps, and filament:assets / filament:upgrade still publish plugin files. If your application is a single-panel admin, fit is high. Multi-panel or multi-tenant installs need a review of which panel the picker attaches to and whether theme selection is global or per-panel — the release notes do not settle this.

Migration path Greenfield: define themes, enable ->picker(), choose a Transition (Fade is the default; Transition::Sweep/Slide/false are options), and register the Appearance page only if you want a full-page surface. Brownfield from beta.1: replace ->userSelectable() / ->appearancePage() with ->picker(userMenuItem: ..., page: ...) now rather than at 1.0; audit any theme that reads getStylesheets() / getColors() for plugin assets, and move those themes to Theme::make()->plugin() or ConfiguresPanel depending on whether you want live preview (panel callback) or plugin fidelity (plugin, with reload).

Compatibility Filament 5.10.2+ is the well-supported path for mode persistence; earlier 5.x works via the dual-written theme key. Octane is accounted for. Compatibility with non-Filament-panel surfaces (front-end, marketing site) is out of scope. Any custom theme with its own CSS transitions should be tested against the cover/reveal sequence — Nitpick holds panel CSS transitions during the reveal, which can visibly delay intentional animations.

Sequencing

1. Spike on a staging panel: install, define two themes (one panel-configuring, one plugin-based), confirm reload vs. live behaviour and Octane cleanliness under load.
2. Replace deprecated calls and inventory theme asset consumers.
3. Build the design-system themes; validate swatch extraction and picker card layout (descriptions(), swatches(false), columns([...])).
4. Decide on the transition and reduced-motion posture with design and accessibility review.
5. Integrate the window.PackstubThemes.pick() JS API only if you need programmatic switching; note the { reload: true } + PackstubThemes.reload() contract for scripted picks.
6. Pin the beta, gate on the 1.0 release, and re-run the regression suite at GA.

Operational Impact

Maintenance Low-to-moderate ongoing cost, front-loaded. The package owns the hard parts (panel restoration, transition orchestration, mode keys). Your maintenance burden is theme authoring plus tracking Filament minors. The deprecation cadence is the main signal: a beta that removes APIs at 1.0 will require a coordinated upgrade, so pin exact versions and treat theme definitions as code under review.

Support Support load will concentrate in three predictable areas: (a) "my theme reloaded the page" — correct behaviour for plugin themes, needs a documented explanation and ideally a UI hint; (b) theme-specific CSS breakage (the Mia/backdrop-filter class of bug); (c) light/dark mode expectations, now that the switcher marks the mode the picked theme applies rather than the mode the page loaded with — arguably more correct but a behaviour change users will notice. Publish an internal FAQ before rollout.

Scaling Runtime cost is negligible for live switching. Reload-based picks cost a full page load and a re-bootstrap of Livewire plus lazy widgets, which the cover waits on (capped at 2.5 s). For large panels with heavy widgets, a theme switch becomes a multi-second operation — acceptable as a rare action, poor if users flip themes often or if themes are used for A/B presentation. Rapid re-picking is handled gracefully (the newer theme applies under the same cover), so no thundering-herd of reloads.

Failure modes

• Cover lifts before content settles, or times out at 2.5 s on slow links, exposing a half-styled page.
• A theme whose panel callback registers pages/resources/widgets — silently excluded, routes 404 or fall back; only "reported".
• A plugin-based theme's assets expected on every panel (previously true) now absent, producing an unstyled or under-styled panel until reload.
• Modal clipping reappears under a new theme with a different compositing property.
• Mode persistence regression on a Filament minor that moves the storage key again.
• Octane state bleed if any custom theme mutates the panel outside the provided callback.

Ramp-up A competent Laravel/Filament engineer can ship a first theme in a day; the docs/theme-authors.md authoring guide materially shortens the path for teams building their own themes. The conceptual load is the panel-callback vs. plugin split and its live-preview/reload consequence — this should be the first thing in your internal runbook, because it determines which of the two authoring models each theme must use.