Getting Started

Minimal Setup

Install the package:

composer require andreia/filament-nord-theme:"^3.0"

Register the plugin in your AdminPanelProvider (or TenancyPanelProvider if using Filament Tenancy):

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->plugin(NordTheme::make())
        ->discoverResources(in: app_path('Filament/Resources'), for: 'App\\Filament\\Resources')
        // ... other panel configurations
        ->discoverPages(in: app_path('Filament/Pages'), for: 'App\\Filament\\Pages');
}

Publish assets (if needed for customization):

php artisan vendor:publish --tag="filament-nord-theme:assets"

Enable dark mode (optional):
- Add data-theme="dark" to your <html> tag in resources/views/layouts/app.blade.php (if using custom layouts).
- Or use the built-in toggle via NordTheme::make()->enableDarkModeToggle().

First Use Case

Apply the theme to a new Filament project:

The package automatically applies the Nord color palette (light/dark variants) to Filament’s UI.
Test the dark mode toggle in the top-right corner (if enabled) or manually switch themes via browser dev tools (data-theme="dark").

Implementation Patterns

Core Workflows

Theme Integration
- Default Usage: Register the plugin once in AdminPanelProvider. No additional config is needed for basic functionality.
- Multi-Panel Support: Register separately for each panel (e.g., AdminPanel and TenancyPanel):
```
TenancyPanel::make()->plugin(NordTheme::make()->disableDarkModeToggle());
```
- Resource-Specific Overrides: Extend the theme for specific resources/pages by publishing assets and overriding SCSS variables:
```
// resources/scss/filament/nord/custom.scss
@use "filament-nord-theme:variables" as nord;

.filament-resources {
  --nord-primary-500: #ff0066; // Override primary color
}
```

Dark Mode Management

Toggle Integration: Enable/disable the toggle via:

NordTheme::make()->enableDarkModeToggle()->persistUserPreference(); // Saves preference to session

Force Dark/Light: Override globally in AdminPanelProvider:
```
->plugin(NordTheme::make()->forceDarkMode())
```

Custom Storage: Use a custom storage driver (e.g., database) by binding FilamentNord\Contracts\DarkModeStorage:

$this->app->bind(\FilamentNord\Contracts\DarkModeStorage::class, function () {
    return new DatabaseDarkModeStorage();
});

Asset Customization
- Publish and Modify:
```
php artisan vendor:publish --tag="filament-nord-theme:assets"
```
  - Edit resources/views/vendor/filament-nord-theme/partials/head.blade.php for meta tags.
  - Override resources/scss/filament-nord-theme/nord.scss for global styles.
- Dynamic Theming: Use Filament’s use directive in Blade to inject theme-specific classes:
```
@use('filament-nord-theme::variables')
<div class="bg-{{ variables.$nord-gray-800 }}">...</div>
```

Localization

Translate the "Toggle Dark Mode" label via config/filament.php:

'nord-theme' => [
    'dark_mode_label' => __('filament-nord-theme::toggle-dark-mode'),
],

Publish translations:

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

Integration Tips

Filament Plugins: Ensure compatibility by testing with plugins like filament-spatie-laravel-permission or filament-notifications. Some plugins may require manual SCSS adjustments.
Livewire Components: Nord’s dark mode works seamlessly with Livewire. Use wire:model="darkMode" to sync preferences across components.

Tailwind CSS: If using Tailwind, extend your tailwind.config.js to include Nord’s palette:

module.exports = {
    theme: {
        extend: {
            colors: {
                nord: {
                    '50': '#2e3440',
                    '100': '#3b4252',
                    // ... add other shades
                }
            }
        }
    }
};

Gotchas and Tips

Pitfalls

Version Mismatches
- Error: Class 'FilamentNord\NordTheme' not found.
- Fix: Ensure the package version matches your Filament version (e.g., ^3.0 for Filament 5.x). Check the compatibility table.
- Debug: Run composer why-not andreia/filament-nord-theme:^3.0 to identify conflicts.
Dark Mode Toggle Not Appearing
- Cause: The toggle is disabled by default. Enable it explicitly:
```
->plugin(NordTheme::make()->enableDarkModeToggle())
```
- Custom Positioning: The toggle uses Filament’s Header component. Override the header in a custom panel provider if needed.
CSS Conflicts
- Issue: Nord’s dark mode clashes with custom CSS (e.g., background-color: #fff).
- Solution: Use Nord’s SCSS variables for consistency:
```
.my-component {
  background-color: var(--nord-gray-50);
}
```
- Debug: Inspect elements in browser dev tools to identify overridden styles.
Session Persistence
- Problem: Dark mode preference resets on page reload.
- Fix: Ensure persistUserPreference() is called:
```
NordTheme::make()->enableDarkModeToggle()->persistUserPreference();
```
- Custom Storage: Implement FilamentNord\Contracts\DarkModeStorage for database-backed persistence.

Asset Loading Order

Issue: Nord’s CSS/JS fails to load.

Fix: Verify the plugin is registered after Filament’s core assets in AdminPanelProvider:

->id('admin')
->path('admin')
->middleware([
    'web',
    'auth',
])
->plugin(NordTheme::make()) // Must come after middleware/assets
->discoverResources(...);

Debugging Tips

Check Published Assets: After publishing, verify files exist in resources/views/vendor/filament-nord-theme/ and resources/scss/filament-nord-theme/.
Tailwind Conflicts: Disable Tailwind’s dark mode (dark: variants) if using Nord’s native dark mode to avoid duplication.
Plugin Isolation: Test the theme in isolation by disabling other Filament plugins to identify conflicts.

Extension Points

Custom Themes

Extend the theme by creating a new class:

use FilamentNord\NordTheme;

class CustomNordTheme extends NordTheme {
    public function configure(): void {
        $this->colors = [
            'primary' => '#ff0066',
            // ... override other colors
        ];
    }
}

Dynamic Theme Switching

Use middleware to force themes based on user roles:

public function handle(Request $request, Closure $next) {
    if (auth()->user()->isAdmin()) {
        app(NordTheme::class)->forceDarkMode();
    }
    return $next($request);
}

Dark Mode API

Expose the dark mode state to JavaScript:

NordTheme::make()->enableDarkModeToggle()->withJavaScript()
    ->script('
        window.nordTheme = {
            darkMode: @entangle('dark-mode'),
        };
    ');

Access in Blade:

<div x-data="nordTheme" x-text="darkMode ? 'Dark' : 'Light'"></div>

Testing

Test dark mode in PHPUnit:

public function test_dark_mode_toggle() {
    $response = $this->actingAs(User::factory()->create())
        ->get('/admin')
        ->assertSee('data-theme="dark"');
}

Use NordTheme::make()->forceDarkMode() in tests to mock dark mode.

Filament Nord Theme Laravel Package