johnrivera7/filament-mia-theme
Filament MIA Theme is a custom visual theme for Laravel Filament admin panels, delivering a polished MIA-inspired interface with tailored colors, layouts, and UI styling to modernize dashboards and back-office screens. Easy to install and customize.
Before any composer require, read the repository description as a hard constraint: "Se terminó. A quienes les gustó el tema: lo siento." This is an end-of-life theme. Everything below assumes you are evaluating it as a design source or a short-lived experiment, not adopting a maintained dependency.
That said, v0.2.3 (a modal-clipping fix) proves a nuance worth internalising: the maintainer still ships sporadic patches. That is not a support commitment — it means "abandoned" here is "no roadmap, no SLA, occasional drive-by fix", which is worse to plan around than a clean freeze because it tempts you into expecting fixes.
Step 1 — Inspect the wiring, not the screenshots. Open the package's composer.json and service provider and answer three questions:
filament/filament constrained to the major you actually run (v5 per the description)? A theme built for one major dropped into another produces silent token breakage, not an exception.resources/views/? View overrides convert a cosmetic package into a per-upgrade merge tax.Plugin (->plugin(...)), a FilamentAsset::register([Css::make(...)]) call in a service provider, or a ->viteTheme() path? "Ships pre-compiled: no build step" strongly suggests the asset-registration route. v0.2.3's changelog talks about .fi-page transforms and stacking contexts — pure stylesheet work, which confirms it.Step 2 — Install pinned, on a branch. v0.2.3 is the floor; do not float it.
composer require johnrivera7/filament-mia-theme:0.2.3 --with-all-dependencies
Note the caret trap: for a 0.x package, ^0.2.3 resolves to >=0.2.3 <0.3.0, so a future 0.3.0 (potentially with its own CSS restructure) is excluded but every 0.2.x patch is pulled in silently on composer update. Given that a single patch line just changed modal layout, prefer an exact pin and upgrade deliberately. If it is not on Packagist with sane semver tags, add a VCS repository entry and pin to a commit SHA — never dev-main on a single-maintainer repo. Sanity-check the resolved constraint:
composer show johnrivera7/filament-mia-theme
Step 3 — Register on the admin panel only, in app/Providers/Filament/AdminPanelProvider.php:
public function panel(Panel $panel): Panel
{
return $panel
->id('admin')
->path('admin')
->plugin(\Johnrivera7\MiaTheme\MiaThemePlugin::make()); // if plugin-style
// otherwise: nothing here — the provider's FilamentAsset registration does the work
}
Step 4 — Publish assets and clear the cache stack. Precompiled themes are cached by Filament's asset pipeline; a stale cache is the #1 reason "the theme isn't applying". v0.2.3's own upgrade instructions specify filament:assets — run the full sequence on install and after every theme bump:
php artisan optimize:clear
php artisan filament:assets
php artisan filament:optimize
php artisan filament:clear-cached-components
Step 5 — First use case: a six-surface visual check. Log in to /admin and inspect, in this order:
Snapshot the commit where all six look correct. That snapshot is your stable reference, and it is also the thing to diff against on the next Filament bump.
Fork-and-own, don't depend. The sustainable pattern for an EOL theme is to extract, not import:
/* resources/css/filament/admin/theme.css */
@import '../../../../vendor/filament/filament/resources/css/theme.css';
/* MIA tokens lifted from the package, then your own overrides */
:root {
--mia-cream: #faf6ef;
--mia-champagne: #e8d9bf;
--mia-espresso: #1f1a17;
}
Copy the dist/ CSS into resources/css/ and the Tailwind theme block into your own config, register via ->viteTheme('resources/css/filament/admin/theme.css'), then drop the Composer dependency. You keep the design, you lose the liability.
v0.2.3 is the strongest argument for this so far: the package's own transform / animation-fill-mode: both on .fi-page created a containing block that clipped Create/Edit modals. A stylesheet you own is one you can patch in five minutes; a stylesheet you depend on is one you wait on, or override with !important from a second file you now have to maintain anyway.
If you must stay dependent, isolate the registration. Wrap the asset/plugin registration in your own service provider so the rest of the codebase never references the package namespace directly. Swapping sources later becomes a one-file change:
final class MiaThemeProvider extends ServiceProvider
{
public function boot(): void
{
// single seam: replace this body when you fork
FilamentAsset::register([
Css::make('mia-theme', __DIR__.'/../../resources/css/mia/theme.css'),
]);
}
}
This seam is also where you'd land a temporary patch for a bug like the v0.2.3 modal clipping if you hit it on a Filament version the maintainer didn't test.
Panel-scoped, always. Apply only to the back office. Internal admin and customer-facing panels should not share a vendored theme; a single abandoned dependency should never dictate the look of every surface in the app.
Load order is the integration. A precompiled theme must land after Filament's base stylesheet. If Filament's FilamentAsset::register([...]) array places your CSS before the base, utilities win over your tokens. Verify computed order in DevTools → Network/Styles before debugging anything else. Load order is also the usual suspect for "my override didn't apply" when you patch a vendor bug locally.
Compose with Filament's own branding hooks, don't fight them:
->brandName('Mia')
->brandLogo(fn () => asset('img/mia-logo.svg'))
->favicon(asset('img/favicon.ico'))
->darkMode(true)
->login()
->passwordReset()
The theme controls surfaces; you still control copy, logos, navigation groups, and panel colour (->colors([...])). Changing the primary colour will not restyle the surfaces — the description says every surface is hand-set — so don't expect accent-driven theming.
Reference tokens in your own views. When you write custom pages, widgets, or Blade blocks, use the theme's custom properties (var(--...-surface), var(--...-border)) rather than hardcoded cream/espresso hex. When the theme is forked or replaced, your custom pages follow along. Avoid putting transform/filter/perspective/animation-fill-mode on containers that hold Filament modals — v0.2.3 is a case study in what that costs. If you need motion on a page wrapper, scope it to a wrapper that does not contain any .fi-modal.
Budget a visual regression guard. Since failures are silent and cosmetic — and occasionally, as in v0.2.3, silently functional — a Playwright/Percy screenshot of login + dashboard in both light and dark mode is the cheapest insurance. Add one interaction: open a resource's Create modal and screenshot it. Run the suite in CI before merging a Filament minor bump and before accepting a theme patch bump.
Upgrade routine. Every composer update that touches filament/filament, johnrivera7/filament-mia-theme, tailwindcss, or vite:
composer update filament/filament -W
php artisan optimize:clear && php artisan filament:assets && npm run build
# then eyeball the six surfaces (modals included) + dark toggle, or let the screenshot job do it
Silent failure is the default failure mode — and it can hide functional bugs. Filament renames CSS custom properties and shifts class prefixes across majors. An unmatched theme doesn't error — it renders default Filament styling, or half-themed chrome. v0.2.3 is the sharper version of the lesson: valid, compiling CSS from a theme broke interaction (clipped Create/Edit modals, sticky headers lost on tall modals) without throwing anything. If a modal, dropdown, or sticky header misbehaves in your admin, bisect the theme before you file a Filament bug.
No upstream is coming — but random patches are. With 8 stars, 0 dependents, and an explicit discontinuation notice, there is no community to triage regressions and no fix path. v0.2.3 landed anyway, which means (a) your bug may sit unfixed for months, and (b) a patch may arrive that changes layout in a way nobody documented beyond a two-line changelog. Budget the theme as internal code from day one. Prefer composer install --no-dev-safe vendoring: commit the compiled CSS so a Packagist disappearance or a VCS repo removal can't break your build.
Read the changelog, then verify it. The v0.2.3 note claims the fix is limited to page transform / animation-fill-mode: both and modal vertical centering. Two-line changelogs on a 0.x package are not a spec. Diff the dist/ CSS between 0.2.2 and 0.2.3 before deploying, and re-run the modal check on your own Filament version — the fix was tested against whatever the maintainer runs, not yours.
Release metadata is unreliable. The listed last release (2026-09-23) is future-dated — a mistag or a broken release pipeline — yet v0.2.3 now exists alongside it. Verify against git tag and Packagist before trusting any version signal, and don't write ^x.y constraints off it.
License before copy. There is no confirmed license. If you extract the CSS into your own repo you are copying code; without a LICENSE file the default is all-rights-reserved. Get it in writing or treat the package as a visual reference only (read it, reimplement the palette — colours and layout conventions aren't copyrightable the way stylesheets are). The fork-and-own advice above is the right engineering call and the uncertain legal one; resolve that tension before you ship.
Check for view overrides early.
ls vendor/johnrivera7/filament-mia-theme/resources/views 2>/dev/null
If anything is there, diff it against current Filament's vendor/filament/*/resources/views and expect staleness. CSS-only is a contained risk; view overrides are a functional risk. Nothing in the v0.2.3 changelog suggests views were touched.
Don't skip the asset cache on every change. php artisan filament:optimize caches aggressively, and filament:assets is the command that republishes the theme's files into public/. Forget it after a version bump and you will spend an hour debugging CSS that isn't the file being served:
php artisan optimize:clear && php artisan filament:assets && php artisan filament:optimize
Dark mode is where hand-picked palettes fail. Espresso backgrounds plus muted text routinely miss WCAG AA. Run axe/Lighthouse on the login and a table page in dark mode, and specifically check:
--gray-900-equivalent surfacesHairline borders and serif headings also reduce perceived contrast at small sizes; check table density and helper text, not just the hero dashboard.
Third-party Filament plugins can break the look — and the modals. Shield, Curator, Activity Log, etc. ship their own colour assumptions, their own modals, and sometimes their own views. Register the theme, install plugins one at a time, and screenshot after each. A theme that renders perfectly until you add a plugin is a normal outcome here.
Debug bisect: comment out the theme registration and reload. If the layout bug persists without the theme, it's your panel code or a plugin — stop chasing CSS. If a modal clips only with the theme on, you're looking at a containing-block / stacking-context conflict, which is what v0.2.3 was.
Extension points to document when you fork. The token file is the API. Write down the variable names (--surface, --border, --heading-font, etc.), the panel-provider registration line, and any modal/stacking overrides you carried over, in your repo README. Six months from now, the person removing or replacing the theme needs only those facts.
Multi-panel proliferation. If the design spreads to N panels, every Filament upgrade becomes N visual checks against an unmaintained stylesheet. Fork first; proliferate second.
How can I help you explore Laravel packages today?