---
name: shadcn-review
description: "Human-triggered review of UI built with defuss-shadcn, or of a new defuss-shadcn component: a bundled checker for invented classes, modifier classes, unknown variants and tokens, loading order and globals, then a judgment pass against the guides - native elements first, the data-attribute API, the State API, composition and module boundaries, tokens, accessibility. Fixes confirmed defects."
disable-model-invocation: true
---

<!-- GENERATED by scripts/lib/agent-skills.ts from src/skills/shadcn-review/SKILL_tpl.md - do not edit by hand; edit the template and rebuild. -->

# defuss-shadcn / shadcn-review

Precondition: a person asked for this review. Default: review and fix what is confirmed; if they ask for a report only, change nothing.
Scope: the defuss-shadcn specifics of defuss-shadcn 0.9.8. General review - requirements, callers, tests, minimalism - stays with the project's own method (defuss-vae `review`, for example).

## Where things are

Paths are relative to this file.

- `scripts/markup-check.mjs` - the checker (Node 18 or later, or Bun; no dependencies). Its vocabulary - every class, part, variant, size and custom property of 234 components - is built from this release's stylesheets, scripts and component skills.
- `references/rules.md` - the rules every markup follows.
- `references/guides.md` - the guide pages each judgment below refers to.
- `references/catalog.md` - every component with its type, states and when to use it.

## Method

1. **Scope.** The changed files (`git diff --name-only`) or the paths the person names. Read each one, and the component skill of every component it uses.
2. **Mechanical pass.** Run `node <this skill's folder>/scripts/markup-check.mjs <files or folders>`. Every finding names `file:line`, the rule and the fix. Errors are defects:
   - `modifier-class` - `btn-outline` instead of `class="btn" data-variant="outline"`;
   - `unknown-part` - a part class the component does not have (a near miss names the part meant);
   - `unknown-variant`, `unknown-size` - a value no stylesheet, script or skill of that component knows;
   - `unknown-token` - `var(--x)` that neither the system nor the project declares;
   - `module-script`, `double-runtime`, `core-css` - how the system is loaded;
   - `icon-button-label` - an icon-only button without a name;
   - `window-global` - a global on `window`.

   Warnings (`html-sink`, `pin-version`, `core-css-order`) are defects unless the code has a stated reason. The vocabulary is this release's: if the project pins another release, a class added later reads as unknown - compare the `defuss-shadcn=` version on the last line.
3. **Judgment pass** - what no checker sees, each with its guide in `references/guides.md`:
   - **native first** (Native Web APIs) - `<dialog>`, `popover`, `<details>`, `commandfor`, native form controls; script that re-implements open, close, toggle or focus is a defect;
   - **data-attribute API** (Data Attribute API) - one base class, variants and sizes as `data-*`;
   - **state** (State API) - through `el.api.setState` or the documented markup; toggling classes for a component's state is a defect; a component keeps state on the element, never in module scope;
   - **composition and boundaries** (JavaScript Modules) - components talk through `df$.shadcn.*` APIs and `CustomEvent`s, never through another component's parts or shared mutable state; a component that ships its own `<dialog>` owns it;
   - **tokens** (Theming) - theme tokens only; a status colour without a token is a literal; no brand colours hard-coded in markup;
   - **layout** (Sizing, Layout) - the utilities from `core.css` instead of inline layout CSS; component CSS in `@layer components` (Cascade Layers);
   - **accessibility** (Accessibility) - the ARIA from the skill, labelled controls, visible focus, and in component CSS `prefers-reduced-motion`, `prefers-contrast` and `forced-colors`;
   - **a new component** - it is not a flavor of an existing one (behavior and design close to it: then it is that component's variant, state or example - a near-duplicate is a defect); an ORG or TPL is composed of reusable smaller units, not of one-off parts that copy an existing component; its declared type matches the classifier in shadcn-plan; skill, page examples and e2e fixture show the same variants, sizes and states.
4. **Fix and prove.** The smallest correct diff per finding; run `markup-check` again. In the defuss-shadcn repository `bun run verify` is the authority: its result outranks this review.

## Output contract

```text
FINDING <rule> <path:line>: <evidence>; fix=<the fix>
VERIFIED[markup-check]=true BC files=<n> errors=0
```

With no finding: `VERIFIED[review.clean]=true BC <files read>; markup-check errors=0`. No praise, no score, no summary.