Filament Mia Theme Laravel Package

Technical Evaluation

Architecture fit. Unchanged at the boundary: still a presentation-layer artifact with no domain logic, routes, migrations or persistence, and still welded to one Filament major. What v0.2.3 changes is our read of how deep the presentation layer reaches. The fix describes page-level transform / animation-fill-mode: both on .fi-page creating a containing block and stacking context under a sticky sidebar, clipping Create/Edit modals and dropping their headers. That is not token-level restyling — it is CSS that reaches into Filament's page shell, sidebar and modal/teleport layering. Treat this as a page-shell skin with behavioral side effects, not a color palette. It also means the theme is version-sensitive to Filament's layout internals, not just its CSS variable names, which is a materially shorter half-life.

Integration feasibility. Mechanically still trivial: one Composer require, one registration line, no build step — but note the release instructions add php artisan filament:assets as a required post-install step. That is cheap, yet it is a per-deploy obligation that can be forgotten in a pipeline; it belongs in the runbook, not in someone's head. Version constraint nuance: ^0.2.3 resolves to >=0.2.3 <0.3.0, so patches and 0.2.x minors flow in automatically while 0.3.0 is a breaking event by 0.x convention. If we were to install it, pin to 0.2.* and treat any 0.3.0 as a re-evaluation, not an upgrade. The original caveats stand: Packagist presence, registration mechanism (->viteTheme() vs. plugin), and whether it ships view overrides — that last one is still the difference between cosmetic and upgrade tax.

Technical risk — high, and the classification of that risk has shifted. One prior note held an explicit end-of-life statement from the maintainer, and we treated it as dominant. v0.2.3 partially supersedes it: someone is still shipping patches. That is a genuine positive and we should record it. It does not, however, change the structural position, and the nature of this release raises a risk we had underweighted.

The important finding is the defect class. Our prior assessment asserted a compensating factor — "blast radius is contained; a theme failure is visual, not transactional." v0.2.3 is direct evidence against that. A theme that manipulates the page's containing block can break Create/Edit flows outright, and the failure surfaces as a rendering artifact with no error, no log line and no test failure. It also demonstrates the support model in practice: the fix existed, but only upstream, on the maintainer's schedule, and only after someone hit it. With zero dependents, "someone" is us.

Secondary risks unchanged and still open: unknown license (blocks code copying until resolved — still a real gate given extraction is the recommended path), unknown Laravel/PHP floors, and whether the pre-compiled CSS targets Tailwind v3 or v4 conventions.

Key questions to close before any decision:

1. Which Filament major(s) and Laravel/PHP floors are supported, and is that encoded in composer.json?
2. What is the theme's actual CSS footprint on the shell — does it transform .fi-page, the body, panel wrappers, or modal/teleport containers? (v0.2.3 says at least one of these.)
3. Does it publish CSS/assets only, or override Blade views and panel components?
4. What is the license, and is the repo archived or merely dormant?
5. Does it register via viteTheme(), a plugin, or a legacy path — and is filament:assets mandatory or optional?
6. Is there any evidence of testing against Filament patch releases, or is the release cadence purely reactive to bug reports?

Verdict as a TPM: unchanged in direction, strengthened in conviction — do not adopt as a runtime dependency. v0.2.3 is simultaneously the best and worst argument we have: it proves the maintainer is responsive, and it proves the package can break core admin flows in ways only its author can fix. Approve at most a timeboxed design-reference spike. Our build path — a panel-scoped theme.css, a Tailwind config, two lines in the panel provider — is one to three engineer-days and leaves us owning code we can fix in an hour. This release is exactly the ticket we would not want to be blocked on.

Integration Approach

Stack fit. Laravel + Filament panel + Tailwind, applied to one back-office panel and not the customer-facing one. Two gates now instead of one: the Filament major (v5 target), and our panel's shell layout. If our admin uses a sticky sidebar and full-page layout — the combination named in the bug report — we are squarely inside v0.2.3's blast radius and should validate the fix visually before anything else. A v5 theme in a v3/v4 panel still fails as broken tokens and missing styles rather than a clean error.

Migration path — source, not dependency, and this release is the worked example. The recommended path is unchanged and now better justified:

1. Spike in a throwaway panel to evaluate the visual result against our current admin, including opening a tall Create and Edit modal.
2. Extract the CSS custom properties and Tailwind theme config into our own resources/css/filament/{panel}/theme.css.
3. Register via ->viteTheme() in our own PanelProvider.
4. Drop the Composer dependency entirely.

Note what step 4 buys us in concrete terms: the v0.2.3 fix is essentially a containing-block/stacking-context correction. Extracted into our own CSS, that is a same-day patch on our schedule. Consumed as a dependency, it was a wait-for-upstream ticket on a single-maintainer repo with no other users filing it first.

If a short-term dependency is genuinely unavoidable: fork to our org, pin to the v0.2.3 tag or a commit SHA (never dev-main), register a path or private Packagist repository, and constrain to 0.2.*.

Compatibility. Five checks, each cheap and each independently blocking: Filament major; Tailwind major (v3 vs v4); PHP/Laravel floors; presence of resources/views/ overrides; and post-upgrade modal/form smoke test on our actual panel layout. If views are overridden, diff them against current Filament and assume stale — that finding alone should kill extraction in favor of a from-scratch theme.

Sequencing. (1) License + Filament-version gate — one hour, go/no-go. (2) Sandbox spike with a visual diff, explicitly exercising tall Create/Edit modals and the sticky sidebar. (3) Extraction into owned CSS, or a decision to build clean. (4) Remove the dependency and close the ticket. Total elapsed under a week, dominated by design review rather than engineering.

Operational Impact

Maintenance. Upstream is alive but pre-1.0 and single-maintainer. That is a better position than "declared finished" and still not a support contract. Whatever we install we own from day one, including every future Filament layout change — and v0.2.3 shows those changes break things in the page shell. Budget as internal code with a named owner and a regression checklist (tables, forms, modals, auth screens) after every Filament bump.

Support. Effectively none. Zero dependents means no community triage and no corpus of others hitting the same Filament-version edges — the reason this bug existed long enough to be reported is that almost nobody runs this package. Escalation is our engineers reading CSS, with the additional wrinkle that a containing-block bug presents as a visual glitch rather than a stack trace. Acceptable for a theme; disqualifying for anything with a data path.

Scaling. Runtime cost negligible — static CSS, one filament:assets publish per deploy. The scaling concern is organizational and now sharper: because the theme touches the page shell rather than just tokens, applying it to N panels multiplies both the styling choice and the layout risk across N admin surfaces, each with its own layout configuration. Keep it panel-scoped from day one.

Failure modes, in likelihood order:

• Silent visual breakage after a Filament minor/major bump — still likely, but reclassify severity upward: it can mean clipped Create/Edit modals, not just off-brand colors.
• Asset pipeline or publish-step mismatch despite the "no build" claim — likely, loud, fixable; filament:assets is now a documented deploy dependency.
• Release cadence stops again, returning us to the prior EOL position — moderate, and the most probable future state for a zero-dependent single-maintainer package; fully mitigated by extraction.
• License ambiguity surfacing during audit or acquisition diligence — low probability, high nuisance, cheap to pre-empt.
• Stale view overrides breaking panel functionality post-upgrade — low probability, highest severity. Confirm this before anything else.

Ramp-up. Hours for any engineer fluent in Tailwind and Filament; days to full ownership of an extracted theme. The curve is trivial, which remains the anti-adoption argument — and v0.2.3 sharpens it rather than softening it. When building costs a day and adopting costs a permanent single-maintainer liability where the failure mode is a broken admin form with no error message, build wins on both risk and total cost of ownership.

Product framing for stakeholders. Admin visual differentiation remains low-leverage relative to core workflow work. The cheapest defensible experiment is a design spike plus a few engineering days on an owned theme, with a stated hypothesis (faster admin task completion, fewer "where do I click" support tickets). Position this package as inspiration and reference, not infrastructure. On our adoption gate — active maintenance, meaningful dependent base, sane and recent releases, clear upgrade story across majors — v0.2.3 moves exactly one criterion from red to amber (active maintenance) and leaves the rest. It still fails the gate, and the release that revived it is also the clearest evidence of why.