product-ui-audit

Invoke the audit on a target path such as a feature folder under src/app or src/explorations. It runs seven independent dimension checks covering tokens, layout primitives, components, mindset, geometry, accessibility, and design principles, then produces a severity-triaged findings report.

product-ui-audit checks consumer UI code that uses the design system, such as app and feature code. design-system-audit checks the design system package itself, including spec, cva, and token source-of-truth drift. They have separate scopes and should not be substituted for each other.

It flags hardcoded hex, rgb, and hsl color values, shadcn compatibility aliases like bg-popover or text-muted-foreground, Tailwind default shadows such as shadow-sm, Tailwind v4 [--foo] shorthand that silently fails, and hardcoded pixel values where tokens exist.

P0 and P1 findings plus P2E engineering issues are fixed autonomously in per-dimension change sets, then verified with type checks and a re-run of the audit. Only P2H findings, which involve genuine product or UX tradeoffs, are escalated for a user decision.

Do not use it to audit the design system package itself, to validate business logic correctness, or as a replacement for final code review. It is a pre-review self-check focused on UI, design system consumption, and design principles.

Code-level checks can pass while the rendered UI still has contrast failures, overlapping overlays, or cross-OS scrollbar issues. The visual phase runs WCAG contrast checks, DOM geometry assertions, and screenshot review before stakeholder-visible work ships.