Aura Design System

shadcn lint

Aura @shadcn/lint policy (no arbitrary values, no raw colors, no-restyle). Installs Cursor rule + eslint.aura-shadcn.mjs. Add with shadcn as @aura/rule-shadcn-lint or @aura/eslint-shadcn-lint.

Aura + @shadcn/lint

Installation

pnpm dlx shadcn@latest add @aura/rule-shadcn-lint

@shadcn/lint is the machine-checkable layer for Aura Tailwind policy. Cursor rules and DESIGN.md guide agents; lint errors tell them how to fix UI.

MUST

  • MUST: After UI changes, run the project lint script and fix @shadcn/lint findings before finishing.
  • MUST: Prefer theme tokens (accent-*, gray-*, semantic) over raw palette colors (bg-pink-500, hex).
  • MUST: Prefer the Aura 13px spacing scale over arbitrary values (p-[16px]).
  • MUST: Do not restyle design-system components with padding, colors, or typography via className — use variants/sizes, or layout/width only.
  • MUST: Form controls (Input, Textarea, SelectTrigger, MaskInput, SegmentedInput) own their padding. Use layout/width only. If the design needs different padding, add a size/variant on the component — do not override padding at the call site.
  • MUST: Never put text-sm / text-xs on editable form controls (Aura floor is 17px).
  • MUST: Never add a horizontal margin to an icon inside Button or Badge — the control owns the icon/label gap, and aura/no-icon-margin reports it (auto-fixable). Space your own icon rows with gap-0.5 on the container.

Rules shipped by eslint.aura-shadcn.mjs

RuleWhat it catches
shadcn/no-arbitrary-valuesValues off the 13px scale (p-[16px]).
shadcn/no-raw-colorsRaw palette colors instead of accent-* / gray-* / semantic tokens.
shadcn/no-restyleRestyling design-system components through className.
aura/no-icon-marginml-* / mr-* / mx-* / ms-* / me-* on an icon inside a control that already has a gap. ml-auto / mr-auto stay allowed.

Setup (if missing)

  1. Ensure ESLint ≥ 9.30 and Node ≥ 20.19.
  2. Install: pnpm add -D @shadcn/lint (in the app that owns eslint.config.*).
  3. Install the Aura snippet: pnpm dlx shadcn@latest add @aura/eslint-shadcn-lint (writes eslint.aura-shadcn.mjs + this rule).
  4. Merge the exported config into the app’s eslint.config.mjs (see snippet file header).
  5. Set settings.shadcn.ui to the project’s UI alias (default @/components/ui).
  6. Keep no-restyle / no-arbitrary-values off under components/ui/** (components own appearance).
  7. Start rules at warn; promote to error as debt clears.

SHOULD

  • SHOULD: Point settings.shadcn.note at DESIGN.md and .cursor/rules.
  • SHOULD: Allow layout + spacing on Form shells (Form, FormField, …) when pages set gap around fields.
  • SHOULD: Document intentional exceptions with eslint-disable-next-line shadcn/… -- reason.

Upstream: shadcn-ui/lint.

Self-documenting system

Maintain a project wiki in Obsidian and keep Bruno API collections in sync with app and API changes.

All Components

A comprehensive list of all available components in the Aura Design System.

On this page

Aura + @shadcn/lintInstallationMUSTRules shipped by eslint.aura-shadcn.mjsSetup (if missing)SHOULD