// Consult this skill automatically when writing or reviewing UI code. Provides 28 principle-based UX heuristic rules organized by category. Assessed by the frontend review agent. Triggers: UX review, heuristics check, UI quality, layout review, accessibility check.
| name | ux-heuristics |
| version | 1.0.0 |
| description | Consult this skill automatically when writing or reviewing UI code. Provides 28 principle-based UX heuristic rules organized by category. Assessed by the frontend review agent. Triggers: UX review, heuristics check, UI quality, layout review, accessibility check. |
| argument-hint | <file-or-pattern> |
28 principle-based rules for evaluating UI quality. Assessed by the frontend review agent during UX reviews.
| Tier | Location | Contents |
|---|---|---|
| General | This file (03-patterns/ux-heuristics/SKILL.md) | Principle-based rules. No pixel values. Universal across projects. |
| Project-specific | .claude/ui-heuristics.md (populated by detect-project) | Concrete values (spacing scale, font sizes, breakpoints, color tokens). Overrides and extends the general tier. |
Rules in this file are intentionally principle-based. Project-specific pixel values, token names, and breakpoints belong in the project tier.
| ID | Severity | Principle |
|---|---|---|
arch-01 | warning | Related items must be visually grouped. Grouping should reflect the user's mental model, not the data model. |
arch-02 | warning | Lists exceeding 8 items should be organized into named categories, tabs, or progressive disclosure. |
arch-03 | warning | Page should have clear visual hierarchy -- most important information is most prominent. |
| ID | Severity | Principle |
|---|---|---|
density-01 | warning | Spacing between related items should be noticeably less than spacing between unrelated groups. |
density-02 | info | Data-dense views should minimize decorative whitespace without sacrificing readability. |
density-03 | info | Content-heavy views should maximize reading comfort -- narrower line width, more vertical spacing. |
| ID | Severity | Principle |
|---|---|---|
a11y-01 | critical | All interactive elements must have a visible focus indicator meeting WCAG 2.1 AA. |
a11y-02 | critical | Text contrast must meet WCAG 2.1 AA: >=4.5:1 normal text, >=3:1 large text/UI components. |
a11y-03 | critical | Information must not be conveyed by color alone -- pair with icon, text, pattern, or position. |
a11y-04 | warning | Every form input must have a visible, associated label. Placeholder is not a label. |
a11y-05 | critical | Modals and sheets must trap focus and be dismissible via Escape. |
a11y-06 | warning | Page must have logical heading hierarchy (h1 -> h2 -> h3, no skips). |
| ID | Severity | Principle |
|---|---|---|
overflow-01 | critical | Page must not horizontal-scroll at its target viewport width. |
overflow-02 | warning | Unbounded content (lists, tables, text) must have truncation, pagination, or virtualization. |
overflow-03 | info | Long text must truncate with mechanism to see full text (tooltip, expand, detail view). |
| ID | Severity | Principle |
|---|---|---|
empty-01 | warning | Zero-data must show descriptive message explaining what would appear and how to add data. |
empty-02 | warning | Loading must provide visual feedback. Prefer skeleton/shimmer over spinners for content areas. |
empty-03 | warning | Errors must show clear message with actionable recovery path. |
| ID | Severity | Principle |
|---|---|---|
nav-01 | warning | Current location must be visually indicated in navigation. |
nav-02 | info | Primary views reachable within 2 clicks from any page. |
nav-03 | critical | Back button and browser history must work correctly. Client-side nav must update URL. |
| ID | Severity | Principle |
|---|---|---|
consistency-01 | warning | Similar elements must be styled consistently across the application. |
consistency-02 | warning | Interaction patterns must be predictable -- similar actions work the same way everywhere. |
| ID | Severity | Principle |
|---|---|---|
feedback-01 | warning | User actions must produce visible feedback within 100ms. |
feedback-02 | critical | Destructive actions must require confirmation. |
feedback-03 | info | Success states must be clearly communicated (not just absence of error). |
| ID | Severity | Principle |
|---|---|---|
forms-01 | warning | Validation errors must appear near the relevant field, not just form top. |
forms-02 | info | Required fields must be visually distinguished from optional. |
forms-03 | critical | Form submission must be possible via keyboard. |
| Level | Meaning | Examples |
|---|---|---|
| critical | Blocks functionality, violates WCAG A, crashes, data loss risk | Missing focus trap, no keyboard submit, broken back button, horizontal overflow, missing contrast, destructive action without confirmation |
| warning | Degrades usability, violates WCAG AA, misleading UI, poor info architecture | Missing labels, no empty state, inconsistent patterns, no loading feedback, poor grouping |
| info | Polish, best practice, WCAG AAA, minor inconsistency | Truncation UX, decorative spacing, success feedback, field distinction |
| Method | Rules | Notes |
|---|---|---|
| Programmatic (axe-core) | a11y-01 through a11y-06 | Checked via axe-core, confirmed by vision agent |
| Vision agent | All other rules | Programmatic agent provides supporting data (DOM structure, CSS values) |
file:line rule-id severity — description format.<!-- ux-ignore rule-id --> above the relevant JSX or // ux-ignore rule-id in the component..claude/ui-heuristics.md take precedence over general rules when both apply.web-design-guidelines, which fetches Vercel's web interface guidelines. This skill is the N2O-specific heuristics layer.Use when the user reports a bug or needs help investigating unexpected behavior. Triggers: found a bug, bug report, something's broken, this doesn't work, investigate this bug, be my debugging partner, help me debug, manual verification failed, why is this failing, unexpected behavior, regression. Investigates root cause and generates tasks — does NOT write fixes (use tdd-agent for that).
Use when the user wants to audit code quality across the repo. Triggers: code health, audit code quality, check code health, tech debt scan, find dead exports, check file lengths, find circular deps, test coverage gaps, code quality check. Spawns 6 parallel subagents to scan for issues and creates tech-debt tasks for findings. Can run standalone, or is invoked by tdd-agent (changed files) and pm-agent (full scan).
Use when the user wants to scan the codebase and fill in CLAUDE.md project context. Triggers: detect project, scan project, fill in CLAUDE, update project context, populate CLAUDE.md, scan codebase, what's in this project, set up project context. Run this after n2o init or whenever the project structure changes.
Multi-agent frontend review agent. Assesses UI quality using programmatic checks + LLM vision + interactive testing. Auto-fixes issues with deterministic merge rules. Triggers: frontend review, review UI, check my page, UX audit, accessibility check, visual review, review this component.
Use when the user wants to plan, scope, or break down work. Triggers: create spec, new feature spec, write spec, break down, decompose tasks, task breakdown, sprint planning, plan sprint, pm workflow, project management, planning agent, scope this feature, what should we build, let's plan, create tasks, load tasks, start a sprint. Use this for planning and orchestration — NOT for implementing code (use tdd-agent for implementation).
Consult this skill automatically when writing, reviewing, or refactoring React or Next.js code. Use as an ambient guide — check these patterns whenever creating components, data fetching hooks, server components, client components, or optimizing bundle size. Triggers: review my React code, check performance, optimize React, Next.js best practices, component performance, bundle optimization, react patterns, writing React components, refactoring React code.