Filament Theme Inspector Laravel Package

Technical Evaluation

Architecture fit. filament-theme-inspector is a developer-experience utility that lives inside a Filament panel, not application infrastructure. Its surface is deliberately narrow: a plugin/service-provider registration plus client-side assets that traverse the rendered DOM, match elements carrying Filament's fi- prefixed classes, and surface the class string in a hover tooltip with click-to-copy. There is no persistence, no migration, no public API, no queue, no business-logic coupling, and no data flowing in or out of the application. The correct placement is a local/dev-only panel concern — ideally one dedicated "design sandbox" panel rather than the shared admin panel — behind a hard environment gate. From a TPM lens its production architecture value is zero while its governance cost is non-zero: treat it as a developer convenience with an explicit boundary, not a platform component.

Integration feasibility. Mechanically trivial — a Composer require, a ->plugin(...) entry in a PanelProvider, and Filament's standard asset-publish flow. Realistic effort for a Filament-fluent engineer is under an hour including verification. The binding constraint is not engineering effort but lifecycle governance: the repository is archived as of its last release (October 2024), with zero dependents and ~45 stars. A raw composer require therefore introduces an unmaintained dependency into the admin toolchain — acceptable only if the organization explicitly accepts ownership. The TPM decision is "adopt as vendored source we control," not "consume as a supported dependency."

Technical risk. Blast radius is low by construction: the tool observes DOM attributes already rendered to an authenticated admin user and reads them back. No exfiltration surface beyond what the panel already shows, no write path, no schema, no queue. The material risks are lifecycle and hygiene:

• Abandonment (high likelihood, low immediate severity). No patch channel, no compatibility matrix, no maintainer. Assume we own every future fix.
• Accidental production exposure (low severity, high policy visibility). Without explicit gating it ships to a production panel — a security-review smell and a self-XSS-adjacent surface even if harmless in practice.
• Asset/CSP friction (moderate likelihood). Injected script can be blocked by a strict Content-Security-Policy; clipboard writes require a secure context, so copy-to-clipboard fails silently on plain-HTTP staging hosts.
• Version coupling (certain over time). A tool keyed to fi- class conventions is directly exposed to Filament major-version changes.
• Convention dependency. Custom themes that rename or extend the fi- prefix may yield partial or misleading results.
• Documentation drift. Two descriptions circulate: one advertises hover-to-reveal fi- classes, the other claims CSS-variable and color-token inspection with light/dark preview. Confirm the actual feature set before scoping a pilot — if token inspection is real, it partially overlaps with Filament's own theming docs; if it isn't, stakeholder expectations are already miscalibrated.

Key questions to resolve before adoption.

1. Which Filament majors (v3 vs. v4) does it support, and what is the minimum PHP version? The v3-era release date suggests v4 is unverified or broken.
2. Is it a true Filament plugin registered via ->plugin(), or a bare service provider requiring manual if (app()->isLocal()) wrapping?
3. Does it ship precompiled assets, or does installation require a Node/Vite build step that must fit our pipeline?
4. Is the license posture clean for forking and internal redistribution? MIT permits it — confirm no bundled assets carry a different license.
5. Is the DOM scan one-shot on load or a MutationObserver? This determines degradation on large, live-updating panels.
6. Can registration be gated by configuration rather than code, so the gate is enforceable in CI rather than dependent on reviewer memory?
7. Who is the named internal owner, and what is the agreed trigger for fork, reimplement, or discard?

Integration Approach

Stack fit. Laravel + Filament, development and design-QA environments only. Belongs as a require-dev entry or a vcs/path repository in the root composer.json, registered on exactly one panel — a dedicated design sandbox is preferable to the shared admin panel, keeping the tool's failure modes away from daily work.

Migration path. Do not adopt from Packagist unmodified. Two defensible paths:

• Fork-and-vendor (recommended if the trial shows value). Fork under MIT into an internal namespace, pin as a vcs repository, accept ownership of a small PHP/JS surface. Cheap, and it converts abandonment risk into a bounded, owned maintenance line item.
• Reimplement (recommended if usage stays narrow). The core behavior — match [class*="fi-"], read className, tooltip, navigator.clipboard.writeText — is a small script. A bookmarklet or a single dev-only Blade-injected script removes both the dependency and the Filament-version coupling.

Either path is a one-commit change with no data or API surface to unwind, which supports a low-ceremony, time-boxed trial rather than a formal architecture review. Treat upstream as a reference implementation, not a dependency.

Compatibility. Verify against the pinned Filament minor before piloting. Confirm asset registration does not collide with the Vite pipeline or with Filament's own asset-publishing command. Under strict CSP, add a nonce or hash for the injected script or the inspector will not initialize; under plain HTTP, document that copy-to-clipboard will fail. Add an explicit minimum-version constraint and a smoke check to the dev environment bootstrap.

Sequencing.

1. Spike (½ day). Install on a throwaway branch, register on a local panel, confirm tooltip and copy behavior under our CSP and asset pipeline.
2. Gate. Wrap registration in an explicit environment/config check; add the gate to the pre-deploy checklist and, ideally, a CI assertion that the plugin is absent from production builds.
3. Pilot (one sprint). Run with the engineers owning Filament theme customization; measure whether it shortens the inspect-edit-reload loop versus DevTools, and whether designers/QA actually adopt it.
4. Decide — fork, reimplement, or discard. Commit to this before the next Filament major appears on the roadmap, not after.
5. Document. One paragraph in the internal frontend guide on the fi- convention and the inspector's scope — this is where much of the durable value sits, independent of the package itself.

Operational Impact

Maintenance. The dominant cost and the one most easily understated. Archived software transfers a maintenance obligation on day one whether or not it is acknowledged. Realistic budget: near-zero in steady state, one to three engineer-days when Filament ships a major version. Weigh that against the alternative — engineers reading class names manually in DevTools — which is also near-zero per occurrence. The honest ROI case is onboarding velocity and design-QA throughput for people new to Filament's conventions, not ongoing productivity for experienced engineers.

Support. No upstream: no issue triage, no advisories, no compatibility guarantees, no community depth at ~45 stars and zero dependents. Internal ownership must be named explicitly — even as a "best effort, fix on break" arrangement — so it does not drift into the unowned-dependency bucket and surface as an archaeology exercise during an upgrade.

Scaling. Negligible. Client-side DOM traversal on an admin panel is a rounding error in performance terms. The only scenario worth measuring is a panel with thousands of live-updating nodes where a MutationObserver-based implementation could add frame cost — and dev-only deployment makes this moot.

Failure modes. Filament major upgrade breaks asset registration or class-prefix assumptions; assets not republished after a fresh clone; CSP blocks the injected script; clipboard unavailable on non-HTTPS staging; plugin registered on a panel that reaches production. All are loud, fast failures with no data consequences — the cheapest category to absorb. The one that can hurt quietly is a production leak: it fails no test, produces no error, and is discovered in a security review. That is the failure mode worth spending CI effort on.

Ramp-up. Near-zero for anyone who has used browser DevTools; the interaction model is hover-and-copy. The real ramp-up cost is organizational, not technical: designers and QA need a short how-to and a known URL for the sandbox panel, or adoption stalls at the two engineers who installed it. Budget the documentation paragraph, not a training session.