setup-react-rules - SKILL.md Agent Skill

name: setup-react-rules description: Enforce React/TS/security rules via PostToolUse hooks -- ban raw HTML, TS escape hatches, XSS vectors, barrel imports, missing passive listeners. Use when enforcing React patterns or component library standards.

Setup React Rules

Repo/code changes: run /deslop before commit, push, PR, or merge. PostToolUse hooks on Edit/Write (auto-skip component library dirs):

Enforced Rules

HTML/Components: ban raw HTML elements (use @/components/ui/), ban inline style={{}} (use Tailwind), ban icon inside AlertTitle (use icon prop), require handler on buttons (onClick/asChild/type="submit"/disabled)

TypeScript: ban as any, as Record<string,any>, @ts-ignore, @ts-expect-error

Security: ban dangerouslySetInnerHTML, eval(), new Function(), .innerHTML = (XSS/OWASP A03)

Performance: ban barrel imports (use direct paths), ban missing { passive: true } on scroll/touch/wheel, ban static import of heavy deps (chart.js/d3/three.js/pdf-lib -- use React.lazy())

Styling: ban raw hex/rgb in className (use design tokens), ban !important, ban outline: none (use focus-visible), ban visual overrides on registry components (use variant prop)

Motion craft: warn on transition-all, scale(0) entries, layout property animation, bounce loops, ease-in UI entries, and durations beyond the usual 300ms threshold. Prefer transform/opacity, specific transition properties, short ease-out feedback, reduced-motion coverage, and origin-aware popovers/drawers.

Navigation: ban onClick + navigate() (use <Button asChild><Link>), require aria-label on icon-only buttons

React Compiler: ban manual useMemo/useCallback/React.memo, ban class components

Protobuf: enforce create() wrapper for message spreads (v2)

Opt-in Rules

REACT_RULES_BAN_USEEFFECT=1: ban useEffect/useLayoutEffect/useInsertionEffect. Escape: // allow: useEffect [reason]
REACT_RULES_BAN_TYPE_ASSERTIONS=1: ban as X (allow as const). Force type guards/generics/schema validation.

Soft Guidance (Claude-enforced, not hooks)

Named useEffect functions describe purpose. No name without "and"? Split.
useSyncExternalStore for browser API subscriptions (navigator.onLine, matchMedia, scroll)
Form-level validate cross-field validation (react-hook-form v7.72+)

Functional Programming (Claude-enforced)

Pure render -- no side effects in component body
Immutable state -- spread/filter/map, never mutate
Derive don't sync -- useMemo not useState+useEffect
useReducer for 3+ interrelated useState
Extract data transforms to named pure functions
Discriminated unions for variant prop types
Generic <T> for reusable typed components

See REFERENCE.md for patterns + examples.

Steps

Copy scripts/react-rules-check.sh + scripts/fp-check.sh + scripts/tailwind-check.sh + scripts/_hook-lib.sh -> .claude/hooks/. chmod +x.
Add to PostToolUse (Edit|Write) in .claude/settings.json.
Optional: codex-compat for .codex/hooks.json.

Verify

Block raw HTML, as any, @ts-ignore in TSX
Auto-skip component library dirs
Opt-in rules work when env vars set