design-system

Constraints

Apply @rules/laravel/filament.md — for custom Blade + Tailwind, create and register a custom theme; use Filament\Support\Icons\Heroicon for icons.
Apply @rules/laravel/livewire.md — keep Blade templates presentation-only; components are slim entry points.
Apply @rules/laravel/architecture.md and @rules/laravel/laravel.md for file placement.
Apply @rules/security/frontend.md if any audit fix touches output rendering or CSP.
Stack is Blade + Livewire + Alpine.js + Filament + Tailwind. No React/Vue/Next.
Any live-URL or browser-screenshot step is optional and tool-agnostic — never a hard dependency.

Modes

This skill runs in one of two modes, selected by the caller via MODE (default design):

design (default) — full design work: write tokens into the Tailwind config and CSS variables, register the Filament theme, build shared components, and author DESIGN.md. The three working modes below (Generate / Visual audit / AI-slop detection) are how that work is scoped; every section behaves as written unless it is explicitly flagged for MODE=cr.
cr (read-only lens — invoked by @skills/code-review/SKILL.md, code-review-github, code-review-jira, and code-review-bugsnag when the diff touches a frontend surface) — never modify a view, a token, a config, or a theme, never author a test, never stage / commit / push, never run fixers or checkers, and never chain a follow-up review. Run the Mode 2 audit dimensions and the Mode 3 slop patterns over the lines added or modified by the PR diff only, and return the findings as markdown only, carrying the reproducer fields the CR folds into its standard Critical / Moderate buckets. Skip Mode 1 entirely — generating a design system is not a review. Drop the 0–10 per-dimension scoring too: a score is not a finding, and the CR reports findings. Every instruction below that would touch a file — define, extract, register, build, replace, or any other such verb — is emitted as a written proposal carrying a concrete token / class / theme snippet, never applied to the project.

What this lens owns in a CR: token and theme consistency — an ad-hoc hex or arbitrary spacing value where a token exists, a component built outside the shared <x-ui.*> set, incomplete dark: coverage, and the AI-slop patterns. It defers every accessibility finding, contrast ratio included, to @skills/frontend-a11y/SKILL.md, and never raises one of its own. Dimension 10 (Polish) splits between two owners: this lens keeps the hover and transition half, which is visual finish it owns anyway, and defers the loading (wire:loading), empty, and error half to @skills/frontend-patterns/SKILL.md, which owns whether those states exist and behave. Never raise a missing loading or empty state as a token finding. It judges consistency across components that already exist, so Component consistency (dimension 4) reads as these elements should use the same existing <x-ui.*> component, never as build one for them. It never raises a finding whose fix is create a component.

Use when

Starting a project that needs a coherent design system.
Auditing an existing codebase for visual consistency.
Before a redesign — to understand what already exists.
The UI looks "off" but the cause is unclear.
Reviewing a PR that touches styling, Tailwind config, or a Filament theme.

In MODE=design this skill has three working modes. Pick the one that matches the request.

Mode 1: Generate a design system

Produce a documented token set wired into Tailwind, a Filament theme, and reusable Blade/Livewire components.

Steps

Scan existing styling for de-facto patterns: tailwind.config.js, resources/css/app.css, Blade views under resources/views, and any Filament theme CSS. Collect every color, font, size, radius, and shadow already in use.
Extract tokens into these groups: colors (brand, neutral, semantic success/warning/danger/info), typography (font families, type scale, weights, line heights), spacing scale, border radius, shadows, breakpoints, z-index layers.
Inspiration (optional) — if a browser tool is available you may reference real sites; never depend on it. Tokens must be derivable from the codebase alone.
Define tokens in Tailwind config plus CSS custom properties so values stay coherent across light/dark and component states.
Theme Filament — register a custom panel theme that consumes the same variables.
Build reusable components as anonymous Blade components (and Livewire components where interactive state is needed) that consume the tokens — never hard-coded hex.
Document decisions and rationale in DESIGN.md.

Tailwind tokens + CSS variables

// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        brand: { DEFAULT: 'rgb(var(--c-brand) / <alpha-value>)' },
        surface: 'rgb(var(--c-surface) / <alpha-value>)',
        danger: 'rgb(var(--c-danger) / <alpha-value>)',
      },
      borderRadius: { card: 'var(--radius-card)' },
      boxShadow: { card: 'var(--shadow-card)' },
    },
  },
};

/* resources/css/app.css */
:root {
  --c-brand: 37 99 235;      /* single source of truth */
  --c-surface: 255 255 255;
  --c-danger: 220 38 38;
  --radius-card: 0.5rem;
  --shadow-card: 0 1px 2px rgb(0 0 0 / 0.06);
}
.dark {
  --c-surface: 17 24 39;
}

Reusable Blade component

{{-- resources/views/components/ui/card.blade.php (anonymous) --}}
@props(['variant' => 'default'])
<div {{ $attributes->class([
    'rounded-card shadow-card bg-surface',
    'border border-gray-200 dark:border-gray-700' => $variant === 'outlined',
]) }}>
    {{ $slot }}
</div>

Use <x-ui.card>…</x-ui.card> everywhere instead of repeating utility strings. For interactive widgets, wrap state in a Livewire or Alpine component but keep the visual shell in the shared Blade component.

Filament theme

/* resources/css/filament/admin/theme.css */
@import '/vendor/filament/filament/resources/css/theme.css';
@import '../../app.css'; /* reuse the same --c-* variables */

Output: DESIGN.md (token tables + rationale), updated tailwind.config.js, CSS variables in app.css, the Filament theme, and the shared Blade/Livewire components.

Mode 2: Visual audit

Score the UI across 10 dimensions, 0–10 each. Every dimension needs a score, a concrete file:line example, and a fix.

Color consistency — palette tokens vs ad-hoc hex/rgb() strings in Blade.
Typographic hierarchy — clear h1 > h2 > h3 > body > caption; no skipped levels.
Spacing rhythm — a consistent scale (4/8/16) vs arbitrary mt-[13px].
Component consistency — similar elements built from the same <x-ui.*> component (in MODE=cr a finding whose fix is to create a new component is not raised; see Modes).
Responsive behavior — fluid across breakpoints; no overflow or layout breaks.
Dark mode — complete dark: coverage, not half-applied.
Motion — purposeful Alpine/transition use vs gratuitous animation.
Accessibility / contrast — token contrast ratios, visible focus states, touch targets (cross-link frontend-a11y).
Information density — clean and scannable vs cluttered.
Polish — hover, transition, loading (wire:loading), and empty states present (in MODE=cr the loading / empty / error half belongs to frontend-patterns; see Modes).

A live-URL crawl or screenshot pass is optional. If no browser tool exists, audit from the Blade/Tailwind source and Filament config directly — that is sufficient.

Report format per dimension:

Color consistency — 6/10
  resources/views/livewire/dashboard.blade.php:42 — bg-[#3b82f6] bypasses the brand token
  Fix: replace with bg-brand and add the token if missing

Mode 3: AI-slop detection

Flag generic AI-generated design tells and propose a deliberate alternative:

Gratuitous gradients on every surface.
Purple-to-blue default gradients with no brand basis.
Glassmorphism / backdrop-blur cards with no functional purpose.
Rounded corners on elements that should be square (tables, inputs in dense UIs).
Excessive scroll-triggered animation.
Generic centered-hero over a stock atmospheric gradient.
A personality-free sans stack that ignores the product domain.

For each hit, give file:line and a concrete fix that ties back to the project tokens and the chosen design direction (cross-link frontend-design-direction).

Done when

(Generate) Tokens live in Tailwind config + CSS variables, the Filament theme consumes them, shared Blade/Livewire components replace duplicated utility strings, and DESIGN.md documents the rationale.
(Audit) All 10 dimensions scored, each with a file:line example and a fix.
(Slop) Every flagged pattern has a location and a deliberate replacement.
No hard-coded colors remain where a token exists; no React/Vue artifacts introduced.

Output Humanization

Use blader/humanizer for all skill outputs to keep the text natural and human-friendly.