Theme Aberdeen Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require spykapps/theme-aberdeen
   

2. Run the installer:

   php artisan aberdeen:install
   

   • The installer detects your Filament panel(s) and prompts for selection if multiple exist.
   • Automatically adds the theme stylesheet import to your existing theme file (or creates one if missing).

3. Register the plugin in your panel provider:

   use SpyApp\ThemeAberdeen\ThemeAberdeenPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugin(ThemeAberdeenPlugin::make());
   }
   

4. Compile assets (if using Vite):

   npm run build
   

First Use Case

Apply the theme to a new Filament admin panel or existing panel to instantly upgrade its visual design with minimal configuration. Ideal for:

• Quickly refreshing a stale admin UI.
• Testing a modern, minimal aesthetic before committing to custom CSS.

Implementation Patterns

Core Workflow

1. Theme Integration:

   • The package automatically merges its styles with your existing Filament theme (e.g., resources/css/filament.css).
   • No manual CSS overrides needed for basic usage.

2. Panel-Specific Customization:

   • Use the ThemeAberdeenPlugin in multiple panels independently by registering it per panel in your PanelProvider.
   • Example for multi-panel projects:

     // app/Providers/Filament/AdminPanelProvider.php
     public function panel(Panel $panel): Panel {
         if ($panel->getId() === 'admin') {
             return $panel->plugin(ThemeAberdeenPlugin::make());
         }
         return $panel;
     }
     

3. Dark Mode:

   • Enable via Filament’s built-in dark mode toggle (no extra config).
   • The theme includes optimized dark mode values (e.g., adjusted shadows, contrast).

4. Component-Level Overrides:

   • Target specific Filament components (e.g., tables, modals) by extending the theme’s CSS classes:

     /* resources/css/filament.css */
     .filament-tables-table th {
         padding: 0.5rem 0.75rem; /* Override compact spacing */
     }
     

Advanced Patterns

• Dynamic Theming: Combine with Filament’s dynamic themes to switch between Aberdeen and other themes at runtime.

  $panel->theme('aberdeen'); // Hypothetical; check for API changes.
  

• Custom Accents: Override the warm-amber palette by extending the theme’s CSS variables:

  :root {
      --aberdeen-primary-500: #ff6b35; /* Custom amber */
  }
  

• Plugin Integration: Use the theme’s subtle shadows and tight spacing to design custom Filament plugins with a cohesive look.

Gotchas and Tips

Pitfalls

1. Asset Compilation:

   • Forgetting to run npm run build after installation may leave styles unapplied.
   • Fix: Add a post-install hook in package.json:

     "scripts": {
       "postinstall": "npm run build"
     }
     

2. CSS Specificity:

   • Aberdeen’s styles rely on Filament’s default classes. Custom CSS with higher specificity (e.g., !important) may override them unintentionally.
   • Tip: Use Filament’s utility classes or extend the theme’s classes instead.

3. Dark Mode Conflicts:

   • Third-party Filament plugins may not fully support dark mode. Test thoroughly.
   • Workaround: Inspect and override conflicting styles in your theme file.

4. Panel Detection Issues:

   • The installer may fail if your panel is not autoloaded or named unconventionally.
   • Fix: Manually register the plugin in your PanelProvider and skip the installer’s panel detection.

Debugging

• Inspect Styles: Use browser dev tools to check if Aberdeen’s classes (e.g., .aberdeen-shadow) are loaded. Missing classes often indicate a build or import issue.

• Clear Cache: After changes, run:

  php artisan view:clear
  php artisan cache:clear
  

Extension Points

1. Customize Spacing: Override the theme’s gap, padding, and margin values via CSS variables:

   :root {
       --aberdeen-spacing-xs: 0.25rem; /* Override smallest spacing */
   }
   

2. Add Animations: Extend the theme’s transitions by targeting interactive elements:

   .aberdeen-transition {
       transition: all 200ms ease-in-out;
   }
   

3. Localization: The theme supports Filament’s RTL mode out-of-the-box. Test with:

   $panel->direction('rtl');
   

4. Testing: Use Filament’s testing utilities to verify theme consistency across views:

   $this->get('/admin')
       ->assertSee('.aberdeen-shadow')
       ->assertSee('.filament-dark\:bg-gray-800');