Northwestern Filament Theme Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require northwestern-sysdev/northwestern-filament-theme
   

2. Register the plugin in your PanelProvider:

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

3. Publish assets (for standalone CSS):

   php artisan filament:assets
   

First Use Case

Apply the Northwestern theme to your Filament admin panel immediately. The package automatically:

• Applies NU’s purple/gold color palette
• Sets the official NU favicon and logo (unless overridden)
• Enables dark mode compatibility
• Includes an environment indicator (visible in non-production)

Implementation Patterns

Core Workflow

1. Basic Integration:

   NorthwesternTheme::make()
       ->footer() // Enable footer for public-facing panels
       ->withoutEnvironmentIndicator(); // Disable for production-like staging
   

2. Vite Theme Integration (for Tailwind users):

   php artisan northwestern-theme:install
   

   Then configure in PanelProvider:

   NorthwesternTheme::make()
       ->withoutAssetRegistration();
   

   Now use NU colors in your CSS:

   .button { background: theme('colors.nu-gold.500'); }
   

3. Conditional Features:

   NorthwesternTheme::make()
       ->footer(enabled: fn () => auth()->check())
       ->impersonationBanner(visible: fn () => session()->has('impersonating'));
   

Common Patterns

• Override Defaults: Publish views (php artisan vendor:publish --tag=northwestern-filament-theme-views) to customize:
  • Environment indicator badge
  • Impersonation banner
  • Footer markup
• Tailwind Utilities: Use bg-nu-purple-100, text-nu-gold, etc. (requires Vite integration).
• Multi-Panel Projects: Disable features per panel:

  // Admin panel (no footer)
  NorthwesternTheme::make()->withoutFooter();
  
  // Public panel (with footer)
  NorthwesternTheme::make()->footer();
  

Integration Tips

• With northwestern-laravel-ui: The theme auto-detects config from the UI package (e.g., office.* for footers).
• With Custom Themes: The package adds CSS layers—your existing viteTheme() remains intact.
• Dark Mode: No config needed; adapts automatically to Filament’s dark mode toggle.

Gotchas and Tips

Pitfalls

1. Double-Loading Assets:

   • Issue: CSS loads twice if both filament:assets and Vite integration are enabled.
   • Fix: Use withoutAssetRegistration() when using Vite:

     NorthwesternTheme::make()->withoutAssetRegistration();
     

   • Debug: Check browser DevTools for duplicate <link> tags.

2. CDN Dependencies:

   • Issue: Fonts/icons/favicon load from common.northwestern.edu. Blocked CSP or restricted networks will break them.
   • Fix: Add to CSP:

     <meta http-equiv="Content-Security-Policy" content="... img-src https://common.northwestern.edu ...">
     

3. Footer Overrides:

   • Issue: Hardcoded IT office info appears if northwestern-laravel-ui isn’t installed.
   • Fix: Explicitly pass office data:

     NorthwesternTheme::make()->footer(
         officeName: 'Custom Office',
         officeAddr: '123 Main St'
     );
     

4. Impersonation Banner Conflicts:

   • Issue: Duplicate banners if using lab404/laravel-impersonate + this package.
   • Fix: Remove the third-party package or disable the built-in banner:

     NorthwesternTheme::make()->withoutImpersonationBanner();
     

Debugging Tips

• View Publishing: After publishing views, clear cached views:

  php artisan view:clear
  

• CSS Specificity: Use !important sparingly—NU’s theme uses utility classes (e.g., .nu-purple-bg). Override with:

  .my-class { --nu-purple-100: #yourcolor !important; }
  

• Environment Indicator: Test visibility logic in tinker:

  php artisan tinker
  >>> NorthwesternTheme::make()->environmentIndicator()->visible()
  

Extension Points

1. Custom Design Tokens: Extend Tailwind’s theme() function in tailwind.config.js:

   theme: {
     extend: {
       colors: {
         'nu-custom': '#yourhex',
       }
     }
   }
   

2. Dynamic Theming: Use Laravel’s config to switch themes:

   NorthwesternTheme::make()
       ->footer(enabled: config('app.show_footer'));
   

3. Local Development:
   • Watch Mode: Run pnpm build:css:watch for live CSS updates.
   • Prettier: Auto-format all files:

     composer fix
     

Pro Tips

• Visual Regression Testing: The package includes Percy snapshots for light/dark mode. Re-run with:

  pnpm test:visual
  

• Modal Styling: Hide borders on empty modals:

  NorthwesternTheme::make()->modalsWithoutBorders();
  

• Table Headers: Ensure purple background applies to all headers:

  .filament-table th { background: var(--nu-purple-surface) !important; }
  

Changelog Highlights

• v2.5.0: Added 3px left borders for active sidebar items and status-tinted notifications.
• v2.4.0: Modularized CSS (e.g., notifications.css, badges.css) for easier overrides.
• v2.2.0: Laravel 13 support; PHP 8.3 minimum (upgrade with composer update).