Filament Design System Laravel Package

Technical Evaluation

Architecture Fit

• Filament v5 Native Integration: The package is purpose-built for Filament v5, leveraging its component library, Blade templates, and Livewire architecture. It extends Filament’s existing panel system without requiring invasive changes to the core application.
• Design-System Focus: Specializes in token-based theming (CSS variables) and component-level overrides, aligning with modern design systems (e.g., Tailwind, Filament’s own theming). The three-layer overlay system (tokens, panel, theme) mirrors industry-standard separation of concerns.
• AI-First Design: The MCP server abstracts away UI interactions, making it ideal for AI agents to programmatically iterate on designs. This is a unique differentiator—most design tools require manual UI clicks.

Integration Feasibility

• Low Friction for Filament Apps: Requires only:
  1. Composer install (--dev).
  2. Provider registration (gated for production).
  3. Theme config publishing (10–15 lines of PHP).
  4. Optional: Playwright setup for screenshots (~5 mins).
• No Core Laravel Changes: Operates as a standalone panel with its own database (demo users, guard). No risk of conflicts with existing Filament panels.
• CSS/Asset Isolation: Overrides are scoped to the design-system panel, preventing bleed into production themes until explicitly exported.

Technical Risk

Key Questions

1. AI Workflow Maturity:

   • How will the AI agent be integrated (e.g., Claude Code, custom LLM)? Does it support MCP natively, or will a proxy be needed?
   • Example: "Can the agent handle multi-step workflows (e.g., generate palette → apply → screenshot → validate) without manual intervention?"

2. Theme Migration Path:

   • How will signed-off CSS from export_theme_css be merged into the host’s theme.css? Will this require a CI step or manual review?

3. Production Guarding:

   • Beyond DNS/basic auth, what additional safeguards are needed (e.g., IP whitelisting, rate limiting) to prevent accidental exposure?

4. Scaling the Catalogue:

   • If the design system grows (e.g., adding Filament plugins like visualbuilder/lottie), how will the class manifest and screenshot tooling scale?

5. Customization Limits:

   • Can the package override all Filament components, or are some (e.g., auth screens) locked down? If so, how will edge cases (e.g., custom resources) be handled?

Integration Approach

Stack Fit

• Primary Stack: Laravel 10+, Filament v5, Livewire 4.
• Secondary Stack:
  • AI Integration: MCP (stdin/stdout) or web transport (if using Laravel MCP’s HTTP bridge).
  • Screenshots: Playwright (Node.js) or custom closure (e.g., Puppeteer, AWS Lambda).
  • Font Loading: Google Fonts (via Filament’s GoogleFontProvider) or self-hosted fonts.
• Anti-Patterns:
  • Avoid mixing this panel’s theme with production panels until explicitly exported.
  • Do not use the demo database in staging/production.

Migration Path

1. Pilot Phase (Dev):

   • Install as --dev dependency.
   • Publish the provider and configure config/design-system.php with your brand assets (logo, fonts, colors).
   • Seed the demo user and test the catalogue at /design-system.
   • Validate MCP tools via php artisan mcp:inspector design-system.

2. AI Integration:

   • Configure .mcp.json to expose the server to your AI agent (Claude Code or custom).
   • Test tool calls:

     { "tool": "generate_palette", "hex": "#ea746b" }
     { "tool": "write_tokens", "tokens": { "colors": { "primary": { "50": "#..." } } } }
     

3. Production Readiness:

   • Gate the panel provider in bootstrap/providers.php:

     if (!app()->environment('production')) { $providers[] = DesignSystemPanelProvider::class; }
     

   • Add DNS/basic auth or a reverse proxy rule (e.g., Nginx allow 192.168.1.0/24;).

4. Graduation to Production:

   • Export final CSS via export_theme_css and merge into resources/css/filament/admin/theme.css.
   • Reset the overlay: reset_overlay(scope="all") (optional, if keeping the panel for future iterations).

Compatibility

Sequencing

1. Pre-requisites:

   • Laravel 10+ with Filament v5 installed.
   • Node.js (for Playwright) or a custom screenshot service.
   • AI agent with MCP support (or a proxy like laravel-mcp/web).

2. Critical Path:

   composer require --dev visualbuilder/filament-design-system
   php artisan vendor:publish --tag=filament-design-system-provider
   php artisan migrate --seed
   php artisan mcp:inspector design-system  # Validate tools
   

3. Post-Install:

   • Configure config/design-system.php (branding, fonts, colors).
   • Set up MCP in your AI environment (.mcp.json).
   • Test screenshot tooling (Playwright or custom closure).

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Token/config updates are handled via the overlay file (storage/app/design-system-tokens.json).
  • Class manifest refresh required only after Filament major upgrades (filament-design-system:rebuild-class-manifest).
• Dependency Updates:
  • Monitor visualbuilder/filament-design-system for Filament v5 compatibility.
  • Playwright updates may require npx playwright install chromium after Node.js upgrades.

Support

• Troubleshooting Aids:
  • MCP Inspector provides a visual tool surface for debugging.
  • Screenshot tool returns setup guidance if Playwright is missing.
  • Demo user credentials are hardcoded on the login page (no secrets to rotate).
• Common Issues:
  • CSS Overrides Not Applying: Verify the class exists in list_classes and the override syntax is valid.
  • MCP Connection Drops: Ensure the AI agent’s environment has laravel/mcp installed.
  • Screenshots Fail: Check Playwright is installed (npx playwright install) and the host allows outbound requests.

Scaling

• Performance:
  • Catalogue rendering is memory-intensive (loads all Filament components). For large teams, consider:
    • Caching the catalogue pages (e.g., php artisan cache:clear after token changes).
    • Hosting the design system on a separate instance with higher resources.
  • Screenshot tooling is the bottleneck if using Playwright. For high-volume AI iteration, replace with a dedicated service (e.g., AWS Lambda + Puppeteer).
• Team Scaling:
  • Multiple designers can use the panel simultaneously (demo user is read-only).
  • AI agents can parallelize tasks (e.g., generate 10 palettes concurrently).

Failure Modes