Getting Started

First Steps

Installation Run composer require resma/filament-awin-theme in your Laravel project. Verify the package appears in composer.json under require.

Vite Integration Add the theme’s CSS to your vite.config.js:

input: [
    'resources/css/app.css',
    'vendor/resma/filament-awin-theme/resources/css/theme.css' // <-- Add this line
],

Rebuild assets with npm run build.

Activate the Theme Register the plugin in your PanelProvider (e.g., App\Providers\Filament\PanelProvider):
```
public function panel(Panel $panel): Panel {
    return $panel->plugins([
        FilamentAwinTheme::make(),
    ]);
}
```
Clear cached views (php artisan view:clear) if the theme doesn’t appear immediately.
First Use Case Test the theme by navigating to your Filament admin panel. Verify:
- Dark/light mode toggle works (if enabled).
- Layout responsiveness on mobile/desktop.
- Primary color matches your brand (default: Awin’s palette).

Implementation Patterns

Core Workflows

Theming Across Panels If using multiple Filament panels (e.g., admin, tenant), register the plugin in each panel() method:

->plugins([
    FilamentAwinTheme::make()->configureUsing(fn (FilamentAwinTheme $theme) => [
        'primary_color' => 'blue', // Override per panel
    ]),
]);

Dynamic Color Switching Use Filament’s use method to conditionally apply colors based on user roles or settings:

public function panel(Panel $panel): Panel {
    $primaryColor = auth()->user()->prefers_dark_mode ? 'gray' : 'blue';
    return $panel->plugins([
        FilamentAwinTheme::make()->configureUsing(fn (FilamentAwinTheme $theme) => [
            'primary_color' => $primaryColor,
        ]),
    ]);
}

Customizing Components Extend the theme’s Tailwind/Sass variables by publishing the config:

php artisan vendor:publish --tag="filament-awin-theme-config"

Modify config/filament-awin-theme.php to override:

'colors' => [
    'primary' => '#3b82f6', // Custom hex
    'dark' => [
        '50' => '#1e293b',
    ],
],

Rebuild assets after changes.

Dark Mode Persistence Sync dark mode preference with the user’s OS or a database flag:

// In a Filament widget or middleware
FilamentAwinTheme::setDarkMode(
    request()->wantsJson() ? false : request()->user()->prefers_dark_mode
);

Integration with Filament Forms/Tables Leverage the theme’s consistency by using Filament’s built-in styling helpers:

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->columnSpanFull()
    ->extraAttributes(['class' => 'awin-theme-input']), // Optional: Add theme-specific classes

Gotchas and Tips

Common Pitfalls

Asset Build Issues
- Problem: Theme styles don’t apply after installation.
- Fix: Ensure theme.css is included after your main CSS in vite.config.js. Run npm run dev (not just build) during development to see live updates.
- Debug: Check browser DevTools for 404 errors on /vendor/resma/.../theme.css.
Color Palette Conflicts
- Problem: Custom primary colors break Filament’s interactive elements (e.g., buttons, badges).
- Fix: Use Filament’s predefined color palettes (e.g., blue, indigo) or ensure your hex values include all required shades (50, 100, ..., 900).
- Workaround: Extend the theme’s Sass variables to generate missing shades:
```
// resources/css/awin-extensions.scss
@use "vendor/resma/filament-awin-theme/resources/css/awin" as awin;
@include awin.generate-shades(#your-hex, 10);
```
Plugin Registration Order
- Problem: Theme overrides are ignored.
- Fix: Register FilamentAwinTheme after other plugins that might modify Filament’s styles (e.g., Filament\Plugins\Settings).
Dark Mode Glitches
- Problem: Dark mode flickers or doesn’t persist.
- Fix: Use Filament’s use method to set dark mode early in the request lifecycle (e.g., in a middleware or service provider):
```
FilamentAwinTheme::setDarkMode(request()->user()?->prefers_dark_mode ?? false);
```

Pro Tips

Debugging Customizations Use Tailwind’s JIT mode for development to test color changes instantly:

// vite.config.js
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/css/awin.css'],
            refresh: true,
        }),
    ],
});

Add a temporary awin.css file to override variables:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
    .awin-theme-primary-500 { @apply bg-blue-500; } /* Override example */
}

Extending the Theme Create a child theme by copying the package’s assets to your project:

mkdir -p resources/css/themes/awin-custom
cp -r vendor/resma/filament-awin-theme/resources/css/* resources/css/themes/awin-custom/

Update vite.config.js to use your custom path:

input: [
    'resources/css/themes/awin-custom/theme.css',
],

Performance Optimization

Lazy-load non-critical CSS: Use @import in your main CSS to load the theme conditionally:

@media (prefers-color-scheme: dark) {
    @import 'vendor/resma/filament-awin-theme/resources/css/theme-dark.css';
}

Purge unused CSS: Configure Tailwind to purge the theme’s classes in tailwind.config.js:

content: [
    './vendor/resma/filament-awin-theme/resources/**/*.blade.php',
    './resources/views/**/*.blade.php',
],

Localization Override the theme’s language strings by publishing translations:
```
php artisan vendor:publish --tag="filament-awin-theme-translations"
```
Modify resources/lang/en/filament-awin-theme.php to change labels (e.g., "Toggle Dark Mode").

Testing Use Filament’s testing helpers to verify theme behavior:

use Resma\FilamentAwinTheme\Testing\TestsFilamentAwinTheme;

public function test_theme_primary_color()
{
    $this->actingAs($user)
         ->get('/admin')
         ->assertSee('style="--awin-primary: #3b82f6;"');
}

Filament Awin Theme Laravel Package