README

A reusable Filament v5 theme package built with a token-first architecture, preset system, accessibility guardrails, and extension hooks for long-term upgrade safety.

Release version: 1.0.0

Highlights

Token-first design with semantic tokens (surface, text, primary, danger, etc.)
Preset system (corporate, minimal, bold, neutral) + import/export commands
Light / Dark / Auto mode handling
Zero-config installer command for fast setup
Panel-level overrides and optional tenant-level branding resolver
Theme Settings page with multilingual support (EN, FR, AR, DE, ES, PT)
Plugin compatibility adapter layer with a TranslationManagerAdapter reference
Accessibility guardrails (focus ring, reduced motion, WCAG contrast audit command)
Upgrade-safe schema (schema_version) + migration command for legacy config
CSS injection–safe token pipeline with color and value sanitization
Per-request theme resolution cache for zero-overhead render hooks

Requirements

PHP ^8.2
Laravel ^11.0 || ^12.0 || ^13.0
Filament ^5.0

Zero-Config Install

composer require benriadh1/filament-benriadh-theme
php artisan filament-benriadh-theme:install --migrate

Manual install remains available:

php artisan vendor:publish --tag="filament-benriadh-theme-config"
php artisan vendor:publish --tag="filament-benriadh-theme-assets"
php artisan vendor:publish --tag="filament-benriadh-theme-lang"
php artisan vendor:publish --tag="filament-benriadh-theme-migrations"
php artisan migrate

Register In Panel

use Benriadh1\FilamentBenriadhTheme\FilamentBenriadhThemePlugin;

public function panel(Panel $panel): Panel
{
    return $panel->plugins([
        FilamentBenriadhThemePlugin::make(),
    ]);
}

Fluent API

FilamentBenriadhThemePlugin::make()
    ->preset('corporate')
    ->mode('auto')
    ->accentColor('#cba24c')
    ->sidebarGradient('#0f172a', '#111827')
    ->showLeftSidebar(true)
    ->compactSidebar(false)
    ->cardRadius('0.9rem')
    ->softShadows(true)
    ->tokens([
        'primary' => '#2563eb',
    ])
    ->layout([
        'compact_sidebar' => true,
    ]);

Config Model

Main config file: config/filament-benriadh-theme.php

Core keys:

schema_version
asset_path
mode
preset
presets
tokens
layout
breadcrumbs
branding
apps_dropdown
panel_overrides
tenant
extensions
a11y
show_theme_settings_page

Legacy keys are still supported and mapped into v1 schema for backward compatibility.

Apps Dropdown

Controls the navigation grid shown in the topbar when the sidebar is hidden:

'apps_dropdown' => [
    'max_items' => 15, // Maximum navigation items shown in the grid
],

Localization

The Theme Settings page is translated into 6 languages out of the box:

Code	Language
`en`	English
`fr`	French
`ar`	Arabic (RTL)
`de`	German
`es`	Spanish
`pt`	Portuguese

Publish the language files to customize or add new locales:

php artisan vendor:publish --tag="filament-benriadh-theme-lang"

Files are placed under lang/vendor/filament-benriadh-theme/{locale}/messages.php.

Panel + Tenancy Support

Use panel_overrides to provide per-panel visual behavior.
Use tenant.enabled + tenant.resolver to inject tenant branding at runtime.
Tenant resolver contract:
- Benriadh1\FilamentBenriadhTheme\Contracts\TenantThemeResolver

Extension API

Implement these contracts to extend without forking:

Benriadh1\FilamentBenriadhTheme\Contracts\ThemeTokenTransformer
Benriadh1\FilamentBenriadhTheme\Contracts\PluginThemeAdapter
Benriadh1\FilamentBenriadhTheme\Contracts\TenantThemeResolver

Plugin Adapter Example

The package ships with TranslationManagerAdapter as a reference implementation. It bridges the optional benriadh1/filament-translation-manager package by mapping its CSS variables to theme tokens. To activate it (or any custom adapter), register it in your config:

'extensions' => [
    'plugin_adapters' => [
        \Benriadh1\FilamentBenriadhTheme\Adapters\TranslationManagerAdapter::class,
        // or your own adapter:
        App\Theme\MyPluginAdapter::class,
    ],
],

The adapter is automatically skipped when the target plugin is not installed.

Commands

php artisan filament-benriadh-theme:install --migrate
php artisan filament-benriadh-theme:migrate-schema
php artisan filament-benriadh-theme:preset-export corporate
php artisan filament-benriadh-theme:preset-import ./preset.json my_custom --overwrite
php artisan filament-benriadh-theme:a11y-check --panel=admin

Theme Settings Page

When enabled, the package registers:

Navigation: Settings > Theme Settings
Route (default admin panel): /admin/theme-settings

Values are stored in filament_theme_settings and merged with config + runtime overrides.

Testing

composer install
composer test        # runs Pest
composer lint        # runs Laravel Pint

Test coverage includes CSS injection sanitization, color token validation, theme mode normalization, ThemeSetting::store() idempotency, and WCAG contrast ratio math.

Roadmap

v1 (current)

Token-first config schema
Presets + mode handling
Panel/tenant/extensibility hooks
Install/migrate/preset/a11y command set
Multilingual Theme Settings page (EN, FR, AR, DE, ES, PT)

v2

Broader component parity coverage for complex Filament states
Additional first-party plugin adapters
Design token validation tooling with stricter schema checks

v3

Visual regression suite (light/dark, desktop/mobile)
Interactive playground UI for live token editing + export
Expanded docs with adapter and tenancy recipes

License

MIT. See LICENSE.md.

benriadh1 / filament-benriadh-theme

Maintainers

Package info

Statistics

Security