Meui Theme Laravel Package

Technical Evaluation

Architecture fit. MeUI (saivra/meui-theme) is not a general Laravel package — it is a Filament 5 panel theme plus an optional appearance-preferences subsystem. That constrains where it fits: it is appropriate for administrative/back-office panels built on Filament, and irrelevant to public-facing, API, or Blade-rendered surfaces. v0.2.0 moves the package from "static theme" to "theme + user-scoped preferences store," which introduces a small persistence and authorization layer that must be evaluated like application code, not like CSS.

• Theming layer: low architectural coupling — registers via a panel provider, ships assets, no domain-model impact.
• Customizer layer (opt-in): adds a migration, a preferences store keyed by panel, guard, and user, and developer-configurable authorization closures, allowlists, and persistence callbacks.
• The callback surface for an "existing preferences store" is the notable architectural point: it lets teams avoid a second source of truth for user settings, which is the right design for a mature application. Teams without an existing store should expect the included one to become a de facto system of record for appearance.

Integration feasibility. High for a Filament shop, in the straightforward case.

• composer require saivra/meui-theme + php artisan filament:assets is a two-step, no-migration path for theme-only adoption — very low integration cost.
• Enabling the customizer is a clean, documented three-step opt-in (publish migrations tag meui-migrations → migrate → register MeUiPlugin::make()->customizer()). Disabled by default is the correct default posture.
• Compatibility matrix explicitly covers Laravel 12 and 13 with minimum and current Filament 5 on SQLite and PostgreSQL — enough to de-risk a modern stack, not enough to cover older estates.

Technical risk.

Key questions for the maintainers / before adoption.

1. What is the public API stability commitment between 0.x and 1.0, specifically for customizerOptions(), authorization closures, and persistence callbacks?
2. Is there a documented upgrade policy tied to Filament major/minor releases, and a stated support window per Laravel/Filament version?
3. Does the preferences table carry any tenant/scope assumptions beyond panel+guard+user — and how does it behave under impersonation, multi-guard loginUsing, or queued/scheduled context where no guard is active?
4. Are the authorization closures fail-closed by default (deny when unset/misconfigured)?
5. What is the accessibility conformance target — the release cites 44px targets, forced-colors, and reduced-motion, but not a WCAG level or audit artifact.
6. Is there a CSS escape hatch (token overrides / custom stylesheet) so teams are not forked into the theme's markup?
7. Is the customizer's per-request preference read cached, and what is the query cost per panel page render?

Assessment: adopt for a Filament 5 pilot panel; defer broad rollout until the API-stability and support-window questions are answered.

Integration Approach

Stack fit. Requires Laravel 12 or 13 and Filament 5. Confirm the estate's actual versions before committing — if any panels are still on Filament 4 or Laravel 11, this package is out of scope for them until upstream support exists (it is not listed in the matrix, so treat it as unsupported rather than assumed-working). Database support is validated on SQLite and PostgreSQL; MySQL/MariaDB teams should run the migration and customizer flow themselves in staging before trusting it.

Migration path. Two distinct tracks, and they should be sequenced rather than done together:

1. Theme-only (no schema change). Composer require, publish/refresh assets, register the theme. Explicitly reversible — no migration, no data, no rollback risk beyond the asset rebuild.
2. Customizer enabled (schema change). Publish meui-migrations, migrate, register ->customizer(). This is additive and idempotent, but it creates a table that will hold user data — treat it as a one-way door for that table's schema and confirm a down-migration exists before production.

Pin an explicit version constraint (0.2.* or a locked tag) rather than floating, given the pre-1.0 API surface. Prefer the persistence callbacks to bridge into any existing user-settings store rather than running two stores in parallel.

Compatibility. Green on Laravel 12/13 + Filament 5 min/current + SQLite/PostgreSQL. Amber on:

• MySQL/MariaDB (untested in the matrix — verify migration and preference writes).
• Any panel that already overrides Filament theme CSS or publishes filament views — expect specificity conflicts; audit existing custom stylesheets first.
• Multi-panel installations: preferences are isolated by panel, so a user's appearance choices are per-panel by design. Confirm that matches the product expectation before enabling broadly.

Sequencing.

1. Design tokens first. Decide neutral palette, accent, corner radius, and density before enabling the customizer, then express those as developer defaults. This prevents users selecting a look that contradicts brand guidance.
2. Theme-only on one internal/non-critical panel. Validate visual regressions across auth pages (sign-in, registration, recovery), tables, forms, statistics, dialogs, and mobile.
3. Accessibility verification. Confirm keyboard dialog dismissal, forced-colors mode, and reduced-motion behavior on the panels you actually ship; test with a real screen reader, not only the cited checks.
4. Enable the customizer on that same panel with an authorization closure restricted to a pilot cohort and a narrowed customizerOptions() allowlist.
5. Decide the persistence target — included store vs. callback into the existing store — and only then widen the cohort.
6. Deploy-pipeline change. Add php artisan filament:assets to every deploy step, including rollbacks, and add a visual smoke check to CI/release QA.

Operational Impact

Maintenance. The dominant long-term cost is not the package, it is the CSS/markup coupling to Filament. Every Filament minor upgrade is a potential visual regression that automated tests will not catch; budget a manual visual pass per Filament upgrade, on both light and dark modes. Pre-1.0 versioning means reading release notes before bumping — v0.2.0 itself is additive and non-breaking for theme-only installs, which is a good sign, but that pattern is not guaranteed. MIT licensing provides a credible fallback: if the project stalls, the theme can be forked and maintained in-house, so the vendor risk is bounded but not zero.

Support. Community-supported via GitHub issues; no SLA, no commercial escalation path, single-vendor ownership. For an internal admin tool this is usually acceptable; for anything customer-facing or regulated, plan internal ownership of the theme layer from day one rather than relying on upstream responsiveness.

Scaling. Low risk. The customizer adds one preference read per authenticated panel request — cache it per user/panel/guard and the cost is negligible. The preferences table grows one row per user per panel (plus any variant rows, depending on schema), so it is trivially small. The customizer UI adds a small JS/CSS payload to authenticated pages only; it is disabled by default and scoped to signed-in users, so public and auth-page performance is unaffected. The only scaling concern worth measuring is per-request preference lookups on high-traffic admin panels with many concurrent operators.

Failure modes to design against.

• Assets not rebuilt after deploy → theme silently reverts or half-applies. Mitigation: mandatory filament:assets in the pipeline plus a post-deploy visual smoke test.
• Customizer registered without running the migration → errors on the profile action. Mitigation: migration and plugin registration in the same change set, never separated.
• Authorization closure unset or wrong → every signed-in panel user gains appearance controls. Blast radius is cosmetic, but verify fail-closed behavior.
• Allowlist drift → users can set combinations (e.g., high contrast + custom density) that the design system has not validated. Mitigation: narrow customizerOptions() initially.
• Identity edge cases (impersonation, multi-guard, support-staff accounts) → preferences attributed to the wrong scope or reset unexpectedly. Mitigation: explicit test cases in staging before rollout.
• Dual preference stores → appearance settings split between MeUI's table and an existing settings store, causing "my theme reset" reports. Mitigation: choose one persistence path via the callbacks before enabling.

Ramp-up. For end users: effectively zero — a "Customize theme" profile action with immediate apply and reset. For engineers: low-to-moderate. The README and gallery are substantially expanded and cover real sign-in, registration, recovery, Studio, customization, wizard, and product screens, plus a dedicated customization guide, which is above average documentation quality for a 0.x community theme. The real learning curve is Filament theming conventions (panel provider registration, asset publishing, view/CSS override precedence), not this package specifically. A team already shipping Filament panels can absorb this in days; a team new to Filament should not adopt the customizer in the same cycle as its first panel.