README

This package analyzes your Laravel Blade components and generates coding rules for AI assistants like Cursor and Antigravity. It helps LLMs understand your specific design system, components, and props.

Installation

composer require davidgut/blade-llm-specs

Usage

Generate the rules:

php artisan blade-specs:generate

By default, this runs the generators defined in your config. You can also run specific ones:

php artisan blade-specs:generate cursor
php artisan blade-specs:generate antigravity
php artisan blade-specs:generate all

Configuration

Publish the config file:

php artisan vendor:publish --tag=blade-specs-config

You can define which generators are enabled by default and where they output their files.

Watch Mode

To automatically regenerate rules when you change a component, add the Vite plugin to your vite.config.js:

import bladeSpecs from './vendor/davidgut/blade-llm-specs/resources/js/vite-plugin';

export default defineConfig({
    plugins: [
        // ...
        bladeSpecs(),
    ],
});

Component Analysis Features

Class Whitelist

By default, the package extracts valid utility classes from your components to help the AI understand your styling. To avoid noise, you can configure a whitelist of patterns in config/blade-specs.php:

'class_whitelist' => [
    'bg-*',
    'text-*',
    'p-*',
    'm-*',
    // ...
],

Categorization

The package uses a simple directory-based categorization strategy:

Subdirectories: Components in folders (e.g., components/form/input.blade.php) are categorized by their folder name (e.g., form).
Root: Components in the root components directory are categorized as general.

Variant Analysis & Design Options

The analyzer goes beyond props and scans your @php blocks for design logic. If you define arrays like $sizes or $variants, the package will extract them and include them in the generated rules.

Example:

@php
    $sizes = [
        'sm' => 'px-3 py-1.5',
        'md' => 'px-4 py-2',
    ];
@endphp

The generated rules will explicitly list these options, allowing the AI to know exactly which size props are valid and what styles they apply.

Advanced Analysis

The package now performs deeper analysis to help the AI write better code:

Type Inference

It guesses prop types from their default values in @props:

false → boolean
'text' → string
[] → array
10 → integer

Slot Detection

It scans your Blade files for usage of $slot and named slots (like {{ $header }}). The generated usage examples will include these slots, showing the AI exactly how to use them:

<x-card title="...">
    <x-slot:header>
        Slot header content...
    </x-slot:header>
    Default slot content...
</x-card>

Docblocks

Add a standard blade comment at the top of your component file, and it will be used as the component's description:

{{-- A flexible card component with header and footer slots --}}
<div class="card">...</div>

Optimization

Context Awareness

To reduce token usage and improve AI accuracy, you can split the generated rules into multiple files based on category. This allows tools like Cursor and Antigravity to load only the relevant rules (e.g., "Forms") instead of the entire design system.

Enable this in config/blade-specs.php:

'split_by_category' => true,

Cursor: Generates .mdc files in .cursor/rules/blade/ with globs: *.blade.php.
Antigravity: Generates .mdc files in .agent/rules/blade/ with globs: *.blade.php and trigger: glob.

Verification & Safety

Safe Cleanup

The package includes a safety mechanism to prevent accidental deletion of your own files. When regenerating modular rules, it scans the target directory and only deletes files that contain the special signature: 

Any manual notes or files you add to these directories are safe.

Canary Test

Verify that your AI is correctly reading the rules by enabling the Canary Test in config/blade-specs.php:

'canary_test' => true,

When enabled, the generator injects a special "Verification Rule" at the top of every file. You can then ask your AI "What are you reading?" and it should respond with the filename (e.g., "I am reading the forms.mdc file"). This confirms that context loading is working as expected.

License

MIT

davidgut / blade-llm-specs

Maintainers

Details