uxproof

Your repo's conventions, made executable.

Every team has a "how we do things here" that lives in seniors' heads. AI agents don't know it, so AI-generated code always reads like a transplant: right framework, wrong house. uxproof extracts those conventions into a committed contract and installs agent skills that create, audit and review code against it.

npx uxproof init

What init does

1. Scans the repo — framework, styling system, design tokens (CSS custom properties), component registry (exported components from your component directories), libraries in use (forms, validation, tables, icons).
2. Writes the contract to .uxproof/:
   • contract.json — the machine-readable summary
   • tokens.json / components.json — the full registries
   • conventions.md — the human-readable house rules, with a manual section for the judgment calls only your team can know. The manual section survives regeneration.
3. Installs skills for coding agents into the project skill directory:
   • uxproof-create — build new UI the way this repo builds it: registry components, tokens, existing screens as models
   • uxproof-audit — check code against the contract and fix violations
   • uxproof-review — evidence-first UX review: every recommendation carries evidence, pattern, trade-off and an acceptance criterion

Commit the lot. The contract is versioned, reviewable and argued about in PRs — like code, because now it is code.

Commands

Command	What it does
uxproof init	Scan, write contract, install skills
uxproof audit	Check source files against the contract (exit 1 on findings — CI-friendly)
uxproof audit --fix	Replace hardcoded colors with the nearest token (perceptual distance in Oklab; semantic aliases win ties; distant colors are reported, never guessed)
uxproof sync	Re-scan and regenerate the contract; manual rules survive
uxproof sync --check	Report drift only, exit 1 if the contract is stale (CI-friendly)
uxproof gallery	Generate .uxproof/gallery.html — a self-contained page with color swatches (click to copy), token tables, the component inventory and screen shapes

Screen shapes

init also classifies the repo's pages into archetypes — list, detail, form, settings, dashboard — and records the canonical examples in conventions.md. A new screen starts from "model it on this file", not from a blank page.

Audit rules (MVP)

• no-hardcoded-colors — raw hex/rgb in component code when the repo defines color tokens
• prefer-house-component — raw <button>/<input>/<select>/<table>/<dialog> when the registry has a house equivalent (registry component files themselves are exempt — wrapping raw elements is their job)

Every finding carries an evidence tag. These rules are [PRODUCT]: grounded in the repo's own contract, not in opinion.

Requirements

Node 20+. React repos (Next.js, Vite, CRA). Zero runtime dependencies.