Filament Design System Laravel Package

Getting Started

Minimal Steps

1. Install as Dev Dependency

   composer require --dev visualbuilder/filament-design-system
   

   Ensure it’s excluded from production via --dev flag or conditional provider registration.

2. Publish Provider & Configure

   php artisan vendor:publish --tag=filament-design-system-provider
   

   Edit app/Providers/Filament/DesignSystemPanelProvider.php to wire your theme assets (e.g., vite_theme, brand.logo).

3. Set Up Database

   php artisan migrate
   php artisan db:seed --class="Visualbuilder\FilamentDesignSystem\Database\Seeders\DemoUserSeeder"
   

   Access the panel at /design-system (configurable) with demo credentials shown on login.

4. Enable MCP (Optional for AI Workflows) Add to .mcp.json:

   {
     "mcpServers": {
       "design-system": {
         "command": "php",
         "args": ["artisan", "mcp:start", "design-system"]
       }
     }
   }
   

   Restart your AI agent (e.g., Claude Code) to access tools.

First Use Case: Theme Token Review

• Navigate to /design-system/tokens to preview all Filament v5 components (forms, tables, widgets) rendered with your current config/design-system.php tokens.
• Use the MCP read_tokens tool to fetch the live token config for AI analysis:

  { "tool": "read_tokens" }
  

• Example AI prompt:

  "Analyze the current primary color palette (tokens.colors.primary). Suggest a 500-shade coral alternative (#ea746b) with a full 11-shade ramp (50→950)."

Implementation Patterns

Core Workflows

1. Token-Driven Theme Iteration

• Pattern: Use write_tokens to override CSS variables via MCP.

  {
    "tool": "write_tokens",
    "args": {
      "tokens": {
        "colors": {
          "primary": {
            "50": "#fce4ec", "500": "#ea746b", "950": "#7a2822"
          }
        }
      }
    }
  }
  

• Integration Tip: Chain with screenshot_catalogue to validate changes:

  { "tool": "screenshot_catalogue", "args": { "page": "forms" } }
  

• Laravel Hook: Listen to design-system.tokens.updated event to trigger rebuilds (e.g., Vite HMR).

2. Panel Chrome Customization

• Override panel.vite_theme, panel.font, or panel.brand.logo via MCP:

  {
    "tool": "write_tokens",
    "args": {
      "panel": {
        "font": { "family": "Inter", "provider": "Filament\\FontProviders\\GoogleFontProvider" },
        "brand": { "logo": "https://example.com/logo.svg" }
      }
    }
  }
  

• Gotcha: Ensure public/design-system/brand/ is writable for logo uploads.

3. Component-Level CSS Overrides

• Use write_theme_overrides for selectors not covered by tokens:

  {
    "tool": "write_theme_overrides",
    "args": {
      "css": ".fi-table th { background: var(--color-gray-100); }"
    }
  }
  

• Tip: Query the class manifest first:

  { "tool": "list_classes", "args": { "prefix": "fi-table" } }
  

4. AI-Assisted Workflows

• Palette Generation:

  { "tool": "generate_palette", "args": { "hex": "#3b82f6" } }
  

• CSS Graduation:

  { "tool": "export_theme_css" }
  

  Paste the output into resources/css/filament/admin/theme.css.

Integration Tips

• Filament Panel Registration: Guard the provider in bootstrap/providers.php:

  if (app()->environment('local') && class_exists(\Visualbuilder\FilamentDesignSystem\FilamentDesignSystemPlugin::class)) {
      $providers[] = App\Providers\Filament\DesignSystemPanelProvider::class;
  }
  

• Playwright Screenshots: Install once per project:

  npm install --save-dev playwright
  npx playwright install chromium
  

  No additional config needed—the package auto-detects Playwright.

• Class Manifest Refresh: After Filament updates, rebuild the manifest:

  php artisan filament-design-system:rebuild-class-manifest
  

Gotchas and Tips

Pitfalls

1. Overlay File Permissions

   • storage/app/design-system-tokens.json must be writable by the web server.
   • Fix: Run chmod -R 775 storage/app or configure Laravel’s filesystem driver.

2. MCP Tool Conflicts

   • If multiple MCP servers use write_tokens, tools may overwrite each other.
   • Solution: Scope tools by prefix (e.g., design_system.write_tokens).

3. Playwright Missing

   • Without node_modules/playwright, screenshot_catalogue returns setup guidance.
   • Workaround: Register a custom capture closure (see Override Closure).

4. Token Validation Errors

   • write_tokens rejects invalid CSS variables (e.g., missing 500 shade).
   • Tip: Use dry_run: true to validate before applying:

     {
       "tool": "write_tokens",
       "args": {
         "tokens": { "colors": { "primary": { "50": "#fff" } } },
         "dry_run": true
       }
     }
     

5. CSP Restrictions

   • If your host blocks api.dicebear.com (used for avatars), the package falls back to local rendering.
   • Note: No action required—it works out of the box.

Debugging

• Tool Failures: Check Laravel logs (storage/logs/laravel.log) for MCP validation errors. Example error:

  [MCP] Invalid tokens: "spacing.base" must be a number.
  

• Screenshot Failures: If Playwright crashes, the MCP connection remains open. Use try/catch in custom closures:

  FilamentDesignSystemPlugin::make()
      ->screenshotCapture(function ($url) {
          try {
              return ['image' => base64_encode(file_get_contents($url)), 'mime' => 'image/png'];
          } catch (\Exception $e) {
              return null; // MCP tool returns error message
          }
      });
  

• Class Manifest Issues: If list_classes returns stale data, rebuild the manifest manually:

  php artisan filament-design-system:rebuild-class-manifest --force
  

Extension Points

1. Custom Screenshot Capture Override the Playwright default with a hosted service (e.g., AWS Lambda):

   FilamentDesignSystemPlugin::make()
       ->screenshotCapture(function ($url) {
           $response = Http::post('https://screenshot-service.com/capture', [
               'url' => $url,
               'token' => config('services.screenshot_api_token'),
           ]);
           return ['image' => $response->json()['base64'], 'mime' => 'image/png'];
       });
   

2. Additional Demo Data Extend DemoUserSeeder to populate search results:

   public function run(): void
   {
       DemoUser::factory()->count(8)->create();
       // Add custom attributes for richer search UX
       DemoUser::all()->each(fn ($user) => $user->update(['full_name' => fake()->name]));
   }
   

3. Token Presets Add a design-system:preset Artisan command to load common palettes:

   // app/Console/Commands/LoadDesignSystemPreset.php
   use Visualbuilder\FilamentDesignSystem\Facades\DesignSystem;
   
   public function handle()
   {
       $preset = json_decode(file_get_contents(__DIR__.'/presets/coral.json'), true);
       DesignSystem::writeTokens($preset['tokens']);
   }
   

4. Animations Support If using visualbuilder/lottie, the Animations catalogue page auto-registers. Customize via:

   FilamentDesignSystemPlugin::make()
       ->withAnimations([
           'triggers' => ['click', 'hover', 'scroll'],
           'components' => ['<x-lottie-player />', '<x-animate />'],
       ]);