Skip to content

jackson2w/claude-code-skills / filament-panel-theming

filament-panel-theming

Verified

Filament v3 panel theming — custom color, fonts, and chrome

Built and verified skinning the Homelab Console app (Filament v3.3) with a bespoke "Resilience Ledger" design system — every gotcha below was hit for real. Distinct from the laravel-filament-proxmox-lxc skill, which covers deploying a Filament app; this one covers reskinning an already-deployed panel. Read the vendor Blade source directly when in doubt (vendor/filament/*/resources/views/...) rather than guessing class names from memory — Filament class names are stable across versions but not documented exhaustively, and the actual bg-white/dark:bg-gray-900 utility classes only show up by reading the real templates.

Scaffolding the theme: make:filament-theme and the Tailwind v3/v4 conflict

php artisan make:filament-theme <panel-id> --pm=npm --no-interaction scaffolds resources/css/filament/<panel>/theme.css + a matching tailwind.config.js. If the host app was created with a recent laravel new (Tailwind v4 by default), the command detects the mismatch — Filament v3's theme system requires Tailwind v3 — and prints the exact fallback command instead of erroring:

npx tailwindcss@3 --input ./resources/css/filament/admin/theme.css \
  --output ./public/css/filament/admin/theme.css \
  --config ./resources/css/filament/admin/tailwind.config.js --minify

This works even though package.json never gets a tailwindcss@3 devDependency — npx fetches it standalone on first run and caches it. Don't downgrade the app's real Tailwind v4 install to work around this; the standalone CLI coexists fine.

Register with ->theme(asset('css/filament/admin/theme.css')), not ->viteTheme(...). viteTheme() expects a Vite-built asset with a manifest entry — this path never produces one (the CLI writes directly to public/, bypassing Vite entirely). ->theme() just needs a plain URL to a compiled CSS file. The compiled public/css/filament/admin/theme.css is meant to be git-tracked (only /public/build, the Vite output dir, is normally gitignored) — there is no dev server watching this file, so re-run the CLI command and commit the output after every edit to the source theme.css.

If the LXC/VM has no Node.js at all (a PHP-only box, common for a Filament app not otherwise needing a JS runtime), install it as a build-time-only tool — NodeSource apt repo is fine, same as proxmox-node-systemd-service uses for actual Node services, but no systemd unit is needed here since nothing runs it continuously.

The asset() mixed-content gap (beyond URL::forceScheme)

If the app is already running behind a TLS-terminating reverse proxy (Tailscale Serve, Caddy) with URL::forceScheme('https') set in AppServiceProvider::boot() — see laravel-filament-proxmox-lxc's mixed-content section for why that's there — know that this does not cover the plain asset() helper. Filament's own internally-generated asset URLs (the core CSS/JS bundles from @filamentStyles/@filamentScripts) correctly resolve to https://, but a raw asset('css/filament/admin/theme.css') call inside a panel provider's ->theme()/->font() still emits http:// — silently blocked by the browser as mixed content, with zero errors anywhere: curl returns clean 200s (curl doesn't enforce mixed-content policy), Laravel's log stays empty, and the page renders structurally correct but completely unstyled, easy to mistake for the CSS itself being broken rather than never having loaded. Diagnose by checking the actual href= scheme in the rendered HTML (curl -s <url> | grep -o 'href="[^"]*\.css[^"]*"'), not by trusting a 200 status.

Fix: pass secure: true explicitly as the second argument on every asset() call in the panel provider:

->font(
    'IBM Plex Sans',
    url: asset('css/filament/admin/fonts.css', secure: true),
    provider: \Filament\FontProviders\LocalFontProvider::class,
)
->theme(asset('css/filament/admin/theme.css', secure: true))

asset($path, $secure) accepts $secure as an explicit override — when non-null it bypasses scheme detection entirely (request scheme, forceScheme, everything) and just emits https:///http:// directly. This is more reliable than debugging why forceScheme isn't propagating to this particular helper.

Self-hosted fonts via LocalFontProvider

->font(
    'IBM Plex Sans',
    url: asset('css/filament/admin/fonts.css', secure: true),
    provider: \Filament\FontProviders\LocalFontProvider::class,
)

LocalFontProvider::getHtml() is trivial — it just emits <link href="{$url}" rel="stylesheet" />, no parsing or validation of the URL's contents. The font family name passed as the first argument sets Filament's --font-family CSS custom property (consumed by the Tailwind preset's fontFamily.sans), independent of what's actually declared in the linked stylesheet — the two must agree (the @font-face font-family inside the CSS should match the string passed here) but Filament doesn't verify this for you.

If a font is already self-hosted elsewhere as base64-embedded @font-face WOFF2 (e.g. inside a published design-system Artifact or an existing ledger-styled-email renderer), extract those exact @font-face blocks rather than re-fetching from Google/Bunny Fonts or Fontsource — byte- identical to what's already shipping elsewhere, and no new network dependency at build or runtime. Filament only needs weights actually used by its own components plus whatever custom CSS overrides reference (typically 400/500/600/700 covers everything).

There is no equivalent panel-level hook for a custom monospace family — if the design uses one (code blocks, an "eyebrow" label style, badges), extend the Tailwind config directly instead:

theme: {
    extend: {
        fontFamily: {
            mono: ['var(--font-family-mono)', 'ui-monospace', 'SFMono-Regular', 'monospace'],
        },
    },
},

with --font-family-mono defined in theme.css's own :root.

What's actually re-themable vs. what needs a direct CSS override

$panel->colors(['primary' => '#4A6FBE', 'gray' => '#6B6656', ...]) accepts either a full 50–950 shade array or a plain hex string — a hex string auto-generates the full ramp via Color::hex()/Color::generateShades(). This covers primary/success/warning/danger/ info/gray, each surfaced as CSS custom properties (--primary-500, etc.) that Filament's own Tailwind preset consumes as rgba(var(--primary-500), <alpha-value>).

gray is the highest-leverage slot for whole-panel re-tinting, not just table/badge accents: the panel body itself (<body class="fi-body ... bg-gray-50 ... dark:bg-gray-950 ...">) uses the gray scale's extremes directly. Registering a brand-tinted gray (e.g. a warm neutral hex instead of a cool default) re-tints the entire page background/border/muted-text system for free, in both light and dark mode, with one line — confirmed by reading vendor/filament/filament/resources/ views/components/layout/base.blade.php directly.

What is not covered by any color slot: Filament's "raised surface" chrome consistently uses literal bg-white ... dark:bg-gray-900 (not bg-gray-white or any custom-scale reference) across essentially every card-like component:

SurfaceClassTemplate
Sidebar.fi-sidebarfilament/resources/views/components/sidebar/index.blade.php
Sidebar header.fi-sidebar-headersame file
Topbar.fi-topbar navfilament/resources/views/components/topbar/index.blade.php
Section/card.fi-sectionsupport/resources/views/components/section/index.blade.php
Stat widget card.fi-wi-stats-overview-statwidgets/resources/views/stats-overview-widget/stat.blade.php
Table row.fi-ta-recordtables/resources/views/index.blade.php

Since white and gray-900 are Tailwind's literal palette, not Filament's re-themable custom scale, no amount of $panel->colors() registration touches them. Override directly in theme.css, bundled since they share the identical pattern:

.fi-sidebar,
.fi-sidebar-header,
.fi-topbar nav,
.fi-section,
.fi-wi-stats-overview-stat,
.fi-ta-record,
.fi-modal-window,
.fi-dropdown-panel {
    background: var(--rl-raised-surface) !important;
}

!important is required here — these are real Tailwind utility classes with normal specificity, so a plain override loses without it. This is a legitimate use of !important (a documented Filament customization point via the theme CSS layer), not a specificity hack to avoid.

Don't try to enumerate every remaining bg-white/text-white occurrence (buttons, badges, tooltips, dropdown items) — most of those are deliberately staying white/near-white for contrast reasons (e.g. white text on a colored primary button) and blanket-redefining Tailwind's white token in tailwind.config.js risks breaking exactly that contrast. Cover the handful of large chrome surfaces above; leave small interactive elements on Filament's defaults.

Brand name

->brandName('Homelab Dashboard')

Replaces the "Laravel" default shown via <x-filament-panels::logo> (class .fi-logo) in the sidebar header and login page. Plain string, no HTML escaping concerns unless passing an Htmlable/closure. If the theme's CSS already applies text-transform: uppercase to .fi-logo (a common "eyebrow label" treatment), pass normal title case here — the casing transform is presentation, not data.

Verification

@filamentStyles/@filamentScripts and a panel's ->theme()/->font() links all render as real <link>/<style> tags in the response body — but a naive single-line regex/grep for <link[^>]*> can miss them if Filament wraps the tag across multiple lines. Search for the asset filename substring instead (grep -o 'forms.css\|theme.css') when confirming a stylesheet is actually being requested, and always confirm final rendering with a real browser (Playwright screenshot, both light and dark via localStorage.setItem('theme', 'dark') + reload — Filament's dark mode is a .dark class toggle on <html>, not a prefers-color-scheme media query, so theme.css dark overrides must use a .dark { ... } selector, not @media (prefers-color-scheme: dark)) — curl alone cannot catch mixed-content blocking or actual visual regressions.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 193kUpdated Claude CodeCodexVerifiedInstall