Filament Italia Laravel Package

Getting Started

Understand what you're installing before you install it. Despite the README blurb about Italian province/comune/CAP fields and codice fiscale validation, everything in the release notes and the package description points to a presentational package: a Filament v5 panel theme that ports the AGID / Bootstrap Italia design language (design tokens, component radii, header utility iconography) via Blade views and CSS custom properties. There are no migrations, models, jobs, or middleware. Confirm this yourself on day one:

composer require robyconte/filament-italia
ls vendor/robyconte/filament-italia/{src,resources,config}
cat vendor/robyconte/filament-italia/composer.json   # Filament + PHP + Laravel constraints

Minimal steps to a first render:

1. composer require robyconte/filament-italia (check the filament/filament constraint first — the description says v5, so a v4 panel is a non-starter).
2. Register the theme/plugin in the target panel provider (the exact FQCN comes from the README — expect something in the shape of ->plugin(...) or a ->viteTheme(...)/asset-registration call).
3. Publish assets or wire the package CSS into your panel's Tailwind entry file, then npm run build.
4. php artisan filament:assets && php artisan optimize:clear, then hard-reload the panel.

Where to look first: the compiled/uncompiled CSS that defines the --bsi-* custom properties, and the Blade overrides for the topbar and buttons. Those two files are the whole package's contract surface. Second stop: the changelog, because with this package patch releases change pixels (v1.4.1 is a pure visual release).

First use case: an Italian PA or PA-adjacent admin panel whose public site already runs Bootstrap Italia, where the back-office must look continuous with it and AGID conformance is a procurement checkbox. Pick one low-traffic panel, apply the theme, and get a screenshot baseline (Playwright/Percy) before you touch anything else — you'll need it as the gate for every future upgrade.

Implementation Patterns

Panel-per-theme ownership. Don't theme every panel by reflex. Apply the theme only to panels that need AGID continuity, and leave internal/ops panels on the Filament default. Filament themes fight over the same Tailwind layers; one owner per panel is the rule that keeps upgrades boring.

Token-first customization, not CSS forks. The package's extension point is CSS custom properties. Override --bsi-* values in your own panel CSS after importing the package stylesheet, rather than editing vendor files or patching Blade views:

/* resources/css/filament/admin/theme.css */
@import '.../vendor/robyconte/filament-italia/...';   /* package layer */
@layer components {
  :root { --bsi-radius-smooth: 4px; }
}

Anything you hard-code becomes a merge conflict the next time the maintainer retunes a token upstream.

Opt-in variants explicitly. v1.4.1 moved badges back to the smooth radius (4px) and kept .rounded-pill as the opt-in pill. That means your "pill badge" intent must now be expressed in code, not inherited from the theme. Grep for badges with pill-looking intent and make them explicit.

Screenshot + axe gate for upgrades. Because the compatibility surface is CSS variables and Filament's class contract — not PHP APIs — a composer update can't fail loudly. Wrap theme upgrades in:

npx playwright test --grep @visual   # list, form, topbar views
npx @axe-core/cli http://panel.test/admin/users   # focus: icon-only topbar, filled colored buttons

Diff the screenshots to separate intended from unintended changes, then run the accessibility scan on exactly the views the changelog touched. Keep the version pinned in composer.lock and batch patch upgrades behind that gate.

Integration tip for PA products: single-source the design tokens. If the public site and the admin both consume the AGID palette, define --bsi-* once (published CSS or a shared token file) and let both consume it. That's the pattern that makes the "our admin matches our site" claim survive a brand-token change.

Watch the build graph. If the package ships compiled assets, great — just publish. If it expects the host app to compile, its views must be in your Tailwind content globs and any dynamic classes need safelisting. A purged class doesn't error; it silently renders the Filament default and you ship a half-themed panel that passes every test.

Gotchas and Tips

Verify the README against the vendor tree before promising features. The description advertises province/comune selects, CAP helpers, and codice fiscale / partita IVA validation; the release notes describe badge radii and topbar icon buttons. These are different packages. Read vendor/robyconte/filament-italia/src and settle it before it lands in a sprint plan or a client deck.

All failure modes here are visual and silent. Missing or renamed --bsi-* tokens fall back to default radii and colors — the panel stays functional, just off-brand, and no test fails. Filament minor releases that restructure theme classes break your overrides the same way. Without a screenshot suite you find out from users.

Delete your old shims after upgrading to v1.4.1. Teams that compensated for squared badges with local CSS will now double-apply the radius, and anyone who forced pill badges globally now has pills where a 4px smooth radius was intended. Grep for .rounded-pill, fi- color overrides, and topbar action classes before you merge.

The icon-color change is a deliberate contrast trade-off. Filled colored buttons now inherit the label color for their icon instead of Filament's contrast-derived dark shade. Correct on the stock Bootstrap Italia palette; on a custom brand palette it can drop below WCAG AA. Check each filled button variant in your palette, not just the default.

Radius changes ripple into dense UI. Badges cluster in tables, filters, and status chips. The places that break are the dense ones nobody screenshots — include a table view with many chips in the baseline.

Confirm the asset strategy as an explicit decision, not an accident. Find out whether compiled assets ship or the host app builds them, and whether the --bsi-* tokens are bundled or expected from the host (and what happens when they're absent). If long-term stability matters more than upstream currency, vendor the compiled CSS and fork-ability-check the package — it's effectively single-maintainer, so plan for that bus factor.

Debugging recipe: devtools → computed styles on the failing element → inspect the resolved --bsi-* value → confirm which cascade layer wins → verify the class wasn't purged from the build. Nine times out of ten it's a purged class or a missing token, not a package bug.

Docs are Italian-only. Fine for the target market, real onboarding friction for a distributed team. Budget half a day for a front-end dev fluent in Tailwind and Filament theming (a backend dev should not own this) and write the internal English cheat-sheet yourself — it's cheaper than translating the README every release.