Filament Sleek Theme Laravel Package

Getting Started

Install the package and assets

composer require hansenmakangiras/filament-sleek-theme:^1.3
php artisan vendor:publish --tag="filament-sleek-theme-config"   # optional but recommended
npm run build

The npm run build step is not optional — this package ships styling, and most "it didn't work" reports after an upgrade are stale compiled assets rather than a broken release.

Where to look first

1. README.md — the 2560×1440 showcase covers now double as an accurate feature matrix (glass, OLED, compact, contrast modes). Match your target look to a mode before writing code.
2. config/filament-sleek-theme.php — every fluent method has a config key (e.g. 'topbar_contrast' => false). This is the fastest way to see the full option surface in one file.
3. Your panel provider — the fluent chain is where day-to-day configuration actually lives.

Register and enable a mode

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentSleekThemePlugin::make())
        ->darkMode() // OLED only renders under .dark
        ->oled();
}

First use case: pick one mode and ship it. A dark admin panel with ->oled() plus ->compact() is the lowest-risk entry point; it fixes the two most common complaints (washed-out dark mode, oversized tables) without touching light-mode layout. Add ->glass() or the contrast modes in a second pass.

Implementation Patterns

Fluent chaining in the panel provider

->plugin(
    FilamentSleekThemePlugin::make()
        ->oled()
        ->glass()
        ->compact()
        ->sidebarContrast()
        ->topbarContrast()
        ->accentGlow()
        ->scrollbars()
        ->grayColor(Gray::Zinc)
        ->font('Inter')
)

Chain order doesn't matter, but enable order does for debugging: add one modifier per commit so a visual regression has an obvious culprit.

Config-driven theming for multi-panel apps

When several panels share a codebase (admin, ops, tenant portal), don't bake styling into PHP per panel — publish the config and drive it from config/filament-sleek-theme.php. This lets an ops panel run OLED + compact while a customer portal keeps a light glass look, and it keeps styling out of git diff on provider files.

Per-panel identity

• Internal ops / NOC: oled() + compact() + sidebarContrast() — maximum density on dark displays.
• Customer-facing portal: glass() + grayColor() + soft radii, light mode only.
• Marketing-style demo panel: topbarContrast() in light mode, which produces the signature inset light canvas under a deep slate header.

Custom theme path instead of forking CSS

The package supports a custom theme path and preserves viteTheme on the panel. Use it to layer app-specific overrides:

->viteTheme('resources/css/filament/admin/theme.css')

Put your overrides in your own theme file and keep the package's CSS untouched — a composer update then never clobbers your work. The flip side: if you do publish/copy package CSS into your app, you opt out of every future fix in this changelog.

SPA / wire:navigate panels

SPA support is explicitly handled, but any JS you add around panel navigation should re-init on livewire:navigated. Theme classes applied to <body>/.fi-main-ctn survive navigation; ad-hoc DOM mutations in a document.addEventListener('DOMContentLoaded') handler will not.

Upgrade workflow

composer update hansenmakangiras/filament-sleek-theme
npm run build
php artisan optimize:clear
php artisan filament:assets

Then hard-refresh and click through: table row action dropdowns, filters, modals, slide-overs, date/color pickers, and the auth pages. Those are the surfaces this release touched most.

Verify with a smoke test

The package ships a test suite and a CI matrix (PHP up to 8.5). Mirror the idea cheaply in your app: one Pest/Livewire test that renders each panel's dashboard for an authenticated user. It catches CSS/asset-pipeline breakage on upgrade without asserting pixel output.

Gotchas and Tips

Stale assets are the #1 false positive. After upgrading, npm run build + php artisan filament:assets + hard refresh. If a feature from the changelog "doesn't exist," check the compiled CSS hash before filing anything.

Published CSS from an older version can mask fixes. v1.3.1 fixed table action/dropdown stacking contexts and the slide-over sticky header. If you previously copied package styles or pinned older published assets, those fixes will not reach you. Prefer the custom-theme-path approach over vendored copies.

Stacking context is fragile and app-specific. The release raises table action dropdowns to z-index: 40/50 and restricts cell z-index to active dropdowns. Custom table columns or widgets that set position: relative, transform, filter, or overflow: hidden create new stacking contexts that will re-trap your action menus. Symptom: menu clipped behind the next row, or filters hidden behind the header toolbar. Fix by removing transforms in the cell, or use x-filament::dropdown with a portal rather than a custom popover.

Glass mode deliberately makes dropdowns opaque. Frosted panels are translucent; dropdown panels are not, to prevent bleed-through. Don't fight this with !important transparency — readability collapses over dense tables.

OLED only applies under .dark. OLED is strictly scoped to .dark (with #000000 canvas and #09090b surfaces). If your app toggles dark via a bespoke class or a custom darkMode() strategy, OLED silently no-ops. Confirm Filament's dark mode is active before debugging styles.

Contrast modes are not "dark mode." topbarContrast() / sidebarContrast() render deep slate frames and, in light mode, an inset light canvas. Brand-colored topbars and logos chosen for a white header will look wrong; re-check brand assets in both modes. Note the config default is false — you must opt in.

compact() shrinks buttons to 2rem. Custom action buttons with hard-coded padding/min-height, icon-only buttons, and third-party widget toolbars are the usual overflow victims. Test dense form grids and the tenant switcher, both of which are compacted.

Tailwind v4 / Filament v5 purge issues. If you build your own theme, ensure the package's classes aren't purged. Missing rounded-full badges or backdrop-filter blur usually means a purge/source-scope problem, not a package bug. Also: don't re-add the fragile @import from vendor/... that this release removed — reference published assets instead.

Auth and third-party plugin interactions were actively being fixed. resolves issues #13, #14, #17 covers pagination rendering, modal z-index over the topbar, and an auth-enhancer conflict. If you run Filament Shield, an auth enhancer, or a custom login page, retest auth and pagination explicitly — these are the areas most likely to still need an app-side tweak.

Debugging visually, not in code. Use browser devtools on the specific element (.fi-badge, .fi-ta-pagination, .fi-modal-close-overlay, .fi-sc-wizard) and toggle individual modifiers off in the config. Isolating one mode is far faster than reading compiled CSS.

Combine modes deliberately. Glass + OLED + both contrast modes is a lot of specificity stacked on the same surfaces. Enable incrementally; if something looks muddy, drop the least important modifier and confirm before filing a bug.

Extension points worth knowing: config publishing, fluent panel methods, grayColor()/font() helpers, custom theme path, and the install command. Editing vendor CSS is the one extension point to avoid — it silently loses every fix in this changelog.