Filament Qt5 Theme Laravel Package

Getting Started

1. Install the package. composer require <vendor>/<qt5-theme> — the release notes don't name the package, so confirm the exact name from Packagist/the repo before writing it into your composer.json. It requires PHP ^8.2 and Filament ^4.0 | ^5.0, so check your panel's Filament constraint first (composer show filament/filament) — a v3 panel will not install.
2. Look at the service provider and resources/ before touching your panel. The README should tell you whether the theme is registered as a Filament plugin (->plugin(Qt5ThemePlugin::make())) or as a Vite theme (->viteTheme('resources/css/filament/admin/theme.css')). Both are plausible for a CSS-heavy theme package; the presence of a Plugin class in src/ is the tell.
3. Build assets. If it's a Vite theme, you must add the package's CSS entry to your Tailwind input and run npm run build — Filament will silently fall back to its default look if the compiled theme isn't registered.
4. First use case: apply it to a single panel (usually AdminPanelProvider) and check the login screen, the resource list table, and a create form — those three screens exercise buttons, inputs, selects, badges, tables, pagination, sections and the auth screens, i.e. most of the advertised surface area.

Implementation Patterns

Theme one panel, not all of them. Filament panels are independent; a common pattern is a Qt5-styled back-office panel while leaving a customer-facing panel on the stock theme. Register the theme only in the panel provider that needs it — this also makes it trivial to A/B the upgrade.

Treat dark mode as a first-class target. The package ships both variants, so verify your panel's ->darkMode() setting and your own custom CSS uses the same strategy (Filament v4 uses the .dark class). If you've layered brand colours on top, test them in both modes before rollout.

Layer your brand on top rather than editing the package. Prefer appending your own @layer rules / CSS variables in your theme file over publishing and editing the package's views. Published views become a fork you have to re-diff on every release — and v1.0.0 is the first release, so expect churn.

Publish views selectively, not wholesale. If a single component (say the topbar or the file-upload drop zone) needs a structural change, publish only that view via php artisan vendor:publish --tag=filament-views-style tags the package exposes, and record it in your upgrade checklist.

Auth screens come free. Because login/registration/password-reset/2FA are in scope, don't hand-roll auth views — point users at the panel's built-in auth pages and let the theme do the work. If you have Breeze/Jetstream alongside, keep the two visually separate on purpose.

Compose with other plugins cautiously. Third-party Filament plugins often ship their own views and Tailwind classes; check the ones you depend on (e.g. anything with custom modals, wizards, or charts) against the theme's component list — anything not listed is styled by Filament defaults and may look inconsistent next to themed chrome.

Pin the version in composer.json. For a 1.0.0 theme in a production panel, "^1.0" is fine, but lock it and read the changelog before bumping — visual packages don't follow semver guarantees the way libraries do.

Gotchas and Tips

• "Nothing changed" is almost always an asset/build problem. Check, in order: theme CSS is actually registered on the panel, npm run build ran after install, php artisan filament:assets (if applicable), php artisan view:clear, and browser cache. Tailwind's content scanning is the usual culprit — vendor view paths must be included (v4: @source directives; v3: content[] in tailwind.config.js), otherwise classes used only by the package's Blade get purged.
• Component coverage has holes. Buttons, inputs, selects, tables, modals, toasts, etc. are covered — but the notes don't mention repeaters, builders, rich editor, date/time pickers, wizards, charts, or the notifications page. Audit the forms you actually ship; a half-themed form is more jarring than an unthemed one.
• Filament 4 → 5 upgrade risk. The package claims ^4.0 | ^5.0; if it's a single codebase supporting both, some components likely branch on the major version. When you upgrade Filament, upgrade this package in the same PR and re-check the highest-traffic screens rather than trusting the constraint.
• Don't fight specificity in the package's own CSS. Use CSS layers or variables for overrides; ad-hoc !important in your theme file will collide with the next release. If you find yourself writing !important, that's a signal to publish the view instead.
• Watch the file-upload drop zone and modals specifically. These are areas where custom CSS most often interacts badly with JS behaviour (drag states, focus trapping, z-index stacking against the topbar/sidebar). Manually verify keyboard focus and ESC-to-close after install.
• Performance: extra CSS is cheap, but if the package ships fonts or icons, check the payload. Qt5-inspired styling often implies a specific typeface — confirm whether it's bundled, loaded from a CDN, or expected to be installed by your app.
• No config file is mentioned. If one exists after install, publish and review it; if not, all customisation goes through your theme CSS and published views — document that for the team so future devs don't hunt for a config/qt5-theme.php that doesn't exist.