Theme Inverness Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require spykapps/theme-inverness
   php artisan vendor:publish --provider="SpykApps\Inverness\InvernessServiceProvider" --tag="inverness-config"
   php artisan inverness:install
   

   • The inverness:install command publishes assets and sets up the theme.

2. Enable the Theme Add the theme to your Filament admin panel configuration in config/filament.php:

   'themes' => [
       'custom' => [
           'path' => 'vendor/spykapps/theme-inverness',
           'view' => 'inverness',
       ],
   ],
   

   Then, in your AppServiceProvider or a dedicated service provider, bind the theme:

   use SpykApps\Inverness\Inverness;
   
   public function boot(): void
   {
       Inverness::make()->use();
   }
   

3. First Use Case

   • Visit your Filament admin panel (/admin). The theme should now reflect the Inverness design (tight spacing, Laravel-red accents, refined aesthetics).

Implementation Patterns

Core Workflows

1. Theme Customization

   • Override Views: Publish and modify Inverness views:

     php artisan vendor:publish --provider="SpykApps\Inverness\InvernessServiceProvider" --tag="inverness-views"
     

     Override files in resources/views/vendor/inverness/.
   • Tailwind Configuration: Extend or override Tailwind classes in resources/css/app.css or via tailwind.config.js:

     module.exports = {
         theme: {
             extend: {
                 colors: {
                     'laravel-red': '#FF2D20',
                 },
             },
         },
     };
     

2. Dark Mode Integration

   • Inverness supports dark mode out-of-the-box. Ensure your Filament admin panel has dark mode enabled in config/filament.php:

     'dark_mode' => true,
     

3. Sidebar and Navigation

   • Customize the sidebar by publishing and modifying the sidebar.blade.php view. Use the active class to style active states:

     <x-inverness::sidebar>
         <x-slot name="logo">
             <x-filament::logo />
         </x-slot>
         <x-inverness::sidebar.item
             href="{{ route('filament.admin.pages.dashboard') }}"
             icon="heroicon-o-home"
             active
         >
             Dashboard
         </x-inverness::sidebar.item>
     </x-inverness::sidebar>
     

4. Form and Table Styling

   • Inverness refines Filament’s default form and table components. Extend or override these in your published views:

     php artisan vendor:publish --provider="SpykApps\Inverness\InvernessServiceProvider" --tag="inverness-forms"
     php artisan vendor:publish --provider="SpykApps\Inverness\InvernessServiceProvider" --tag="inverness-tables"
     

5. Asset Management

   • Inverness includes compiled assets (CSS/JS). To rebuild or customize:

     npm run dev  # or `npm run build` for production
     

   • Override assets by publishing them:

     php artisan vendor:publish --provider="SpykApps\Inverness\InvernessServiceProvider" --tag="inverness-assets"
     

Integration Tips

• Filament Plugins: Inverness is designed to work seamlessly with Filament plugins. No additional configuration is required for most plugins.
• Localization: If using localization, ensure your language files extend Inverness’s terminology (e.g., resources/lang/en/filament.php).
• Performance: Inverness is optimized for performance. Avoid excessive customizations that could bloat asset sizes.
• Testing: Test the theme in both light and dark modes, as well as on different screen sizes, to ensure consistency.

Gotchas and Tips

Pitfalls

1. Asset Conflicts

   • If you manually include Tailwind or Alpine.js, conflicts may arise with Inverness’s bundled assets. Stick to the package’s asset pipeline.
   • Fix: Remove manual asset inclusions and rely on Inverness’s published assets.

2. View Override Mismatches

   • Overriding views incorrectly can break layout structure. Always compare your custom views with the originals in vendor/spykapps/theme-inverness/resources/views.
   • Tip: Use artisan vendor:publish to get the latest view templates before customizing.

3. Dark Mode Inconsistencies

   • Some Filament components may not fully respect dark mode. Inverness handles most core components, but third-party plugins might need manual adjustments.
   • Tip: Inspect the dark mode classes (e.g., dark:) in the browser’s dev tools and override as needed.

4. Caching Issues

   • After customizing views or assets, clear Filament’s cache:

     php artisan filament:cache:clear
     php artisan view:clear
     npm run dev
     

5. Laravel Mix/Inertia Conflicts

   • If using Inertia.js or custom Laravel Mix setups, ensure your configuration doesn’t override Inverness’s asset compilation.
   • Tip: Disable Mix for Filament assets in webpack.mix.js:

     mix.disableSuccessMessages();
     

Debugging

1. Inspect Elements

   • Use browser dev tools to inspect classes and styles. Inverness uses utility classes (e.g., ti-spacing-tight, ti-shadow-subtle), so overrides should target these.

2. Tailwind Conflicts

   • If styles aren’t applying, check for Tailwind class conflicts. Use !important sparingly; instead, extend Tailwind’s theme in tailwind.config.js:

     module.exports = {
         important: true, // Force Tailwind styles to override others
     };
     

3. Log Errors

   • Enable Filament’s debug mode in config/filament.php:

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

   • Check Laravel logs (storage/logs/laravel.log) for theme-related errors.

Extension Points

1. Custom Components

   • Inverness follows Filament’s component structure. To add custom components, extend the theme’s view composers or create new Blade components in resources/views/vendor/inverness/components.

2. Dynamic Theming

   • Use Filament’s use method to conditionally apply Inverness:

     public function boot(): void
     {
         if (auth()->user()->is_admin) {
             Inverness::make()->use();
         }
     }
     

3. Plugin Support

   • To support Inverness in a custom Filament plugin, ensure your plugin’s views extend Inverness’s base classes (e.g., <x-inverness::layout>).

4. Configuration

   • Publish the config file for advanced customization:

     php artisan vendor:publish --provider="SpykApps\Inverness\InvernessServiceProvider" --tag="inverness-config"
     

   • Adjust settings like spacing, shadows, or colors in config/inverness.php.

Pro Tips

• Consistency: Stick to Inverness’s design system (spacing, shadows, typography) for a cohesive look. Avoid arbitrary overrides.
• Performance: Use PurgeCSS to remove unused Tailwind classes in production:

  // tailwind.config.js
  module.exports = {
      purge: [
          './resources/**/*.blade.php',
          './vendor/spykapps/theme-inverness/**/*.blade.php',
      ],
  };
  

• Community: Monitor the GitHub issues for updates or common solutions.