Lint

Run it

php artisan ui:check
php artisan ui:check --fail-on=warning          # CI gate
php artisan ui:check --format=sarif > brok.sarif # editors and code scanning
php artisan ui:check --json                      # agents and scripts
php artisan ui:check --explain no-restyle        # one rule, its options, its docs
php artisan ui:check --list-rules                # every rule with its effective level
php artisan ui:check --fix                       # apply exact replacements and spelling fixes, then re-check
php artisan ui:check --fix --unsafe-fixes        # also apply approximations (nearest theme colour)

Every finding carries a stable id (UI-408), a name (no-restyle), the file and line, the guidance, and a link to this documentation. A finding that knows the exact replacement carries a fix; --fix applies the safe ones (a scale step with the same value, a spelling correction, the logical twin of a physical utility) and re-checks. A nearest-colour suggestion is an approximation and needs --unsafe-fixes.

UI-408 resources/views/orders/edit.blade.php:12 ........ ERROR no-restyle
    "p-4" is not allowed on <button>: <button> owns its spacing. Use a size (sm, md, lg, icon),
    or margin on it, gap on the parent element, or padding on the container for space around it.

Configure

Add a lint block to ui.json. Each rule takes a level (off, warning, error) or [level, options]. Rules are keyed by name or id; a rule you do not list keeps its default. Component internals under resources/views/components/ui are outside the default scan, so components can style themselves; a rule's include adds paths it should also run on (keep no-raw-colors and no-unknown-classes on inside the component directory, as shadcn recommends), and exclude takes paths away from any rule. Both accept project-relative prefixes or globs.

{
  "lint": {
    "note": "See docs/design-rules.md for approved exceptions.",
    "rules": {
      "no-restyle": ["error", {
        "allow": ["layout"],
        "contracts": [
          { "pattern": "^card\\.title$", "allow": ["layout", "typography"], "deny": ["font-*"] },
          { "pattern": "^card\\.content$", "allow": ["layout", "spacing"] }
        ]
      }],
      "no-raw-colors": "error",
      "no-arbitrary-values": ["warning", { "allow": ["layout"] }],
      "no-inline-styles": ["error", { "allow": ["transform"] }],
      "no-unknown-classes": ["warning", { "include": ["resources/views/components/ui"] }],
      "require-static-classes": "error",
      "no-dark-color-override": "off",
      "no-physical-direction": ["warning", { "exclude": ["resources/views/legacy/**"] }]
    }
  }
}

A mistake in the block, such as a misspelled rule, an unknown option or a category typo, is reported as UI-006 invalid-config on ui.json, and the affected rule pauses until it is fixed. Nothing is silently ignored.

The policy

The class rules share one option shape. allow exempts matching classes, deny removes matches from allow, and contracts set a policy for the components a pattern matches.

Entries are categories (layout, color, typography, spacing, shape, effects, motion), class groups (px, bg-color, rounded), or classes and wildcard patterns (p-4, p-*, md:p-*). An entry without a colon matches the base class, ignoring variants, important markers, negative prefixes and opacity modifiers; an entry with a colon matches the whole class. Margin, sizing, position, transforms and text alignment are layout; padding and gap are spacing.

A contract's pattern is a regex on the component name as written after the prefix: ^button$ matches only <brok:button>; ^card\. matches every card part. A contract replaces the keys it writes and inherits the rest; when several match, the last one applies. For no-inline-styles the entries are CSS property names (transform, border-*, --*).

Your own words

Every rule accepts message. no-restyle also accepts an object keyed by category with a default. A contract can carry its own message. The linter picks the contract's category message, then its default, then the rule's message, then the built-in guidance. {{key|fallback}} fills an empty slot; an unknown key stays literal and a near-miss is warned about. note is appended to every finding.

"no-restyle": ["error", {
  "allow": ["layout"],
  "message": {
    "spacing": "Use a {{component}} size: {{sizes|none defined}}.",
    "default": "Use a {{component}} variant: {{variants|none defined}}."
  }
}],
"no-raw-colors": ["error", {
  "message": "Use a theme color for \"{{className}}\". See {{file}}."
}]

Suppress one line

A reasoned comment on the preceding line suppresses one rule by name or id. Malformed, unknown and unused suppressions fail as UI-005, so an exception never outlives its reason.

{{-- ui-lint-disable-next-line no-raw-colors: Brand moment approved by design, see DES-142. --}}
<span class="bg-pink-500">New</span>

For agents

Findings are written to be acted on, never to be argued with: no message asks the reader to change the policy. --json returns every finding with its meta (the component, the class, the allowed values, the suggestions) and a docs link. --explain <rule> prints the rule's contract, options and effective level. --path takes a single file, --stdin=<path> lints an unsaved buffer, and --watch re-runs on every change, so the loop stays under a second. Put php artisan ui:check --json in your agent instructions and let it run after each edit; the MCP server exposes the same rule catalog.

Does it pay off?

We ran the shadcn/lint eval method against ui:check: three Blade tasks (a settings page, a pricing table, an orders table), an agent with no tools that answers with the file, up to three correction rounds, and the shipped linter as the only judge. The feedback after each round was either a generic "it still breaks the design rules" or the exact ui:check findings.

With the findings in the loop the agent reached zero almost always in one round; with a nudge it fixed what it guessed and left the rest, round after round. The findings loop cost 55 to 86 % less per task (token cost at API list price, as the CLI reports it). Small sample (36 cells, September 2026); the harness, the raw cells and the caveats are in packages/evals/lint.

Editors

The Brok Lint extension for VS Code (packages/vscode-brok-lint) runs ui:check --stdin on the unsaved buffer as you type and shows each finding on its class, with the rule id as the code, the docs page one click away, and a quick fix wherever the finding carries one; "Apply safe lint fixes in file" applies them all. Any editor that reads SARIF can use ui:check --format=sarif instead.

JSX and the extension kit

@brokui/eslint-plugin holds Preact and React code to the same six class rules: the engines are shadcn/lint's, the defaults, the UI-nnn ids and the docs links are this catalog's, so a finding on a <Button> in the extension kit reads like one on <brok:button>. Add recommended() from the package to your flat ESLint config.

Rules

Every rule has a page with examples, options and limits. Six rules police classes with the shared policy; the rest read component contracts, accessibility and Livewire usage.

Tokens and classes

Component contracts

Adoption

Accessibility

Livewire

Boundaries