Filament Abyss Theme Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require osamanagi/filament-abyss-theme
   

   Add the theme CSS to your vite.config.js:

   export default defineConfig({
       plugins: [
           laravel({
               input: [
                   'resources/js/app.js',
                   'vendor/osamanagi/filament-abyss-theme/resources/css/theme.css', // Add this line
               ],
           }),
       ],
   });
   

   Run:

   npm run build
   

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

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->id('admin')
           ->path('admin')
           ->plugins([
               \Osamanagi\FilamentAbyssTheme\FilamentAbyssThemePlugin::make(),
           ]);
   }
   

3. First Use Case The theme will automatically apply to your Filament admin panel. No additional configuration is required for basic usage. Refresh your admin panel to see the Abyss theme in action.

Implementation Patterns

Usage Patterns

1. Theme Customization Override the default theme colors or styles by publishing the package's assets:

   php artisan vendor:publish --provider="Osamanagi\FilamentAbyssTheme\FilamentAbyssThemeServiceProvider" --tag="filament-abyss-theme-config"
   

   Modify the published config/filament-abyss-theme.php to adjust colors, fonts, or other theme properties.

2. Conditional Theme Application Dynamically enable/disable the theme based on user roles or preferences:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               auth()->user()->hasRole('designer')
                   ? \Osamanagi\FilamentAbyssTheme\FilamentAbyssThemePlugin::make()
                   : null,
           ]);
   }
   

3. Integration with Filament Widgets Ensure widgets and custom components align with the theme by using Filament's built-in styling utilities (e.g., filament-typography, filament-colors). Example:

   use Filament\Widgets\StatsOverviewWidget;
   
   StatsOverviewWidget::make()
       ->columns(2)
       ->styleFn(fn (array $widgets) => 'bg-gray-800 text-white') // Align with Abyss theme
       ->widgets([
           // ...
       ]);
   

4. Dark/Light Mode Toggle Leverage Filament's built-in dark mode support to toggle between light and dark variants of the Abyss theme. Ensure your theme.css includes both variants or use CSS variables for dynamic switching.

Workflows

• Theme Development Workflow

  1. Install the package and publish assets.
  2. Customize the theme by editing the published CSS or config.
  3. Test changes in a staging environment before deploying to production.
  4. Rebuild assets after CSS changes:

     npm run build
     

• Collaborative Workflow For teams, document the theme's customizations in a THEME_CUSTOMIZATIONS.md file. Include:

  • Screenshots of before/after changes.
  • CSS variable overrides.
  • Dependencies (e.g., Filament version, Tailwind config).

Gotchas and Tips

Pitfalls

1. Asset Build Issues

   • Problem: Forgetting to add theme.css to vite.config.js or running npm run build after installation.
   • Fix: Double-check vite.config.js and rebuild assets:

     npm run dev  // For development
     npm run build // For production
     

2. Theme Conflicts

   • Problem: Custom CSS or other Filament plugins overriding the Abyss theme.
   • Fix: Use higher specificity in your custom CSS or inspect the theme's CSS classes (e.g., .filament-abyss-theme-*) to target overrides.

3. Dark Mode Inconsistencies

   • Problem: Widgets or components not respecting the dark/light theme toggle.
   • Fix: Ensure components use Filament's useDarkMode() hook or Tailwind's dark mode classes (e.g., dark:bg-gray-800).

4. Plugin Registration Errors

   • Problem: The theme not appearing after registration.
   • Fix: Verify the plugin is registered in the correct Panel provider and that no syntax errors exist in the provider file.

Debugging

• Inspect Theme Classes Use browser dev tools to inspect the rendered HTML and identify missing or overridden classes. Look for:

  <body class="filament-abyss-theme ...">
  

• Check CSS Variables The theme likely uses CSS variables (e.g., --abyss-primary). Override these in your custom CSS if needed:

  :root {
      --abyss-primary: #your-color;
  }
  

• Clear Cache If changes aren’t reflecting, clear Filament's cache:

  php artisan filament:cache-reset
  

Tips

1. Extend the Theme Create a custom theme by copying the package's CSS to your project and modifying it:

   cp vendor/osamanagi/filament-abyss-theme/resources/css/theme.css resources/css/custom-theme.css
   

   Update vite.config.js to use your custom file instead.

2. Performance Optimization

   • Minify the theme CSS in production by enabling Laravel Mix's production mode.
   • Consider lazy-loading non-critical theme assets if the panel has heavy customizations.

3. Version Compatibility

   • Monitor FilamentPHP updates. The Abyss theme may require adjustments for major Filament versions.
   • Pin the package version in composer.json for stability:

     "osamanagi/filament-abyss-theme": "^1.0"
     

4. Community Contributions

   • Contribute to the package by submitting PRs for missing features (e.g., additional theme variants, better dark mode support).
   • Star the repository to show support and encourage maintenance.