design-system

<user_request>$ARGUMENTS</user_request>

<step number="1" name="Resolve mode and scope">
  Parse $ARGUMENTS. Do NOT ask the user anything that the arguments already answer.

  MODE (default `validate`):
  - `--fix`   → validate, then fix violations
  - `--setup` → scaffold guardrails into a project that lacks them
  - otherwise → validate and report only (read-only)

  SCOPE (default: whole repo):
  - `--changed` → only files changed vs the base branch. Use the plugin's
    capture script rather than a hand-rolled range — it resolves the base,
    includes staged, unstaged and **untracked** files, and never touches the
    index:
    ```bash
    bun "${CLAUDE_PLUGIN_ROOT}/scripts/capture-review-surfaces.ts" \
      --repo "$(git rev-parse --show-toplevel)" --stat
    ```
    If it warns that no base branch resolved, say so in the report and audit
    the working tree only. **Never fall back to `HEAD~1`** — that silently
    audits one commit of a many-commit branch and presents it as the whole
    change.
    Filter to auditable extensions (.tsx .jsx .ts .js .vue .svelte .astro .css .scss .less .html .mdx).
  - a path argument → scope to that path
  - otherwise → repo root

  STRICTNESS:
  - `--strict` → warnings are treated as blocking
  - `--changed` without `--strict` → warnings blocking on changed files only
    (this is the rollout order from `references/enforcement.md`: new code clean
    first, existing drift paid down after)
  - full-repo without `--strict` → warnings are advisory

  If $ARGUMENTS is empty, default to: validate, whole repo, advisory warnings.
  Announce the resolved mode/scope in one line before proceeding.
</step>

<step number="2" name="Preflight">
  Confirm this is a frontend project before auditing. Check for any of:
  `package.json` with react/vue/svelte/astro/next/nuxt, any `.tsx|.jsx|.vue|.svelte`
  file, or a `tailwind.config.*` / `@theme` block.

  If none are present, STOP and report: "No frontend code detected in {path} —
  the design-system guardrails don't apply here." Do not audit further.

  Locate the audit script:
  ```bash
  SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/frontend/design-system-guardrails/scripts/audit-ui.ts"
  ```
  Check `bun --version`. If bun is missing, tell the user
  (`curl -fsSL https://bun.sh/install | bash`) and continue with the manual
  checks in step 4 only — do not silently skip the audit.
</step>

<step number="3" name="Static audit">
  Run the bundled auditor and parse its JSON:
  ```bash
  bun "$SCRIPT" <scope-paths> --json
  ```
  Useful flags — apply them when the project's conventions call for it, and say so:
  - `--lib <path>` when the component library is not `components/ui`, `design-system`, or `packages/ui`
  - `--layout-components A,B,C` for project-specific layout primitives beyond the built-in set
  - `--allow <glob>` for extra token/theme files where raw values are correct
  - `--skip <check>` only with an explicit reason stated in the report

  The script is a heuristic — it flags for review, it does not prove correctness.
  Before reporting any finding, open the cited line and confirm it is real.
  Discard false positives rather than padding the report.
</step>