Northwestern Filament Theme Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require northwestern-sysdev/northwestern-filament-theme
   

   Ensure your project meets the requirements: PHP 8.3+, Laravel 12/13, and Filament 4/5.

2. Register the Plugin: Add the theme to your PanelProvider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   use Northwestern\FilamentTheme\NorthwesternTheme;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               NorthwesternTheme::make(),
               // Other plugins...
           ]);
   }
   

3. First Use Case: Refresh your Filament admin panel. The theme will automatically apply Northwestern’s branding (colors, typography, and UI elements) without additional configuration.

Implementation Patterns

Core Workflow

1. Theme Integration:

   • The package is a Filament plugin, so it integrates seamlessly with Filament’s plugin system. No manual CSS/JS overrides are needed for basic branding.
   • Works out-of-the-box with Filament 4.x and 5.x (adapts to the version detected).

2. Customization Points:

   • Override Colors/Fonts: Extend the theme via app/Providers/AppServiceProvider.php:

     NorthwesternTheme::configure(fn (NorthwesternTheme $theme) => $theme
         ->colors(['primary' => '#123456']) // Customize palette
         ->fonts(['body' => 'Inter'])     // Override typography
     );
     

   • Component-Specific Styling: Use Filament’s modify method to target specific UI elements:

     NorthwesternTheme::make()->modify(function (NorthwesternTheme $theme) {
         $theme->modifyCard(function (Card $component) {
             $component->classes(['bg-nu-blue-50']);
         });
     });
     

3. Dark Mode Support:

   • The theme includes Northwestern’s dark mode palette. Enable it via Filament’s built-in dark mode toggle or force it globally:

     NorthwesternTheme::make()->darkMode(true);
     

4. Asset Publishing:

   • Publish the theme’s assets (e.g., for custom SVG icons or fonts):

     php artisan vendor:publish --tag=northwestern-filament-theme-assets
     

5. Localization:

   • The package respects Filament’s localization system. Northwestern-specific translations (e.g., for labels) can be added via:

     NorthwesternTheme::make()->translations([
         'nu' => [
             'labels' => [
                 'dashboard' => 'NU Dashboard',
             ],
         ],
     ]);
     

Gotchas and Tips

Pitfalls

1. Plugin Registration Order:

   • Register NorthwesternTheme before other plugins that might override styles (e.g., Filament\Plugins\Settings). Test your panel after adding the theme to catch conflicts early.

2. Caching Issues:

   • After updating the package, clear Filament’s view cache:

     php artisan filament:cache-reset
     

   • If styles don’t apply, check for CSS specificity conflicts with other plugins or custom styles.

3. Filament 5.x Migration:

   • The package supports Filament 5.x, but some component names (e.g., Card → filament-card) may differ. Refer to the changelog for breaking changes.

4. Asset Paths:

   • Avoid hardcoding paths to the theme’s assets (e.g., /vendor/northwestern-sysdev/...). Use the package’s helper methods:

     NorthwesternTheme::asset('images/logo.svg');
     

Debugging

• Inspect Rendered HTML: Use browser dev tools to verify the theme’s classes (e.g., nu-{color}-{shade}) are applied. Missing classes often indicate registration or caching issues.
• Log Configuration: Enable debug mode in config/filament.php to log plugin initialization:

  'debug' => env('FILAMENT_DEBUG', false),
  

Extension Points

1. Custom Components:

   • Extend the theme’s component classes by publishing and overriding the package’s views:

     php artisan vendor:publish --tag=northwestern-filament-theme-views
     

   • Example: Modify resources/views/vendor/northwestern-filament-theme/components/card.blade.php.

2. Dynamic Theming:

   • Use Filament’s Livewire hooks to dynamically switch themes (e.g., based on user role):

     use Northwestern\FilamentTheme\NorthwesternTheme;
     
     NorthwesternTheme::make()->hook('theme.switch', function () {
         // Logic to toggle theme (e.g., via API)
     });
     

3. Testing:

   • Test theme consistency across:
     • Different Filament versions (4.x vs. 5.x).
     • Browsers (Chrome, Firefox, Safari) for color/spacing issues.
     • Screen sizes (responsive design may need adjustments).

4. Performance:

   • The theme adds minimal overhead. For large panels, audit unused CSS by disabling the theme temporarily and comparing performance metrics.

5. Fallbacks:

   • The package includes fallbacks for missing assets/colors. Override them only if you’re certain the customization is intentional:

     NorthwesternTheme::make()->fallbacks([
         'colors' => ['primary' => '#000000'], // Fallback if NU palette fails to load
     ]);
     

```markdown
---
**Note**: For advanced use cases (e.g., multi-tenancy with dynamic branding), consider forking the package or extending it via a custom plugin that wraps `NorthwesternTheme`.