# Aesthetic Direction

Shared calibration layer for both tracks; make UI look human-designed, not AI-default.

## AI slop signals

AI slop is plausible defaults compounding without a shared reason, not one forbidden motif. Any item below can be the right call when it serves the product, audience, hierarchy, or state, and one of them is usually a choice. Three or more on one surface with no such reason is the threshold: that reads as assembled rather than designed, and is what a refinement pass exists to remove.

Two bullets are absolute regardless of count, because they misinform rather than merely underwhelm: invented proof, and product framing that shows something the product does not do.

- A fashionable font chosen for category signalling rather than the product's tone, including decorative monospace on developer tools.
- Purple, cyan, or sunset gradients, glow, blur, glass, grids, and noise used as atmosphere without a content or brand role.
- Repeated card grids, pill clusters, oversized numerals, numbered rails, giant wordmarks, and symmetric sections that flatten the real priority.
- Fake browser chrome, fabricated dashboards, empty split panels, generic device frames, and invented logo strips, testimonials, or statistics standing in for authentic product proof. Real, checkable proof is not this bullet.
- Decoration stacked on controls and content that still use unowned default shape, weight, hierarchy, and states.

## Philosophy

- Delete aggressively; clarity over decoration.
- Don't compete for attention you haven't earned.
- Structure should be felt, not seen.
- Prune extra icons, controls, and separators before styling what remains.
- Restraint plus hierarchy beats noise.
- Treat visual design as functional UX, not veneer: hierarchy, rhythm, contrast, alignment, and motion decide whether the task feels clear, fast, and reliable.
- A design system is an ingredient, not proof of quality. Compose its parts into a coherent experience and adjust the relationships when the default component stack feels generic or cluttered.
- Type, colour, radius, and interface language must agree on one personality for the product and audience. Four individually attractive choices can still make a collage.
- Reuse the project's token scales. A size, gap, radius, weight, colour, or elevation that cannot be traced to a scale is drift unless the exception has a concrete optical or functional reason.
- Upgrade the elements already required before adding another one. Own the button, field, link, and content hierarchy before reaching for a badge, icon tile, panel, or decorative layer.
- Every visible choice should have a reason: spacing, size, color, radius, shadow, alignment, and empty space. If a random point on the screen cannot be explained, simplify it or align it to a rule.

## Study references

- Study the annotated "Reference calibration" list in [SKILL.md](../SKILL.md) (Linear, Raycast, Things 3, OpenAI, ElevenLabs, Mintlify, Family, Zed) for what each is calibration for.

## Upgrade choices

- Icon sets: use the project's existing library. When none exists, pick one of Phosphor, Heroicons, or Tabler and use it exclusively; mixing sets is a slop tell.
- Typography: start with the project's existing type system. Use Typewolf, Fonts In Use, or commercial foundries when exploring a new direction.
- Animation study: animations.dev, devouringdetails.com.

## Polish details

- Match box-shadows to references.
- If a two-stop gradient should read as one surface, keep its hues close, roughly within 30 degrees. First prove the gradient has a job.
- Dark-mode aware SVG favicon.
- Intentional hover/active and loading/error/empty states.

## Reject these failures

- Generic SaaS card grid as the first impression.
- Beautiful image with weak brand presence.
- Strong headline with no clear action.
- Busy imagery behind text.
- Sections that repeat the same mood statement.
- Carousel with no narrative purpose.
- App UI made of stacked cards instead of layout.

# Brand Kit Prompt

## Contents

- [Purpose](#purpose)
- [Source Handling](#source-handling)
- [Attached Images](#attached-images)
- [Workflow](#workflow)
- [Canonical Board Spec](#canonical-board-spec)
- [Page Mockups](#page-mockups)
- [Design-System Rail](#design-system-rail)
- [Creative Direction](#creative-direction)
- [Final Prompt Structure](#final-prompt-structure)
- [Rendering](#rendering)
- [Rules](#rules)

## Purpose

Generate one production-ready image prompt for a fixed-structure 4K marketing-site brand case-study image. Output prompt text only; do not generate images.

Prioritize distinctive frontend art direction and production-grade public marketing-site mockups. Even for a web/desktop/mobile/SaaS product, the board shows that product's public marketing site, not an app-UI board or brand-system sheet: two real website surfaces plus a concise typography/color rail, not a cramped moodboard or component inventory.

Whitespace is non-negotiable across every mockup and section (stated once): generous margins, open rhythm, low-to-moderate density, calm, never cramped. Use scale, contrast, and composition for impact, not more modules.

## Source Handling

- Use only the user's inputs: concept, brief, notes, constraints, references, attached images, audience, tone, required pages, avoid-list.
- Thin but usable input: make careful creative inferences.
- Ask a question only when there is no usable brand, product, company, idea, or concept.
- Preserve user-supplied vocabulary, constraints, page requests, examples, references, attached-image inspiration, and avoid-list items.
- Output only the final prompt: no preamble, rationale, commentary, follow-up, or setup text.

## Attached Images

Inspect attached images and translate their visual qualities into prompt language. Inspiration only:

- Extract: aesthetic direction, composition, visual density, color atmosphere, type mood, spacing, texture, lighting, layout rhythm, interaction/presentation patterns.
- Do not copy or recreate their content, logos, wordmarks, marks, icons, mascots, characters, product names, readable text, photography subjects, proprietary UI, exact layouts, or distinctive artwork.
- Do not treat them as mandatory content unless the user says the image is their own brand asset and asks to use it.
- On conflict with the written concept, keep the concept; use images only for visual direction.
- When images are attached, add a short "Reference Image Use" note in the prompt: the style inspiration to borrow, plus an explicit statement that attached images are style references only, not content or logo sources.

## Workflow

1. Infer purpose, audience, positioning, product context, brand personality.
2. Choose one memorable aesthetic direction that fits the concept.
3. Choose the two public marketing-site pages (see Page Mockups). For an app/software product, choose pages that can naturally show product screenshots inside the marketing site.
4. If images are attached, summarize their reusable visual qualities per `Attached Images`.
5. Assemble one internally consistent prompt using `Final Prompt Structure`.

## Canonical Board Spec

The prompt must request this exact structure unless the user explicitly asks for a different one:

- Canvas: one single 3840 x 2160 px, 16:9 landscape, high-quality 4K image.
- Layout: three full-height vertical columns with clean gutters.
- Widths: page mockup 1 = 40%, page mockup 2 = 40%, design-system rail = 20% (ratio 2 : 2 : 1).
- Left = page mockup 1; middle = page mockup 2; right = design-system rail.
- The two mockups dominate as large, inspectable website pages; the rail is quieter but legible at full 4K.
- No extra panels, page thumbnails, floating device mockups, moodboard imagery, standalone logo explorations, component inventories, callout overlays, or decorative filler.
- No separate design-system board, two-board split, multiple images, unreadably tiny UI fragments, or dashboard/workspace/app UI board unless the user explicitly requests an interface-only board.

## Page Mockups

Two substantial public-facing marketing pages. Treat an app concept as a product needing a marketing site; product/app UI appears only as supporting content embedded inside a page. For any software product (web/desktop/mobile app, SaaS, marketplace, creator or productivity tool), embed at least one realistic screenshot or framed view that explains the product while the surrounding page stays the main subject.

Defaults (use the user's requested pages instead when given): mockup 1 = homepage; mockup 2 = a supporting page with a different content pattern (pricing, signup, product/service detail, collection/category, editorial, comparison, case study, lead-capture, checkout, search/results, commerce, dense typography, or screenshot-led feature explanation).

For each page, define:

- Page type and purpose; layout structure, hierarchy, key components, copy tone.
- Primary navigation with an appropriate logo/wordmark/mark (same mark across both pages); a strong hero and primary CTA on the homepage.
- Product screenshot or device-frame placement for a software product.
- Visible design behavior: grid/composition, type scale, navigation, CTAs, forms, cards, pricing tables, proof blocks, product tiles, filters, commerce or editorial modules.
- Distinctive frontend composition: asymmetry, overlap, strict grid, dense utility, editorial pacing, diagonal flow, immersive media, tactile/active/hover states, or scroll moments.

## Design-System Rail

Document only values hard to recover from the mockups without OCR.

Include:

- Typography: display/headline, body, and UI/label/numeric/mono typeface names or directions; brief hierarchy, casing, weight, tracking, or pairing notes only when useful.
- Color: dominant/core colors separated from supporting/accent; approximate hex-style values; short role labels (background, foreground, primary, surface, border, signal, accent, semantic, category).
- Color hierarchy: dominant/load-bearing colors as larger swatches or bars; supporting/accent/signal colors as smaller grouped chips.
- Rail text for full-4K readability: short labels, large enough type, clear spacing, no dense captions.

Do not include:

- Logo, wordmark, mark construction, lockups, logo notes, variations, or specs.
- Spacing scales, border radius, grid specs, motion notes, component inventories or states, icon notes, elevation/shadow specs, or arbitrary brand copy.
- Slogans, positioning paragraphs, mood words, or any text not directly documenting typography or color values used in the mockups.

## Creative Direction

Choose a bold but concept-appropriate aesthetic direction (brutally minimal, maximalist, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft, industrial, utilitarian, or another inferred from the brief).

Define:

- Purpose: what visitors should understand, trust, and do.
- Marketing focus: how the site introduces, explains, proves, and sells the brand.
- Tone: 3-5 strong adjectives, not a neutral default.
- Differentiation: the one visual, typographic, interaction, material, motif, or page-structure idea someone remembers.
- Constraints: production-grade, functional, accessible, plausible for a real frontend.
- Intensity: maximalist systems may be rich; refined systems rely on restraint, proportion, precision.

Avoid: the AI-slop signals from aesthetic-direction.md (default Inter/Roboto/Arial/system fonts, purple-blue gradients on white, generic glassmorphism, bland SaaS dashboards, default rounded cards), plus cramped or overfilled layouts and reusing the same trendy typefaces or color systems across concepts.

## Final Prompt Structure

Assemble the answer as the image prompt itself, in these eight sections. Pull each from the section named above; do not restate spec already defined there.

1. Brand Positioning (audience, the tone adjectives, comparables, avoid list).
2. Aesthetic Concept (`Creative Direction`).
3. Reference Image Use (only when images are attached; `Attached Images`).
4. Board Layout (`Canonical Board Spec`).
5. Page Mockups (`Page Mockups`, or the user's requested pages).
6. Design-System Rail (`Design-System Rail`).
7. Visual Style Constraints (the Creative Direction avoid list; the fixed layout holds even when the aesthetic is expressive).
8. Rendering line: one closing line: 3840 x 2160 px 16:9 4K, fixed 40 / 40 / 20 columns, crisp readable UI and rail text, production-grade marketing mockups, concept-specific art direction, generous whitespace, realistic polished design.

## Rendering

Rendering the final board needs the `imagegen` skill (Codex, gpt-image-2), passing attached images as style references when supported; generate exactly one 3840 x 2160 px 16:9 board, then return it with minimal commentary. In agents without `imagegen` (such as Claude Code), stop at the prompt and deliver the direction as text (typography, palette, mockup descriptions) plus the prompt for the user to render. Treat the prompt as intermediate working content: do not present it as the final answer unless asked, and do not over-summarize it so brand details are lost. If the user asks for the image plus the prompt, render the image first, then include the prompt text. If generation yields multiple boards or any shape other than the fixed structure, normalize to the fixed structure before rendering.

## Rules

- Be specific and concrete; keep internal consistency across all sections.
- Make the aesthetic direction memorable and concept-specific.
- Use specific typeface names or precise typeface directions and approximate color values.
- Specify which colors are dominant/load-bearing vs supporting/rare accents, and require that hierarchy to be visible.
- Keep all visible rail text short enough to render legibly.
- Do not hardcode examples from one concept into another.
- Do not ask for a separate design-system board or two images.
- Do not explain your reasoning.

# Conversion Fundamentals

Landing page conversion strategy. Load when building or auditing marketing pages.

## Table of contents

- [Persuasion principles](#persuasion-principles)
- [Social proof patterns](#social-proof-patterns)
- [Conversion benchmarks](#conversion-benchmarks)
- [Voice of Customer research](#voice-of-customer-research)
- [Page length decision](#page-length-decision)

---

## Persuasion principles

Cialdini's seven principles for landing pages. Each is a tool, not a trick; misuse destroys trust faster than it builds conversion.

| Principle | Landing page application | Misuse to avoid |
|-----------|--------------------------|-----------------|
| **Reciprocity** | Offer something free first (a tool, calculator, guide) before asking for commitment | Gating basic information behind a form; the "gift" must feel genuinely useful |
| **Commitment** | Start with a micro-yes (quiz, configurator, email-only form) before the full ask | Bait-and-switch: small ask hiding a large commitment |
| **Social proof** | Reviews, badges, user counts, testimonials near the CTA (see below) | Fake reviews or fabricated numbers; readers smell it instantly |
| **Authority** | Certifications, press logos, expert endorsements, "as seen in" strips | Citing authority without specifics: "trusted by thousands" proves nothing |
| **Liking** | Brand voice, customer-as-hero framing, relatable imagery | Over-familiarity or forced warmth that doesn't match the product |
| **Scarcity** | Limited-time offers, remaining seats, closing deadlines | Fake countdown timers that reset on refresh; permanent "last chance" banners |
| **Unity** | In-group language ("fellow founders"), shared identity framing | Exclusionary language that alienates adjacent audiences |

Urgency (a subset of scarcity) lifts conversion substantially when real, and destroys credibility when fabricated. For the figure and other CTA conversion stats, see the canonical "CTA statistics" table in `testing.md`.

---

## Social proof patterns

Pages with social proof convert 34% better. Not all proof is equal.

### Credibility hierarchy

Highest to lowest trust:

1. **Third-party review badges** (G2, Capterra, Trustpilot, Product Hunt): independently verified; highest credibility for B2B SaaS.
2. **Specific-outcome testimonials:** "Cut our reporting from 4 hours to 20 minutes." Named person, real photo, company.
3. **X/Twitter testimonials:** publicly verifiable. Underused but high-trust because anyone can check.
4. **Logo walls:** recognisable companies use the product. Less persuasive alone.
5. **User counts:** "Join 50,000+ teams." Effective at scale, meaningless below ~1,000.
6. **Vague praise:** "Great product, love it!" Almost never moves the needle.

### Placement rules

- **Near the CTA:** within one scroll of every conversion point.
- **Above the fold:** 3-5 logos or one credibility stat; don't delay trust signals. Every logo, number, and quote must be real and checkable. If the product has none yet, leave the slot empty or show the product working; a fabricated logo strip is the single most common AI tell on a landing page.
- **Adjacent to pricing:** testimonials matched to plan type reduce choice anxiety.
- **After objection sections:** proof answers "but does it actually work?"

### The specificity test

If a competitor could use the same testimonial unchanged, it's too generic. "Great tool" fails. "Reduced our deploy time from 45 minutes to 3" passes.

---

## Conversion benchmarks

Median conversion rates by industry and channel:

| Segment | Median | Top quartile |
|---------|--------|--------------|
| All industries | 6.6-8.1% | 10%+ |
| Financial services | 8.4% | 12%+ |
| Legal services | 7.4% | 11%+ |
| eCommerce | 4.3% | 8%+ |
| Healthcare | 3.0-4.2% | 8-10% |
| B2B SaaS (cold) | 1-3% | 5%+ |

| Traffic source | Average conversion |
|----------------|-------------------|
| Email campaigns | 19.3% |
| Webinar pages | 22.3% |
| Organic search | 4-6% |
| Paid search | ~1.2% |
| Paid social | 2-4% |

Directional benchmarks, not targets. 3% for a $50K ACV product is a different business than 3% for a free trial.

CRO tools report average ROI of 223%. AI-assisted A/B testing, common in mid-market, lifts median rates.

---

## Voice of Customer research

Copy-research methodology (mining reviews, tickets, and transcripts for the reader's exact words) is owned by the `copywriting` skill; it feeds the copywriting brief. Route VoC work there.

---

## Page length decision

Short-form and long-form pages serve different situations. Decide by the reader's needs, not preference.

### Decision matrix

| Price | Complexity | Awareness | Recommended length |
|-------|-----------|-----------|-------------------|
| Low | Simple | High (warm traffic) | Short: under 125 words. 15% higher conversion. |
| Low | Simple | Low (cold traffic) | Medium: establish context, then convert. |
| High | Complex | High | Medium-long: address objections, show proof. |
| High | Complex | Low | Long: full persuasion sequence. Crazy Egg saw 363% lift. |

### Short-form rules

- Under 125 words of body copy
- One screen on desktop, two on mobile
- Hero, one proof point, CTA, nothing else
- Best for: free resources, newsletter signups, known brands, warm referral traffic

### Long-form rules

- Each section answers a specific objection or builds specific confidence
- Sections that just "fill space" are friction, not persuasion
- Repeat the CTA after hero, after proof, and at bottom
- Best for: high-ticket products, complex services, cold traffic, solution-aware comparison shoppers

The Rule of One applies regardless of length: one reader, one offer, one promise, one CTA.

# Design in Code

Fast, low-fi planning before visual polish.

## Start low-fi

- Plan the layout with ASCII wireframes (Markdown or a comment block).
- Build structure first; make it usable before pretty.
- Use constraints early (grid, spacing, type scale).

## Copy what works

- Start from a gold-standard product; match layout, spacing, and hierarchy, then adapt to context.
- When refreshing a product, keep a live old/new toggle behind a feature flag to compare fast.
- Tune colour and token changes in the running product, then sync exact values to the design system.
- During polish ask: what should hold focus, which controls are louder than the task, which borders or icons can be removed with no loss of meaning.

## Tools (defaults)

- shadcn/ui + Tailwind tokens.
- Keep components boring and conventional for fast iteration.

# Marketing / Brand UI

Commit to a clear aesthetic point of view before writing code. Avoid generic AI aesthetics.

## Contents

- Working model
- Beautiful defaults
- Landing page default sequence (Hero rules, Viewport budget)
- Imagery
- Copy
- UX baseline
- Aesthetic rules
- Motion
- Hard rules
- Litmus checks
- Conversion strategy

## Working model (before building)

Write three things before touching code:

- **Visual thesis**: one sentence on mood, material, and energy.
- **Content plan**: hero, support, detail, final CTA, with what each must communicate.
- **Interaction thesis**: 2-3 motion ideas that change the page's feel.

Each section gets one job, one dominant visual idea, one primary takeaway or action.

## Beautiful defaults

- Start with composition, not components.
- Prefer a full-bleed hero or full-canvas visual anchor.
- Make the brand or product name the loudest text.
- Keep copy scannable in seconds.
- Use whitespace, alignment, scale, cropping, and contrast before chrome.
- Two typefaces max, one accent color by default.
- Default to cardless layouts: sections, columns, dividers, lists, media blocks.
- Treat the first viewport as a poster, not a document.

## Landing page default sequence

1. **Hero**: brand or product, promise, CTA, one dominant visual.
2. **Support**: one concrete feature, offer, or proof point.
3. **Detail**: atmosphere, workflow, product depth, or story.
4. **Final CTA**: convert, start, visit, or contact.

### Hero rules

- One composition only. Full-bleed image or dominant visual plane.
- On branded pages the hero runs edge-to-edge: no inherited gutters, framed container, or shared max-width. Constrain only the inner text/action column.
- Brand first, headline second, body third, CTA fourth.
- No hero cards, stat strips, logo clouds, pill soup, or floating dashboards by default.
- Headlines roughly 2-3 lines on desktop, readable in one glance on mobile.
- Keep the text column narrow, anchored to a calm area of the image.
- All text over imagery: strong contrast, clear tap targets.

If the first viewport still works without the image, the image is too weak. If the brand disappears with the nav hidden, the hierarchy is too weak.

### Viewport budget

- A sticky/fixed header counts against the hero; header + hero content must fit the initial viewport.
- For `100vh`/`100svh` heroes, subtract persistent chrome (`calc(100svh - header-height)`) or overlay the header instead of stacking it.

## Imagery

Imagery must do narrative work.

- Use at least one strong, real-looking image for brands, venues, editorial pages, lifestyle products.
- Prefer in-situ photography over abstract gradients or fake 3D objects.
- Choose or crop images with a stable tonal area for text.
- No embedded signage, logos, or typographic clutter fighting the UI.
- No images with built-in UI frames, splits, cards, or panels.
- For multiple moments, use multiple images, not one collage.

## Copy

- Write in product language, not design commentary.
- Let the headline carry the meaning.
- Supporting copy is usually one short sentence.
- Cut repetition between sections.
- No prompt language or design commentary in the UI.
- Each section has one job: explain, prove, deepen, or convert.

If deleting 30 percent of the copy improves the page, keep deleting.

## UX baseline (non-negotiable)

- Full keyboard support and visible focus.
- Hit targets meet the touch-target size in [guidelines/buttons.md](../guidelines/buttons.md). 24x24px is the floor only for dense desktop UI under `pointer: fine` (WCAG 2.5.8).
- Accessible forms (labels, enter-to-submit, inline errors).
- Handle loading/empty/error states and long content.

## Aesthetic rules

- Typography: distinctive fonts (not Inter/Roboto/Arial/system). Weight >= 400. Use `clamp()`. This is a hard rule on the marketing track specifically, where the type is the brand; product surfaces follow [aesthetic-direction.md](aesthetic-direction.md) instead.
- Colour: commit to a palette via CSS variables; avoid pure black/white; one sharp accent.
- Composition: intentional asymmetry, contrast, and negative space.
- Backgrounds: give the canvas a material via tint, texture, imagery, or a gradient whose stops sit within roughly 30 degrees of hue. Never a purple or cyan wash on white, and never a flat default fill you did not choose.
- Interaction: set `pointer-events: none` on decorative layers; allow text selection by default.

## Motion

- Ship 2-3 intentional motions: a hero entrance sequence, one scroll-linked or depth effect, one hover/reveal/layout transition. Fewer is fine when the page has nothing to reveal; more is furniture.
- Follow `ui-animation` for timing, easing, implementation, and review.

## Hard rules

- No cards by default.
- No boxed or center-column hero when the brief calls for full bleed.
- No more than one dominant idea per section.
- No headline overpowering the brand on branded pages.
- No filler copy.
- No split-screen hero unless text sits on a calm, unified side.
- No more than two typefaces without a clear reason.
- No more than one accent color unless the product already has a strong system.

## Litmus checks

- Is the brand or product unmistakable in the first screen?
- Is there one strong visual anchor?
- Can the page be understood by scanning headlines only?
- Does each section have one job?
- Are cards actually necessary?
- Does motion improve hierarchy or atmosphere?
- Would the design still feel premium with all decorative shadows removed?

## Conversion strategy

For conversion-goal pages, load [cro.md](cro.md) (persuasion, social proof, benchmarks, page length), [testing.md](testing.md) (experiment planning), and [modern.md](modern.md) (mobile, speed, personalisation, microcopy). Below are the track-level layout decisions; the references cover the psychology and the numbers.

### Conversion-aware layout

- **One CTA, repeated.** Primary CTA appears after hero, after proof, and at bottom. No competing actions. Drop the middle placement on pages under two scrolls; do not add CTA blocks as furniture beyond these three.
- **Strip navigation** on landing pages. Every link that isn't the CTA is a leak.
- **Every section must earn its place.** Each builds confidence, handles an objection, or drives toward the CTA. Sections that just describe the company are furniture; cut them.
- **Message match.** The hero headline must echo the promise that brought the reader (ad, email, referral). If the ad said "Cut your AWS bill in half" and the page opens with "Welcome to CloudSave", the reader bounces.
- **Proof near every conversion point:** within one scroll of each CTA, with 3-5 logos or one credibility stat above the fold. Use real, checkable proof only. If none exists, show authentic product behavior rather than inventing a logo strip, statistic, testimonial, or framed dashboard, and leave the slot empty rather than filling it. Placement and the proof credibility hierarchy are in [cro.md](cro.md).
- **Mobile is a separate design**, not a reflow: sticky above-the-fold CTA, proof within two scroll-lengths, single-column 16px+ forms. Full rules in [modern.md](modern.md).

# Modern Conversion Techniques

Personalisation and mobile-first conversion. Load alongside `cro.md` when building or auditing marketing pages. Page speed, accessible copy, and microcopy are covered here only as pointers to their owning skills (`seo`, `copywriting`, `ui-design`/`typography-audit`).

## Table of contents

- [AI personalisation](#ai-personalisation)
- [Mobile-first conversion](#mobile-first-conversion)
- [Owned elsewhere](#owned-elsewhere)

---

## AI personalisation

Non-personalised B2B landing pages convert at 1-3%. Personalised pages lift conversion by 25-40%, and the gap is widening: personalisation is becoming table stakes, not a competitive advantage.

### What to personalise

| Element | Personalisation source | Example |
|---------|------------------------|---------|
| Headline | UTM campaign or referral source | Ad: "Cut your AWS bill" → headline: "Cut your AWS bill in half" |
| CTA | Awareness stage | First visit: "See how it works" / Return visit: "Start your free trial" |
| Hero image | Industry or persona | Dashboard for SaaS buyers, storefront for ecommerce |
| Social proof | Visitor segment | Testimonials from the visitor's industry |
| Pricing emphasis | Company size (firmographic) | Highlight the best-fit plan |

### Data sources

- **UTM parameters:** campaign, source, medium, content
- **IP-based firmographics:** company size, industry, location (Clearbit, 6sense)
- **Behavioural:** returning visitor, pages viewed, time on site
- **Cookie/session data:** previous interactions, abandoned forms

### The risk spectrum

- **Under-personalisation:** wastes the infrastructure. Dynamic content that shows everyone the same thing.
- **Over-personalisation:** creepy. "Hi Sarah from Acme Corp, we noticed you visited our pricing page three times" crosses the line.
- **Sweet spot:** adapt to the visitor's context without revealing how much you know.

### Common mistakes

- **Personalising before the baseline page converts.** Fix fundamentals first. Personalisation amplifies a working page, not a broken one.
- **Too many segments, too little traffic.** Each needs enough visitors to validate. Start with 2-3, not 20.

---

## Mobile-first conversion

62% of ecommerce traffic is mobile. Design mobile-first, then enhance for desktop.

### Layout rules

- **Single-column layout.** No side-by-side comparisons forcing horizontal scroll.
- **Tap targets.** Apple's floor is 44px and Google recommends 48px; this skill ships 48, per [guidelines/buttons.md](../guidelines/buttons.md). Smaller frustrates thumb navigation.
- **Thumb-zone CTA placement.** Primary actions in the bottom-centre, reachable without stretching.
- **Sticky CTA.** Keep the primary CTA visible as the user scrolls. A fixed bottom bar or floating button keeps the action one tap away.

### The 70% rule

70% of mobile users don't scroll to mid-page. This changes section ordering:

- CTA must appear above the fold on mobile.
- Social proof must appear within the first two scroll-lengths.
- Problem/pain sections that work on desktop may need shortening or reordering for mobile.
- Test mobile and desktop layouts independently; what converts on desktop may fail on mobile.

### Forms

- **Fewer fields.** Every field removed cuts friction. Test 3-field vs 5-field.
- **Larger inputs.** Font size ≥ 16px prevents iOS zoom-on-focus.
- **`inputmode` attributes.** Use `inputmode="email"`, `inputmode="tel"`, `inputmode="numeric"` to show the right keyboard.
- **Single-column forms only.** Never place fields side-by-side on mobile.

---

## Owned elsewhere

Three conversion levers belong to sibling skills; name the lever, then route the work.

- **Page speed.** Pages under 1 second convert roughly 3x better than 5+ seconds, so mobile speed is a conversion decision. Core Web Vitals (LCP/INP/CLS), `font-display`, WebP/AVIF, and third-party script budgets: route to `seo`.
- **Accessible copy.** Descriptive link and CTA text and plain-language reading level: route to `copywriting`. The a11y checks (WCAG link purpose, heading hierarchy, contrast): route to `ui-design` or `typography-audit`.
- **Microcopy.** Button labels, form help text, privacy reassurance, error messages: route to `copywriting`.

# Product UI (SaaS/Admin/Data-heavy)

For dashboards, admin tools, and data-dense workflows.

## Contents

- Commit to a direction
- Core craft rules
- Calm dense interfaces
- Controls
- Type and data
- Colour and contrast
- Navigation context
- Motion
- Utility copy
- Anti-patterns
- Litmus checks

## Commit to a direction

- Define context, user type, emotional goal.
- Pick a personality: precision/density, warm/approachable, trust/financial, bold/modern, utility/dev, data/analytics.
- Pick a colour foundation (warm/cool/neutral/tinted), light or dark, one accent.
- Pick a layout: dense grid, spacious, sidebar, top nav, or split list-detail.
- Match typography to the product (system, geometric sans, humanist, mono).

## Core craft rules

- 4px spacing grid.
- Keep padding symmetrical unless there's a clear visual reason.
- Use one radius system everywhere.
- **Concentric border radius:** `outer-radius = inner-radius + padding`. Mismatched radii on nested elements (a card around an inner component, a button around an icon badge) are the most common unnoticed visual error in production UIs.
- Choose one depth strategy: borders-only, subtle shadow, layered shadow, or surface tint. On non-white backgrounds, prefer `box-shadow` over `border`: rgba transparency adapts to any surface; solid colors don't.
- **Layered shadow formula** for cards, inputs, and containers:
  ```css
  box-shadow:
    0 0 0 1px rgba(0, 0, 0, 0.06),
    0 1px 2px -1px rgba(0, 0, 0, 0.06),
    0 2px 4px 0 rgba(0, 0, 0, 0.04);
  ```
  Hover: increase each opacity by `0.02`; transition `box-shadow 200ms ease`. In dark mode drop the lift and ambient layers and keep only the ring (`dark:shadow-none dark:inset-ring dark:inset-ring-white/5`, as in the dark-mode guideline): depth layers are invisible on dark surfaces.
- **Image outlines:** add a 1px inset outline for depth. Use `outline` (not `border`) so layout dimensions are unaffected:
  ```css
  img {
    outline: 1px solid rgba(0, 0, 0, 0.1);
    outline-offset: -1px;
  }
  .dark img { outline-color: rgba(255, 255, 255, 0.1); }
  ```
- Keep surface treatment consistent across cards, even when internal layouts differ.

## Calm dense interfaces

Default to Linear-style restraint: calm hierarchy, strong typography and spacing, few colors, dense but readable, minimal chrome. Cards only when the card is the interaction.

- Make the work surface dominant; navigation and orientation chrome recede after the user arrives.
- Separate location/context, view controls, and page actions so each bar has one job.
- Keep shared header actions in predictable slots across comparable views.
- Use compact tabs and secondary bars; avoid full-width chrome when a smaller group conveys the same state.
- Reduce brightness, saturation, and icon size on supporting chrome before shrinking the content area.
- Audit every border, icon, and tint; if it doesn't clarify meaning, remove or soften it.
- If a panel works as plain layout, drop the card treatment.

## Controls

- Default to native selects/date inputs for accessibility and mobile UX.
- Use custom controls only when product requirements justify the complexity.
- Preserve keyboard navigation, semantics, and screen-reader support in any custom control.
- For select triggers, use `inline-flex` + `white-space: nowrap`.

## Type and data

- Clear hierarchy (headline, body, label).
- Tabular numbers or monospace for data tables and IDs.
- Icons must add meaning; remove decorative icons and unnecessary icon backgrounds.
- Sentence case; follow the project locale/style guide.

## Colour and contrast

- 4-level contrast hierarchy (primary, secondary, muted, faint).
- Colour only for meaning (status, action).
- Restrained neutrals for core surfaces; keep warm/cool bias subtle.

## Navigation context

- Show navigation, page location, and user/workspace context.
- Keep supporting bars and inactive nav a step quieter than the main surface.
- In dark mode, keep only the ring layer of the shadow formula; adjust semantic colours.

## Motion

- Keep motion subtle and functional.
- Follow `ui-animation` guidelines.

## Utility copy

On dashboards, app surfaces, admin tools, or operational workspaces, default to utility copy over marketing copy.

- Prioritize orientation, status, and action over promise, mood, or brand voice.
- Start with the working surface: KPIs, charts, filters, tables, status, or task context. No hero section unless explicitly requested.
- Section headings should say what the area is or what the user can do there (e.g. "Selected KPIs", "Plan status", "Search metrics", "Last sync").
- Avoid aspirational hero lines, metaphors, or campaign language on product surfaces.
- Supporting text explains scope, behavior, freshness, or decision value in one sentence.
- If a sentence could be a homepage hero or ad, rewrite it to sound like product UI.

## Anti-patterns

- Heavy shadows, glowing or thick borders on routine controls: everything shouts, so nothing reads as primary.
- Large radii on small controls: buttons and inputs look toy-like next to dense data.
- Dashboard-card mosaics as the primary layout: a wall of boxes where hierarchy comes from the grid, not the data.
- Decorative gradients behind routine product UI: they cut text contrast and read as marketing on a work surface.
- Multiple competing accent colors: status colours stop carrying meaning when accents are everywhere.
- Ornamental icons and icon backgrounds: each costs a fixation without aiding scanning.
- Excessive spacing on data-dense surfaces: operators scroll instead of scan.
- Stacked cards instead of plain layout when the card boundary adds no meaning.

## Litmus checks

- Is the work surface louder than its navigation and chrome?
- Does every border, icon, and tint clarify meaning? Is everything else removed?
- Is colour reserved for status and action?
- Do nested elements follow the concentric radius rule (outer = inner + padding)?
- Can an operator scanning only headings, labels, and numbers understand the page?

# Testing and Optimisation

Reference for A/B testing, heatmap analysis, and conversion optimisation loops. Load when optimising an existing landing page or planning a testing strategy.

## The CRO loop

Measure → Hypothesise → Test → Implement → Repeat. Most teams optimise ad-hoc; only 39.6% have a documented CRO strategy. Structure the loop instead:

1. **Measure:** find the weakest conversion point via analytics (bounce rate, scroll depth, click maps)
2. **Hypothesise:** state what's wrong and why, with a predicted outcome
3. **Test:** run an A/B test with one variable changed
4. **Implement:** ship the winner
5. **Repeat:** move to the next weakest point

## What to test first

Prioritised by typical impact on conversion rate. Test high-leverage elements first; don't optimise button colour when the headline doesn't match the ad.

| Priority | Element | Why it matters |
|----------|---------|----------------|
| 1 | **Headline** | First thing read; determines whether the rest gets read |
| 2 | **CTA text** | Personalised CTAs convert 202% better than generic |
| 3 | **Hero image/video** | Sets emotional tone; context-of-use images outperform stock |
| 4 | **Social proof placement** | Moving proof above the fold or near the CTA shifts conversion significantly |
| 5 | **Form length** | Every field removed reduces friction; test 3-field vs 5-field |
| 6 | **Page length** | Short vs long; see `cro.md` for the decision matrix |
| 7 | **CTA colour/size** | Lower-leverage but easy to test; button size change can yield +90% |

## A/B vs multivariate

| Method | When to use | Traffic requirement |
|--------|-------------|---------------------|
| **A/B testing** | Most landing page optimisation. One variable per test, clean isolation: you know exactly why one version won. | Moderate (hundreds to low thousands of conversions) |
| **Multivariate** | Combinations of multiple elements at once. Powerful but needs massive traffic to isolate which combination caused the lift. | Very high (thousands of conversions per variant) |

**Default to A/B.** Multivariate is impractical for most landing pages unless you run tens of thousands of visitors per week.

## Statistical significance

- **Run until significant, not until the result looks good.** +20% after 50 visitors is noise, not signal.
- **Minimum sample** depends on baseline conversion rate and minimum detectable effect: use a sample size calculator before starting.
- **Duration:** at least one full business cycle (typically 1-2 weeks) to account for day-of-week variation.
- **Never stop a test early** because a variant is "clearly winning." Early results are unreliable. Pre-commit to a sample size and honour it.

## Heatmap and scroll map insights

Heatmaps and scroll maps show where attention actually goes, not where you assume.

### Key findings

- **Most mobile users don't scroll to mid-page** (see the "70% rule" in `modern.md`). Strongest proof or CTA below the mobile fold is never seen by most visitors.
- **Desktop scroll depth is deeper** but drops off sharply after the hero and first support section.
- **Dead clicks** reveal where users expect interactivity but find none: a missed CTA opportunity.

### What to do with scroll data

1. **Move your strongest message higher.** If attention clusters in the top 30%, put your best proof and CTA there.
2. **Create separate mobile and desktop strategies.** Mobile users scan faster and scroll less, so prioritise differently.
3. **Test section order.** Move testimonials above features, or features above the problem statement, and measure.
4. **Identify drop-off cliffs.** A section where 60% stop scrolling is boring or confusing: fix or remove it.

### Real example

Scroll maps showed 70% of a local service business's mobile users never reached the mid-page offer; moving it above the fold doubled conversions within one month.

## CTA statistics

Directional, not guaranteed; every audience is different. Test your own variants, starting with the highest-leverage changes.

| Change | Impact on conversion |
|--------|---------------------|
| Personalised CTA (vs generic) | +202% |
| Single CTA per page (vs multiple) | +266% |
| Adding urgency (real, limited-time) | +332% |
| Increasing button size | +90% CTR |
| Changing button colour | +21% |
| Mobile-optimised CTA | +32.5% |
| Inline CTA (vs sidebar) | +121% CTR |

{
  "skill_name": "ui-design",
  "evals": [
    {
      "id": 1,
      "prompt": "Improve the spacing of one existing settings panel. It has consistent tokens but no design-system.md.",
      "expected_output": "Inspect local token sources and make the targeted change without a full extraction project.",
      "files": [],
      "assertions": [
        "Uses existing tokens",
        "Does not require a new design-system artifact for one edit",
        "Verifies the affected rendered panel"
      ]
    },
    {
      "id": 2,
      "prompt": "Is this existing checkout ready to ship? Return a review only. A rendered-rule candidate needs browser evidence but no browser is connected.",
      "expected_output": "Return evidence-scoped findings with runtime checks unknown.",
      "files": [],
      "assertions": [
        "Leaves source unchanged",
        "Does not invent rendered results",
        "Does not redesign the checkout during audit",
        "Keeps unmeasured rendered candidates unknown, including in passed or rejected findings; does not infer two-dimensional touch-target size from minimum height alone."
      ]
    },
    {
      "id": 3,
      "prompt": "Audit this settings row: a disabled Invoice button wrapped in a hover Tooltip that says you need billing access. Report only.",
      "expected_output": "Flags a11y-disabled-control-tooltip; does not treat the hover hint as an accessible explanation.",
      "files": [],
      "assertions": [
        "Names a11y-disabled-control-tooltip",
        "Leaves source unchanged because the request is report-only",
        "Does not recommend pointer-events-none on the button as the fix"
      ]
    }
  ],
  "routing": {
    "should_trigger": [
      "Improve the spacing of one existing settings panel. It has consistent tokens but no design-system.md.",
      "Is this existing checkout ready to ship? Return a review only. A rendered-rule candidate needs browser evidence but no browser is connected.",
      "Audit this settings row: a disabled Invoice button wrapped in a hover Tooltip that says you need billing access. Report only."
    ],
    "near_miss": [
      {
        "prompt": "Prove this hit-target finding in the running browser.",
        "expected": "ui-verification"
      }
    ]
  }
}

[
  {
    "skills": [
      "ui-design"
    ],
    "query": "Is this invite form ready to ship? Tell me what's broken.",
    "files": [
      "fixtures/invite-member-form.tsx"
    ],
    "expected_behavior": [
      "Selects Audit mode, not Build or Direction: reports defects in the code as written instead of restyling or regenerating the form",
      "Reports file:line findings for the data loss (email and role cleared before the request resolves), the unguarded submit (no pending state, so the button double-fires), the unchecked res.ok with no rendered error state, and the icon-only close button with no accessible name",
      "Applies the fixes in the same pass rather than handing back a report alone",
      "Emits a ship verdict",
      "Does not propose a new palette, type scale, or layout: no visual direction work appears in the output"
    ]
  },
  {
    "skills": [
      "ui-design",
      "product-design"
    ],
    "query": "Two things on this modal. First, Delete should remove the whole project, not just the one version, and people should be able to undo it for 30 days. Second, the destructive button sits at the same visual weight as Cancel.",
    "files": [
      "fixtures/delete-version-modal.tsx"
    ],
    "expected_behavior": [
      "Splits the request instead of treating code-in-hand as a blanket route to ui-design",
      "Routes the first ask to product-design: it changes which object the action affects (version to project) and whether it is reversible, so it is a capability decision, not a visual one",
      "Runs product-design first and ui-design second, rather than editing the handler and the className in one pass",
      "Has product-design name the object, scope, and consequence, replacing the 'Confirm' label and the now-false 'cannot be undone' copy, and cites its rule IDs",
      "Routes the second ask to ui-design end to end: it changes how the same capability looks, not what it does",
      "product-design stops at decision altitude and does not write the line-level fix itself"
    ]
  },
  {
    "skills": [
      "ui-design",
      "typography-audit"
    ],
    "query": "Audit this pricing page before launch.",
    "files": [
      "fixtures/pricing-page.tsx"
    ],
    "expected_behavior": [
      "ui-design Audit mode owns the pass: a broad pre-launch audit is not handed wholesale to typography-audit",
      "Reports the non-type defects itself: the clickable div that is not a button and cannot be reached by keyboard, and the missing empty state when plans is empty",
      "Flags the type defects its own type- rule owns (13px body copy below the readable floor) and routes measure, leading, punctuation, and faux bold to typography-audit, which owns them, rather than opening a full type pass itself",
      "Routes the deep type work (the scale, the pairing, the measure) to typography-audit rather than duplicating its rule set",
      "Keeps a single ship verdict for the page instead of emitting two competing verdicts"
    ]
  },
  {
    "skills": [
      "ui-design",
      "ui-animation"
    ],
    "query": "Make this settings page feel native on mobile. Hover sticks after tap and pull-to-refresh reloads the page.",
    "files": [
      "fixtures/clean-settings.tsx"
    ],
    "expected_behavior": [
      "Selects Audit mode, not Retrofit/make-responsive and not Build",
      "Runs existing mobile-* rules (viewport, hover-only actions) and routes hover gating and :active press / touch-action: manipulation to ui-animation",
      "Does not invent a hover-stuck rule or a new skill",
      "Applies press feedback in the audited files; pull-to-refresh is craft-checklist overscroll, reported with file:line if the shell lives outside the fixture"
    ]
  }
]

[
  {
    "skills": [
      "ui-design"
    ],
    "query": "This feels AI-generated. Clean it up.",
    "files": [
      "fixtures/real-proof-landing.tsx"
    ],
    "expected_behavior": [
      "Selects Audit mode with the Deslop scope, and captures the rendered page at desktop and mobile before editing anything",
      "KEEPS the amber brand gradient: its stops sit within roughly 30 degrees, it gives the hero a focal point, and one wash is below the slop-decoration-no-role threshold of 3",
      "KEEPS all six customer logos: they are real named companies with real asset paths, which slop-unverifiable-proof explicitly excludes",
      "KEEPS the product screenshot at full size and straight on, and does not replace it with an illustration or a device mockup",
      "KEEPS the browser chrome bar: it sits directly above a real screenshot, which is the presentation-device carve-out slop-faux-product-chrome states, and the URL text corroborates only and cannot open a finding",
      "DELETES the three sourceless blur and grid layers, which put the file over the threshold of 3, and two of the three trailing CTA blocks",
      "Applies the fix ladder in order: deletes unsupported furniture before restyling anything that remains",
      "Reports slop-token-drift and slop-near-duplicate-scale as unknown, because no theme file is in scope",
      "Names what it considered and deliberately did not flag, with the guard for each"
    ]
  },
  {
    "skills": [
      "ui-design"
    ],
    "query": "Remove the AI slop from this.",
    "files": [
      "fixtures/clean-settings.tsx"
    ],
    "expected_behavior": [
      "Reports that there is little or nothing to remove, plainly, without padding the output to look useful",
      "Emits no slop findings: values trace to the Tailwind scale, there is one accent, there are no decorative layers, and no proof is invented",
      "Populates the considered-and-rejected section, naming the skeleton loader (a loading state, not an empty decorative panel) and the red revoke button (a semantic role, not an unearned accent)",
      "Does not manufacture a finding to justify the pass, and does not restyle a screen that already works",
      "Ends the report at the considered-and-rejected block: no closing line, sign-off, or promotional footer"
    ]
  },
  {
    "skills": [
      "ui-design"
    ],
    "query": "this looks vibe coded, fix it",
    "files": [
      "fixtures/real-proof-landing.tsx"
    ],
    "expected_behavior": [
      "Reaches the same conclusions as the first scenario from a query that names no defects, proving the detection is doing the work rather than the prompt",
      "Selects Audit mode with the Deslop scope from the phrase alone",
      "Still keeps the earned gradient, the real logos, the screenshot, and the chrome bar that holds it",
      "Still deletes the three stacked layers and the duplicate CTAs"
    ]
  }
]

# Assets API

Covers: placeholder marks, avatars, logos, screenshots, wallpapers, and concrete asset URL parameters.

## Contents

- [Marks](#marks)
- [Avatars](#avatars)
- [Logos](#logos)
- [Screenshots](#screenshots)
- [Wallpapers](#wallpapers)
- [Color Resolution](#color-resolution)

Base URL: `https://assets.ui.sh`

Prefer file extensions whenever the route supports them: `/marks/{id}.svg`, `/avatars/{id}.webp`, `/logos/{id}.svg`, `/screenshots/{id}.webp`, `/wallpapers/{type}.webp?variant={name}`. Image routes (avatars, screenshots, wallpapers) also accept `.jpg`, `.jpeg`, `.png`, but prefer `.webp`.

## Marks

`GET /marks/{id}` returns an SVG mark, optionally with text. IDs: `1`

| Param           | Type   | Default | Notes                                                                    |
| --------------- | ------ | ------: | ------------------------------------------------------------------------ |
| `text`          | string | none | Optional label text                                                      |
| `font`          | string | `inter` | `inter`, `dm-sans`, `sora`, `outfit`, `instrument-sans`, `space-grotesk` |
| `weight`        | number |   `600` | Font weight                                                              |
| `color`         | string | `black` | Mark color                                                               |
| `textColor`     | string | `color` | Text color                                                               |
| `letterSpacing` | number |    `-1` | Spacing between letters in pixels                                        |

## Avatars

`GET /avatars/{id}` returns an avatar image. IDs: `1`-`16`

| Param       | Type   | Default | Notes           |
| ----------- | ------ | ------: | --------------- |
| `size`      | number | none | Square resize   |
| `w`         | number | none | Width           |
| `h`         | number | none | Height          |
| `grayscale` | flag   |     off | Apply grayscale |

## Logos

`GET /logos/{id}` returns an SVG logo. IDs match fuzzily: case-insensitive, ignoring non-alphanumeric characters.

IDs: `align`, `artifact`, `axiom`, `concise`, `looply`, `orbital`, `pinelabs`, `quirk`, `relay`

| Param          | Type   | Default | Notes          |
| -------------- | ------ | ------: | -------------- |
| `color`        | string | none | Primary fill   |
| `accent-color` | string | `color` | Secondary fill |
| `height`       | string | none | SVG height     |
| `width`        | string | none | SVG width      |

## Screenshots

`GET /screenshots/{id}` returns a screenshot image. IDs: `1`

- `1` colors: `mauve`, `mist`, `olive`, `stone`, `taupe`

| Param    | Type   | Default | Notes            |
| -------- | ------ | ------: | ---------------- |
| `color`  | string | none | Variant name     |
| `top`    | number | none | Crop from top    |
| `bottom` | number | none | Crop from bottom |
| `left`   | number | none | Crop from left   |
| `right`  | number | none | Crop from right  |

Crop (positive integers only):

- `top`+`bottom`: height `top + bottom` from `y=0`
- `top` only / `bottom` only: crop that height from that edge
- `left`+`right`: width `left + right` from `x=0`
- `left` only / `right` only: crop that width from that edge

## Wallpapers

`GET /wallpapers/{type}` returns a wallpaper image.

| Param     | Type   |       Default | Notes        |
| --------- | ------ | ------------: | ------------ |
| `variant` | string | type-specific | Variant name |

Aliases: `landscape` -> `landscapes`

### `blend`

Default `arctic-glimmer`. Gradient flows (upper-left to lower-right):

- `arctic-glimmer`: slate/frosted mint to cerulean to deep navy/obsidian (cool)
- `emerald-mist`: forest green/moss to sage/lime to eucalyptus/silver-grey
- `golden-hour-mist`: champagne/cream to apricot glow to honey/sienna
- `midnight-nebula`: indigo/charcoal to violet haze to magenta to turquoise
- `nebula-glow`: rose/lilac to coral/peach to plum/cosmic indigo

### `haze`

Default `default`. All monochrome:

- `dark`: dark charcoal/grey
- `default`: warm off-white/cream
- `mauve-dark`: dark purple-grey
- `mauve`: purple-grey/lavender
- `mist-dark`: dark cool blue-grey
- `mist`: cool blue-grey
- `sage`: sage green/olive-grey
- `taupe-dark`: dark warm taupe
- `taupe`: warm taupe/grey

### `horizon`

Default `arctic-rim`. Format is background, highlights:

- `arctic-rim`: navy/cold-charcoal, cyan/frosted silver
- `calcite-dusk`: charcoal/slate, pearl/bone-white
- `celestial-lead`: lead-gray/charcoal, lilac/frosted zinc
- `jade-corner`: oceanic-gray/charcoal, jade/misty teal
- `obsidian-ember`: mahogany/umber, bronze/ash-gray
- `oxide-center`: graphite/charred-umber, rust/bronze
- `sepia-rim`: umber/warm-charcoal, gold/bronze

### `landscapes`

Default `valley`. Format is scene: palette:

- `arctic-fjord`: glacial fjord, granite cliffs, ice peaks: cerulean, indigo, frosted slate, bone white
- `basalt-plateau`: basalt plateau, volcanic ridges: ash grey, obsidian, pewter, umber
- `coast`: coastal beach, gentle waves: slate blue, teal, pale grey sky, sandy beige
- `dunes`: desert dunes at sunset: dusty rose, terracotta, mauve, peach sky
- `forest`: misty pine forest valley: sage green, cool grey, blue-green
- `fossil-cliffs`: chalk cliffs over pale sea: bone white, oyster grey, sea-foam green, flint blue
- `highland-moors`: highland moor, heather/moss: heather purple, moss green, peat brown, charcoal
- `hills`: pastoral hills, autumn trees: olive, ochre, burnt umber, taupe
- `lake`: lake at twilight, forested shore: slate blue, teal, peach
- `limestone-karst`: limestone pillars in misty bay: lichen green, grey stone, misty blue water
- `meadow`: alpine meadow, distant mountains: sage green, grey-blue mountains, hay
- `misty-marshland`: wetlands, pools, reeds: mossy green, bronze, water grey, foggy lavender
- `pampas-grassland`: pampas plains, open sky: straw, silver, lilac, grey-blue
- `salt-crust-expanse`: salt flats, distant mountains: pearl white, ivory, lilac shadow, silver-grey
- `snow`: snowfield, rolling dunes: off-white, blue-grey shadow, pale sky
- `valley`: misty mountain valley, scattered trees: sage green, soft grey, warm taupe
- `weathered-badlands`: eroded hills/canyons, strata lines: terracotta, clay, sandstone, ochre, charcoal

### `silk`

Default `crimson-surge`. Textures:

- `crimson-surge`: scarlet/ruby
- `cyan-glacier`: turquoise/crystalline
- `emerald-glint`: hunter green/iridescent teal
- `midnight-violet`: obsidian/translucent violet
- `molten-amber`: burnt orange/bronze
- `platinum-flow`: mercury/titanium
- `sapphire-flux`: royal blue/sapphire

## Color Resolution

Color params accept Tailwind names like `red-500` and `blue-600`, resolved to `oklch()`. Other CSS colors pass through unchanged.

# Avatars

Covers: profile photos, user thumbnails, testimonial people, comments, team members, overlapping groups.

- See [Assets API](./assets-api.md) for avatar URLs and query parameters
- Prefer extension-suffixed avatar URLs like `/avatars/1.webp`
- `outline-1 -outline-offset-1 outline-black/5` or `outline-black/10` on light surfaces; `outline-white/10` on dark surfaces
- Give stacked/overlapping groups a 2px `ring` matching the background (e.g. `ring-2 ring-white`)

# Badges

Covers: badges, tags, pills, labels, chips, status indicators, and compact metadata with icons.

- Badges with a leading/trailing icon: never use symmetric `px-*`; use `pl-*`/`pr-*` with the icon side's padding equal to the vertical padding: `py-1 pr-2 pl-1` (left icon), `py-1 pr-1 pl-2` (right icon)

# Border Radius

Covers: rounded cards, panels, buttons, images, screenshots, nested surfaces, any UI element where radius consistency matters.

- Use concentric radii on closely nested rounded elements: define the relationship with CSS variables and `calc()` so the math is enforced, e.g. `rounded-(--radius) p-(--padding)` on the outer element, `rounded-[calc(var(--radius)-var(--padding))]` on the inner. Past roughly 24px of padding, or when the inset is deliberately asymmetric, treat the layers as independent surfaces and keep each component's radius token instead of forcing the math.
- Use `min()` with viewport units for image/screenshot radii instead of fixed `rounded-*`: e.g. `rounded-[min(1vw,12px)]`; match the intended value at full desktop width and scale down proportionally as the screen shrinks.
- Keep one radius family per view: don't mix rounded and sharp corners on sibling elements; pick a small set of radii (controls, cards, fullscreen surfaces) and apply them consistently.
- Continuous corners (squircles) belong on app icons, avatars, and iOS-like tiles where a circular arc looks pinched at large sizes. Use `corner-shape: squircle` where supported, otherwise a superellipse mask. Nested cards, inputs, and buttons stay on CSS `border-radius` so concentric math still holds. Do not mix squircle and circular-arc siblings in one toolbar.

# Buttons

Covers: primary/secondary buttons, CTAs, icon buttons, destructive actions, form actions, touch targets.

## Design Rules

- Button shadows follow `shadows.md`: never pair `shadow-*` with solid gray borders; use `ring-1 ring-black/5` or `ring-1 ring-black/10` instead
- Primary buttons with a ring: never use reduced ring opacity; use a solid color matching the button background (e.g. `ring-indigo-600` on a `bg-indigo-600` button, not `ring-black/10`)
- Dangerous actions (e.g. "Delete") use a secondary/muted style by default: only use a primary style when the dangerous action is the page's or dialog's primary action (e.g. a confirm-delete dialog)
- Only one primary button per page: scan the whole page and ensure only one uses a filled/solid primary style; every other must use secondary, soft/muted (solid with opacity), outline, or ghost (text-only); treat dialogs/modals as their own page
- Never make a secondary button higher contrast than the primary: the primary must always be the most visually prominent
- Any button that is not the page's primary submit/save action is an inline form action (change avatar, change photo, upload file, generate password, verify email, add item, resend code, etc.): always use the smaller of the two button sizes and a secondary style; never the same height as the form's primary/submit button
- Choice buttons, presets, segmented controls, and toggle buttons need a persistent selected state. Hover is not selection: the selected state stays unmistakable once the pointer leaves. Use `aria-pressed` on a toggle button, `role="radio"` with `aria-checked` inside a `radiogroup` for a single-choice preset set, and `aria-selected` only on the roles that accept it (`option`, `tab`, `row`, `gridcell`, `treeitem`). `aria-selected` on a plain `<button>` is invalid.

### Sizing

- Less horizontal padding: `px-3 py-2` not `px-4 py-2`, `px-4 py-3` not `px-5 py-3`
- Application UIs (dashboards, settings, admin): `text-sm` with compact padding, never `text-base`; total rendered button height (including outer wrapper/ring) must stay within 28-38px; account for the `p-px` border wrapper (adds 2px total)
- Maximum 2 button sizes per application UI: pick two distinct heights and use only those; the difference must be at least 6px
- Buttons with a leading/trailing icon: never use symmetric `px-*`; use `pl-*`/`pr-*` and set the icon side's padding equal to the vertical padding: `py-2 pr-3 pl-2` (left icon), `py-2 pr-2 pl-3` (right icon), `py-1.5 pr-2.5 pl-1.5` (left icon, compact)

### Focus Styles

- Solid buttons need a custom focus ring: `focus-visible:outline-*` with `focus-visible:outline-offset-2`; default to `focus-visible:outline-blue-500` if the project has no established focus color

## Coding Rules

- Small/icon buttons ship at a 48x48px touch target: make the button `relative` and add `<span class="absolute top-1/2 left-1/2 size-[max(100%,3rem)] -translate-1/2 pointer-fine:hidden" aria-hidden="true" />` as a direct child. This file owns the 48px build default. It sits deliberately above the 44x44 WCAG 2.5.5 floor that `rules/interaction-target-size.md` audits to, so a later padding change cannot drop the control under conformance
- Interactive labels: apply `select-none` (or `user-select: none`) on button and control inner text so drag-select does not fight clicks. Do not disable selection on body copy or inputs.

# Colors

Covers: brand colors, accent colors, neutral palettes, text colors, default color families, semantic color scales.

- Never default to indigo as the brand/accent color: use it only if the project already does or the user requests it.
- Never default to `gray-*` or `slate-*` for neutral/text colors: use them only if the project already does or the user requests them; prefer `zinc-*` or `neutral-*`.
- Prefer near-black and near-white over pure `#000` and `#fff` for large surfaces and text-heavy UI. Pure extremes are reserved for deliberate contrast moments.
- When a palette has a clear warm or cool bias, tint neutrals slightly in the same direction. Do not mix warm-neutral backgrounds with cool-neutral foregrounds unless the brand system already does.
- On saturated fills, soften secondary text with a lighter tint of the fill hue or transparency rather than generic grey. Verify the resulting contrast in the rendered component.
- Give palette colors distinct brightness roles as well as different hues. Similar-brightness accents compete, especially in charts, badges, and status-heavy UIs.
- Increase contrast for primary tasks and important content; lower contrast for structural support like dividers, shadows, inactive chrome, and decorative marks.

## Semantic color scales

When defining a custom multi-step palette, give each step a role so component states are derivable, not hand-picked: steps encode intent, not just lightness. For a 10-step scale (scale the mapping to the project's actual step count):

- `100` background, `200` hover background, `300` active background
- `400` border, `500` hover border, `600` active border
- `700` solid fill (high contrast), `800` solid fill hover
- `900` secondary text and icons, `1000` primary text and icons

Derive states by stepping up the scale: fill `700`→`800` on hover; background `100`→`200` (hover), `300` (active); border `400`→`500`→`600`. Build the scale once; reference roles, never pick a new color per state.

Hold chroma as high as the gamut allows at each step rather than letting it fade toward neutral through the middle of the ramp, which is what makes a scale look chalky. Chroma has to fall away at the extremes because the gamut narrows there, so that is expected, not drift. When lightness alone leaves a difficult hue muddy, rotate the hue slightly as you step: toward yellow as the scale lightens, toward blue as it darkens, keeping the total shift within about 15 degrees end to end so the colour keeps its identity. Author the ramp in `oklch()` so equal lightness steps stay perceptually even across hues; HSL lightness is not perceptual.

# Copywriting

Covers: headings, taglines, subtitles, descriptions, labels, list items, button text, other UI copy.

- Headings: periods or none, but stay consistent within a page.
- Use proper ending punctuation on full sentences and paragraphs.
- Use a period on standalone descriptive text: taglines, subtitles, tier descriptions like "For professionals and growing teams.", single-line descriptions like "For organizations that need more power and control."
- Omit periods only on list items (e.g. feature bullets in pricing cards).
- Never use emojis anywhere: headings, descriptions, buttons, labels, or any text.

## UI microcopy

- Name actions verb + noun ("Delete member", "Deploy project"), never bare "Confirm", "OK", or a lone verb.
- Write errors as what happened + what to do next: "Build failed. Bundle exceeds 50 MB. Reduce it or raise the limit."
- Toasts name the specific thing changed, no trailing period, never say "successfully": "Project deleted", not "Successfully deleted the project."
- Empty states point to the first action: "No deployments yet. Push to your Git repository to create one."
- In-progress states use the present participle plus a real ellipsis character: "Deploying…", "Saving…", never three periods.
- Sentence case everywhere: labels, buttons, titles, tabs, body, helper text, and toasts. This matches `copywriting`, which owns final wording.

# Custom Fonts

Covers: loading custom fonts, registering font theme variables, applying display/body font utilities.

- Load custom fonts before using them: add `<link>` tags in the HTML `<head>` (preferred); if no `<head>` exists, use `@import url('…');` at the top of the CSS file instead.
- Register frequently used custom fonts in the CSS `@theme` block: e.g. `--font-display: "Oswald", sans-serif;`; optionally set `--font-display--font-feature-settings` and `--font-display--font-variation-settings` for fine-tuning.
- Register headline/display fonts as `--font-display` (creates a `font-display` utility): use `--font-sans` for body/UI fonts and `--font-display` for fonts used only on headings and display text; apply `font-display` on headings alongside `font-sans` on the body.

# Dark Mode

Covers: dark-mode styling, light-to-dark conversion, contrast audits, dark-mode images, dark-mode SVGs.

## Design Rules

- Dark mode maintains the same contrast ratios as light mode, not a simple color inversion
- Dark mode needn't preserve every detail of the light design: it just needs to look good
- Default dark mode to the OS `prefers-color-scheme` setting (Tailwind's built-in `dark:` behavior); add a manual toggle only when the user explicitly asks
- Remove all shadows in dark mode: use `dark:shadow-none`
- On dark-mode-only sites, add `scheme-only-dark` to `<html>` or the top-level element: ensures native elements (scrollbars, form controls, `color-scheme`) render in dark mode
- Optical compensation: light text on dark reads heavier than the same weight on light. Prefer the existing face at the same weight with `-webkit-font-smoothing: antialiased` (owned in typography-audit `font-rendering`) rather than dropping below 400. If a display line still looks overweight, tighten tracking slightly instead of inventing a lighter cut.

## Component Rules

- Never keep large branded/colored panels in dark mode; use the same background color and add a light divider between sections
- Style cards only slightly lighter than the page background (e.g. `dark:bg-gray-900` on a `dark:bg-gray-950` page); add `dark:inset-ring dark:inset-ring-white/5` for definition
- Make decorative testimonial quote marks very faint (e.g. `dark:text-white/5`)
- Never use multiple heading colors in dark mode (e.g. dark gray + brand); use one light color like `white` or `gray-100` for all headings

## Raster Image Rules

- When adding or improving dark mode, audit the page for rasterized images needing dark-mode versions: photos, screenshots, product mockups, decorative backgrounds, textures, rasterized illustrations
- Never use CSS filters (`invert`, `brightness`, `contrast`, `opacity`) as the final raster dark-mode treatment; always create real dark-mode image files
- Generate dark-mode raster variants by following [../dark-mode-image.md](../dark-mode-image.md), which requires the `imagegen` skill before creating or editing raster assets

## SVG Rules

- For inline `<svg>`, style dark mode with Tailwind `dark:*` classes (e.g. `dark:fill-*`, `dark:stroke-*`, `dark:text-*`)
- For external SVGs referenced via `<img>`, always create a dark version alongside the original (e.g. `logo.svg` and `logo-dark.svg`); never substitute CSS filters (`invert`, `brightness`) or opacity for a true dark variant

# Dashboards

Covers: layouts, stat grids, KPI cards, metric cards, admin panels, analytics views, summary data.

## Design Rules

- Never let stat/metric card titles wrap; use `truncate` to keep them on one line
- Never put icons in stat/metric cards: use plain text labels and values only

## Coding Rules

- Use container queries (not media queries) for responsive dashboard widgets

# Description Lists

Covers: `<dl>`, `<dt>`, and `<dd>` content, term/detail pairs, metadata groups, and definition-style lists.

- Style `<dt>` with higher-contrast text and slightly heavier weight (e.g. `font-medium`); style `<dd>` with regular weight and lower-contrast color, so links inside `<dd>` use the higher-contrast color to stand out

# Feature Lists

Covers: feature grids, benefit lists, product feature sections, and any section listing multiple features with titles and descriptions.

- Use `<dl>`/`<dt>`/`<dd>` for feature sections listing multiple features, not `<ul>`/`<li>` or plain `<div>` groups

# Flexbox Layout

Covers: flex containers, flexible children, fixed-size icons/images, truncation, sidebars, layouts using `flex-1`, `min-w-0`, or `shrink-0`.

- Add `min-w-0` (or `min-width: 0`) to flex children that must shrink below their content size: flex items default to `min-width: auto` and won't shrink past their content without it. Applies at every scale, from page-level layouts (a fluid content area next to a fixed-width sidebar using `flex-1`) down to small UI pieces (a truncated text label in a row, a flexible input next to a fixed button).
- Add `shrink-0` to flex children that should never shrink: icons, SVGs, images, logos, avatars, and any element that would become visually distorted if compressed.

# Font Recommendations

Covers: optional font suggestions, type-direction exploration, and font ideas for design variations.

Optional. Reference only when font selection is part of the task; never force them.

## Contents

- [General Guidelines](#general-guidelines)
- [By Purpose](#by-purpose)
- [Font Details](#font-details)

## General Guidelines

- Start with the project's existing body/UI face. When no type system exists, choose a restrained sans that fits the product and audience; Inter is one valid option, not an automatic default.
- Recommend sans-serif unless the user asks for serif, says "sophisticated" or "editorial", or the project calls for it (luxury brand, literary magazine, fashion editorial).

## By Purpose

Name lists only; see [Font Details](#font-details) for traits, sourcing, and registration.

### Body & UI

- Sans-serif: [DM Sans](#dm-sans), [Figtree](#figtree), [General Sans](#general-sans), [Geist](#geist), [Host Grotesk](#host-grotesk), [Inter](#inter), [Instrument Sans](#instrument-sans), [Mona Sans](#mona-sans), [Satoshi](#satoshi)
- Serif: [Lora](#lora)

### Headlines & Display

Most Body & UI fonts also head well; strongest display picks:

- Sans-serif: [DM Sans](#dm-sans), [Fixel Display](#fixel-display) (display only), [Geist](#geist), [Inter](#inter), [Mona Sans (wide)](#mona-sans) (headlines only), [Satoshi](#satoshi)
- Serif: [Instrument Serif](#instrument-serif)

### Monospace

For code, inline code, or a technical/developer aesthetic.

- [Geist Mono](#geist-mono), [IBM Plex Mono](#ibm-plex-mono)

---

## Font Details

### DM Sans

Low-contrast geometric, open apertures, large x-height. Single-storey `a`/`g`, straight-legged `R`. Excellent at small sizes; great body font paired with other headline fonts, also heads.

- **Source:** Google Fonts (`family=DM+Sans:opsz,wght@9..40,100..1000`)
- **Registration:** in `@theme`, `--font-sans: "DM Sans", sans-serif;`
- **Pairs with:** Inter, Geist

### Figtree

Friendly geometric; curved `t`/`f`/`y` add warmth without playfulness. Monolinear stroke. Headlines and body.

- **Source:** Google Fonts (`family=Figtree:wght@300..900`)
- **Registration:** in `@theme`, `--font-sans: "Figtree", sans-serif;`
- **Pairs with:** Inter, Geist, DM Sans

### Fixel Display

Geometric-humanist hybrid, open letterforms, wide proportions. Headlines and display only, never body.

- **Source:** self-host from `https://fixel.macpaw.com`
- **Registration:** in `@theme`, `--font-display: "Fixel Display", sans-serif;`
- **Pairs with:** Inter, Geist, DM Sans

### Geist

Swiss-inspired Vercel sans: minimal, precise, built for UI. Body, app UI, headings.

- **Source:** Google Fonts (`family=Geist:wght@100..900`)
- **Registration:** in `@theme`, `--font-sans: "Geist", sans-serif;`
- **Pairs with:** Inter, DM Sans

### Geist Mono

Vercel monospace. Code snippets, inline code, developer sites.

- **Source:** Google Fonts
- **Registration:** in `@theme`, `--font-mono: "Geist Mono", monospace;`

### IBM Plex Mono

IBM monospace: versatile, highly legible. Code, technical content, developer sites.

- **Source:** Google Fonts (`family=IBM+Plex+Mono:wght@400;500;600;700`)
- **Registration:** in `@theme`, `--font-mono: "IBM Plex Mono", monospace;`

### General Sans

Compact rationalist sans, small apertures, disciplined closed feel. Space-efficient for dense UI and tight layouts. Headlines and body.

- **Source:** Fontshare (`https://api.fontshare.com/v2/css?f[]=general-sans@200,300,400,500,600,700&display=swap`)
- **Registration:** in `@theme`, `--font-sans: "General Sans", sans-serif;`
- **Pairs with:** Inter, Geist, DM Sans

### Host Grotesk

Uniwidth sans: letter widths stay constant across weights, so weight changes never shift layout. Ideal for tabs, buttons, navigation, anywhere reflow must not happen. Headlines and body.

- **Source:** Google Fonts (`family=Host+Grotesk:wght@300..800`)
- **Registration:** in `@theme`, `--font-sans: "Host Grotesk", sans-serif;`
- **Pairs with:** Inter, Geist, DM Sans

### Instrument Sans

Geometric neo-grotesque from straight lines and simple circles. Uniform strokes, straight terminals, 12 stylistic sets for alternate glyphs. Clean technical interfaces. Headlines and body.

- **Weight restriction:** only supports `font-normal` (400): never use `font-medium`, `font-semibold`, or `font-bold`
- **Source:** Google Fonts (`family=Instrument+Sans:wght@400..700`)
- **Registration:** in `@theme`, `--font-sans: "Instrument Sans", sans-serif;`
- **Pairs with:** Inter, Geist, DM Sans

### Instrument Serif

High-contrast editorial serif for headlines and display. Premium editorial feel paired with a clean sans body; great for marketing sites, landing pages, brand-forward designs.

- **Sizing:** optically small: never use `text-4xl` or smaller for headings; use `text-5xl` and up where other fonts would use `text-4xl`
- **Source:** Google Fonts
- **Registration:** in `@theme`, `--font-display: "Instrument Serif", serif;`
- **Pairs with:** Inter, Geist, DM Sans

### Inter

Clean, highly legible screen sans. Body, app UI, headings.

- **Source:** `https://rsms.me/inter/inter.css` or self-host; never the Google Fonts version (lacks the Display optical-size variant and `font-feature-settings` support)
- **Optical sizing:** Display variant auto-activates at larger sizes via `font-optical-sizing: auto`; the Google Fonts build strips this out
- **Feature settings:** turn on optional OpenType features for a more custom feel: `cv02` (double-story `a`→single-story), `cv03` (open `6`/`9`), `cv04` (open `4`), `cv11` (single-story `l`), `ss01` (open digits), `ss03` (round quotes)
- **Registration:** in `@theme`, `--font-sans: "InterVariable", sans-serif;` with `--font-sans--font-feature-settings: "cv02", "cv03", "cv04", "cv11";` for global features
- **Pairs with:** Geist, DM Sans

### Lora

Contemporary serif with calligraphic roots. Moderate contrast, subtle brush-stroke terminals; refined yet readable at body sizes. Editorial, blogs, long-form; also heads.

- **Source:** Google Fonts (`family=Lora:wght@400..700`)
- **Registration:** in `@theme`, `--font-serif: "Lora", serif;`
- **Pairs with:** Inter, Geist, DM Sans, Satoshi

### Mona Sans

GitHub neo-grotesque with an optical-size axis that adjusts letterforms by size. Strong, industrial. Headlines and body.

- **Source:** Google Fonts (`family=Mona+Sans:wght@200..900`)
- **Width axis:** has a `wdth` variable axis: use a wider value (e.g. `"wdth" 112.5`) for headlines to give a bolder, more expanded feel; the wide variant is strictly for headlines, never for body copy
- **Registration:** in `@theme`, `--font-sans: "Mona Sans", sans-serif;`; for the wide headline variant also add `--font-display: "Mona Sans", sans-serif;` with `--font-display--font-variation-settings: "wdth" 112.5;`
- **Pairs with:** Inter, Geist, DM Sans

### Satoshi

Modernist sans blending rounded shapes with sharp angular details. Double-storey `a`/`g` add personality beyond typical geometrics; lean in for brand-forward designs. Headlines and body.

- **Source:** Fontshare (`https://api.fontshare.com/v2/css?f[]=satoshi@300,400,500,700,900&display=swap`)
- **Registration:** in `@theme`, `--font-sans: "Satoshi", sans-serif;`
- **Pairs with:** Inter, Geist, DM Sans

# Footers

Covers: page footers, footer logos, footer navigation, footer links, and social media icons.

## Design Rules

- Logo height between `h-5` and `h-7`
- Use `font-normal` for footer links
- Social icons at least `text-gray-600`: never `text-gray-400` or lighter

## Coding Rules

- Use the [placeholder content](./placeholder-content.md) logo endpoint when no logo file is provided; never build logos from HTML or icons

# Form Controls

Covers: inputs, selects, textareas, checkboxes, radio buttons, toggles, search bars, checkout forms, auth forms, and input/button combos.

## Contents

- [Design Rules](#design-rules)
- [Coding Rules](#coding-rules)
- [Selects](#selects)
- [Checkboxes](#checkboxes)
- [Radio Buttons](#radio-buttons)
- [Toggles](#toggles)

## Design Rules

- Never pair `shadow-*` with solid gray borders on any form control:

  Don't:

  ```html
  <... class="border border-gray-300 shadow-* ..." />
  ```

  ```html
  <... class="border border-gray-950/10 shadow-* ..." />
  ```

  Do:

  ```html
  <... class="ring-1 ring-black/10 shadow-* ..." />
  ```

- Use `max-w-xs` for compact, single-purpose forms (login, sign-up, single-field inputs); `max-w-sm` and wider is too spacious for focused UI.
- If a text input's font size is smaller than `16px`, add `max-sm:text-base/{lh}` to bump it to `16px` on mobile.
- Never use `outline-offset-*` on custom focus rings for `<input>`/`<textarea>`; use `outline-offset-0` or omit the offset entirely.
- With a 2px focus outline on `<input>`/`<textarea>`, inset it with `-outline-offset-1` so it doesn't extend outside the element.
- Never use the conjoined input + button pattern where they share a border: use a gap between them, or nest the button visually inside the input.

## Coding Rules

- Always include a `name` attribute on `<input>`, `<select>`, and `<textarea>`.
- Every `<input>`, `<select>`, and `<textarea>` must have a `<label>` associated via `id`/`for`, or an `aria-label`.
- Always set an explicit `type` on `<button>`: `type="submit"` inside forms, `type="button"` otherwise.
- For ecommerce/checkout forms where the field purpose is obvious from context, use `placeholder` with `aria-label` instead of visible `<label>` elements; still use section headings (e.g. "Shipping address", "Payment") to group related fields.
- Prefix/suffix icons (search, currency, units) must be absolutely positioned on top of the input with matching padding so the whole control is one hit target; clicking the icon focuses the field. Do not place the icon as a sibling that splits the click target. Audit rule: `forms-input-affix-hit-target`.

## Selects

- Use a custom chevron for consistent cross-browser styling: wrap only the `<select>` and chevron in `inline-grid grid-cols-[1fr_--spacing(8)]` (never the label); add `col-span-full row-start-1 appearance-none pr-8` to the `<select>`; place an SVG chevron with `pointer-events-none col-start-2 row-start-1 place-self-center`.

```html
<svg
  viewBox="0 0 8 5"
  width="8"
  height="5"
  fill="none"
  class="pointer-events-none col-start-2 row-start-1 place-self-center"
>
  <path d="M.5.5 4 4 7.5.5" stroke="currentcolor" />
</svg>
```

## Checkboxes

- Native `<input type="checkbox">`; all styling applied in CSS based on input state.
- **Never use JavaScript to toggle classes based on input state**: use CSS states and variants exclusively.
- Replace `{brand}` with the appropriate brand color. Every class is required; omit none.
- When a label is present, associate it via `id` and `for`; otherwise give it an `aria-label`.
- To vertically center with adjacent text, wrap it in an element with `h-lh items-center` and the matching `text-{size}`: never put `h-lh` on the `inline-grid` wrapper; never use top margins or manual alignment.
- Larger on mobile, e.g. `size-5 sm:size-4`.

```html
<span class="group inline-grid size-4 grid-cols-1">
  <input
    type="checkbox"
    class="checked:border-{brand} checked:bg-{brand} indeterminate:border-{brand} indeterminate:bg-{brand} focus-visible:outline-{brand} dark:checked:border-{brand} dark:checked:bg-{brand} dark:indeterminate:border-{brand} dark:indeterminate:bg-{brand} dark:focus-visible:outline-{brand} col-start-1 row-start-1 appearance-none rounded-sm border border-gray-300 bg-white focus-visible:outline-2 focus-visible:outline-offset-2 disabled:border-gray-300 disabled:bg-gray-100 disabled:checked:bg-gray-100 dark:border-white/10 dark:bg-white/5 dark:disabled:border-white/5 dark:disabled:bg-white/10 dark:disabled:checked:bg-white/10 forced-colors:appearance-auto"
  />
  <svg
    viewBox="0 0 14 14"
    fill="none"
    class="pointer-events-none col-start-1 row-start-1 size-7/8 self-center justify-self-center stroke-white group-has-disabled:stroke-gray-950/25 dark:group-has-disabled:stroke-white/25"
  >
    <path
      d="M3 8L6 11L11 3.5"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
      class="group-not-has-checked:opacity-0"
    />
    <path
      d="M3 7H11"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
      class="group-not-has-indeterminate:opacity-0"
    />
  </svg>
</span>
```

## Radio Buttons

- Same rules as Checkboxes (native `<input type="radio">`, CSS-only state, no JS class toggling, `{brand}`, every class required, label via `id`/`for` or `aria-label`, `h-lh items-center` centering, larger on mobile e.g. `size-5 sm:size-4`), but `rounded-full` with a filled dot instead of a checkmark.

```html
<span class="group inline-grid size-4 grid-cols-1">
  <input
    type="radio"
    class="checked:border-{brand} checked:bg-{brand} focus-visible:outline-{brand} dark:checked:border-{brand} dark:checked:bg-{brand} dark:focus-visible:outline-{brand} col-start-1 row-start-1 appearance-none rounded-full border border-gray-300 bg-white focus-visible:outline-2 focus-visible:outline-offset-2 disabled:border-gray-300 disabled:bg-gray-100 disabled:checked:bg-gray-100 dark:border-white/10 dark:bg-white/5 dark:disabled:border-white/5 dark:disabled:bg-white/10 dark:disabled:checked:bg-white/10 forced-colors:appearance-auto"
  />
  <span
    class="pointer-events-none col-start-1 row-start-1 size-[round(down,40%,1px)] self-center justify-self-center rounded-full bg-white group-not-has-checked:opacity-0 group-has-disabled:bg-gray-400 dark:group-has-disabled:bg-white/25"
  ></span>
</span>
```

## Toggles

- Native `<input type="checkbox">`, CSS-only state (no JS class toggling), every class required, label via `id`/`for` or `aria-label`.
- A toggle takes effect immediately on change. Do not require a separate Save to apply a binary preference; Save is for multi-field forms.
- Replace `{brand}` and `{gray}` with the appropriate brand/gray colors.
- Use `w-9` as the default size; only adjust the width to make it larger or smaller. Larger on mobile, e.g. `w-11 sm:w-9`.
- Remove all `dark:` classes if the site has no dark mode; for always-dark sites, use the `dark:` values as the base classes and remove the `dark:`-prefixed versions.

```html
<div
  class="group outline-{brand}-600 has-checked:bg-{brand}-600 dark:outline-{brand}-500 dark:has-checked:bg-{brand}-500 bg-{gray}-200 inset-ring-{gray}-900/5 relative inline-flex w-9 shrink-0 rounded-full p-0.5 inset-ring outline-offset-2 transition-colors duration-200 ease-in-out has-focus-visible:outline-2 dark:bg-white/5 dark:inset-ring-white/10"
>
  <span
    class="ring-{gray}-900/5 aspect-square w-1/2 rounded-full bg-white ring-1 shadow-xs transition-transform duration-200 ease-in-out group-has-checked:translate-x-full"
  ></span>
  <input type="checkbox" class="absolute inset-0 size-full appearance-none focus:outline-hidden" />
</div>
```

# General

Covers: general markup and Tailwind CSS authoring rules not specific to one component.

## Coding Rules

### Markup

- Never apply `text-*` (font size) or `leading-*` (line height) to inline elements (`<span>`, `<a>`, `<strong>`, `<em>`, `<code>`); apply them to containing block-level elements (`<div>`, `<p>`, `<h1>`, `<h6>`, `<li>`, `<td>`)
- Never add display classes matching an element's default display: no `block` on `<div>`/`<p>`/`<h1>`/`<h6>`; no `inline` on `<span>`/`<a>`; no `inline-block` on `<input>`/`<button>`/`<select>`; no `table` on `<table>`. Only applies to classes that don't change child layout: `flex`, `grid`, `inline-flex`, `inline-grid` are never redundant
- Never apply conflicting classes for the same property on one element without a distinguishing variant: no `outline-1 outline-2`, no `outline-black/5 outline-white`; keep only the intended value
- Always add `role="list"` to `<ul>` and `<ol>` unless a `list-style-*` class (e.g. `list-disc`, `list-decimal`) is applied
- Never add `hover:*` to non-interactive elements: reserve for buttons, links, and other clickables
- Never add `transition-*` for hover color/background changes: reserve transitions for elements that move or transform

### Tailwind CSS

- Always apply `antialiased` to the root element
- Always apply `isolate` to the main app container (gets `inert` when dialogs open): prevents z-index conflicts with portalled elements
- Place `@import` statements with remote URLs (`http`/`https`) or `url()` at the very top of the CSS file, before `@import "tailwindcss"` (but after `@charset` if present)
- Add `tabular-nums` to elements displaying numbers, especially values that change over time (counters, timers, prices, stats): prevents layout shift as digits update
- Never use `mt-*`/`mb-*`/`ml-*`/`mr-*`/`mx-*`/`my-*` between flex/grid children: use `gap-*` on the parent instead
- Prefer `size-{n}` over `h-{n} w-{n}` when both values are the same
- Prefer shorthand over split axis classes: `p-8` not `px-8 py-8`, `inset-0` not `inset-x-0 inset-y-0`; keep them split when a variant overrides one axis, e.g. `p-8 md:px-10`
- Use `--spacing(…)` for arbitrary spacing values: `--padding: --spacing(2)` not `--padding: 8px`
- Never use `calc(var(--spacing)*…)`: use `--spacing(…)` instead
- Never use `theme(spacing.…)`: use `--spacing(…)` instead
- Never use `theme()` for colors or other tokens in arbitrary values: use CSS variables instead; `[stop-color:var(--color-emerald-500)]` not `[stop-color:theme(colors.emerald.500)]`
- Use `rem` for arbitrary font sizes: `text-[0.8125rem]` not `text-[13px]`
- Pixels are fine for properties that use pixels natively in Tailwind: `border-*`, `outline-*`
- Use theme variable references for arbitrary radii: `--radius: var(--radius-xl)` not `--radius: 16px`
- Never use named line-height values (`tight`, `snug`, `relaxed`): not in `leading-tight`, not in `text-6xl/tight`; only spacing scale values (e.g. `leading-6`, `text-sm/5`), and only when a custom line height is specifically required
- Never use inline `style` for static CSS properties lacking a utility class: use arbitrary property syntax instead; `class="[animation-delay:300ms]"` not `style="animation-delay: 300ms"`
- Set CSS variables with arbitrary property syntax, not inline styles: `class="[--padding:--spacing(3)]"` not `style="--padding: --spacing(3)"` (unless the value is dynamic)
- For dynamic values, prefer CSS variables over CSS properties in `style`: `class="w-(--progress)" style="--progress: 72%"` not `style="width: 72%"`; name the variable descriptively relative to the context
- Prefer bare values over arbitrary values for integers and multiples of `0.25`: `z-999` not `z-[999]`
- Prefer bare opacity modifiers on color utilities: `bg-neutral-950/2` not `bg-neutral-950/[0.02]`; use `[…]` only for non-`0.25`-increment values
- Negate `hidden` with a single conditional variant instead of setting `hidden` then re-applying the display class: `flex items-center gap-x-6 max-lg:hidden` not `hidden lg:flex lg:items-center lg:gap-x-6`; `not-dark:hidden` not `hidden dark:block`
- Prefer `not-*` variants over a base value with conditional override: `group-not-has-checked:opacity-0` not `group-has-checked:opacity-100 opacity-0`; place `not-` directly before the negated state, not `not-group-has-checked:…` (fires without a `group` parent) or `group-has-not-checked:…` (matches any unchecked element)
- Use bare values in variants over arbitrary values in variants: `data-closed:…` not `data-[closed]:…`, `group-data-open:…` not `group-data-[open]:…`
- Always use `min-h-dvh/svh/lvh`, never `min-h-screen` (`screen` is deprecated)
- Always use `bg-linear-*` for gradients, never `bg-gradient-*` (deprecated)
- Use `shrink-*` not `flex-shrink-*`, `grow-*` not `flex-grow-*` (deprecated)
- Prefer whole-number ratios in arbitrary grid/flex values: `grid-cols-[21fr_19fr]` not `grid-cols-[1.05fr_0.95fr]`; multiply all values by the same factor to eliminate decimals
- Prefer `@utility my-utility { … }` over plain class selectors (`.my-utility { … }`): utilities work with all Tailwind variants (`hover:my-utility`, `lg:my-utility`)
- Use `@utility my-utility-* { … }` with `--value()` and `--modifier()` for parameterized utilities that accept arguments
- Use `@variant the-variant { … }` inside `@utility` definitions to apply an existing variant: don't manually write the media query or selector
- Use `@custom-variant` to define new custom variants when the built-in set doesn't cover the case
- Never nest `@utility` inside another at-rule (`@media`, `@supports`): move the at-rule inside the `@utility` block instead

# Headers

Covers: site headers, navigation bars, top bars, logos, mobile menus, hamburger menus, header CTAs.

## Design Rules

- Wrap the main logo in `<a href="/">` with `aria-label="Homepage"`
- Navbar buttons must feel secondary to the hero's primary CTA: use ghost, outline, subtle, or a smaller solid button; matching the hero color is fine if the navbar button is noticeably smaller

# Heading Groups

Covers: headline, subheadline, and optional eyebrow groups atop marketing/landing sections.

A heading group is a headline and subheadline (and optional eyebrow) at the top of a marketing or landing section: the title and description above a feature grid, team grid, pricing table, testimonial section, CTA, or hero. These rules apply to promotional/marketing sections only, not blog posts, articles, documentation, or editorial content.

The measures below are heading measures, deliberately tighter than body text. Running body copy is a different range, owned by `typography-audit` and the `type-readable-scale` floor; a 24ch headline is correct here and is not a violation of it.

- Never constrain the heading group wrapper's width: no `max-w-*`, no `max-lg:max-w-*`, no width constraint of any kind on the wrapper `<div>`. Constrain each text element (headline, subheadline) individually with `max-w-[*ch]` directly on it: `text-base` → `max-w-[56ch]`, `text-lg` → `max-w-[48ch]`, `text-xl` → `max-w-[40ch]`, `text-2xl`, `text-3xl` → `max-w-[40ch]`, `text-4xl` → `max-w-[35ch]`, `text-5xl` → `max-w-[30ch]`, `text-6xl` → `max-w-[24ch]`, `text-7xl` → `max-w-[20ch]`.

  ```html
  <div class="/* never add a max width here */">
    <h2 class="mx-auto max-w-[35ch] text-4xl font-semibold tracking-tight text-balance">…</h2>
    <p class="mx-auto mt-6 max-w-[48ch] text-lg text-pretty text-gray-600">…</p>
  </div>
  ```

- Use a left-aligned layout when the subheadline exceeds ~120 characters (~3 lines when centered).
  - **⚠️ ask-user** if a centered layout is requested but the subheadline exceeds ~120 characters: offer a rewritten version that fits; only center if the user accepts the shorter copy.

# Icons

Covers: SVG icons, Heroicons, inline checkmarks, icon buttons, icon sizing, icon alignment with text.

## Design Rules

- Never generate raw SVG icons: import from the project's icon library, or Heroicons if none is established.
- Never wrap icons in decorative containers (colored squares, circles with backgrounds): use the icon directly.
- Never scale icons: `viewBox="0 0 24 24"` uses `size-6`, `viewBox="0 0 20 20"` uses `size-5`, `viewBox="0 0 16 16"` uses `size-4`. If an icon looks too small, switch icon sets, don't bump the size class.
- Use 16px/micro icons (`size-4`) inline with `text-sm` text (checklists, feature items, comparison tables, inline labels); use 20px/mini (`size-5`) only for navigation list icons.
- Aligning an icon next to a text group (label + supporting text): align it to the first line/label with `items-start` or `items-baseline`, never `items-center` on the group.
- Application UIs (dashboards, settings, admin, sidebar nav, forms): use only Heroicons Micro (16px, `size-4`); never 20px/mini or 24px/outline.
- Icons paired with text should usually be visually quieter than the label: lower opacity, use the secondary text color, or reduce emphasis so the icon supports recognition without becoming the focal point.
- With a stroke-based icon set (Lucide, Tabler), match stroke to the adjacent text weight: `1.5px` beside regular (400) text, `2px` beside medium/semibold (500-600), `2.5px` beside bold (700). A hairline icon beside a bold label reads as broken. One stroke weight per surface; never mix icon libraries on one toolbar.
- Optically center asymmetric icons in icon-only buttons. If geometry looks off, adjust the SVG viewBox or wrapper alignment rather than trusting mathematical centering.

## Coding Rules

- Use `size-{n} h-lh` on SVG icons to vertically center them with adjacent text; set `font-size` on a wrapper instead of top margins or manual alignment.
- Use `fill-{color}` for filled icons and `stroke-{color}` for stroked icons; never `text-{color}` with `currentColor` (legacy v2 hack).
- Always add `shrink-0` to icons inside flex containers.

# Images

Covers: photos, thumbnails, screenshots, app mockups, product images, media frames, and image borders/outlines.

## Design Rules

- Never border photos or thumbnails: use `outline-1 -outline-offset-1 outline-black/5` or `outline-black/10` if a visible edge is needed
- For screenshots and app UI mockups: `outline-1 -outline-offset-1 outline-black/5` or `outline-black/10` on light surfaces, `outline-white/10` on dark
- When the screenshot is proof people must inspect, keep it straight-on, legible, and large enough to read. Avoid perspective, depth-of-field, aggressive crops, and fake device or browser chrome that obscure product detail.
- Put the shadow and outline on the same element that clips, not on a child of it. A rounded `overflow-hidden` parent clips its descendants, so a child carrying `shadow-*` loses the shadow at the corners; the clipping element's own outline and shadow are never clipped.

## Coding Rules

- Use `alt=""` when adjacent visible text identifies the subject

# Landing Pages

Covers: landing pages, marketing pages, stacked page sections, heroes, CTAs, pricing sections, feature sections, full-page consistency.

- Reuse one primary/secondary button style across the whole page: if the hero's secondary is link-style, every section's secondary action (CTA, pricing, etc.) is link-style too.
- Reuse the same font treatment (size, weight, color) wherever the same or similar idea repeats: match the existing instance exactly.
- Reuse one container style across the page: once set (outline, tinted, etc.), all later containers match.
- Use one border radius for all sibling containers at the same level (panels, cards).
- Use one column `gap-*` across all multi-column sections (card grids, split layouts): check existing sections and match the value already in use before adding a new one.
- Never place a centered layout directly below a left-aligned one; use left-aligned, unless the section above ends with full-width containers, a background color change, or a visible divider separates them.
- Never have more centered heading groups than left-aligned on a landing page: center heroes, CTAs, and symmetrical content (centered pricing cards, logo clouds); default to left-aligned for feature grids, split layouts, and content-heavy sections.

# Login Pages

Covers: login, sign-in, sign-up, authentication, password reset, and account access pages.

- Never use light-tinted backgrounds (e.g. `bg-gray-50`, `bg-gray-100`, `bg-slate-50`) on login/sign-in pages: use solid white (`bg-white`) or dark (`bg-gray-900`, `bg-gray-950`, `bg-black`), unless the form is in a distinct panel or card

# Logo Clouds

Covers: logo grids, customer logos, partner logos, trust bars, client rows, and collections of brand marks.

- Distribute logos evenly across rows when wrapping; never an unbalanced last row. Use a grid that splits as evenly as possible (e.g. 3+3, not 5+1, for 6 logos)
- A logo cloud directly beneath a hero extends the hero: match its alignment; left-aligned hero → left-aligned label and logos

# Materials

Covers: translucent chrome, backdrop-filter layers, material weight as hierarchy, vibrancy text legibility, scroll edge effects, grain against banding, and reduced-transparency fallbacks. Approximates Apple-style materials on the web.

- Build nav bars, toolbars, and sheets as translucent layers, `backdrop-filter: blur() saturate()` over a semi-transparent background, with content scrolling underneath, rather than opaque bars that consume a fixed strip. A bright top border reads as light catching the material.
- Material weight encodes hierarchy: darker, heavier materials separate structural regions (sidebars); lighter materials draw attention to interactive elements (buttons). Never stack a light translucent surface on another translucent surface: legibility collapses.
- Bigger surfaces read as thicker: give them stronger blur and a deeper shadow than small chips. Consider context-aware shadow, heavier over busy or text content for separation, lighter over plain backgrounds.
- Dim to focus, separate to keep flow. A modal task pairs the surface with a dimming scrim and pushes the background back. A parallel, non-blocking panel uses translucency and offset without a scrim so the flow isn't broken. For stacked sheets, progressively dim and push back each parent layer.
- Vibrancy keeps text legible over changing backgrounds. Over blurred or translucent surfaces, don't use flat gray text: use higher contrast, a slightly heavier weight, and a small letter-spacing bump. Put color on a solid layer, not the translucent foreground.
- Scroll edge effects, not hard dividers. Instead of a 1px border under a sticky header, fade a small blur or gradient mask where content meets floating chrome, only where floating UI actually overlaps content.
- Materialize, don't just fade. For glass or blur surfaces, animate blur radius and scale together on enter and exit, so the surface reads as a real material arriving rather than a plain opacity fade.
- Provide fallbacks: `@media (prefers-reduced-transparency: reduce)` raises background opacity and drops the blur; `@media (prefers-contrast: more)` uses a near-solid background with a defined, contrasting border.
- Grain vs banding: a very faint noise overlay (`pointer-events-none`, `aria-hidden`) hides banding from large blurs and stretched gradients. One layer, low opacity. Do not stack multiple noise layers (see `slop-decoration-no-role`).
- Large `blur()` / `backdrop-filter` values are expensive; prefer smaller blur plus a solid or gradient underlay.

```css
.toolbar {
  background: rgba(255, 255, 255, 0.6);
  backdrop-filter: blur(20px) saturate(180%);
  border-top: 1px solid rgba(255, 255, 255, 0.4); /* bright top edge = light catching the material */
}

@media (prefers-reduced-transparency: reduce) {
  .toolbar { background: white; backdrop-filter: none; }
}
```

# Navigation

Covers: sidebar nav, header nav, mobile menus, tabs, tab bars, vertical menus, active states, current-page indicators.

- Give every app a mobile nav menu on small screens, whether the desktop nav is a header or sidebar: use a dialog or disclosure panel with a hamburger toggle; hide the desktop nav with `hidden lg:flex` (header) or `hidden lg:block` (sidebar) and show the mobile menu below `lg:`.
- Never use a high-contrast or primary-color background for active nav items: use darker text, a soft/muted background, or both.
- Never change `font-weight` between nav states (default, hover, active): use color and background only.
- Never let horizontal menus (tabs, tab bars, pill navs) overflow the parent: scroll horizontally when items don't fit.
- Never use icons in top header horizontal nav links: text-only.
- To center nav links on the page (not just between side items), use a three-section flex layout: `<div class="flex flex-1 items-center">` for the left (logo), the nav links at natural width (no `flex-1`), and `<div class="flex flex-1 items-center justify-end">` for the right (actions). The matching `flex-1` gutters force the centered group to true page center. Use the same pattern to center a logo: keep it at natural width with `flex-1` on the side sections.

# Pagination

Covers: pagination, page number links, previous/next buttons, and paged navigation controls.

- Hide page numbers on mobile when pagination includes both page numbers and previous/next buttons

# Placeholder Content

Placeholder logos, avatars, screenshots, app images, wallpapers, people, and fallback assets when real content is missing.

See [Assets API](./assets-api.md) for endpoints, parameters, and asset IDs.

- No logo file: use the marks endpoint with the user's app name; pick a font matching the design
  - Use `color` for the mark and `textColor` for the text; make the mark white, black, dark gray, or an accent color; keep text white, black, or dark gray
  - Prefer extension-suffixed asset URLs when supported
  - Omit `text` (and `textColor`/`font`) for just the mark icon: e.g. `/marks/1.svg?color=blue-500`
  - Never build logos from HTML or icons: always use the marks or logos endpoint
  - Same endpoint for all other logos: testimonials, client logo grids, etc.
- Always use `https://assets.ui.sh/screenshots/1.webp` for app screenshots, dashboard images, or any UI that should look like a real product: never use Unsplash or stock photos for these; content needn't match, just look like a realistic app UI at a glance
  - Hero images (full or near-full-width): use the uncropped screenshot; never crop at large sizes
  - For feature section screenshots, use only these exact cropped variants; never invent new crop parameters:
    - `?top=900&left=1200&position=bottom-right`: Sidebar + inbox list (1200×900)
    - `?top=900&right=1200&position=bottom-left`: AI agent panel with customer insights (1200×900)
    - `?top=600&right=800&position=bottom-left`: AI agent header, tight focus (800×600)
    - `?top=1200&left=1600&position=bottom-right`: Full interface overview (1600×1200)
    - `?top=1500&left=2000&position=bottom-right`: Wide overview with sidebar, inbox, and conversation (2000×1500)
    - `?top=1400&right=1867&position=bottom-left`: Email conversation + AI assistant (1867×1400)
- Placeholder avatars: use the avatars endpoint, preferring extension-suffixed URLs like `/avatars/1.webp`
- Use unisex names for placeholder people: avatars are random, so names must fit any photo

# Pricing Cards

Covers: pricing tiers, pricing cards, pricing tables, plan comparisons, emphasized plans, popular/recommended plans.

## Design Rules

- Emphasize cards via button styling and optional "Popular" or "Recommended" text: never a different background color for the whole card.
- For feature-list checkmarks, follow [Icons](./icons.md): use `size-4 h-lh` to vertically center with text.

## Coding Rules

- Never isolate the emphasized card: it's a grid sibling, not a standalone section.
- Align buttons across cards with `flex flex-col justify-between` on each card; wrap all content above the button in one `<div>` so the button pushes to the bottom:

```html
<div class="flex flex-col justify-between …">
  <div>
    <!-- name, price, description, features -->
  </div>
  <div>
    <button>Get started</button>
  </div>
</div>
```

- If the emphasized card is taller than its siblings, use CSS grid with explicit rows (never negative margins or relative positioning): the gap rows define how far the card pokes out, unemphasized cards sit in the middle row, the emphasized card spans all rows.

```html
<!-- Pokes out top and bottom -->
<div class="{breakpoint}:grid-cols-3 {breakpoint}:grid-rows-[--spacing(6)_1fr_--spacing(6)] grid">
  <div class="{breakpoint}:row-start-2"><!-- normal card --></div>
  <div class="{breakpoint}:row-span-full"><!-- emphasized card --></div>
  <div class="{breakpoint}:row-start-2"><!-- normal card --></div>
</div>

<!-- Pokes out top only -->
<div class="{breakpoint}:grid-cols-3 {breakpoint}:grid-rows-[--spacing(6)_1fr] grid">
  <div class="{breakpoint}:row-start-2"><!-- normal card --></div>
  <div class="{breakpoint}:row-span-full"><!-- emphasized card --></div>
  <div class="{breakpoint}:row-start-2"><!-- normal card --></div>
</div>
```

# Prose Content

Covers: raw HTML from markdown, CMS content, database content, blog posts, articles, documentation, and rendered markup where classes can't be applied to individual elements.

- Never use the `@tailwindcss/typography` plugin: instead create a `.prose` class that styles raw HTML elements (headings, links, lists, code blocks, images, etc.) with plain CSS using Tailwind's CSS theme variables (`var(--color-*)`, `var(--text-*)`, `var(--font-weight-*)`, `var(--radius-*)`, `--spacing(*)`, `--alpha()`); use `@variant dark { … }` and `@variant hover { … }` for dark mode and hover states; use `* + *` for vertical spacing between elements; style every element that could appear: `h1`, `h6`, `p`, `a`, `ul`, `ol`, `li`, `pre`, `code`, `img`, `strong`, `blockquote`
- Apply the `.prose` wrapper class to the container holding the rendered HTML: `<div class="prose">` around blog post content, markdown output, CMS-generated markup, or any HTML where you can't add Tailwind classes to individual elements
- Default to `var(--text-base)` (`16px`) for prose body text; use `var(--text-lg)` (`18px`) or larger only if specifically requested or if the project already uses that size for body text elsewhere
- Never set `max-width` in `.prose` CSS: constrain with a `max-w-[*ch]` class alongside `prose` (e.g. `<div class="prose max-w-[65ch]">`); use `60ch` to `75ch`, matched to the site's content widths. Go past `75ch` only for a documented reason such as a two-column layout or a code-heavy documentation page where wrapping costs more than measure, and raise leading toward `1.75` when you do
- Set prose body `line-height` to `1.6-1.75x` the font size: e.g. `--spacing(7)` for `var(--text-base)`. Go higher only past `80ch`, and constrain the measure before reaching for extra leading.
- Use `text-pretty` on blog post and article titles, not `text-balance`
- If the article `h1` is sans-serif, use the same sans-serif for all subheadings (`h2`, `h6`); never mix a sans-serif title with serif subheadings

# Responsive Design

Covers: mobile, tablet, desktop, breakpoints, container queries, overflow, wrapping, clipping, cramped narrow viewports. For the full retrofit ruleset (navigation, tables, pagination, touch targets, overflow patterns), see [../make-responsive.md](../make-responsive.md).

## Design Rules

- Adapt every layout mobile to desktop with breakpoint classes (`sm:`, `md:`, `lg:`): adjust grid columns, spacing, font sizes, and visibility.
- Collapse multi-column desktop layouts (sidebars, secondary nav, filter panels) to single column on small screens via mobile menu, disclosure, or compact pattern; never just shrink columns.
- Make body text, subheadings, form controls, and icons **larger on mobile**, smaller at `sm:`: write the mobile (larger) size as default and the desktop (smaller) size with `sm:` (e.g. `text-2xl/8 sm:text-xl/8`, `text-base/7 sm:text-sm/6`, `text-lg/6 sm:text-sm/6`, `size-5 sm:size-4`, `py-2.5 sm:py-1.5`). Applies to body text, subheadings, stat values, form input labels, badges, buttons, select/input padding, and icons. **Not** h1s (page titles stay equal or get smaller on mobile, never bigger).
- Keep body text at least `text-base` (16px) on mobile; `text-sm` only at `sm:` or larger (e.g. `text-base/7 sm:text-sm/6`, never `text-sm/6` unprefixed for body copy).

## Coding Rules

- Use container queries (`@container`) for component-level responsiveness: anything whose layout depends on available space, not the viewport (dashboard widgets, feature cards, pricing tiers, testimonial grids).
- Place the `@container` element as close to the responsive content as possible: a direct wrapper around the items, never a page-level container.

# Section Layout

Covers: page sections, constrained containers, centered vs left-aligned layouts, section padding, grids, stacked content alignment.

## Design Rules

- Align left-aligned sections to the page container edge: never narrow `max-w-*` + `mx-auto`; use a page-level `max-w-*` and constrain inner content separately.
- Align containers and boundings that occupy the same proportion across stacked sections: e.g. a 1/2-width card grid and a 1/2-width split with bounding below share the same column edges. Use consistent grid definitions and gap values so edges line up when scrolling.
- Avoid nested max-width on grids/lists that fill their container: if a feature grid or icon list spans the full constrained width, don't add a narrower `max-w-*`; align it to the page container edges, not floating in the middle. Nested `max-w-*` is fine for self-contained units meant to feel bounded (pricing cards, forms, comparison tables, centered media).
- Use a three-step spacing rhythm so grouping reads from the gaps: tightest within a group, more between groups, most between sections (e.g. 8px / 16px / 32-40px). Keep the same jumps across the page, not per-spot gaps.
- Give shared chrome one owner. Before adding a page title, global action, close or done control, or navigation affordance in a leaf component, inspect the shell and layout so it renders exactly once.
- Keep captions, helper text, and status lines in the tightest spacing group with the media or control they explain.
- Size compact forms, dialogs, and focused panels to their task and content before expanding to available width. Empty canvas is valid when it protects the glance path.
- Measure spacing between visible contrast edges, not invisible boxes. If a block has a tinted background, the section gap starts at the background edge, not at the first line of text inside it.
- Every element should align to a neighbor or a grid edge for a reason. Floating offsets are only acceptable when they create an intentional optical correction or hierarchy.
- In rows or columns of mixed visual weight, order from heaviest to lightest with the heaviest element on the outside edge. This keeps action groups and link clusters stable when scanned.

## Coding Rules

- Two-element pattern for constrained sections: outer handles background and vertical padding, inner handles max-width, centering, and horizontal padding:

  ```html
  <... class="{vertical-padding}">
    <... class="{max-width} mx-auto {horizontal-padding}">
      ...
    </...>
  </...>
  ```

  Apply consistently across all sections so content edges align when scrolling.

# Shadows

Covers: cards, modals, popovers, dropdowns, buttons, elevated surfaces, shadow/border pairings.

- Never pair shadows with solid gray borders. Use `ring-1 ring-black/5` or `ring-1 ring-black/10` (or `950` of your neutral).
- Never make elevated elements (cards, modals, popovers with `shadow-*`) darker than their canvas: use `white` or the lightest neutral, not `gray-100`/`gray-50`. Inset panels/wells without outer shadows can be darker.
- Use one depth technique per view: borders-only, tint, soft shadow, or layered shadow. Mixing hard shadows, soft shadows, borders, and tints makes hierarchy feel accidental.
- Use one top light source across the view: raised surfaces catch light above and cast shadow below, inset wells reverse that edge relationship, and a surface that is neither gets no edge lighting at all.
- Map depth to semantic z-order. Dialogs sit above menus, menus above routine controls, and routine controls above or within the work surface. A larger shadow is not decoration for a more important label.
- For close-view surfaces, combine a tight contact layer with a wider soft wash. As elevation rises, the contact layer weakens while the wash grows.
- In dark UI, avoid shadows as the main depth cue. Use surface brightness, borders, or subtle tint because dark shadows either disappear or become too harsh.
- For custom shadows, make blur roughly twice the offset and lower opacity as elevation increases, e.g. `0 4px 8px rgba(...)` reads cleaner than a hard 4px shadow.

# Surfaces

Covers: cards, wells, borders, dividers, white space, recessed backgrounds, content grouping.

- Don't default to white cards on gray backgrounds: prefer content directly on white, or white cards with just a `border`
- Choose surface treatments by information hierarchy: white space alone for tightly related items; subtle borders/dividers for sibling content needing separation; wells (recessed backgrounds like `bg-gray-50`) for secondary or nested content; cards with borders or shadows for standalone, interactive, or highly distinct items
- Use the lightest separation that works: whitespace, then subtle borders/dividers, then cards; never jump straight to cards
- Reserve cards for independently interactive content (clickable to navigate) or fundamentally different content types
- Make semantic roles look different. Context, references, previews, and captions must not receive the same card or action treatment as selectable or clickable peers; if five items look equally interactive, users will assume five choices.
- Container borders must contrast with both adjacent surfaces. On dark-on-darker UI the border is lighter than both surfaces; on light-on-lighter UI it is darker than both.
- Avoid two hard divides touching: a background transition plus a card edge plus a divider creates visual noise. Remove one layer or soften it with whitespace.
- Put simple foregrounds on complex backgrounds, and complex foregrounds on simple backgrounds. Avoid complex-on-complex unless the content is intentionally decorative and low-stakes.
- In containers, outer padding is at least equal to inner gaps between child elements. Related children sit closer to each other than to the container edge.
- Subtle top borders or vertical dividers for sibling items in shared context: stat grids, metric rows, dashboard KPIs
- Divider-separated items: middle items get equal padding on both sides of the divider (`px-*`); the first item in a row gets only `pr-*` (no `pl-*`), the last gets only `pl-*` (no `pr-*`); for horizontal dividers: first item only `pb-*` (no `pt-*`), last only `pt-*` (no `pb-*`); when grid columns change at a breakpoint, reset padding per the new first/last, e.g. a 4-column grid becoming 2-column: items 1 and 3 are now row-starts (no `pl-*`), items 2 and 4 are now row-ends (no `pr-*`); use responsive prefixes like `sm:pl-0` or `lg:pr-0` to override at each breakpoint
- Reconfigure dividers at each breakpoint when grid columns change: use `nth-child` to target items not in the first column: 2 columns use `[&:nth-child(2n)]:border-l-*`; 4 columns use `[&:not(:nth-child(4n+1))]:border-l-*`; adjust the pattern per breakpoint to match the column count; when collapsing to a single column, remove vertical dividers and add horizontal dividers between rows (`border-t-*` on all items except the first)
- Whitespace alone suffices when content has inherent contrast (large numbers vs small labels, bold headings vs body text)
- Never use solid divider colors: use opacity-based like `divide-gray-950/5` or `border-gray-950/10`, not `divide-gray-200` or `border-gray-300`
- When a faint divider disappears at its rendered size, add weight before adding contrast. A soft 2px rule separates without repeating a harsh dark line.

# SVG

Covers: inline SVG, SVG color styling, `fill`, `stroke`, `currentColor`, and SVG markup conventions.

- Omit `xmlns` on inline `<svg>` in HTML/JSX: only needed for standalone `.svg` files
- Style SVG colors with Tailwind classes (`fill-*`, `stroke-*`, `text-*` with `fill="currentColor"`/`stroke="currentColor"`), not hardcoded attributes or ternaries: use `data-*`/`aria-*` variants or conditional classes to switch colors
- Never combine `fill="currentColor"`/`stroke="currentColor"` attributes with `fill-*`/`stroke-*` classes on one element (they conflict): use `fill-current`/`stroke-current` to inherit text color, or drop the attribute when using a specific class like `fill-zinc-400`

# Tables

Covers: data tables, comparison tables, table headings, row dividers, horizontal scrolling tables, table containers.

## Design Rules

- Never use uppercase in table headings: use sentence case.
- Never let table headings wrap: add `whitespace-nowrap` to `<th>`.
- In dense work surfaces, default to tables directly on the page with row dividers. Use a bounded shell when search, filters, the table, page size, and pagination form one module, or when the project already does.
- Divide rows with horizontal lines only: no vertical lines, no outer borders.
- Always use `w-full` so tables fill their container.
- Hide headings with `sr-only` when column content is self-explanatory (typically 2-3 column tables where headings add no value).
- Make tables responsive when all columns won't fit on small screens, using a two-div wrapper:
  - Outer div: `overflow-x-auto whitespace-nowrap` with negative margins: horizontal margins cancel the page container's padding (e.g. `-mx-4 sm:-mx-6 lg:-mx-8`), vertical margin always `-my-2`.
  - Inner div: `inline-block min-w-full align-middle` with horizontal padding matching the container's (e.g. `px-4 sm:px-6 lg:px-8`) and `py-2`.
  - Always match the negative horizontal margins and horizontal padding to the container padding actually used in the page layout.

  ```html
  <!-- Example assumes container padding of px-4 sm:px-6 lg:px-8 -->
  <div class="-mx-4 -my-2 overflow-x-auto whitespace-nowrap sm:-mx-6 lg:-mx-8">
    <div class="inline-block min-w-full px-4 py-2 align-middle sm:px-6 lg:px-8">
      <table>
        …
      </table>
    </div>
  </div>
  ```

# Team Sections

Covers: team grids, member cards, staff listings, about-us sections, people galleries, photos, names, roles, bios.

## Design Rules

- Never use landscape aspect ratios for team images
- Use a muted color for role/job title text

## Coding Rules

- Render people lists as `<ul>` with `<li>` items
- Use `alt=""` on team photos when the name is visible nearby

# Testimonials

Covers: customer quotes, reviews, social proof sections, testimonial cards, quote punctuation, avatars, and attribution.

## Design Rules

- Hanging punctuation for quotes: `relative before:absolute before:inline before:-translate-x-full before:content-['\201C'] after:inline after:content-['\201D']`
- Bottom-align avatars/names across equal-height cards: `flex flex-col justify-between` per card; wrap quote and attribution in separate elements
- Never add whitespace inside quote `<p>` tags: write `<p>The quote text</p>` not `<p> The quote text </p>` (breaks hanging punctuation)
- Photos follow [avatar rules](./avatars.md) and [placeholder content rules](./placeholder-content.md)
- Use unisex names so random avatars fit any name

# Typography

Covers: text sizes, line heights, heading styles, font weights, tracking, text width, `text-pretty`, `text-balance`, eyebrow text.

## Design Rules

- Body, paragraph, and general content is `text-base` (16px) at every breakpoint. `text-sm` is for labels, captions, and helper text, never for reading copy; `text-xs` is for neither.
- Never use `font-bold` for headings: use `font-semibold` or `font-medium`.
- Use at most two font weights per view: one for emphasis (headings, labels), one for body; reuse them.
- Make hierarchy levels identical or clearly different, never nearly the same. Merge almost-equal sizes or separate them enough to create a visible rank.
- Don't hand-tune leading on display type. Tailwind ships `line-height: 1` from `text-5xl` up, which is already correct; overriding it with `leading-[1.05]` or similar loosens type that should stay tight. Hand-tune leading on body copy instead, where the default is set for a measure your layout may not have.
- Use `text-balance` on short headings, `text-pretty` on paragraph text and on any title long enough to wrap past two lines (article and blog titles: see [Prose Content](./prose-content.md)).
- Add `tracking-tight` to headings larger than `text-xl`, unless the font is a condensed headline font (already tight).
- Large type should not look airy: tighten tracking before adding weight, and constrain line length before shrinking the type.
- Small labels need more air than display type: avoid cramped `tracking-tight` or dense line-height on `text-sm` and below unless the text is numeric or code-like.
- Never use `uppercase` on eyebrow text unless it's a monospace font; with monospace `uppercase`, always add `tracking-wide`.

- For displayed data, omit labels when format, position, or context makes the value self-explanatory. Keep explicit labels for forms, specifications, and views people scan by field name.
- In dense product UI, links need not all use the accent colour. Preserve affordance through context, ink, weight, underline, hover, and focus; reserve bright link colour for sparse actions that need emphasis.

## Coding Rules

- Constrain text width with `max-w-[*ch]` directly on the element: see [Heading Groups](./heading-groups.md) for values per `text-*` size.
- When a project uses Inter, use the official variable font (`InterVariable`) with `font-display: swap`; enable useful OpenType features through `font-feature-settings` (for example `cv02`, `cv03`, `cv04`, `cv11`, `ss01`, `ss03`). Do not introduce Inter merely because it is a familiar UI default.
- Always read [Custom Fonts](./custom-fonts.md) when using custom fonts.
- Do not change `font-weight` on hover or selected states of controls or nav items: the width shift reflows adjacent text. Change color, opacity, or underline instead. Audit rule: `type-hover-weight-shift`.

# Craft Checklist (Detailed)

Final polish sweep for pre-release sign-off. Run after the rule-based CRITICAL/HIGH passes; it carries only the built-UI details no rule file encodes. Anything already owned by a rule (`rules/interaction-*`, `forms-*`, `a11y-*`, `nav-*`, `layout-*`, `perf-*`, `rules/states-*`, `dark-i18n-*`) is not repeated here, so a craft finding never duplicates a rule finding. Visual direction, motion, SEO, and deep typography belong to sibling skills and are pointed to, not restated.

## Contents
- Legibility and typography → sibling
- Keyboard, focus, and targets
- Forms and input behaviour
- Navigation and feedback
- Resilience and layout
- Performance
- Accessibility and theming
- Motion → sibling
- Visual direction and SEO → sibling

## Legibility and typography

Surface type defects are the `type-` rules; punctuation, OpenType, pairing, brand, and display type are the `typography-audit` skill. Not duplicated here.

## Keyboard, focus, and targets
- Buttons/links need a `hover:` state; hover/active/focus more prominent than rest. Set `-webkit-tap-highlight-color` on controls.
- `scroll-margin-top` on heading anchors for in-page links.
- `autoFocus` sparingly: desktop only, single primary input.
- Decorative layers (glows, gradients) get `pointer-events: none`.
- If it looks clickable, it must be clickable; remove dead zones between items. Avoid text selection during drag (`inert` or disable selection).
- Nested menus have a forgiving pointer corridor so moving diagonally into a submenu does not close it.
- Multi-key shortcuts tolerate release-order mistakes where the app owns the chord handling; don't cancel a chord the instant the first key lifts.
- Movable controls with natural stops (carousels, sliders, drawers) snap to valid positions after release, not halfway states.

## Forms and input behaviour
- Enter submits; textarea uses Cmd/Ctrl+Enter.
- Hydration-safe (no lost focus/value after hydration).
- Disable spellcheck for emails/codes/usernames; `autocomplete="off"` on non-auth fields to avoid password-manager triggers; keep password managers and one-time codes working.
- Allow incomplete submission to surface validation; keep submit enabled until the request starts, then disable with a spinner and keep the original label.
- Checkboxes/radios: label + control share one hit target (no dead zones).
- Placeholders end with `…` and show an example pattern.
- Warn before navigation with unsaved changes (`beforeunload` or router guard).
- Input affix hit targets are `forms-input-affix-hit-target`; not duplicated here.

## Navigation and feedback
- Preserve URL state; Back/Forward restores scroll.
- Supporting chrome (sidebars, tabs, secondary bars) recedes beneath the current task; keep shared header actions in consistent slots across comparable screens; prefer compact tab groups over full-width bars at equal state.
- Confirm destructive actions or provide undo.
- Spinners/skeletons: show-delay 150-300ms, min duration 300-500ms (avoid flicker).
- Preserve user position: filters, route changes, pagination, list updates, and Back/Forward keep scroll position or restore the equivalent item in view.
- Context menus open with stable action placement relative to the cursor, and never put a destructive action under the current cursor after the menu appears.
- Tooltips delay on first hover, but neighbouring tooltips in the same group switch instantly once the first tooltip is open.

## Resilience and layout
- `overscroll-behavior: none` on `html` for app shells; `contain` in modals and drawers. Document sites keep pull-to-refresh.
- Stress test with long labels, one-word values, dense rows, empty lists, and one-item lists. The UI should not only survive the populated demo state.
- Added or removed list rows preserve subjective position: content around the changed row should not jump unless the action is explicitly a reorder or navigation.
- If the same object appears across two views, preserve object permanence through the transition when practical: keep position, thumbnail, title, or shape continuous instead of replacing it with an unrelated hard cut.

## Performance
- No layout reads in render (`getBoundingClientRect`, `offsetHeight`); batch DOM reads/writes.
- `will-change` sparingly; avoid heavy blur and excessive video autoplay.

## Accessibility and theming
- Disabled-control tooltips and interactive hover-tooltips are `a11y-disabled-control-tooltip` and `a11y-tooltip-no-interactive`; not duplicated here.
- HTML illustrations (inline SVG, CSS art) need an accessible name, same as `<img>`.
- No animation during theme switches; set `color-scheme` and `<meta name="theme-color">`. Native `<select>`: explicit `background-color` and `color` (Windows dark mode fix).
- Guard hydration for date/time; `value` inputs require `onChange`; `suppressHydrationWarning` only where needed (dates, theme).

## Motion → sibling

Timing, easing, springs, gestures, and transform/opacity-only animation belong to the `ui-animation` skill. Route motion findings there for the fix.

## Visual direction and SEO → sibling

- Visual-direction polish (matching box-shadows to references, concentric border radius, optical alignment of icons/text, image outlines on light backgrounds, the fundamentals→visual→polish quality pyramid) belongs to this skill's Direction and Build modes, not to a built-UI defect check.
- SEO metadata, canonical/OG tags, and dynamic OG images belong to the `seo` skill.

# Defer to Other Tools

ui-design's value is the gap between "lint passes and axe is clean" and "the product still feels broken." It does not duplicate what other tools handle well. When a finding falls into another tool's territory, link out.

## Deferring is not the same as dispatching

Two different moves live in this file, and conflating them is how an audit ends by telling the user to go run the tools that would have confirmed it.

**Dispatch** goes to `ui-verification`, which is not another vendor's product but the skill that owns a browser session. It runs axe against the rendered page in both themes, measures hit areas and layout shift, walks focus, injects 500s, and hands back a measurement keyed to the rule id that raised the candidate. Where a running app exists, an audit dispatches rather than defers, and the finding arrives with `32x32px at 360px width` instead of `h-8 on line 42`. Its `references/rule-coverage.md` maps every rule in this corpus to the probe that decides it.

**Defer** is the table below: budgets, baselines, field data, and write-time linting, none of which a one-off run should pretend to own.

The tools in that table stay named exactly as they are. The change is which of them the audit can invoke rather than recommend: axe-core and a rendered-viewport measurement, yes; Lighthouse budgets, Chromatic baselines, and RUM, no.

## Coverage map

| Concern | Defer to | Why |
|---|---|---|
| LCP, CLS, INP, FCP, TTFB measurement | **Lighthouse** + **web-vitals** library + **Vercel Agent** | Field + lab measurement; ui-design reads source and inspects a rendered viewport, it does not measure field performance |
| WCAG 2.x rule violations | **axe-core** (runtime, dispatched to `ui-verification`) + **eslint-plugin-jsx-a11y** (lint) | Authoritative WCAG rule list with structured violations |
| `alt` text, `aria-*` attribute presence | **eslint-plugin-jsx-a11y** | Catches at write time |
| Color contrast ratios | **axe-core** per theme (dispatched to `ui-verification`) + **Storybook a11y addon** | Computed contrast per element, and it differs between light and dark |
| Visual regression (pixel-level) | **Chromatic** / **Percy** / **Playwright snapshots** | Per-component visual diffs |
| Bundle size budgets | **size-limit** / **bundle-analyzer** / **next/bundle-analyzer** | Continuous budget tracking |
| Dependency vulnerabilities | **npm audit** / **Dependabot** / **Snyk** | CVE matching |
| Generic bug review | **CodeRabbit** / **Vercel Agent** | LLM PR review of whole diff |
| TypeScript errors | **tsc** | Type system |
| ESLint rules | **eslint** | Lint at write time |
| End-to-end flow correctness | **Playwright** / **Cypress** | Runtime browser execution |
| Real-user RUM data | **Vercel Speed Insights** / **Sentry** / **Datadog RUM** | Field measurement |

## What ui-design catches that none of the above catch

The high-leverage gaps; ui-design's reason to exist:

| Gap | Tools that miss it | ui-design rule |
|---|---|---|
| Component has empty state but no CTA | All | `states-no-empty-state` (action-required variant) |
| Form clears values on validation error | All | `forms-lost-data-on-error` |
| `useFormStatus` called in same component as `<form>` | None: runtime bug | `forms-use-form-status-misuse` |
| Modal closes without restoring focus | axe checks landmarks, not focus return | `focus-not-restored` |
| Optimistic UI doesn't roll back on failure | All | `async-optimistic-without-rollback` |
| Loading placeholder has different height than loaded content (CLS) | Lighthouse measures CLS but not the cause | `states-layout-shift` |
| Error message says "invalid" / "error occurred" / "please try again" | All | `microcopy-vague-error` / `microcopy-leaked-error-message` |
| `useOptimistic` not wrapped in `startTransition` | None: silent runtime bug | `async-optimistic-without-rollback` |
| Out-of-order async responses overwrite newer data | None | `async-out-of-order-responses` |
| Submit button doesn't disable while pending | All | `forms-no-disable-while-submitting` |
| Hover-only affordance on touch device | jsx-a11y catches some patterns | `mobile-hover-only-affordance` |
| Color-only state (red/green without icon) | Partial via axe | `a11y-color-only-meaning` |

## Linking out

When a finding overlaps another tool, the rule's `Fix` section links out:

```markdown
**Fix:** Add a skeleton with `min-height` matching loaded state to prevent CLS.
**Also run:** `lighthouse --only-categories=performance` to confirm CLS budget; Lighthouse measures the metric, ui-design catches the static cause.
```

The audit summary always lists deferred categories explicitly:

```text
Verified in the browser (ui-verification):
  WCAG rule violations:  axe-core, both themes
  Hit targets, focus:    measured at 360px

Defer-to (not audited here):
  Performance budgets:   Run Lighthouse CI
  Bundle size:           Run size-limit
  Field performance:     Speed Insights / Sentry
  Visual regression:     Run Chromatic
```

The first block is empty when no app was running, and saying so is the point: a report that lists only the defer block has told the reader nothing about whether the findings are real.

This sets expectations and prevents the "why didn't ui-design catch X" complaint when X is another tool's job.

# Design System Extract

Reads an existing codebase and writes down what it already decided, as a durable artifact the other modes consume. Run it once per project, and again when the theme or the component library moves.

This exists because the guidelines defer to the project constantly and nothing establishes what the project is. `guidelines/colors.md` says "use it only if the project already does" three times in its first three lines. Build has no way to answer that, so it answers with a plausible default, and `slop-token-drift` catches the mismatch afterward as a density heuristic rather than a conformance check.

## What the artifact is for

| Consumer | Uses it to |
|---|---|
| Build | Compose from what exists instead of inventing a second Button, and pick values from the real scale rather than a plausible one |
| Audit | Judge drift against the project's actual scale. This is the one design-system file the audit load contract permits, because it records what the project decided rather than what it should decide |
| `ui-verification` | Check the written scale against computed styles on a rendered page, which is what catches a tokens file that no longer matches the shipped CSS |

The load-contract distinction is the whole reason this is an artifact and not a guideline. Prescription stays out of an audit; project state does not.

## Extract only what changes a decision

An inventory nobody acts on is a second README. Five things earn their place:

1. **Where the theme lives, and which source wins.** A `@theme` block, a `tailwind.config.*`, a CSS custom-property sheet, and a published tokens package can all be present at once, with the build honouring one. Name the authoritative one and how you established it, because every value below is only as good as that answer.
2. **The scales actually in use, not the ones defined.** Read the values that appear in components, not just the theme's declarations. A theme with twelve radius steps where the codebase uses three has a three-step ladder; recording twelve invites Build to reach for a step no surface uses. Cover spacing, radius, shadow, type sizes and weights, and the neutral family (`zinc` and `slate` and `neutral` are different decisions, and the guideline bans two of the common defaults).
3. **The component inventory.** What exists, where it lives, and what it is called. This is the highest-value half: shipping a second Button is a worse outcome than any amount of token drift, and it is the failure a fresh session makes by default.
4. **The conventions in force.** The class-merging helper, the variant library, the icon set, the dark-mode mechanism (class, data attribute, or media query), and whether components are compound or prop-driven. These decide whether generated code reads as native or as a graft.
5. **What is deliberately off-system.** A one-off value with a documented reason, a vendor widget that cannot be themed, a legacy surface nobody is migrating. Recording it stops the next audit re-flagging a decision someone already made, which is the fastest way for an audit to lose its reader.

Everything else is discoverable in seconds when it is needed, and belongs in the codebase rather than in a summary of it.

## Procedure

```text
Extract progress:
- [ ] 1. Locate every theme source; establish which one the build actually honours
- [ ] 2. Read the scales out of component usage, not only out of the theme declarations
- [ ] 3. Inventory components: name, path, and the variants each exposes
- [ ] 4. Record the conventions (merging helper, variant library, icons, dark-mode mechanism)
- [ ] 5. Record the documented exceptions and their reasons
- [ ] 6. Write the artifact; point the repo's agent instructions at it
- [ ] 7. Spot-check three values against the rendered app before trusting the file
```

Step 7 is the one to keep. A tokens file is a claim about the build, and a build step can override it: a value in the theme that no computed style ever shows is a value Build will use and the browser will discard. Hand the artifact to `ui-verification` and check three of its scale values against computed styles on a real page. Anything that disagrees goes in the artifact as a discrepancy, not silently corrected, because which of the two is wrong is a repo decision.

## Writing it

Default to `design-system.md` at the repo root, beside the agent instruction files, and add a pointer from `AGENTS.md` or `CLAUDE.md` so it loads without anybody remembering it exists (the `agents-md` skill owns that wiring). A file nothing points at is invisible to the next session, which is the same failure as an unlinked reference inside a skill.

Write values, not prose. "Radius ladder: `sm` 4px, `md` 8px, `lg` 12px; cards use `lg`, inputs use `md`" is usable. "The project uses a consistent radius scale" is not, and is also unfalsifiable when it stops being true.

Date nothing and version nothing. The artifact describes the current tree, and the tree is the source of truth; a stale artifact is corrected by re-running the extract, not by reading a changelog inside it.

## When to re-run

- The theme source changes, or a second one appears.
- A component library is adopted, replaced, or forked.
- An audit reports drift findings the artifact does not explain, which usually means the artifact is behind rather than the code being wrong.

Re-running is cheap and replaces the file wholesale. Do not maintain it by hand: a hand-edited artifact drifts from the codebase in exactly the way it exists to prevent.

# Feature Playbooks

Detect each feature from element + filename + route, then run its checks in order. All checks name a file in `rules/`; the category index is `rules/_sections.md`.

**Also run the matching category checks.** Beyond the checks below, run the `rules/` category fitting each surface: any form runs `forms-*` + `a11y-*` (labels, accessible names, error association, overlaid affixes; contrast ratios stay with axe); any list/dashboard runs `a11y-semantic-html-first`, `nav-semantic-links`, `interaction-keyboard-operable`, `interaction-focus-visible`, `type-hover-weight-shift`; hover-only helper UI also runs `a11y-disabled-control-tooltip` and `a11y-tooltip-no-interactive`; any media or image runs `a11y-image-alt-text`, `perf-image-dimensions-and-priority`; any user-facing surface runs `mobile-*`. Motion has no rules here: an animated surface with a timing, easing, or gesture problem is a finding that names `ui-animation`. Category map: `rules/_sections.md`.

## Table of contents

- [Feature detection](#feature-detection)
- [Sign-in / Sign-up](#sign-in--sign-up)
- [Checkout](#checkout)
- [Onboarding](#onboarding)
- [Search](#search)
- [Form (multi-step or long single page)](#form-multi-step-or-long-single-page)
- [List / Feed / Inbox](#list--feed--inbox)
- [Dashboard](#dashboard)
- [Modal / Dialog / Sheet](#modal--dialog--sheet)
- [Toast / Notification / Banner](#toast--notification--banner)
- [Empty state](#empty-state)
- [Error / 404 / 500 state](#error--404--500-state)
- [Loading state](#loading-state)

## Feature detection

Match on element semantics + filenames + route paths:

| Feature | Detect by |
|---|---|
| sign-in / sign-up | `<form>` with `<input type="email">` or `password`, OR route `/login`, `/signin`, `/signup`, `/register` |
| checkout | route `/checkout`, `/cart`, `/order`, `/billing`; OR component name `*Checkout*` `*Payment*` |
| onboarding | route `/onboarding`, `/welcome`, `/getting-started`; OR multi-step `<form>` with progress indicator |
| search | `<input type="search">` OR `role="combobox"` OR component `*Search*` `*Combobox*` |
| form | `<form>` with ≥3 fields not matching above features |
| list / feed | `<ul>`/`<ol>` of ≥5 children OR `role="list"` OR `*List*` `*Feed*` `*Inbox*` |
| dashboard | route `/dashboard`, `/home`, `/admin`; ≥4 distinct cards/widgets |
| modal | `role="dialog"`, `role="alertdialog"`, OR component `*Modal*` `*Dialog*` `*Sheet*` `*Drawer*` `*Popover*` |
| toast | `role="status"`, `role="alert"` (transient), `aria-live`, OR `*Toast*` `*Notification*` `*Snackbar*` |
| empty state | conditional render keyed on `items.length === 0`, `isEmpty`, OR text matching `/no .* yet|empty/i` |
| error state | route `/error`, `/404`, `/500`; OR `error.tsx`/`not-found.tsx` (Next.js); OR `role="alert"` with persistent error |
| loading state | conditional on `isLoading|isPending|<Skeleton>|<Spinner>`; OR Next.js `loading.tsx` |

---

## Sign-in / Sign-up

User need: enter the product without losing data or being locked out.

Checks:

1. **`forms-no-disable-while-submitting`**: submit `disabled` while pending, else double-submits create duplicate accounts. Bumps to **release-blocker** for sign-up.
2. **`forms-lost-data-on-error`**: wrong password must not clear the email field; password manager must still autofill. **release-blocker.**
3. **`microcopy-vague-error`**: "Wrong email or password" is fine for security; "Error 401" / "Invalid" is not. **fix-this-sprint.**
4. **`focus-not-restored`**: if "Forgot password?" opens a modal/route, focus returns on close. **fix-this-sprint.**
5. **`states-no-error-state`**: server-down shows a recoverable message with retry, not a blank page. **release-blocker.**

## Checkout

User need: complete payment without losing data, confident the right thing was bought.

Checks:

1. **`forms-lost-data-on-error`**: card/shipping/billing fields persist across all server-side validation errors. **release-blocker.**
2. **`forms-no-disable-while-submitting`**: "Place order" disables + shows pending, else double-charge. **release-blocker.**
3. **`async-optimistic-without-rollback`**: an optimistic cart update the server rejects must roll back to server state. **release-blocker.**
4. **`states-no-error-state`**: payment failures show specific cause + retry, not a generic toast. **release-blocker.**
5. **`microcopy-leaked-error-message`**: never surface raw `error.message` from a payment provider. **release-blocker.**
6. **`states-layout-shift`**: card form, address autocomplete, and order summary must not jump as fields validate. **fix-this-sprint.**

## Onboarding

User need: feel oriented and make progress; not give up.

Checks:

1. **`states-no-empty-state`**: first-run dashboard shows next-step guidance, not "no data." **release-blocker.**
2. **`forms-lost-data-on-error`**: back button preserves entered values. **release-blocker.**
3. **`focus-on-dynamic-content`**: when the next step renders, focus moves to its heading. **fix-this-sprint.**

## Search

User need: find the thing or know it isn't there.

Checks:

1. **`async-out-of-order-responses`**: fast typing must not show stale results from earlier queries. Use `useDeferredValue` or AbortController. **release-blocker.**
2. **`states-no-empty-state`**: zero results offer "did you mean" or "broaden filters" CTA. **fix-this-sprint.**
3. **`states-layout-shift`**: typing pause must not flash empty or collapse the list. **fix-this-sprint.**
4. **`microcopy-vague-error`**: search service down → "Search is temporarily unavailable, here's [recent items]" not "Error". **fix-this-sprint.**
5. **`focus-on-dynamic-content`**: `aria-live="polite"` on result count for screen readers. **fix-this-sprint.**
6. **`forms-input-affix-hit-target`**: a search icon overlays the field; it is not a flex sibling that steals the click. **backlog.**

## Form (multi-step or long single page)

User need: enter data once, not lose it, fix errors easily.

Checks:

1. **`forms-lost-data-on-error`**: `useActionState` with `state.fields` preserved across validation. **release-blocker.**
2. **`forms-no-disable-while-submitting`**: submit disabled during `pending`. **release-blocker.**
3. **`forms-use-form-status-misuse`**: `useFormStatus` must be in a child of `<form>`, not the same component. **release-blocker** (silent runtime bug).
4. **`microcopy-vague-error`**: "Email already in use, sign in instead" beats "Invalid". **fix-this-sprint.**
5. **`states-layout-shift`**: async-loaded form (e.g. user profile) reserves field layout while loading. **fix-this-sprint.**
6. **`forms-input-affix-hit-target`**: search, currency, and unit marks overlay the field; they are not flex siblings that steal clicks. **backlog.**

## List / Feed / Inbox

User need: scan, find, navigate.

Checks:

1. **`states-layout-shift`**: loading rows reserve item height (CLS-safe). **fix-this-sprint.**
2. **`states-no-empty-state`**: empty list has CTA to populate it. **fix-this-sprint.**
3. **`states-no-error-state`**: fetch failure has retry + cause. **fix-this-sprint.**
4. **`focus-on-dynamic-content`**: keyboard arrow navigation works; focus visible on row. **fix-this-sprint.**
5. **`interaction-target-size`**: row tap targets ≥44 px on mobile. **fix-this-sprint.**
6. **`type-hover-weight-shift`**: selected or hover rows do not bump `font-weight` and reflow neighbours. **backlog.**

## Dashboard

User need: at-a-glance status, drill into details.

Checks:

1. **`states-layout-shift`**: widgets reserve their space; no CLS. **fix-this-sprint.**
2. **`states-no-error-state`**: per-widget error fallback with retry; one widget failing doesn't break the dashboard. **release-blocker.**
3. **`async-no-error-boundary`**: wrap each widget in an error boundary. **release-blocker.**

## Modal / Dialog / Sheet

User need: focus on one thing, then return where they were.

Checks:

1. **`focus-broken-focus-trap`**: Tab cycles inside modal; Esc closes. **release-blocker.**
2. **`focus-not-restored`**: focus returns to trigger button on close. **release-blocker.**
3. **`states-no-error-state`**: async actions inside modal (save, delete) show success/error before closing. **fix-this-sprint.**
4. **`interaction-target-size`**: close button ≥44 px on mobile. **fix-this-sprint.**
5. **`states-layout-shift`**: modal content height stable across loading/loaded states. **backlog.**

## Toast / Notification / Banner

User need: see the message before it disappears, recover from errors.

Checks:

1. **`microcopy-vague-error`** + **`microcopy-leaked-error-message`**: actionable + non-leaky. **fix-this-sprint.**
2. **`nav-live-region-feedback`**: `role="alert"` for urgent (errors), `role="status"`/`aria-live="polite"` for info. **fix-this-sprint.**
3. **`interaction-target-size`**: dismiss button + action button ≥44 px. **backlog.**

## Empty state

User need: understand why nothing is here, what to do next.

Checks:

1. **`states-no-empty-state`** action variant: has a CTA, not just "no items." **fix-this-sprint** (or **release-blocker** on a critical onboarding path).
2. **`microcopy-vague-error`**: empty copy is context-specific, not "No data." **fix-this-sprint.**

## Error / 404 / 500 state

User need: understand what failed, recover or escape.

Checks:

1. **`states-no-error-state`** root variant: Next.js `error.tsx` exists at app/route level. **release-blocker.**
2. **`states-no-error-state`**: error page has retry + alternative path (home, contact support). **fix-this-sprint.**
3. **`microcopy-vague-error`** + **`microcopy-leaked-error-message`**: explains what went wrong without leaking stack traces. **release-blocker** for leaks.
4. **`focus-on-dynamic-content`**: focus moves to the error heading; screen reader announces. **fix-this-sprint.**
5. **`async-no-error-boundary`**: root layout wraps in an error boundary. **release-blocker.**

## Loading state

User need: see progress, not blank, not jumping.

Checks:

1. **`states-layout-shift`**: loading placeholder has `min-height` matching loaded content. **fix-this-sprint.**
2. **`async-no-suspense-boundary`**: server components / async streaming wrapped in `<Suspense fallback={...}>`. **fix-this-sprint.**

# Output Adapters

One JSON document, two formats. Build the JSON first, then render to what the user or pipeline wants.

## Table of contents

- [Three counts: found, applied, remaining](#three-counts-found-applied-remaining)
- [Fix blast radius](#fix-blast-radius)
- [Considered and rejected](#considered-and-rejected)
- [Adapter 1: Terminal table](#adapter-1-terminal-table)
- [Adapter 2: CI JSON](#adapter-2-ci-json)
- [JSON schema](#json-schema)
- [Field reference](#field-reference)
- [Validation rules](#validation-rules)
- [Choosing the adapter](#choosing-the-adapter)
- [Common rendering rules](#common-rendering-rules)

## Three counts: found, applied, remaining

The audit reads and edits in the same pass, so a single total is a lie: it describes a working tree that no longer exists by the time the report prints. Every run carries three counts instead.

| Count | Meaning |
|---|---|
| `found` | Every finding the rules produced, measured against the code as it arrived |
| `applied` | Findings this run fixed in the working tree |
| `remaining` | Findings still present when the run ended |

Invariant, per tier and in total: `found = applied + remaining`. If they do not reconcile, the run is `INCOMPLETE`.

**The ship verdict computes over `remaining` only.** A release-blocker that was found and fixed does not block the ship; a release-blocker that was found and left does. `found` stays in the report so nobody loses sight of what the code looked like on arrival, and so a run that fixed nine real bugs reads as nine bugs fixed rather than a suspiciously green audit.

| Verdict | Condition |
|---|---|
| `READY` | 0 remaining release-blockers AND ≤3 remaining fix-this-sprint |
| `READY_WITH_FOLLOW_UP` | 0 remaining release-blockers AND ≥4 remaining fix-this-sprint |
| `NOT_READY` | ≥1 remaining release-blocker |
| `INCOMPLETE` | `audit.selfCheck.passed === false` |

Every applied finding states what was changed, with the file and line range touched. The count is only trustworthy if a reviewer can walk it against the diff. An `applied: true` finding with no `appliedChange` fails the self-check.

## Fix blast radius

**Fixes stay inside the audited files.** The audit's licence covers the diff it was pointed at, nothing else.

When the real fix lives outside that set (a shared `<Dialog>`, a design-token file, a layout wrapper the diff only consumes), do not apply it. Emit the finding with:

- `applied: false`
- `outOfScope: true`
- `outOfScopeReason`: which file the fix would have to touch, and what else consumes it
- `proposedDiff`: the unified diff a human can apply deliberately

The finding still counts toward `remaining`, and still tiers normally. A release-blocker whose fix is out of scope leaves the verdict at `NOT_READY`, which is the correct outcome: someone has to make a call about a shared component, and that someone is not the audit.

Silently editing a shared component to clear a blocker is the single worst failure mode of an audit that writes. One caller's bug becomes every caller's regression, and the report says "fixed".

## Considered and rejected

Every report names **2 to 5 things the audit looked at and deliberately did not flag**, each with the guard that killed it. This section is required, including on a clean run.

It is what keeps the taste rules honest. `slop-` findings are judgement calls against a threshold, and a rule that only ever fires reads as a rule with no threshold at all. Naming the near-misses proves the threshold was applied rather than pattern-matched.

Each entry is one candidate, the rule it was tested against, and the specific fact that cleared it:

- "Logo strip under the hero, tested against `slop-unverifiable-proof`: six real named customers with live links, not filler."
- "Hero gradient, tested against `slop-decoration-no-role`: one layer, threshold is 3."
- "Close control on the dialog, tested against `interaction-target-size`: 44px on both axes."

Vague entries ("checked the spacing, seemed fine") do not count. If the audit cannot name the guard, it did not really consider the candidate.

**An audit that finds nothing is a valid, good result.** Report it plainly: the counts, the verdict, the rules run, the rejections. Do not promote a backlog nit to fill the page, and do not pad with restated rule names. A four-line clean report is a stronger signal than a padded one.

## Adapter 1: Terminal table

For local dev, fast scan in the agent transcript or piped output. Tight, monospace-aware.

```text
═══════════════════════════════════════════════════════════
UI Audit · 8 files · diff vs main
FOUND 8  ·  APPLIED 3  ·  REMAINING 5
SHIP VERDICT: ✅ READY (0 release-blocker, 2 sprint, 3 backlog remaining)
═══════════════════════════════════════════════════════════

APPLIED IN THIS PASS (3)

✔ src/checkout/PaymentStep.tsx
  L42  was release-blocker  forms-lost-data-on-error
       Card number cleared on shipping-address 422 response.
       Applied L42-58: hoisted form state into useActionState with
       field-level errors, so unrelated fields survive a 422.

✔ src/checkout/PaymentStep.tsx
  L88  was fix-this-sprint  states-layout-shift
       <CardElement> rendered during stripe load with no reserved height (CLS risk).
       Applied L88: wrapped in <Suspense fallback={<CardSkeleton h="44px" />}>.

✔ src/checkout/ConfirmStep.tsx
  L51  was fix-this-sprint  forms-no-disable-while-submitting
       Applied L51: Place order stays enabled through the request; now disabled while pending.

REMAINING (5)

⚠️  src/checkout/PaymentStep.tsx
  L102 fix-this-sprint  microcopy-vague-error
       Error copy is "Something went wrong."
       Fix: name the cause and the retry path.
       Not applied: the wording is a product decision, not a mechanical edit.

⚠️  src/checkout/ConfirmStep.tsx  (fix is out of scope)
  L34  fix-this-sprint  focus-not-restored
       Modal closes; focus returns to <body>, not the trigger button.
       Root cause is src/components/Dialog.tsx, which this diff does not touch
       and 14 other surfaces consume. Not applied. Proposed diff:
         - <DialogPrimitive.Content>
         + <DialogPrimitive.Content onCloseAutoFocus={restoreToTrigger}>

📋 src/checkout/CheckoutForm.tsx
  L12  backlog  dark-i18n-untested
       No dark-mode story or visual regression. Not applied: needs a test file.

📋 src/checkout/PaymentStep.tsx
  L67  backlog  mobile-hover-only-affordance
       Help tooltip only on hover; touch users miss it.

📋 src/checkout/ConfirmStep.tsx
  L88  backlog  slop-token-drift
       `top: 37px` on the badge; no token covers it.

CONSIDERED AND REJECTED (3)

  · Logo strip under the hero, vs slop-unverifiable-proof: six real named
    customers with live links, not filler proof.
  · Hero gradient, vs slop-decoration-no-role: one layer, threshold is 3.
  · Close control on the dialog, vs interaction-target-size: 44px on both axes.

═══════════════════════════════════════════════════════════
Defer to:
  Performance (CWV):     Run Lighthouse on /checkout
  Bundle size:           Run next-bundle-analyzer
  WCAG violations:       Run axe-core in Storybook

Suppress a finding: add {/* ui-audit-ignore:<rule-slug> */} above the element.

Audit self-check: ✓ 14 rules run · ✓ counts reconcile (8 = 3 + 5)
                  ✓ every applied fix names its edit · ✓ 3 rejections named
═══════════════════════════════════════════════════════════

```

Rules:
- Two groups, `APPLIED` then `REMAINING`. Within `REMAINING`, sort by tier (blocker, sprint, backlog), then group by surface.
- Applied entries lead with `was <tier>` and a past-tense `Applied L<range>:` line naming the edit. Never render an applied finding with a bare `Fix:` line: that reads as outstanding work.
- Remaining entries carry a `Not applied:` reason. "Out of scope" entries name the owning file and show the proposed diff indented, not fenced.
- Unicode emoji for tier (`⛔ ⚠️ 📋`, `✔` for applied); ASCII fallback (`X ! . +`) on `--no-emoji`.
- Line numbers as `L42` not `:42` (easier to spot in terminals).
- One line per fix; if longer, truncate with `→` and keep the full text in JSON.
- `CONSIDERED AND REJECTED` is required and never empty.
- Close with the defer-to, suppression, and self-check footers.

A clean run is short and stays short:

```text
═══════════════════════════════════════════════════════════
UI Audit · 3 files · diff vs main
FOUND 0  ·  APPLIED 0  ·  REMAINING 0
SHIP VERDICT: ✅ READY
═══════════════════════════════════════════════════════════
11 rules ran. No findings.

CONSIDERED AND REJECTED (2)
  · Loading placeholder on the settings list, vs states-layout-shift: min-height at L22.
  · Close control on the dialog, vs interaction-target-size: 44px on both axes.
═══════════════════════════════════════════════════════════
```

## Adapter 2: CI JSON

For pipelines, dashboards, and merge gates. Emit the document exactly as specified below; this adapter adds no fields and drops none.

There is no binary to invoke: the audit runs as an agent, and this adapter describes the JSON it writes for a consumer to read. Two gates are worth building against that document, whatever pipes it:

- **Merge gate:** fail when `summary.remaining.releaseBlockers` is greater than 0, that is, when the audit found a blocker it could not fix.
- **Reconciliation guard:** fail when `summary.found.total` does not equal `summary.applied.total + summary.remaining.total`. That catches a run that lost findings between the two counts.

Gate on `remaining`, never on `found`. A gate on `found` fails a run that fixed everything it saw, which trains everyone to skip the audit.

There is no PR-comment adapter. Posting per-line review comments on a diff is the `pr-reviewer` skill's territory, and duplicating it here produces two bots arguing on the same line.

## JSON schema

Findings emit as JSON matching this schema; render the terminal table only after the JSON is complete.

### Top-level

```json
{
  "audit": {
    "ranAt": "2026-05-01T12:34:56Z",
    "skill": "ui-design",
    "mode": "audit",
    "scope": {
      "mode": "diff",
      "diffBase": "main",
      "files": ["src/checkout/PaymentStep.tsx", "..."],
      "filesAudited": 8
    },
    "featuresDetected": ["checkout", "modal"],
    "rulesPlanned": 18,
    "rulesRun": 18,
    "selfCheck": { "passed": true, "failures": [] }
  },
  "verdict": "READY",
  "summary": {
    "found":     { "releaseBlockers": 1, "fixThisSprint": 4, "backlog": 3, "total": 8 },
    "applied":   { "releaseBlockers": 1, "fixThisSprint": 2, "backlog": 0, "total": 3 },
    "remaining": { "releaseBlockers": 0, "fixThisSprint": 2, "backlog": 3, "total": 5 },
    "outOfScope": 1,
    "unknown": 0,
    "suppressed": 0
  },
  "consideredAndRejected": [
    {
      "candidate": "Logo strip under the hero",
      "rule": "slop-unverifiable-proof",
      "guard": "Six real named customers with live links, not filler proof."
    },
    {
      "candidate": "Hero background gradient",
      "rule": "slop-decoration-no-role",
      "guard": "One gradient layer; threshold is 3."
    },
    {
      "candidate": "Close control on the dialog",
      "rule": "interaction-target-size",
      "guard": "44px on both axes."
    }
  ],
  "deferredTo": [
    { "concern": "performance", "tool": "Lighthouse", "reason": "CWV measurement" },
    { "concern": "wcag", "tool": "axe-core", "reason": "Authoritative rule violations" }
  ],
  "findings": [ /* Finding[] */ ]
}
```

`verdict` is computed from `summary.remaining` alone. `tier` per finding is one of `release-blocker | fix-this-sprint | backlog`, and does not change when a fix is applied: an applied blocker stays a blocker in `found` and in its own record. Only the bucket it counts toward changes.

Default tier comes from the rule's frontmatter (`defaultTier`); the rule's `surfaceOverrides` table bumps it up or down per detected feature. Always include `defaultTier`, `assignedTier`, and `tierReason`.

### Self-check codes

`audit.selfCheck.failures[]` is empty on a clean audit. Codes:

```
"rules-not-fully-executed"     // rulesRun < rulesPlanned
"too-many-unknown"             // > 30% of run rules returned "unknown"
"no-evidence-cited"            // No file:line on any fail/warn finding
"no-fix-provided"              // Some fail/warn findings missing `fix`
"counts-do-not-reconcile"      // found ≠ applied + remaining, per tier or total
"applied-not-described"        // An applied finding has no `appliedChange`
"out-of-scope-applied"         // An edit landed outside audit.scope.files
"too-few-rejections"           // consideredAndRejected has < 2 entries
"uniform-tier"                 // ≥5 findings and every one landed in the same tier
```

`uniform-tier` needs the floor. Two backlog nits sharing a tier is what a small clean diff looks like; five or more findings that all land on the same tier is a tiering pass that never ran.

If `failures[]` is non-empty, set `verdict: "INCOMPLETE"`.

One finding example follows, for the `observed` / `expected` threshold shape. Everything an applied, out-of-scope, or unknown finding needs is a field in the table below with its own **Required when** condition; a worked object for those would narrow the shape without adding anything.

### Finding, threshold rule

```json
{
  "rule": "interaction-target-size",
  "feature": "modal",
  "surface": "ConfirmDialog",
  "file": "src/checkout/ConfirmDialog.tsx",
  "line": 18,
  "result": "fail",
  "defaultTier": "fix-this-sprint",
  "assignedTier": "fix-this-sprint",
  "severity": "HIGH",
  "observed": { "width": 28, "height": 28 },
  "expected": { "min": 44 },
  "fix": "Close control is 28px; enlarge to 44px on both axes.",
  "applied": false
}
```

## Field reference

| Field | Required when | Description |
|---|---|---|
| `rule` | always | the rule's `id`, which matches its filename in `rules/` |
| `category` | always | the rule's `category`, one of the 14 in `rules/_sections.md` |
| `detect` | always | `static \| rendered \| rubric`, copied from the rule's frontmatter |
| `feature` | always | feature playbook this finding came from (`checkout`, `sign-in`, etc.) |
| `surface` | always | component or page name (PascalCase, no extension) |
| `file` | when result ≠ unknown | source file path |
| `line` | when grep reveals it | line number |
| `result` | always | `pass \| warn \| fail \| unknown` |
| `defaultTier` | fail / warn | rule's default tier |
| `assignedTier` | fail / warn | tier after surface overrides applied |
| `tierReason` | when assignedTier ≠ defaultTier | explanation of override |
| `severity` | fail / warn | `HIGH \| MEDIUM \| LOW` |
| `observed` | fail on a non-rubric rule | string OR object describing measurement |
| `expected` | fail on a non-rubric rule (when applicable) | object with rule threshold |
| `score` | `detect: rubric` | integer 1-5 |
| `anchor` | `detect: rubric` | verbatim text from rule's rubric table |
| `evidence` | fail (recommended) | array of `file:line: observation` strings |
| `fix` | fail / warn | string with the literal change |
| `fixSnippet` | fail (recommended) | code snippet for the prescribed change |
| `applied` | fail / warn | boolean; true if this run edited the working tree for this finding |
| `appliedChange` | applied=true | `file:startLine-endLine` plus one line naming the edit actually made |
| `outOfScope` | applied=false, fix reaches outside `audit.scope.files` | boolean |
| `outOfScopeReason` | outOfScope=true | the owning file and what else consumes it |
| `proposedDiff` | outOfScope=true | unified diff a human can apply deliberately |
| `docsLink` | fail (recommended) | URL to React/Next.js doc for the API in the fix |
| `reactApis` | when the fix uses a React or Next.js API | array of React 19 / Next.js APIs used in the fix |
| `suppressed` | always | boolean, true if `// ui-audit-ignore:<slug>` was present |
| `reason` | unknown | why the rule could not produce a verdict |

The suppression token is literally `ui-audit-ignore:`, matching what already exists in users' repos. It does not track the skill name.

## Validation rules

- Every `fail` and `warn` finding has `assignedTier`, `severity`, `fix`, and `applied`.
- Every `applied: true` finding has `appliedChange` naming a file and line range inside `audit.scope.files`.
- Every `outOfScope: true` finding has `applied: false`, an `outOfScopeReason`, and a `proposedDiff`.
- `summary.found` = `summary.applied` + `summary.remaining`, per tier and in total.
- `verdict` is derived from `summary.remaining` only.
- `consideredAndRejected` has 2 to 5 entries, each with `candidate`, `rule`, and `guard`.
- Every `detect: static` or `detect: rendered` fail finding has `observed`.
- Every `detect: rubric` finding has `score` AND `anchor`.
- Every `unknown` finding has `reason`, no tier, and no `applied`.
- Every finding belongs to exactly one `feature` and one `surface`.
- `pass` findings can be elided from the terminal rendering; keep them in JSON for the self-check.
- If `audit.selfCheck.passed === false`, set `verdict: "INCOMPLETE"`.
- `summary.suppressed` counts findings where `suppressed: true`. Suppressed findings are never applied.
- `assignedTier` defaults to `defaultTier` unless a surface override applies; always populate both.

## Choosing the adapter

| Where the audit runs | Adapter |
|---|---|
| Local terminal (`npm run audit`, agent CLI) | terminal |
| Claude Code chat | terminal |
| CI gating (block merge on remaining release-blockers) | JSON + jq |
| Status dashboard | JSON |

## Common rendering rules

- **JSON first.** Render the complete JSON document, then transform to the chosen adapter.
- **Pass findings elide.** Don't render `result: "pass"` findings in the terminal adapter; keep them in JSON.
- **One finding = one observable bug.** Don't bundle bugs under one rule; two issues firing the same rule are two findings.
- **Applied and remaining never mix.** A reader scanning the report should be able to answer "what do I still owe" from one block.
- **Tier-first, surface-second sort** inside each block: ⛔ first, ⚠️ next, 📋 last; within tier, group by surface.
- **The report ends at its footers.** Defer-to, suppression, and self-check close a run with findings; a clean run ends at the rejections. No sign-off, promotion, or summary paragraph follows either.

# Ship Readiness: Three-Tier Verdict

Every finding gets exactly one tier, deciding whether the PR ships, waits, or merges with follow-up.

The audit fixes what it can in the same pass, so tier and verdict answer different questions. Tier is a property of the finding and never changes when a fix lands: a payment-data-loss bug is a release-blocker whether or not the audit repaired it. The verdict is a property of the working tree at the end of the run, so it counts only what remains.

## Table of contents

- [The three tiers](#the-three-tiers)
- [Tier assignment rules](#tier-assignment-rules)
- [Verdict logic](#verdict-logic)
- [Anti-patterns](#anti-patterns)
- [Examples](#examples)

## The three tiers

### ⛔ release-blocker: fix before merge

These cause user-visible harm or data loss in production. Fix them in the pass if the fix lands inside the audited files. If it doesn't, the finding stays remaining, and the PR does not ship until a human resolves it.

Tier triggers:
- **Data loss**: user input destroyed by code (form clears on validation error, optimistic update without rollback on server reject)
- **Broken critical path**: sign-in, checkout, payment, or auth flows failing silently or blocking the user
- **Missing critical-path error state**: async fetch on the primary goal with no error UI
- **Broken focus management**: focus trap that doesn't restore (keyboard users locked out)
- **Dark patterns**: confirmshaming, hidden cancel, pre-checked upsells, fake urgency
- **Hydration mismatch on the primary route**: SSR/CSR diff causing layout flash
- **Race condition to inconsistent state**: out-of-order responses, double-submit creating duplicates

Examples per playbook:
- Sign-in: password manager autofill broken; form re-renders during auth
- Checkout: card field loses CVC on shipping-address validation; "Place order" enables before payment confirmation
- Modal: Esc-to-close doesn't restore focus to trigger
- Form: 422 response ignored, user sees no field-level errors
- Loading: blocking spinner without escape hatch (no cancel after 10 s)

### ⚠️ fix-this-sprint: merge but log issue

Degrade UX but don't block shipping. Fix in the pass where the change is mechanical and in scope. Whatever remains gets a tracking issue before merge, resolved within the sprint.

Tier triggers:
- Sub-44 px tap target on touch surface
- Loading placeholder that does not reserve height (causes CLS)
- Vague error message ("Invalid", "Error occurred")
- Missing empty-state CTA (stalls the user)
- 422 response shown as a generic error toast instead of inline field errors

Examples:
- Form submit shows "Error" toast instead of "Email already in use: sign in or reset password"
- Empty inbox shows "No messages" with no compose CTA
- Loading the dashboard shows a centered spinner with no reserved height, so widgets jump in

### 📋 backlog: track, ship

Real but low-stakes. Ship, log a backlog issue, prioritize by frequency or impact later. Apply a backlog fix only when it is a one-line change in a file already being edited; otherwise leave it and log it. Backlog nits are not worth widening the diff.

Tier triggers:
- Dark mode untested (works but may have contrast issues)
- RTL not verified
- Touch-vs-pointer affordances slightly misaligned (hover hint visible on touch device but doesn't break function)
- Container queries not used where they would help
- 1px / spacing-token nits

## Tier assignment rules

When a rule's default tier conflicts with surface context, use the higher tier:

| Surface context | Default tier upgrades to |
|---|---|
| Sign-in / sign-up | Bump 1 tier (sprint → blocker; backlog → sprint) |
| Checkout / payment | Bump 1 tier: money flows are unforgiving |
| Account deletion / data export | Bump 1 tier: destructive |
| Authenticated app shell | Same |
| Marketing landing page | Down 1 tier (blocker → sprint; sprint → backlog): usually no data on the line |
| Internal admin tool | Down 1 tier: different audience tolerance |

## Verdict logic

Aggregate the tiers of the findings still present at the end of the run. Findings the audit fixed in the pass do not count toward the verdict; findings it could not fix, including ones whose fix falls outside the audited files, do.

| Verdict | Condition |
|---|---|
| ✅ READY | 0 remaining release-blockers AND ≤3 remaining fix-this-sprint |
| ⚠️ READY WITH FOLLOW-UP | 0 remaining release-blockers AND ≥4 remaining fix-this-sprint |
| ❌ NOT READY | ≥1 remaining release-blocker |
| 🚫 INCOMPLETE | Audit-self-check failed; re-run |

Verdict shows in the summary block atop every audit report, under the found / applied / remaining counts, so a reader can see both what the code arrived as and what it ships as.

## Anti-patterns

- ❌ **Tier inflation**: marking every finding `release-blocker`. Kills signal; reserve it for genuine ship-blockers.
- ❌ **Tier deflation**: dumping everything to `backlog` for a greener verdict. Catches up at the next prod incident.
- ❌ **Tier per rule, not per finding**: a default tier is a starting point; surface context bumps it up or down.
- ❌ **Skipping the override step**: justify every tier in the output ("release-blocker because checkout flow"). Never render bare tiers.
- ❌ **Fixing quietly to reach green**: an applied fix that isn't reported is indistinguishable from a missed finding. Every fix names the file, the lines, and the edit, so the verdict can be walked against the diff.
- ❌ **Downgrading a tier because the fix was hard**: an out-of-scope release-blocker is still a release-blocker, and the verdict stays ❌ NOT READY until a human decides on the shared component.

## Examples

Two tier assignments worth stating, both about the bump rules above rather than about JSON shape:

- A `forms-lost-data-on-error` finding on a checkout surface bumps to release-blocker, and being fixed in the same pass does not lower it. It counts as a found release-blocker and an applied one, and the verdict reads `remaining`, so it does not hold the ship.
- A `dark-i18n-untested` finding on an internal admin surface bumps down to backlog. Four of those do not make a `READY_WITH_FOLLOW_UP`, because that threshold counts remaining fix-this-sprint findings, not backlog ones.

The emitted object's shape, including every field these two would show, is owned by `references/output-adapters.md`. It is not repeated here: two files describing one JSON shape is how the two drift apart.

# States Coverage

The highest-leverage check: every component that fetches data, takes input, or runs a transient process needs a full set of states. The commonest production UX bug is a happy-path-only component missing `loading`, `empty`, or `error`. Per-rule detection greps live in the `rules/states-*` and `rules/forms-*` files; this reference is the coverage map, not a second copy of those greps.

## Table of contents

- [Canonical state matrix per component type](#canonical-state-matrix-per-component-type)
- [Mandatory state pairings](#mandatory-state-pairings)

## Canonical state matrix per component type

Each component type must implement these states (or mark N/A with a comment). Trimmed to the four types the feature playbooks dispatch on; button/input/toast state details live in the `rules/interaction-*`, `rules/forms-*`, and `rules/nav-*` rules.

### Async data fetcher (list, dashboard widget, search)

| State | What user sees | Pass | Fail |
|---|---|---|---|
| `loading` | Skeleton matching loaded layout (CLS-safe) | `<Skeleton h="N">` with `min-height` ≥ loaded height | Centered spinner without `min-height` |
| `empty` | Helpful guidance + primary CTA | "No invoices yet" + `<Button>Create invoice</Button>` | "No items" with no CTA |
| `error` | Cause + retry path + preserved input (if any) | "Couldn't load: Try again" with retry handler | Generic toast that disappears |
| `success` | Loaded data | Default render | - |
| `partial` (paginated/infinite) | Loaded prefix + spinner for next | Skeleton row at bottom for pending page | Layout jump on next-page load |

### Form

| State | What user sees | Pass | Fail |
|---|---|---|---|
| `idle` | Default form, fields empty or autofilled | - | - |
| `pending` | Submit disabled + visible pending indicator | `useFormStatus().pending` drives `disabled` + `aria-busy`, label stays stable | No disable; double-submit possible |
| `error` | Field-level errors + values preserved | `useActionState` `state.errors` + `state.fields` | Form clears on error |
| `success` | Confirmation; route forward or reset | Named completion screen | Generic toast then redirect |

### Modal / Dialog

| State | What user sees | Pass | Fail |
|---|---|---|---|
| `closed` | Trigger button | - | - |
| `opening` | Animation, focus moves to first focusable | `autoFocus` or `initialFocus` set | Focus on `<body>` |
| `open` | Modal content; Esc + backdrop close | `onEscapeKeyDown` + `onPointerDownOutside` handled | Cannot dismiss without confirm-button |
| `closing` | Animation, focus returns to trigger | `onCloseAutoFocus` set OR `triggerRef.focus()` in `onClose` | Focus to `<body>` (lost) |
| `unmounted` | Trigger button regains focus | Same as closed | - |

### List / Feed / Table

| State | What user sees | Pass | Fail |
|---|---|---|---|
| `loading` | N skeleton rows matching item layout | `Array.from({length: 5}, …)` of `<RowSkeleton>` | Spinner centered above empty area |
| `empty` | Helpful empty + create CTA | "No invoices yet: Create one" | "No items" |
| `error` | Cause + retry | "Couldn't load: Try again" | Generic toast |
| `partial` (pagination/infinite) | Loaded prefix + spinner row | `<RowSkeleton />` at end | Page jumps when next loads |
| `populated` | Items rendered | - | - |

## Mandatory state pairings

These pairs always go together; one without the other is the bug that ships to production. Pairings a rule owns are checked there (`states-no-empty-state`, `states-no-error-state`, `states-layout-shift`, `forms-lost-data-on-error`, `forms-no-disable-while-submitting`, `async-optimistic-without-rollback`, `a11y-color-only-meaning`, `nav-live-region-feedback`, `focus-broken-focus-trap`, `focus-not-restored`). The rest are coverage, not extra findings.

| Pair | Why they pair | Bug if violated |
|---|---|---|
| `loading` ↔ skeleton with `min-height` | CLS-safe | Skeleton renders at 0×0, then jumps to full content on data arrival (Lighthouse CLS) |
| `empty` ↔ primary CTA | Empty without next-step is a dead-end | "No items" with no CTA; user stalls |
| `error` ↔ retry path | Errors without recovery are dead-ends | "Something went wrong" with no action; user reloads or leaves |
| `error` ↔ preserved input | Re-entering data is hostile | Form clears on 422; user abandons |
| `disabled` ↔ explanation | Mystery disabled buttons confuse | No `aria-disabled` or tooltip; user can't unblock self |
| `pending` ↔ disabled submit | Otherwise double-submit | User clicks twice; backend gets a duplicate record |
| `optimistic` ↔ rollback | Otherwise inconsistent state | Server returns 422; UI keeps the optimistic value until a reload reveals the truth |
| `destructive` ↔ confirm or undo | Mistakes are unrecoverable; a reversible action earns undo instead of a dialog | Data loss with no undo |
| `color-state` ↔ icon/text | Color blindness | Red border without icon or `aria-invalid`; ~8% of users miss the signal |
| `toast` ↔ `aria-live` | SR users miss async alerts | No `aria-live`; screen-reader and slow readers miss a 3 s toast |
| `dialog open` ↔ focus moves in | Keyboard users lose context | Tab key escapes the modal |
| `dialog close` ↔ focus restored | Keyboard users lose their place | Focus lands on `<body>`; Tab restarts from the top |

---
title: Avoid Color-Only Meaning
id: a11y-color-only-meaning
category: a11y
defaultTier: release-blocker
detect: static
---

## Avoid Color-Only Meaning

State carried by hue alone (a red row, a green dot, a colored border) is invisible to color-blind users and on washed-out screens. Pair color with text, an icon, or shape. Contrast ratios are axe's job, not this rule's.

## Detection

Search for conditional `className` expressions whose branches differ only in a semantic hue; a hit is confirmed when nothing else in the element changes with the same condition (no text, icon, or shape).

```bash
rg -nP '\?[^:]*\b(text|bg|border)-(red|green|amber|emerald|rose|yellow)-\d' -g '*.tsx' -g '*.jsx' src/
```

An element that already pairs the hue with a label or icon matches too, since the grep only sees the class. Read the rest of the element: if the same condition also drives a `<Badge>`, an icon swap, or `aria-label` text, the state has a second channel and it passes.

**Incorrect (status is hue only):**

```tsx
<td className={run.failed ? 'text-red-700' : 'text-green-700'}>{run.name}</td>
```

**Correct (same color, state also in text):**

```tsx
<td className={run.failed ? 'text-red-700' : 'text-green-700'}>
  {run.name} <Badge>{run.failed ? 'Failed' : 'Passed'}</Badge>
</td>
```

---
title: Mark Up Data Tables With Real Table Semantics
id: a11y-data-table-semantics
category: a11y
defaultTier: release-blocker
detect: static
---

## Mark Up Data Tables With Real Table Semantics

Tabular data needs a real `<table>` with `<caption>`, header cells, and `scope`. Divs styled as a grid carry no row/column relationships, so screen readers read cells as a flat list. (Layout-only grids use CSS, not `<table>`.)

## Detection

Find files that render a table and never declare header semantics; a hit is confirmed when the first row holds column labels but no `<caption>` or `<th scope>` exists.

```bash
rg -lP '<table\b|role="(table|grid)"' -g '*.tsx' -g '*.jsx' src/ \
| xargs -r rg --files-without-match -P '<caption\b|scope="(col|row)"'
```

A call site that renders a shared `<DataTable>` matches while the `th` and `scope` live in the library component, so read the imported component before reporting. Div grids styled as tables do not match at all (`grid-cols-*` is layout markup too often to grep), so scan grid containers whose first row is a set of column labels by eye.

**Incorrect (div grid, no header semantics):**

```tsx
<div className="grid">
  <div>Name</div><div>Role</div>
  <div>Ada</div><div>Engineer</div>
</div>
```

**Correct (caption, header cells, scope):**

```tsx
<table>
  <caption>Team members</caption>
  <thead>
    <tr><th scope="col">Name</th><th scope="col">Role</th></tr>
  </thead>
  <tbody>
    <tr><th scope="row">Ada</th><td>Engineer</td></tr>
  </tbody>
</table>
```

---
title: Do not put tooltips on disabled controls
id: a11y-disabled-control-tooltip
category: a11y
defaultTier: fix-this-sprint
detect: static
related: a11y-icon-controls-labeled, a11y-tooltip-no-interactive
---

## Do not put tooltips on disabled controls

A tooltip on a `disabled` button never reaches keyboard or screen-reader users: disabled controls are omitted from the tab order, so the reason the action is blocked is invisible. Mouse users see a hover hint; everyone else hits a dead control with no explanation.

Wrap the control and put the message on the wrapper, or keep the control enabled and handle the blocked action with an inline error. Do not use `pointer-events-none` on the button plus a tooltip on a parent as a substitute unless the parent is focusable and named.

## Detection

Search for `disabled` on a control that sits inside a tooltip trigger, or a tooltip whose child is a disabled button.

```bash
rg -nUP '<[^>]*\bdisabled\b[^>]*>[\s\S]{0,400}<(Tooltip|HoverCard)' -g '*.tsx' -g '*.jsx' src/
rg -nUP '<(Tooltip(Trigger)?|HoverCard)[^>]*>[\s\S]{0,500}\bdisabled\b' -g '*.tsx' -g '*.jsx' src/
```

A native `title` on a disabled button matches the same failure. Skip `aria-disabled="true"` controls that remain focusable and expose the reason via `aria-describedby`.

**Incorrect (tooltip on a disabled button):**

```tsx
<Tooltip content="You need billing access">
  <button type="button" disabled>
    Invoice
  </button>
</Tooltip>
```

**Correct (focusable wrapper carries the message):**

```tsx
<Tooltip content="You need billing access">
  <span tabIndex={0} className="inline-flex">
    <button type="button" disabled>
      Invoice
    </button>
  </span>
</Tooltip>
```

---
title: Declare Document and Inline Language
id: a11y-document-language
category: a11y
defaultTier: release-blocker
detect: static
---

## Declare Document and Inline Language

Set the primary language on `<html lang>` with a valid BCP 47 tag, and mark any inline passage in another language with its own `lang`. Without it, a screen reader reads everything with one pronunciation engine.

## Detection

Search for the root `<html>` element with no `lang` attribute; a single hit confirms it, since an app has one root layout.

```bash
rg -nUP '<html(?![^>]*\blang=)[^>]*>' -g '*.tsx' -g '*.jsx' -g '*.html' .
```

A root layout that spreads its attributes (`<html {...htmlProps}>`) or takes the locale from i18n middleware matches without being broken. Confirm against the served page source before reporting.

**Incorrect (no document language, foreign phrase unmarked):**

```html
<html>
  <body><p>The chef called it a <em>coup de grâce</em>.</p></body>
</html>
```

**Correct (document and inline language declared):**

```html
<html lang="en">
  <body><p>The chef called it a <em lang="fr">coup de grâce</em>.</p></body>
</html>
```

---
title: Label Icon-Only Controls
id: a11y-icon-controls-labeled
category: a11y
defaultTier: fix-this-sprint
detect: static
---

## Label Icon-Only Controls

Any control with no visible text requires an accessible name. Without one, assistive tech announces nothing usable and the control cannot be identified.

## Detection

Search for buttons whose only child is an icon component and that carry no `aria-label`, `aria-labelledby`, or `title`; a hit is confirmed when the button renders no text node at all.

```bash
rg -nUP '<button\b(?![^>]*(aria-label|aria-labelledby|title=))[^>]*>\s*<[A-Z][\w.]*[^>]*/>\s*</button>' -g '*.tsx' -g '*.jsx' src/
```

Some icon libraries build the accessible name from a prop on the icon itself (`<XIcon title="Close" />`), which matches here but passes. Open the icon component: if it renders a `<title>` or `sr-only` text, the button already has a name.

**Incorrect (no accessible name):**

```tsx
<button onClick={closeModal}>
  <XIcon />
</button>
```

**Correct (explicit label):**

```tsx
<button type="button" aria-label="Close dialog" onClick={closeModal}>
  <XIcon aria-hidden="true" />
</button>
```

---
title: Give Every Image a Correct Alt Attribute
id: a11y-image-alt-text
category: a11y
defaultTier: release-blocker
detect: static
---

## Give Every Image a Correct Alt Attribute

Every `<img>` needs an `alt`: describe the purpose for informative images, use an empty `alt=""` for decorative ones so screen readers skip them. A missing `alt` makes the file name get read aloud. The `alt` is also what renders when the image itself fails to load.

## Detection

Search for `<img>` tags with no `alt` attribute anywhere in the tag, including tags split across lines.

```bash
rg -nUP '<img\b(?![^>]*\balt=)[^>]*>' -g '*.tsx' -g '*.jsx' -g '*.html' src/
```

A wrapper that forwards props (`<img {...rest} />`) matches while every call site passes `alt`, so check the callers before reporting. The grep also cannot judge an `alt` that exists but is wrong, so read the decorative images separately: `alt="decorative swirl divider"` needs to become `alt=""`.

**Incorrect (missing alt, and decorative image announced):**

```tsx
<img src="/chart.png" />
<img src="/divider.svg" alt="decorative swirl divider" />
```

**Correct (purpose described; decorative image silenced):**

```tsx
<img src="/chart.png" alt="Revenue grew 40% from Q1 to Q2" />
<img src="/divider.svg" alt="" />
```

---
title: Caption Video and Transcribe Audio
id: a11y-media-captions
category: a11y
defaultTier: release-blocker
detect: static
---

## Caption Video and Transcribe Audio

Deaf and hard-of-hearing users get nothing from uncaptioned media. Video needs synchronised captions via `<track kind="captions">`; audio-only needs a text transcript. Auto-generated captions alone are not sufficient for meaning-critical media.

## Detection

Find files that render `<video>` or `<audio>` and never ship a captions track; a hit is confirmed when the media carries speech or meaning-critical sound.

```bash
rg -lP '<video\b|<audio\b' -g '*.tsx' -g '*.jsx' src/ \
| xargs -r rg --files-without-match -P 'kind="captions"'
```

A muted decorative background loop has no audio to caption and is not a finding. A shared player component that injects its own `<track>` also matches at each call site, so read the player before reporting.

**Incorrect (video with no captions track):**

```tsx
<video src="/demo.mp4" controls />
```

**Correct (captions track + transcript link):**

```tsx
<video controls>
  <source src="/demo.mp4" type="video/mp4" />
  <track kind="captions" src="/demo.en.vtt" srcLang="en" label="English" default />
</video>
<a href="/demo-transcript">Read the transcript</a>
```

---
title: Prefer Native Semantics Before ARIA
id: a11y-semantic-html-first
category: a11y
defaultTier: release-blocker
detect: static
---

## Prefer Native Semantics Before ARIA

Use semantic HTML controls first; only add ARIA when native elements cannot express intent. Rebuilding those semantics in ARIA reimplements keyboard behaviour, role, and state by hand, and any gap leaves assistive tech reporting the wrong thing.

## Detection

Search for click handlers attached to non-interactive elements; a hit is confirmed when that element is the only way to trigger the action.

```bash
rg -nUP '<(div|span|li|td)\b[^>]*\bonClick=' -g '*.tsx' -g '*.jsx' src/
```

A full-bleed overlay whose `onClick` only dismisses a modal matches but is legitimate: the action is also reachable from a real `<button>` inside, and Escape covers the keyboard path. Tell them apart by asking whether removing the handler would strand the user.

**Incorrect (clickable div):**

```tsx
<div onClick={submitForm}>Save</div>
```

**Correct (semantic button):**

```tsx
<button type="button" onClick={submitForm}>Save</button>
```

---
title: Provide Skip Link and Logical Heading Order
id: a11y-skip-link-heading-order
category: a11y
defaultTier: fix-this-sprint
detect: static
---

## Provide Skip Link and Logical Heading Order

Include a skip link and keep heading levels sequential. Without both, keyboard and screen reader users walk the whole header on every page and lose the outline they navigate by.

## Detection

Find files that render `<main>` with no in-page anchor above it; a hit is confirmed when no layout wrapping that file provides one either.

```bash
rg -lP '<main\b' -g '*.tsx' -g '*.jsx' src/ | xargs -r rg --files-without-match -P 'href="#'
```

The skip link usually lives in the root layout rather than the file rendering `<main>`, so every page component matches until you check the layout above it. Heading order is not in this recipe on purpose: a component that starts at `<h2>` is correct when the page supplies the `<h1>`, so read the composed page outline for that half.

**Incorrect (no skip link, jumps heading levels):**

```tsx
<main>
  <h1>Dashboard</h1>
  <h4>Recent activity</h4>
</main>
```

**Correct (skip link + ordered headings):**

```tsx
<a className="skip-link" href="#main-content">Skip to content</a>
<main id="main-content">
  <h1>Dashboard</h1>
  <h2>Recent activity</h2>
</main>
```

---
title: Hover tooltips must not contain interactive content
id: a11y-tooltip-no-interactive
category: a11y
defaultTier: fix-this-sprint
detect: static
related: a11y-disabled-control-tooltip, interaction-keyboard-operable
---

## Hover tooltips must not contain interactive content

A hover tooltip that contains a link, button, or input cannot be used with a keyboard or a touch screen, and it vanishes when the pointer moves to reach the inner control. Users see an action they cannot activate reliably.

Put actions in a focusable popover, dropdown, or dialog that opens on click or keyboard. Hover tooltips are for short non-interactive names and descriptions.

## Detection

Search tooltip content slots for nested interactive elements.

```bash
rg -nUP '<(Tooltip(Content)?|HoverCard(Content)?)[^>]*>[\s\S]{0,800}<(button|a |input|select|textarea)\b' -g '*.tsx' -g '*.jsx' src/
```

Radix/Base UI `Popover` and `DropdownMenu` match similar names but are click/keyboard surfaces: skip those. A single icon that is `aria-hidden` decoration inside the tooltip is not interactive.

**Incorrect (button inside a hover tooltip):**

```tsx
<Tooltip>
  <TooltipTrigger>Plan</TooltipTrigger>
  <TooltipContent>
    Pro includes SSO.
    <button type="button" onClick={upgrade}>
      Upgrade
    </button>
  </TooltipContent>
</Tooltip>
```

**Correct (actions live in a popover):**

```tsx
<Popover>
  <PopoverTrigger>Plan</PopoverTrigger>
  <PopoverContent>
    Pro includes SSO.
    <button type="button" onClick={upgrade}>
      Upgrade
    </button>
  </PopoverContent>
</Popover>
```

---
title: Async tree without an error boundary
id: async-no-error-boundary
category: async
defaultTier: release-blocker
detect: static
related: async-no-suspense-boundary, states-no-error-state, microcopy-leaked-error-message
---

## Async tree without an error boundary

A thrown error in a server component or client async tree with no ancestor error boundary unmounts the whole route: a blank page in production, a stack trace in dev. Every route segment and every independently-fetching widget needs its own boundary so one failure does not take the page down.

## What goes wrong

A widget fetch returns 500. With no boundary, the error bubbles past page and layout and unmounts everything to the nearest boundary (usually root). A user mid-checkout now sees a blank screen with no recovery path.

## Detection

**Surfaces:** dashboard, list, checkout, sign-in, error-state, modal (anything that fetches data or runs server actions).

**Static signals:**
1. List App Router segments: `find app src/app -type f \( -name 'page.tsx' -o -name 'layout.tsx' \) 2>/dev/null`.
2. Check each segment for a sibling `error.tsx`.
3. Find client components using `useQuery`, `fetch`, `useSWR`, or server actions; confirm an `<ErrorBoundary>` ancestor.
4. Flag segments with awaits but no `error.tsx`, and any client async tree with no boundary.

**Concrete commands:**
```bash
# Route segments lacking error.tsx
find app src/app -type f -name 'page.tsx' 2>/dev/null | while read p; do
  dir=$(dirname "$p")
  [ ! -f "$dir/error.tsx" ] && echo "$dir: no error.tsx"
done

# Root-level global-error.tsx
find app src/app -type f -name 'global-error.tsx' 2>/dev/null | grep -q . || echo 'missing global-error.tsx'

# Client components with fetches but no ErrorBoundary import
rg "useQuery|useSWR|'use client'" --type=ts -l | while read f; do
  rg -q 'ErrorBoundary' "$f" || echo "$f: client async tree without local ErrorBoundary"
done
```

**False-positive guards:**
- Skip leaf segments inherited from a parent that defines `error.tsx` (App Router cascades).
- Skip components inside Storybook (`*.stories.tsx`).
- Skip files annotated `// ui-audit-ignore:async-no-error-boundary`.

## Fix

Add an `error.tsx` per route segment with a `reset()` button. For client trees, wrap in `react-error-boundary`'s `<ErrorBoundary>`.

```tsx
// app/dashboard/error.tsx
'use client';

import { useEffect } from 'react';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    console.error(error);
  }, [error]);

  return (
    <div role="alert">
      <h2>Couldn&apos;t load your dashboard</h2>
      <p>We&apos;ve logged this. Try again?</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}
```

```tsx
// client-side widget boundary
import { ErrorBoundary } from 'react-error-boundary';

<ErrorBoundary
  fallbackRender={({ error, resetErrorBoundary }) => (
    <WidgetError onRetry={resetErrorBoundary} />
  )}
>
  <BillingWidget />
</ErrorBoundary>;
```

Docs:
- Next.js error.tsx: https://nextjs.org/docs/app/api-reference/file-conventions/error
- Next.js global-error.tsx: https://nextjs.org/docs/app/getting-started/error-handling
- react-error-boundary: https://github.com/bvaughn/react-error-boundary

## Default tier and overrides

**Defaults to:** `release-blocker`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Sign-up | release-blocker |
| Checkout | release-blocker |
| Dashboard widget (per-widget) | release-blocker |
| Marketing landing | fix-this-sprint |
| Internal admin | fix-this-sprint |

## Defer-to (when this is another tool's job)

- Sentry / Vercel Observability for error capture and alerting.
- Vercel Agent for surfacing failing routes in PR review.
- Lighthouse cannot detect this; it's a runtime concern.

## Suppression

```tsx
{/* ui-audit-ignore:async-no-error-boundary, covered by parent layout error.tsx */}
<Widget />
```

---
title: Async server component without Suspense boundary
id: async-no-suspense-boundary
category: async
defaultTier: fix-this-sprint
detect: static
related: states-layout-shift, async-no-error-boundary
---

## Async server component without Suspense boundary

In the App Router and React 19, an async server component with no enclosing `<Suspense>` boundary blocks the whole route from streaming. Users wait for the slowest fetch before seeing anything: no shell, no skeleton, no progressive paint. Wrap the slow async tree in `<Suspense fallback={...}>` to unblock the rest of the page.

## What goes wrong

Page renders four widgets; one calls a slow third-party API. With no Suspense boundary, the whole route hangs on that fetch. TTFB explodes, the user sees a blank screen, and nothing paints until the slowest dependency resolves.

## Detection

**Surfaces:** dashboard, list, search, loading-state, checkout, onboarding (anywhere server-fetched data renders).

**Static signals:**
1. Find async server components: `rg '^export (default )?async function' --type=ts app/ src/app/`.
2. For each, walk up the tree to check whether the parent renders it inside `<Suspense>`.
3. Confirm the route segment lacks a `loading.tsx` (Next.js auto-wraps the segment in Suspense when present).
4. Flag if neither a `<Suspense>` ancestor nor a sibling `loading.tsx` exists.

**Concrete commands:**
```bash
# Async server components in the App Router
rg '^export (default )?async function' --type=ts app/ src/app/ -l

# Files that import Suspense
rg "from 'react'" --type=ts -l | while read f; do
  rg -l 'Suspense' "$f"
done

# Routes missing loading.tsx
find app src/app -type f -name 'page.tsx' 2>/dev/null | while read p; do
  dir=$(dirname "$p")
  [ ! -f "$dir/loading.tsx" ] && echo "$dir: no loading.tsx"
done
```

**False-positive guards:**
- Skip if a `loading.tsx` exists at any ancestor segment; Next.js wraps the segment in Suspense automatically.
- Skip if the component is a leaf and renders inline static markup (no awaits).
- Skip files annotated `// ui-audit-ignore:async-no-suspense-boundary`.

## Fix

Wrap the slow async tree in `<Suspense>` with a skeleton fallback that matches the loaded layout (CLS-safe).

```tsx
// before: entire dashboard waits for SlowWidget
export default async function DashboardPage() {
  return (
    <main>
      <FastWidget />
      <SlowWidget /> {/* awaits a 3s API */}
      <AnotherWidget />
    </main>
  );
}

// after: SlowWidget streams in; rest of the page paints immediately
import { Suspense } from 'react';

export default function DashboardPage() {
  return (
    <main>
      <FastWidget />
      <Suspense fallback={<SlowWidgetSkeleton />}>
        <SlowWidget />
      </Suspense>
      <AnotherWidget />
    </main>
  );
}
```

Docs:
- React: https://react.dev/reference/react/Suspense
- Next.js streaming: https://nextjs.org/docs/app/getting-started/fetching-data
- Next.js loading.tsx: https://nextjs.org/docs/app/api-reference/file-conventions/loading

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Dashboard with >2 widgets | release-blocker |
| Checkout / Sign-in | release-blocker (TTFB on critical path) |
| Marketing landing | fix-this-sprint |
| Internal admin | backlog |

## Defer-to (when this is another tool's job)

- Lighthouse for measured TTFB / LCP regressions.
- Vercel Speed Insights for field measurement of streaming impact.
- ESLint plugin `eslint-plugin-react-server-components` for write-time checks.

## Suppression

```tsx
{/* ui-audit-ignore:async-no-suspense-boundary, leaf is sync, no await */}
<StaticWidget />
```

---
title: Optimistic update without rollback on server reject
id: async-optimistic-without-rollback
category: async
defaultTier: release-blocker
detect: static
related: states-no-error-state, microcopy-leaked-error-message
---

## Optimistic update without rollback on server reject

`useOptimistic` shows the post-action state immediately (liked post, cart item added, renamed file). Contract: on server reject (422, 500, network error) the UI must roll back to real server state, or it lies and a reload reveals the truth, costing trust. Second half of the contract: optimistic updates **must** run inside `startTransition` (or an action, which React wraps in one), or React warns and the optimistic value renders for one frame and reverts, so the feature looks like a flicker rather than an update.

## What goes wrong

Click "Like," UI flips to liked, server rejects (rate-limited), the handler swallows the error so the optimistic state never reverts. Reload: the like is gone and the user thinks the product is broken. Worse: calling the setter outside `startTransition` logs "An optimistic state update occurred outside a Transition or Action. To fix, move the update to an Action, or wrap with startTransition" and the optimistic value never sticks, so the UI flickers and the update looks broken in every environment except the one where someone reads the console.

## Detection

**Surfaces:** checkout (cart updates), list (inline edits, likes, reorder), form (instant rename), dashboard (toggle widgets), modal (in-modal saves).

**Static signals:**
1. `rg 'useOptimistic' --type=ts -l`: find all callers.
2. Confirm each optimistic dispatch sits inside `startTransition`, a `useTransition` action, `<form action>`, or an async server action.
3. Confirm the handler has `try { ... } catch` that re-throws or signals failure (React then auto-reverts), or an explicit revert call.
4. Confirm a user-facing error UI (toast, inline) appears on failure.

**Concrete commands:**
```bash
# All optimistic call sites
rg 'useOptimistic\b' --type=ts -l

# Optimistic without startTransition / action context
rg -l 'useOptimistic\b' --type=ts src/ app/ | while read f; do
  rg -A 10 'useOptimistic\b' "$f" | rg -q 'startTransition|useTransition|action=' \
    || echo "$f: optimistic update outside transition or action context"
done

# Optimistic without catch / rollback / onError
rg 'useOptimistic\b' --type=ts -l | while read f; do
  rg -q 'catch|onError|throw' "$f" || echo "$f: optimistic with no error path"
done
```

**False-positive guards:**
- Skip server actions invoked via `<form action={fn}>`: React auto-reverts when the action throws.
- Skip files annotated `// ui-audit-ignore:async-optimistic-without-rollback`.
- Skip Storybook fixtures.

## Fix

Apply optimistic updates inside `startTransition`; let the action throw on failure so React reverts; surface a toast or inline error.

```tsx
// before: silent lie on reject
'use client';
function Likes({ post }: { post: Post }) {
  const [optimistic, setOptimistic] = useOptimistic(post.likes);
  return (
    <button
      onClick={async () => {
        setOptimistic(optimistic + 1); // ❌ outside transition
        await likePost(post.id);        // ❌ failure silently kept optimistic
      }}
    >
      Like ({optimistic})
    </button>
  );
}

// after: rollback on reject + transition + error UI
'use client';
import { useOptimistic, useTransition } from 'react';
import { toast } from 'sonner';

function Likes({ post }: { post: Post }) {
  const [optimistic, addOptimistic] = useOptimistic(
    post.likes,
    (current, delta: number) => current + delta,
  );
  const [pending, startTransition] = useTransition();

  return (
    <button
      disabled={pending}
      onClick={() =>
        startTransition(async () => {
          addOptimistic(1);
          try {
            await likePost(post.id);
          } catch (err) {
            // throwing reverts the optimistic state automatically
            toast.error('Could not like, try again');
            throw err;
          }
        })
      }
    >
      Like ({optimistic})
    </button>
  );
}
```

Docs:
- React useOptimistic: https://react.dev/reference/react/useOptimistic
- React useTransition: https://react.dev/reference/react/useTransition
- Next.js server functions (the action the optimistic update wraps): https://nextjs.org/docs/app/getting-started/mutating-data

## Default tier and overrides

**Defaults to:** `release-blocker`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Checkout (cart total) | release-blocker (financial truth) |
| Form (rename, edit) | release-blocker |
| List (likes, reorder) | release-blocker |
| Dashboard toggle | fix-this-sprint |
| Internal admin | fix-this-sprint |

## Defer-to (when this is another tool's job)

- TanStack Query: its own `onMutate`/`onError` rollback if the project uses it.
- Sentry: capturing the thrown errors.
- Vercel Agent: review-time spotting of missing `try`/`catch`.

## Suppression

```tsx
{/* ui-audit-ignore:async-optimistic-without-rollback, operation is idempotent and
    server return is authoritative on next render */}
```

---
title: Out-of-order async responses (stale results)
id: async-out-of-order-responses
category: async
defaultTier: release-blocker
detect: static
related: async-no-suspense-boundary
---

## Out-of-order async responses (stale results)

Type "ca" then "cat" quickly: two requests fly. On a slow network the "ca" response can land after "cat", so the UI shows "ca" results while the input says "cat." Fix: cancel in-flight requests with `AbortController`, or drive the request key with `useDeferredValue` so React collapses to the latest value.

## What goes wrong

A search input fetches on every keystroke over a jittery network. The "iphon" response lands after "iphone", overwriting the iphone results with iphon results. It looks broken, yet intermittently looks correct, so it is hard to reproduce.

## Detection

**Surfaces:** search (highest priority), list filter, form async-validation, dashboard with a date-range picker that refetches.

**Static signals:**
1. `rg 'onChange|onInput' --type=ts -A 5`: find handlers containing `fetch(`, `useQuery`, or any async call.
2. For each, confirm one of:
   - `AbortController` created, `signal` passed to fetch, aborted on the next call or in `useEffect` cleanup.
   - `useDeferredValue` drives the request key (React debounces).
   - A query library (TanStack Query, SWR) keys the request so the latest wins.
3. Flag handlers that fetch without any of the above.

**Concrete commands:**
```bash
# onChange/onInput handlers that fetch
rg -A 8 'onChange=|onInput=' --type=ts | rg -B 2 'fetch\(|useQuery\(|axios\.'

# Files using fetch in inputs without AbortController
rg 'onChange|onInput' --type=ts -l | while read f; do
  rg -q 'AbortController|useDeferredValue|signal:' "$f" || echo "$f: input fetch with no cancellation"
done

# useEffect with fetch but no cleanup
rg -l 'useEffect\(' --type=ts src/ app/ | while read f; do
  rg -A 10 'useEffect\(' "$f" | rg -q 'fetch\(' \
    && ! rg -q 'return \(\) =>|abort\(\)' "$f" \
    && echo "$f: useEffect fetch without cleanup or abort"
done
```

**False-positive guards:**
- Skip handlers whose only fetch is a fire-and-forget mutation (POST without rendering the response).
- Skip when a query library is in use and the query key includes the input value (TanStack Query, SWR keep the freshest).
- Skip files annotated `// ui-audit-ignore:async-out-of-order-responses`.

## Fix

Two canonical approaches.

**A. AbortController in `useEffect`**, best for plain `fetch` driven by state:

```tsx
// before: race condition
function Search({ q }: { q: string }) {
  const [results, setResults] = useState<Item[]>([]);
  useEffect(() => {
    fetch(`/api/search?q=${q}`).then((r) => r.json()).then(setResults);
  }, [q]);
  return <Results items={results} />;
}

// after: abort on re-render or unmount
function Search({ q }: { q: string }) {
  const [results, setResults] = useState<Item[]>([]);
  useEffect(() => {
    const controller = new AbortController();
    fetch(`/api/search?q=${q}`, { signal: controller.signal })
      .then((r) => r.json())
      .then(setResults)
      .catch((err) => {
        if (err.name !== 'AbortError') throw err;
      });
    return () => controller.abort();
  }, [q]);
  return <Results items={results} />;
}
```

**B. `useDeferredValue` + Suspense**, React keeps the latest:

```tsx
function SearchPage({ q }: { q: string }) {
  const deferred = useDeferredValue(q);
  return (
    <Suspense fallback={<Results.Skeleton />}>
      <Results key={deferred} q={deferred} />
    </Suspense>
  );
}
```

Docs:
- React useDeferredValue: https://react.dev/reference/react/useDeferredValue
- AbortController: https://developer.mozilla.org/en-US/docs/Web/API/AbortController
- TanStack Query cancellation: https://tanstack.com/query/latest/docs/framework/react/guides/query-cancellation

## Default tier and overrides

**Defaults to:** `release-blocker` for search; `fix-this-sprint` elsewhere.

**Surface overrides:**
| Surface | Tier |
|---|---|
| Search / Combobox | release-blocker |
| Async form validation | fix-this-sprint |
| Dashboard date-range refetch | fix-this-sprint |
| Marketing | backlog |

## Defer-to (when this is another tool's job)

- TanStack Query / SWR: built-in cancellation; verify it's wired up rather than re-implementing.
- ESLint `react-hooks/exhaustive-deps` for missing cleanup.
- Lighthouse / Vercel Speed Insights for INP impact (out-of-order also wastes bandwidth).

## Suppression

```tsx
{/* ui-audit-ignore:async-out-of-order-responses, backend is idempotent and last-wins */}
```

---
title: Layout uses physical (left/right) instead of logical (start/end) properties
id: dark-i18n-rtl-untested
category: dark-i18n
defaultTier: backlog
detect: static
related: dark-i18n-untested
---

## Layout uses physical (left/right) instead of logical (start/end) properties

Arabic, Hebrew, Persian, and Urdu read right-to-left. A layout using physical properties (`margin-left`, `padding-right`, `text-align: left`, Tailwind `ml-2`, `pr-4`, `text-left`) does not flip when document direction is `rtl`: icons land on the wrong side, "forward" chevrons point backward, padding clears the wrong edge. CSS logical properties (`margin-inline-start`, `padding-inline-end`, `text-align: start`) and Tailwind's `ms-` / `me-` / `ps-` / `pe-` / `start-` / `end-` variants flip automatically with `dir="rtl"`. The bug is silent until someone tests a Hebrew locale.

## What goes wrong

A list row renders `<Icon className="mr-2" />` before text. Under `dir="rtl"` the icon stays left of the text instead of moving to the inline-start (right in RTL). A back arrow `<ChevronLeft />` still points left though "back" in Arabic is to the right. A modal close button at `right-4 top-4` stays top-right instead of moving to top-left (the inline-end corner in RTL).

## Detection

**Surfaces:** any layout, especially navigation, list rows with icons, form-field icon adornments, modal headers, breadcrumbs.

**Static signals:**
1. Grep physical Tailwind classes with logical equivalents:
   - Margins: `\bml-`, `\bmr-` → `ms-`, `me-`
   - Padding: `\bpl-`, `\bpr-` → `ps-`, `pe-`
   - Position: `\bleft-`, `\bright-` → `start-`, `end-`
   - Text align: `text-left`, `text-right` → `text-start`, `text-end`
   - Float / clear: `float-left`, `float-right` → `float-start`, `float-end`
   - Borders: `border-l`, `border-r` → `border-s`, `border-e`
2. Grep CSS for `margin-left`, `padding-right`, `text-align: left|right`, `left: 0`, `right: 0` with no logical equivalent.
3. Check for any `dir="rtl"` test (Storybook story, Playwright fixture, layout doc).
4. Flag if physical properties are used **and** no RTL coverage exists.

**Concrete commands:**
```bash
# Tailwind physical → logical migrations
rg -n 'className="[^"]*\b(ml-|mr-|pl-|pr-|left-|right-|text-(left|right)|float-(left|right)|border-(l|r))\b' --type=ts

# Physical CSS properties
rg -n '(margin|padding)-(left|right):|text-align:\s*(left|right)' --type=css

# RTL test coverage
find . -name '*.stories.tsx' -type f -exec rg -l 'dir="rtl"|direction:\s*rtl' {} + 2>/dev/null || echo "NO RTL STORIES"
```

**False-positive guards:**
- Skip directional icons that must not flip (external-link, Latin-only brand marks); wrap with `dir="ltr"` if needed.
- Skip projects explicitly scoped to LTR-only locales (verify via i18n config).
- Skip files with `// ui-audit-ignore:dark-i18n-rtl-untested` near the match.

## Fix

Two-step: replace physical with logical properties, and add a `dir="rtl"` Storybook story (or Playwright fixture) to catch regressions.

```tsx
// before: physical, breaks in RTL
<div className="flex items-center pl-4 pr-2">
  <Icon className="mr-2" />
  <span className="text-left">{label}</span>
  <button className="ml-auto">
    <ChevronRightIcon />
  </button>
</div>

// after: logical, flips automatically
<div className="flex items-center ps-4 pe-2">
  <Icon className="me-2" />
  <span className="text-start">{label}</span>
  <button className="ms-auto">
    <ChevronRightIcon className="rtl:rotate-180" />
  </button>
</div>
```

### Which icons flip

Logical properties move an icon to the correct side; they do not decide whether the glyph itself should mirror. That is a per-icon judgement, and flipping everything is as wrong as flipping nothing.

| Flip under `dir="rtl"` | Leave alone |
| --- | --- |
| Back and forward arrows, navigation chevrons | Logos and brand marks |
| Text-block glyphs: alignment, lists, indent | Checkmarks |
| Send-style directional glyphs | Physical objects: clocks, cups, pencils |
| Speaker and volume waves, which emanate in reading direction | Media playback, where play and rewind follow tape-direction convention and stay LTR |

Judge composite icons part by part: a badge, slash, or count overlay can hold its corner while the base glyph mirrors. Apply the flip with `rtl:-scale-x-100` or `rtl:rotate-180` on the icon itself, not on its container.

For raw CSS, prefer the logical names:

```css
/* before */
.card { margin-left: 1rem; padding-right: 0.5rem; text-align: left; }

/* after */
.card {
  margin-inline-start: 1rem;
  padding-inline-end: 0.5rem;
  text-align: start;
}
```

Add an RTL story so the regression gets caught:

```tsx
// Component.stories.tsx
export const RTL: Story = {
  ...Default,
  decorators: [
    (Story) => (
      <div dir="rtl" lang="ar">
        <Story />
      </div>
    ),
  ],
};
```

For directional icons (chevrons, arrows), use Tailwind's `rtl:` variant or a `ChevronInline` component that flips by direction:

```tsx
<ChevronRightIcon className="rtl:rotate-180" />
// or
<ArrowForwardIcon /> // component reads dir from context
```

Reference docs:
- MDN CSS logical properties: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Logical_properties_and_values
- Tailwind logical-property utilities (`ps-*`, `pe-*`, `ms-*`, `me-*`): https://tailwindcss.com/docs/padding
- W3C RTL guide: https://www.w3.org/International/articles/inline-bidi-markup/

## Default tier and overrides

**Defaults to:** `backlog`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Sign-up | fix-this-sprint (when targeting MENA / IL markets) |
| Checkout | fix-this-sprint (when targeting MENA / IL markets) |
| Marketing landing | backlog |
| Internal admin | backlog |
| Any locale-aware product | fix-this-sprint |

## Defer-to (when this is another tool's job)

- **Chromatic** with an `RTL` story captures the visual flip.
- **Playwright** with `dir="rtl"` page fixture verifies layout end-to-end.
- **stylelint-use-logical** lints CSS source for physical-property usage at write time: https://github.com/csstools/stylelint-use-logical

## Suppression

```tsx
{/* ui-audit-ignore:dark-i18n-rtl-untested, directional brand icon, must not flip */}
<ExternalLinkIcon className="ml-1" />
```

---
title: Component lacks dark-mode coverage and hardcodes light tokens
id: dark-i18n-untested
category: dark-i18n
defaultTier: backlog
detect: static
related: states-layout-shift
---

## Component lacks dark-mode coverage and hardcodes light tokens

Hardcoded colors (`bg-white`, `text-black`, `#fff`, `text-gray-900`) break in dark mode: white surfaces glow on a dark background, fixed grays lose contrast, borders disappear. CSS-variable tokens (`bg-background`, `text-foreground`) make the same JSX work in both themes. The companion bug: no Storybook dark story or Chromatic dark snapshot, so the regression ships unnoticed.

## What goes wrong

A card uses `bg-white border-gray-200 text-gray-900`. In dark mode it's a white rectangle on a near-black canvas, and nothing catches it because the component's only Storybook story renders the default (light) theme.

## Detection

**Surfaces:** any UI surface, especially marketing components migrated into a dark-mode-aware product.

**Static signals:**
1. Grep for hardcoded color classes: `bg-white`, `bg-black`, `text-black`, `text-white`, `bg-gray-\d+`, `text-gray-\d+`, `border-gray-\d+`.
2. Grep for hardcoded hex/rgb in inline styles or CSS modules.
3. Confirm a `*.stories.tsx` with a dark-themed story (or Chromatic param `parameters: { backgrounds: { default: 'dark' } }`).
4. Confirm `dark:` variants exist on the offending classes.

**Concrete commands:**
```bash
# Hardcoded Tailwind tokens (likely missing dark variants)
rg -n 'className="[^"]*\b(bg-white|bg-black|text-black|text-white|bg-gray-\d{2,3}|text-gray-\d{2,3}|border-gray-\d{2,3})\b[^"]*"' --type=ts \
  | rg -v 'dark:'

# Hardcoded hex
rg -n '#(fff|000|FFF|000000|FFFFFF)\b' --type=ts --type=css

# Storybook dark coverage
find . -name '*.stories.tsx' -type f -exec rg -l 'dark|theme: ["\']dark' {} + 2>/dev/null
```

**False-positive guards:**
- Skip marketing-only directories (`app/(marketing)`) where the brand forbids dark mode; verify via the CSS entry file's `@theme` and `@custom-variant dark` lines, or a legacy `tailwind.config.*`.
- Skip illustrations, brand SVGs, and logos where fixed color is intentional.
- Skip `// ui-audit-ignore:dark-i18n-untested` near the match.

## Fix

Replace hardcoded tokens with semantic CSS variable tokens, and add a dark Storybook story.

```tsx
// before: light-only
<div className="bg-white border border-gray-200 text-gray-900 p-4 rounded-lg">
  <h3 className="text-gray-700">Title</h3>
  <p className="text-gray-500">Body</p>
</div>

// after: semantic tokens (shadcn / Blode UI convention)
<div className="bg-card border border-border text-card-foreground p-4 rounded-lg">
  <h3 className="text-foreground">Title</h3>
  <p className="text-muted-foreground">Body</p>
</div>
```

For a genuine one-off, use `dark:` variants:

```tsx
<div className="bg-white dark:bg-zinc-950 text-zinc-900 dark:text-zinc-50">
```

Add a dark Storybook story:

```tsx
// Card.stories.tsx
export const Default: Story = { args: { /* … */ } };
export const Dark: Story = {
  ...Default,
  parameters: { backgrounds: { default: 'dark' }, themes: { themeOverride: 'dark' } },
};
```

Or derive variants with `color-mix` (no second token):

```css
.surface-subtle {
  background-color: color-mix(in oklch, var(--background) 92%, var(--foreground));
}
```

Docs:
- shadcn theming via CSS variables: https://ui.shadcn.com/docs/theming
- Tailwind dark mode strategies: https://tailwindcss.com/docs/dark-mode
- MDN `color-mix()`: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/color-mix

## Default tier and overrides

**Defaults to:** `backlog`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Sign-up | fix-this-sprint (high-traffic surface) |
| Checkout | fix-this-sprint |
| Dashboard | fix-this-sprint |
| Marketing landing | backlog |
| Internal admin | backlog |

## Defer-to (when this is another tool's job)

- **Chromatic** captures the actual dark-mode regression: https://www.chromatic.com/docs/themes/
- **Storybook a11y addon** flags low-contrast pairs after the dark switch.
- **axe-core** flags contrast violations at runtime.

## Suppression

```tsx
{/* ui-audit-ignore:dark-i18n-untested, brand mark, fixed color by design */}
<svg fill="#FF6F00" />
```

---
title: Modal without working focus trap
id: focus-broken-focus-trap
category: focus
defaultTier: release-blocker
detect: static
related: focus-not-restored, focus-on-dynamic-content, states-no-error-state
---

## Modal without working focus trap

When a modal opens, Tab and Shift+Tab must cycle inside it and Esc must close it. Without a focus trap, keyboard users tab into the page behind the modal, lose context, and may not realise it is open. Hand-rolled traps almost always miss edge cases (iframes, contenteditable, dynamically-added focusables). Use a primitive that gets it right: Radix UI, react-aria, or `focus-trap-react`.

## What goes wrong

A custom `<div role="dialog">` opens. The user presses Tab; focus moves to a body link below the modal. They keep tabbing and navigate the page underneath, hidden by the scrim. Total disorientation. Screen-reader users fare worse: VoiceOver navigates the entire DOM, ignoring the modal.

## Detection

**Surfaces:** modal, sheet, drawer, popover, command-palette.

**Static signals:**
1. `rg 'role="dialog"|role="alertdialog"' --type=ts -l`: find all dialog markup.
2. For each file, confirm one of these imports/usages:
   - `@radix-ui/react-dialog` (built-in trap).
   - `react-aria` / `react-aria-components` (built-in trap).
   - `focus-trap-react` (`<FocusTrap>`).
   - Headless UI `<Dialog>`.
3. Flag any `role="dialog"` markup with no trap library import.
4. Bonus: confirm Esc closes the modal (`onKeyDown` for Escape OR primitive's built-in).

**Concrete commands:**
```bash
# Hand-rolled dialogs
rg 'role="(dialog|alertdialog)"' --type=ts -l | while read f; do
  rg -q '@radix-ui/react-dialog|react-aria|focus-trap-react|@headlessui/react' "$f" \
    || echo "$f: dialog without trap library"
done

# Components named *Modal*/*Dialog* without primitive
rg -l --type=ts '(Modal|Dialog|Sheet|Drawer|Popover)\b' src/ | while read f; do
  rg -q '@radix-ui|react-aria|@headlessui|focus-trap' "$f" \
    || echo "$f: custom modal without primitive"
done
```

**False-positive guards:**
- Skip non-modal dialogs (`role="dialog"` with `aria-modal="false"`: rare, but valid).
- Skip components imported from a known wrapper that already uses Radix/react-aria internally.
- Skip files annotated `// ui-audit-ignore:focus-broken-focus-trap`.

## Fix

Use Radix UI Dialog (or react-aria's `<Modal>`). Both ship with focus trap, restoration, Esc handling, scroll lock, and `aria-modal="true"`.

```tsx
// before: hand-rolled, no trap, no Esc
function MyModal({ open, onClose, children }) {
  if (!open) return null;
  return (
    <div role="dialog" aria-modal="true">
      <button onClick={onClose}>Close</button>
      {children}
    </div>
  );
}

// after: Radix Dialog
import * as Dialog from '@radix-ui/react-dialog';

export function ConfirmDialog({ children, trigger }) {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>{trigger}</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed inset-0 m-auto h-fit w-fit p-6">
          <Dialog.Title>Confirm</Dialog.Title>
          <Dialog.Description>Are you sure?</Dialog.Description>
          {children}
          <Dialog.Close>Cancel</Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}
```

Docs:
- Radix Dialog: https://www.radix-ui.com/primitives/docs/components/dialog
- react-aria Modal: https://react-aria.adobe.com/Modal
- focus-trap-react: https://github.com/focus-trap/focus-trap-react

## Default tier and overrides

**Defaults to:** `release-blocker`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Checkout modal | release-blocker |
| Confirm-destruction dialog | release-blocker |
| Marketing newsletter modal | fix-this-sprint |
| Internal admin | fix-this-sprint |

## Defer-to (when this is another tool's job)

- axe-core / jsx-a11y for missing `aria-labelledby`/`aria-label` on the dialog.
- Lighthouse a11y audits for the WCAG-criteria coverage.
- Manual VoiceOver / NVDA pass for screen-reader correctness.

## Suppression

```tsx
{/* ui-audit-ignore:focus-broken-focus-trap, non-modal popover, trap intentionally off */}
```

---
title: Focus not restored after modal/sheet/popover close
id: focus-not-restored
category: focus
defaultTier: release-blocker
detect: static
related: focus-broken-focus-trap, focus-on-dynamic-content, async-no-error-boundary
---

## Focus not restored after modal/sheet/popover close

When a dialog closes, focus must return to the element that opened it (the trigger). If it does not, keyboard and screen-reader users land on `<body>` and must tab from the top to recover their place. One of the most common accessibility bugs, and invisible to mouse users. Radix and react-aria handle it automatically; hand-rolled dialogs almost never do.

## What goes wrong

User opens "Edit profile" via keyboard, submits, and closes. Focus drops to `<body>`; Tab now jumps to the page header, three sections from where they were working, with no way back without scanning the whole page.

## Detection

**Surfaces:** modal, sheet, drawer, popover, command-palette, any "Forgot password?" trigger.

**Static signals:**
1. `rg 'role="(dialog|alertdialog)"|<Dialog|<Sheet|<Popover' --type=ts -l`.
2. For each, confirm focus-restoration evidence:
   - Radix `onCloseAutoFocus` handler OR not overriding it (Radix default restores).
   - A `triggerRef` passed and `triggerRef.current?.focus()` called on close.
   - react-aria's `<DialogTrigger>` (built-in restoration).
   - `focus-trap-react` with `returnFocusOnDeactivate` (defaults to `true`).
3. Flag dialogs that override `onCloseAutoFocus` with `e.preventDefault()` without focusing another element.

**Concrete commands:**
```bash
# Dialogs missing focus-restoration evidence
rg 'role="dialog"|<Dialog\b|<Sheet\b' --type=ts -l | while read f; do
  rg -q 'onCloseAutoFocus|triggerRef|finalFocus|returnFocusOnDeactivate' "$f" \
    || echo "$f: dialog with no focus restoration"
done

# Cases where onCloseAutoFocus is preventDefault'd
rg -B 1 -A 3 'onCloseAutoFocus' --type=ts | rg 'preventDefault'
```

**False-positive guards:**
- Skip if Radix is used and `onCloseAutoFocus` is not provided (default behaviour restores focus).
- Skip if the dialog closes by navigating to a new route (focus management is the new page's responsibility).
- Skip files annotated `// ui-audit-ignore:focus-not-restored`.

## Fix

Patterns:

**A. Use Radix (no extra code needed):**

```tsx
// Radix handles restoration automatically: leave onCloseAutoFocus alone.
<Dialog.Root open={open} onOpenChange={setOpen}>
  <Dialog.Trigger asChild>
    <button>Edit profile</button>
  </Dialog.Trigger>
  <Dialog.Content>...</Dialog.Content>
</Dialog.Root>
```

**B. Hand-rolled with `triggerRef`:**

```tsx
function EditProfile() {
  const triggerRef = useRef<HTMLButtonElement>(null);
  const [open, setOpen] = useState(false);

  const close = () => {
    setOpen(false);
    // Defer to allow unmount before focus
    queueMicrotask(() => triggerRef.current?.focus());
  };

  return (
    <>
      <button ref={triggerRef} onClick={() => setOpen(true)}>
        Edit profile
      </button>
      {open && <MyDialog onClose={close} />}
    </>
  );
}
```

**C. Override Radix carefully** (e.g. focus a confirm result, not the trigger):

```tsx
<Dialog.Content
  onCloseAutoFocus={(e) => {
    e.preventDefault();
    successBannerRef.current?.focus(); // explicit alternative target
  }}
>
```

Docs:
- Radix Dialog onCloseAutoFocus: https://www.radix-ui.com/primitives/docs/components/dialog#content
- react-aria `FocusScope` (`restoreFocus`): https://react-aria.adobe.com/FocusScope
- WCAG 2.4.3 Focus Order: https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html

## Default tier and overrides

**Defaults to:** `release-blocker`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in (Forgot password modal) | release-blocker |
| Checkout (address modal) | release-blocker |
| Confirm-delete dialog | release-blocker |
| Marketing newsletter | fix-this-sprint |
| Internal admin | fix-this-sprint |

## Defer-to (when this is another tool's job)

- axe-core: WCAG 2.4.3 (Focus Order) checks at runtime.
- Manual keyboard pass; automated tooling can't always verify "focus returned to the right place."
- Storybook a11y addon for component-level checks.

## Suppression

```tsx
{/* ui-audit-ignore:focus-not-restored, close action navigates to new route, parent owns focus */}
```

---
title: No focus management on dynamic content (route change, async load, error)
id: focus-on-dynamic-content
category: focus
defaultTier: fix-this-sprint
detect: static
related: focus-not-restored, a11y-skip-link-heading-order, states-no-error-state
---

## No focus management on dynamic content (route change, async load, error)

SPAs don't reload on navigation, so the browser never moves focus or announces new content to screen readers. Same for async-loaded sections, validation errors, and result-list updates: without manual focus management or `aria-live`, SR users never know the content changed. Two-pronged fix: focus the new heading on route/section change, and use `aria-live="polite"` (or `assertive` for errors) for updates that don't shift focus.

## What goes wrong

Search submitted, results render. Sighted users see the list; SR users hear nothing because focus stays on the input, the results have no live region, and nothing was focused. They don't know the search worked. Or: route goes `/dashboard` to `/dashboard/billing`: visually new, but for assistive tech focus is still wherever the click happened.

## Detection

**Surfaces:** search results, route transitions, async-loaded content, validation error summaries, in-page error/success banners.

**Static signals:**
1. `rg 'router\.(push|replace)|useRouter\(\)' --type=ts -l`: programmatic nav callers.
2. `rg 'isLoading|isPending' --type=ts -l`: components that swap async content.
3. For each, look for one of:
   - `useEffect` + `ref.current?.focus()` after content mounts.
   - `aria-live="polite"` or `role="status"` on the dynamic region.
   - `aria-live="assertive"` or `role="alert"` on error regions.
4. Flag dynamic regions with neither focus management nor a live region.

**Concrete commands:**
```bash
# Route changes without focus management
rg -l 'router\.(push|replace)' --type=ts src/ app/ | while read f; do
  rg -A 5 'router\.(push|replace)' "$f" | rg -q 'focus\(\)|aria-live' \
    || echo "$f: route change without focus or live-region handling"
done

# Async content updates without aria-live or focus
rg -l 'isLoading\s*\?\s*' --type=ts src/ app/ | while read f; do
  rg -B 2 -A 6 'isLoading\s*\?\s*' "$f" | rg -q 'aria-live|role="status"|role="alert"|\.focus\(' \
    || echo "$f: async update without focus or live-region handling"
done

# Error banners without role="alert"
rg -l 'errors?\.length|hasError|state\.error' --type=ts src/ app/ | while read f; do
  rg -B 2 -A 4 'errors?\.length|hasError|state\.error' "$f" | rg -q 'role="alert"|aria-live="assertive"' \
    || echo "$f: error banner without alert semantics"
done
```

**False-positive guards:**
- Skip if a known live-region wrapper (e.g. `<Toaster />` from sonner) covers the content.
- Skip new App Router segments (Next.js focuses the route on hard navigation; SPA nav still needs help).
- Skip files annotated `// ui-audit-ignore:focus-on-dynamic-content`.

## Fix

Pick one (or both) per dynamic region.

**A. Focus the new heading on route or section mount:**

```tsx
'use client';
import { useEffect, useRef } from 'react';

export default function BillingPage() {
  const headingRef = useRef<HTMLHeadingElement>(null);
  useEffect(() => {
    headingRef.current?.focus();
  }, []);
  return (
    <main>
      <h1 ref={headingRef} tabIndex={-1}>
        Billing
      </h1>
      ...
    </main>
  );
}
```

**B. `aria-live` for inline updates that don't move focus** (search results, count badges, "saved" hints):

```tsx
<div role="status" aria-live="polite" className="sr-only">
  {results.length === 0
    ? `No results for "${q}"`
    : `${results.length} results`}
</div>
<Results items={results} />
```

**C. `aria-live="assertive"` (or `role="alert"`) for errors:**

```tsx
{error && (
  <div role="alert" className="error">
    {error.message}
  </div>
)}
```

Docs:
- React refs: https://react.dev/reference/react/useRef
- ARIA live regions: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions
- WCAG 4.1.3 Status Messages: https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Search results | release-blocker (core feature broken for SR users) |
| Critical-path errors (sign-in, checkout) | release-blocker |
| Onboarding step transitions | fix-this-sprint |
| Marketing landing | backlog |
| Internal admin | backlog |

## Defer-to (when this is another tool's job)

- axe-core: WCAG 4.1.3 (Status Messages) checks.
- Manual screen-reader pass: automated tools can't verify announcements were heard.
- Vercel Agent / CodeRabbit: diff-time spotting.

## Suppression

```tsx
{/* ui-audit-ignore:focus-on-dynamic-content, content change is purely decorative */}
```

---
title: Do Not Block Paste or IME Input
id: forms-dont-block-paste-ime
category: forms
defaultTier: fix-this-sprint
detect: static
---

## Do Not Block Paste or IME Input

Avoid handlers that prevent paste or aggressively filter keystrokes. Blocking paste breaks password managers and assistive input, and keystroke filters swallow the composition events IME users type with.

## Detection

Search for `onPaste` handlers that call `preventDefault`, then read the handler body to confirm nothing re-inserts the pasted text.

```bash
rg -nUP 'onPaste=\{[^}]*preventDefault' -g '*.tsx' -g '*.jsx' src/
```

A sanitizing paste handler (calls `preventDefault`, then reads `e.clipboardData` and writes the cleaned value back) matches too and is legitimate. If the handler never touches `clipboardData`, paste is simply blocked.

**Incorrect (blocks user input):**

```tsx
<input onPaste={(e) => e.preventDefault()} onKeyDown={blockNonDigits} />
```

**Correct (accept input, validate after):**

```tsx
<input
  value={value}
  onChange={(e) => setValue(e.target.value)}
  onBlur={() => validate(value.trimEnd())}
/>
```

---
title: Associate and Announce Form Errors
id: forms-error-association
category: forms
defaultTier: release-blocker
detect: static
---

## Associate and Announce Form Errors

Tie each error to its input via `aria-describedby`, mark the field `aria-invalid`, and announce it through a live region (`role="alert"`). A message only visually near the field is invisible to screen readers. Complements `forms-inline-errors-first-focus`, which covers placement and focus.

## Detection

List the files that render a conditional error message, then keep only the ones that never mention `aria-describedby`.

```bash
rg -lP '\{\s*[\w.?]*[Ee]rror[\w.?]*\s*&&' -g '*.tsx' -g '*.jsx' src/ \
  | xargs -r rg --files-without-match -P 'aria-describedby'
```

A shared field wrapper (`<FormField>`, `<FormMessage>`, a react-hook-form `<Controller>`) can wire the association internally, leaving no literal attribute at the call site. Open the wrapper once: if it sets `aria-describedby`, `aria-invalid`, and `role="alert"`, its consumers are clean.

**Incorrect (orphan error text, no announcement):**

```tsx
<input name="email" />
<span className="error">Enter a valid email</span>
```

**Correct (associated, marked invalid, announced):**

```tsx
<input
  name="email"
  aria-invalid={Boolean(error)}
  aria-describedby={error ? "email-error" : undefined}
/>
{error && <span id="email-error" role="alert">Enter a valid email</span>}
```

---
title: Show Inline Errors and Focus the First Invalid Field
id: forms-inline-errors-first-focus
category: forms
defaultTier: fix-this-sprint
detect: static
---

## Show Inline Errors and Focus the First Invalid Field

On submit, reveal all relevant errors and move focus to the first failing field. Errors the user has to hunt for are the point where they abandon the form.

## Detection

List the files containing a `<form>`, then keep only the ones that never move focus.

```bash
rg -lP '<form\b' -g '*.tsx' -g '*.jsx' src/ \
  | xargs -r rg --files-without-match -P '\.focus\(\)|autoFocus|shouldFocusError'
```

A form that leans on native constraint validation (`required` inputs, no `noValidate`) also matches, and there the browser focuses the first invalid field itself. Distinguish by the submit handler: if it calls `preventDefault` and validates in JS, focus is the code's job.

**Incorrect (generic top error only):**

```tsx
{hasError && <p>Form invalid</p>}
```

**Correct (field-level message and focus management):**

```tsx
{errors.email && <p id="email-error">Enter a valid email address</p>}
<input aria-invalid={Boolean(errors.email)} aria-describedby="email-error" />

if (errors.email) {
  emailRef.current?.focus()
}
```

---
title: Overlay input affixes on the field
id: forms-input-affix-hit-target
category: forms
defaultTier: backlog
detect: static
related: interaction-target-size, forms-labels-and-autocomplete
---

## Overlay input affixes on the field

A search icon, currency mark, or unit sitting beside the field as a sibling splits the hit target: clicks on the decoration do not focus the input, and the control reads as two widgets. Prefix and suffix decorations belong on top of the text input, with padding so the value does not collide, and they must not steal pointer events.

## Detection

Search for an icon or addon element as a flex sibling of an input, rather than an overlay inside a `relative` wrapper.

```bash
rg -nUP '(?s)<div[^>]*(flex|grid)[^>]*>\s*<(svg|Icon|Search|span)[^>]*>[\s\S]{0,400}<input\b' -g '*.tsx' -g '*.jsx' src/
```

A separate submit button next to a field (search form, OTP paste) is a second control on purpose: skip it. Skip input groups where the addon is itself a `<button>` that performs an action (show password, clear, generate).

**Incorrect (icon beside the field):**

```tsx
<div className="flex items-center gap-2">
  <SearchIcon />
  <input type="search" name="q" />
</div>
```

**Correct (icon overlaid, clicks reach the input):**

```tsx
<div className="relative">
  <SearchIcon className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2" />
  <input type="search" name="q" className="w-full pl-9" />
</div>
```

---
title: Label Inputs and Set Autocomplete Metadata
id: forms-labels-and-autocomplete
category: forms
defaultTier: release-blocker
detect: static
---

## Label Inputs and Set Autocomplete Metadata

Inputs require explicit labels and appropriate `type`, `name`, and `autocomplete` values. Without them users retype data the browser already has, and assistive tech has no name to announce.

## Detection

Search for inputs carrying a `placeholder` but no `id` and no `aria-label`, which is the placeholder-as-label shape.

```bash
rg -nUP '<input\b(?![^>]*\bid=)(?![^>]*aria-label)[^>]*placeholder=' -g '*.tsx' -g '*.jsx' src/
```

An input nested inside its own `<label>` element is implicitly labelled and needs no `id`, so check the enclosing element before reporting. Design-system `<Input>` wrappers generate the `id` from context and are skipped by the lowercase pattern; audit the wrapper itself once instead.

**Incorrect (placeholder-only label):**

```tsx
<input placeholder="Email" />
```

**Correct (explicit label + metadata):**

```tsx
<label htmlFor="email">Email</label>
<input
  id="email"
  name="email"
  type="email"
  autoComplete="email"
  inputMode="email"
/>
```

---
title: Form data lost on validation error
id: forms-lost-data-on-error
category: forms
defaultTier: fix-this-sprint
detect: static
related: forms-no-disable-while-submitting, forms-use-form-status-misuse
---

## Form data lost on validation error

When a form fails server validation, typed values must survive the round-trip. Clearing fields on error is one of the highest-cost UX bugs in production: users abandon checkout, retype passwords wrong, lose multi-paragraph inputs. React 19's `useActionState` makes preservation the default, but only if the action returns `state.fields` and inputs use `defaultValue`.

## What goes wrong

User submits sign-in; server returns "Invalid password"; the email field is blank again. User retypes the email (sometimes wrong) and the password manager autofills the wrong account. Or: a checkout shipping-address form clears all 8 fields when the server rejects a ZIP mismatch.

Two code shapes cause this:

1. `useState` per field plus `setEmail("")` (or implicit `e.currentTarget.reset()`) inside the error branch.
2. A form action that returns only `{ error }` without echoing the submitted fields.

## Detection

**Surfaces:** sign-in, sign-up, checkout, onboarding, multi-step form.

**Static signals:**
1. `rg '<form' --type=ts -l`: list form files in scope.
2. Per form, read the action's return shape (`useActionState`): it must include `fields` (or per-field values) on the error path.
3. Find explicit clears: `\.reset\(\)`, `setEmail\(""\)`, `setPassword\(""\)`, `setForm\(initialState\)` inside `catch` or error branches.
4. Inputs must use `defaultValue={state.fields?.email}` (uncontrolled, seeded) OR `value={state.fields?.email}` (controlled).
5. Fail: no `state.fields` echo AND no controlled-input preservation.

**Concrete commands:**
```bash
# Find forms in scope
rg '<form' --type=ts -l src/

# Find action handlers that don't echo input on error
rg -l 'useActionState' --type=ts src/ | while read f; do
  rg -A 20 'useActionState' "$f" | rg -q 'return \{ error' \
    && ! rg -q 'fields' "$f" \
    && echo "$f: action error path does not preserve submitted fields"
done

# Find suspicious clears in catch blocks
rg -B 2 -A 5 'catch' --type=ts src/ | rg 'reset\(\)|set\w+\(""\)|set\w+\(null\)'

# Find inputs that aren't seeded with prior value
rg '<input' --type=ts src/ | rg -v 'defaultValue|value='
```

**False-positive guards:**
- Skip files containing `// ui-audit-ignore:forms-lost-data-on-error`.
- Skip Storybook fixtures (`*.stories.tsx`) and `*.test.tsx` forms.
- Skip password-only fields where clearing is intentional (`type="password"` plus an `intentional clear` comment).

## Fix

Use `useActionState` and echo `fields` from the server action:

```tsx
// before
"use client";
import { useState } from "react";

export function SignInForm() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState<string | null>(null);

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault();
    const res = await signIn({ email, password });
    if (!res.ok) {
      setError(res.error);
      setEmail("");      // ❌ user's email is gone
      setPassword("");   // ❌ password manager will try to refill
    }
  }
  return <form onSubmit={onSubmit}>...</form>;
}

// after
"use client";
import { useActionState } from "react";
import { signInAction } from "./actions";

export function SignInForm() {
  const [state, action, isPending] = useActionState(signInAction, {
    error: null,
    fields: { email: "" },
  });
  return (
    <form action={action}>
      <input
        name="email"
        type="email"
        defaultValue={state.fields?.email ?? ""}
        aria-invalid={state.fieldErrors?.email ? "true" : undefined}
      />
      <input name="password" type="password" />
      {state.error && <p role="alert">{state.error}</p>}
      <SubmitButton />
    </form>
  );
}

// actions.ts
"use server";
export async function signInAction(_prev: State, formData: FormData) {
  const email = String(formData.get("email") ?? "");
  const password = String(formData.get("password") ?? "");
  const res = await auth.signIn({ email, password });
  if (!res.ok) {
    return { error: res.error, fields: { email } }; // password is NOT echoed
  }
  redirect("/");
}
```

Docs:
- React: https://react.dev/reference/react/useActionState
- React server actions: https://react.dev/reference/rsc/server-functions

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Sign-up | release-blocker |
| Checkout | release-blocker |
| Onboarding | release-blocker |
| Internal admin tools | backlog |
| Marketing landing form | backlog |

Data loss on critical paths (payment, account creation, multi-step) is a release blocker: the cost compounds across millions of submissions.

## Defer-to (when this is another tool's job)

- jsx-a11y enforces `aria-invalid` at lint time.
- React Hook Form / Zod resolvers handle client-side preservation where the form is not driven by a React action.

## Suppression

```tsx
{/* ui-audit-ignore:forms-lost-data-on-error, password reset form intentionally clears for security */}
<form action={resetAction}>
```

---
title: Keep Mobile Input Text at Readable Size
id: forms-mobile-input-font-size
category: forms
defaultTier: fix-this-sprint
detect: static
---

## Keep Mobile Input Text at Readable Size

Set input text to at least 16px on mobile and avoid autofocus on touch-first flows. iOS zooms the viewport in on any field below 16px and does not zoom back out, leaving the user panned into a form they now have to scroll sideways. Do not stop that zoom with `maximum-scale=1` or `user-scalable=no`: that fails WCAG 1.4.4. The field size is the fix.

## Detection

Search for field text below 16px, both in CSS rules whose selector names a field and in Tailwind `text-xs`/`text-sm` on field elements.

```bash
rg -nUP '\b(?:input|textarea|select)\b[^{}/]*\{[^}]*font-size:\s*(?:0?\.\d+rem|(?<![\d.])(?:\d|1[0-5])(?:\.\d+)?px)|<(?:input|textarea|select|Input|Textarea)\b[^>]*className="[^"]*\btext-(?:xs|sm)\b' -g '*.css' -g '*.tsx' -g '*.jsx' src/
```

A rule scoped to pointer devices (inside `@media (pointer: fine)`, or a desktop-only admin bundle) matches but never reaches iOS Safari. Check the enclosing media query and the surface before reporting.

**Incorrect (tiny field text):**

```css
input,
textarea {
  font-size: 13px;
}
```

**Correct (touch-safe field text):**

```css
input,
textarea,
select {
  font-size: 16px;
}
```

---
title: Submit button not disabled while pending
id: forms-no-disable-while-submitting
category: forms
defaultTier: release-blocker
detect: static
related: forms-use-form-status-misuse, forms-lost-data-on-error
---

## Submit button not disabled while pending

A double-clickable submit button creates duplicate accounts, double-charges cards, and posts the same comment twice. React 19's `useFormStatus` makes the fix mechanical: a child component reads `pending` from the surrounding `<form>`, disables itself, and exposes a busy state. Keep the label stable while busy and show a non-text affordance: swapping the text jumps the layout and loses which action is in flight (`rule/loading-stable-labels`, owned by `product-design`). Unprotected forms are release blockers on any monetary or account-creation surface.

## What goes wrong

Slow network, button stays enabled, user clicks again: two POSTs fire before the first response and the server creates two orders, charging twice. Or three rapid clicks on an un-debounced sign-up during a 4-second hand-off log two errors and one success.

## Detection

**Surfaces:** every `<form>` that submits.

**Static signals:**
1. Find every `<form>` in scope.
2. Find its submit `<button type="submit">` (or default-typed button inside the form).
3. The button (or its parent) must reference one of: `useFormStatus().pending`, `isPending` from `useActionState`, `isSubmitting`, or an explicit `disabled={pending}` prop.
4. If none present, fail.

**Concrete commands:**
```bash
# Forms in scope
rg -l '<form' --type=ts src/

# For each form file, look for any pending-aware mechanism
rg -l '<form' --type=ts src/ | while read f; do
  rg -q 'useFormStatus|isPending|isSubmitting|disabled=\{.*pending' "$f" \
    || echo "$f: form without pending-aware submit"
done

# Submit buttons that hard-code disabled=false or no disabled at all
rg '<button[^>]*type=["\']submit' --type=ts src/
```

**False-positive guards:**
- Skip `// ui-audit-ignore:forms-no-disable-while-submitting` and Storybook fixtures.
- Skip search forms where idempotent re-submission is intentional (covered by `async-out-of-order-responses`).
- Skip filter / facet forms that are GET-style and idempotent.

## Fix

Use `useFormStatus` in a child `SubmitButton`. The hook **must** live in a child of `<form>`, not the component that renders `<form>` (see `forms-use-form-status-misuse`):

```tsx
// before
"use client";
export function CheckoutForm() {
  return (
    <form action={placeOrder}>
      {/* fields */}
      <button type="submit">Place order</button>
    </form>
  );
}

// after
"use client";
import { useFormStatus } from "react-dom";

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending} aria-busy={pending}>
      Place order{pending && <Spinner aria-hidden="true" />}
    </button>
  );
}

export function CheckoutForm() {
  return (
    <form action={placeOrder}>
      {/* fields */}
      <SubmitButton />
    </form>
  );
}
```

If you already use `useActionState`, read `isPending` directly:

```tsx
const [state, action, isPending] = useActionState(placeOrderAction, initial);
return (
  <form action={action}>
    {/* fields */}
    <button type="submit" disabled={isPending} aria-busy={isPending}>
      Place order{isPending && <Spinner aria-hidden="true" />}
    </button>
  </form>
);
```

**Backend layer (warn-tier):** disabling the button is necessary but not sufficient; a slow network or a retry can still fire a second request. True safety lives on the backend: pass an `Idempotency-Key` so a repeat never creates a second order or charge.

```ts
// server action
const key = formData.get('idempotency-key') as string;
await processOrder({ idempotencyKey: key, ... });
```

Docs:
- React: https://react.dev/reference/react-dom/hooks/useFormStatus
- React: https://react.dev/reference/react/useActionState
- Stripe Idempotency Keys: https://docs.stripe.com/api/idempotent_requests

## Default tier and overrides

**Defaults to:** `release-blocker`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Checkout / Payment | release-blocker |
| Sign-up | release-blocker |
| Sign-in | release-blocker |
| Comment / message send | fix-this-sprint |
| Newsletter signup | fix-this-sprint |
| Internal admin | fix-this-sprint |
| Search / filter | N/A (idempotent) |

Double-submit on a payment is real money lost; one of the few rules that defaults to release-blocker without further reasoning.

## Defer-to (when this is another tool's job)

- Idempotency keys at the API layer are the durable fix; UI-level disable is the second line of defense. Both belong on payment surfaces.
- React Hook Form's `formState.isSubmitting` where the form is not driven by a React action.

## Suppression

```tsx
{/* ui-audit-ignore:forms-no-disable-while-submitting, search form, idempotent */}
<form action={searchAction}>
```

---
title: useFormStatus called in same component as form (silent bug)
id: forms-use-form-status-misuse
category: forms
defaultTier: release-blocker
detect: static
related: forms-no-disable-while-submitting
---

## useFormStatus called in same component as form (silent bug)

`useFormStatus` returns the **parent** `<form>`'s status. Called in the same component that renders the `<form>`, it returns `{ pending: false }` forever (no parent form to inspect). It compiles, runs, never warns, and silently breaks everything depending on it (disabled submit, pending label, optimistic UI gating). Detecting it means reading the component tree, not the console.

## What goes wrong

A developer copies the docs example:

```tsx
export function CheckoutForm() {
  const { pending } = useFormStatus(); // ❌ always false
  return (
    <form action={placeOrder}>
      <button disabled={pending}>Place order</button>
    </form>
  );
}
```

The button never disables; a double-click bug ships. No console warning, no TypeScript error, no test failure unless a test asserts `disabled` during pending. This is the most common `useFormStatus` mistake, called out as a caveat in the React docs.

## Detection

**Surfaces:** every `<form>` that calls `useFormStatus`.

**Static signals:**
1. Find every file importing `useFormStatus`.
2. Check whether the component calling `useFormStatus()` also renders a `<form>` directly in its JSX.
3. If yes, fail: the hook must live in a child component.
4. Acceptable shape: parent renders `<form>...<SubmitButton /></form>` where `SubmitButton` calls `useFormStatus`.

**Concrete commands:**
```bash
# Files importing useFormStatus
rg -l 'useFormStatus' --type=ts src/

# Of those, files where the SAME component returns a <form>
rg -l 'useFormStatus' --type=ts src/ | while read f; do
  if rg -q '<form' "$f" && rg -q 'useFormStatus\(\)' "$f"; then
    # Heuristic: same file contains both. Read the file to confirm
    # the call site is in the component returning <form>.
    echo "$f: useFormStatus and <form> co-located: read to verify"
  fi
done

# Confirm by reading the call site context
rg -B 2 -A 8 'useFormStatus\(\)' --type=ts src/
```

The grep is a heuristic; `Read` the file to confirm the hook is in the same component as `<form>`. A correctly factored file has two components: one with `<form>`, one with the hook.

**False-positive guards:**
- Skip files with `// ui-audit-ignore:forms-use-form-status-misuse`.
- Two components in one file is fine if `useFormStatus` is in the one that does NOT render `<form>`.
- Skip Storybook fixtures.

## Fix

Extract a child component:

```tsx
// before: silent bug
"use client";
import { useFormStatus } from "react-dom";

export function ContactForm() {
  const { pending } = useFormStatus(); // always false
  return (
    <form action={sendMessage}>
      <input name="message" />
      <button type="submit" disabled={pending} aria-busy={pending}>
        Send{pending && <Spinner aria-hidden="true" />}
      </button>
    </form>
  );
}

// after
"use client";
import { useFormStatus } from "react-dom";

function SubmitButton() {
  const { pending } = useFormStatus(); // reads parent <form> state
  return (
    <button type="submit" disabled={pending} aria-busy={pending}>
      Send{pending && <Spinner aria-hidden="true" />}
    </button>
  );
}

export function ContactForm() {
  return (
    <form action={sendMessage}>
      <input name="message" />
      <SubmitButton />
    </form>
  );
}
```

Docs:
- React: https://react.dev/reference/react-dom/hooks/useFormStatus#caveats, see "useFormStatus will not return status information for a `<form>` rendered in the same component."

## Default tier and overrides

**Defaults to:** `release-blocker`

A silent runtime bug that nullifies `useFormStatus` entirely. Blocks merge regardless of surface (sign-in, checkout, or comment box): the developer's intent is silently broken.

**Surface overrides:**
| Surface | Tier |
|---|---|
| All | release-blocker |

## Defer-to (when this is another tool's job)

- `eslint-plugin-react-hooks` may add a rule that catches this at write time; absent that, this audit is the only static check.

## Suppression

Rarely justified (almost always a real bug). If suppressed, document why:

```tsx
{/* ui-audit-ignore:forms-use-form-status-misuse, useFormStatus is a no-op here, kept for parity with sibling code */}
```

---
title: Preserve Visible Focus States
id: interaction-focus-visible
category: interaction
defaultTier: release-blocker
detect: static
---

## Preserve Visible Focus States

Never remove outlines without a clear `:focus-visible` replacement. With the outline gone, keyboard users cannot see where they are and the interface stops being navigable.

## Detection

Find files that remove the outline and never define a `:focus-visible` replacement anywhere.

```bash
rg -lP 'outline:\s*(none|0)|\boutline-(none|hidden)\b' -g '*.css' -g '*.tsx' -g '*.jsx' src/ \
| xargs -r rg --files-without-match -P 'focus-visible'
```

Tailwind v4 split the old utility: `outline-none` now sets `outline-style: none` for real, and `outline-hidden` keeps a transparent outline so forced-colors mode still draws one. Either is a finding without a `focus-visible:` replacement. `outline-hidden` on a container focused programmatically with `tabIndex={-1}` (a modal panel, a scroll region) matches but has no ring to show and is not a finding. The file-level pairing also cuts the other way: one `focus-visible` rule hides an unrelated outline removal in the same file, so read each hit rather than trusting the file list.

**Incorrect (focus removed):**

```css
button:focus {
  outline: none;
}
```

**Correct (high-contrast focus ring):**

```css
button:focus-visible {
  outline: 2px solid var(--focus-ring);
  outline-offset: 2px;
}
```

---
title: Ensure Full Keyboard Operability
id: interaction-keyboard-operable
category: interaction
defaultTier: release-blocker
detect: static
---

## Ensure Full Keyboard Operability

Pointer-only handlers are not acceptable for critical actions. Anything reachable only by pointer cannot be completed by keyboard, switch, or screen reader users at all.

## Detection

Search for elements given a button role or a focusable `tabIndex` that carry no key handler; a hit is confirmed when the element's action has no keyboard path.

```bash
rg -nUP '(?s)<[A-Za-z][^>]*?\b(?:role="button"|tabIndex=\{[0-9])(?![^>]*?(?:onKeyDown|onKeyUp|onKeyPress))[^>]*?>' \
   -g '*.tsx' -g '*.jsx' src/
```

The key-handler exclusion is a lookahead inside the element, not a `| rg -v` after it. Filtering the output of a multiline match works line by line, so a correctly written element whose attributes Prettier split across lines gets its `onKeyDown` line stripped and the rest reported. That is the common formatting, so the pipeline form fires on correct code more often than on broken code.

Headless libraries spread the handlers in (`{...getButtonProps()}`, Radix `asChild`), so the keyboard path is real but lives in the hook, not this file. A clickable element with no role at all does not match here: that is `a11y-semantic-html-first`.

**Incorrect (mouse only):**

```tsx
<div onClick={openMenu}>Open menu</div>
```

**Correct (keyboard + pointer by default):**

```tsx
<button type="button" onClick={openMenu}>Open menu</button>
```

---
title: Meet Minimum Hit Target Size
id: interaction-target-size
category: interaction
defaultTier: fix-this-sprint
detect: static
---

## Meet Minimum Hit Target Size

Touch targets need 44x44px (WCAG 2.5.5 Target Size Enhanced). 24x24px (WCAG 2.5.8 Target Size Minimum) is the floor only for dense desktop UI under `pointer: fine`; on touch it is a mistap generator, not a pass.

This file owns the 44px number, and it is a conformance floor, not a build target. New UI in this skill ships 48x48 per `guidelines/buttons.md`, which owns that number. An existing control between 44 and 47px is a pass with a note, never a fail.

## Detection

Search for interactive elements sized below 44px, in Tailwind classes (anything under `h-11`) and in button-like CSS rules.

```bash
rg -nP '\b(h|w|size)-([1-9]|10)\b' -g '*.tsx' -g '*.jsx' src/ | rg 'button|role="button"'
rg -nUP '[.\w-]*(button|btn|icon)[^{}]*\{[^}]*(width|height):\s*([1-9]|[1-3][0-9])px' -g '*.css' src/
```

The small class usually belongs to the glyph inside an adequately sized control (`<XIcon className="h-4 w-4" />` inside an `h-11` button), which matches whenever both sit on one line. Read the enclosing element: the hit target is the button's box, not the icon's.

**Incorrect (small tap area):**

```css
.icon-button {
  width: 18px;
  height: 18px;
}
```

**Correct (expanded hit area):**

```css
.icon-button {
  min-width: 44px;
  min-height: 44px;
  display: inline-grid;
  place-items: center;
}
```

---
title: Handle Long and Unbroken Content Safely
id: layout-long-content-safety
category: layout
defaultTier: fix-this-sprint
detect: rendered
---

## Handle Long and Unbroken Content Safely

Protect UI against long names, URLs, and dense content blocks. Unhandled, a single long token overflows its container and breaks the layout around it.

## Detection

No grep decides this. Whether a container overflows depends on its rendered width and the content it actually receives, and the failing shape (a `truncate` child inside a flex parent missing `min-width: 0`) is a relationship between elements that no single-file pattern can confirm.

Evidence to collect: render the surface at 320px and at the narrowest supported desktop width, seeded with a hostile fixture (a 60-character unbroken token, a 200-character name, a raw URL with no spaces, a locale whose strings run 30% longer). Then, per candidate container, compare `scrollWidth` against `clientWidth` and screenshot anything where the content escapes its box or pushes a sibling off screen. Report the overflowing element with its viewport width and the string that broke it.

The `ui-verification` skill runs exactly that as its viewport-stress probe, including the culprit walk that finds the deepest overflowing element rather than its ancestors. Dispatch to it when an app is running; with no browser this rule is `unknown`, never a fail.

**Incorrect (overflow risk):**

```css
.card-title {
  white-space: nowrap;
}
```

**Correct (safe truncation/wrapping):**

```css
.card {
  min-width: 0;
}
.card-title {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}
.card-body {
  overflow-wrap: anywhere;
}
```

---
title: Leaked raw error message in UI
id: microcopy-leaked-error-message
category: microcopy
defaultTier: release-blocker
detect: static
related: microcopy-vague-error, states-no-error-state, async-no-error-boundary
---

## Leaked raw error message in UI

Rendering `error.message`, `e.stack`, or a stringified error directly into JSX exposes implementation details to users, and frequently to attackers. SQL fragments, ORM stack traces, AWS error codes, payment-provider raw responses, and internal endpoint paths routinely appear in production UIs because the dev wrote `<p>{error.message}</p>` and never came back. This is a **release-blocker security and trust issue**: it leaks stack info, embarrasses the brand, and confuses users with text written for engineers.

## What goes wrong

A checkout fails because Stripe returns `card_declined: insufficient_funds`. The catch block does `setError(e.message)` and the UI shows the user `StripeError: Your card has insufficient funds. Request ID req_AbC123 at /v1/payment_intents`. The user sees "Request ID" and assumes a bug; support gets a screenshot ticket; the user abandons checkout. The fix is to log the raw error server-side and show the user "Card was declined, try another card or contact your bank."

## Detection

**Surfaces:** every surface that catches errors. Checkout, sign-in, sign-up, form, error/404/500 page, toast, dashboard.

**This is a candidate-finding rule.** Regex finds renders of error properties; the agent confirms each is user-facing (not a logger, not a dev-only `<ErrorOverlay>`).

**Static signals:**
1. Grep error-property renders inside JSX.
2. For each match, Read context to confirm: is this in JSX returned to the user, or is it `console.error` / `Sentry.captureException` / `logger.error`?
3. Check whether the error is sanitized through a known-codes map before rendering.

**Concrete commands:**
```bash
# error.message / e.message / err.message rendered into JSX.
rg -n '\{(error|err|e)\.(message|stack)\}' --type=ts src/
rg -n '\{String\((error|err|e)\)\}' --type=ts src/
rg -n '\{JSON\.stringify\((error|err|e)\)\}' --type=ts src/

# String-concatenated error objects.
rg -n "'.*' \+ (error|err|e)\.message" --type=ts src/

# Common provider-raw-response leaks.
rg -n -i 'stripeError|paypalError|awsError|errorCode.*amazonaws' --type=ts src/

# SQL fragments leaking through (ORM error passthroughs).
rg -n -i 'SELECT \*|UPDATE .* SET|duplicate key|relation .* does not exist' --type=ts src/
```

**False-positive guards:**
- **Logging-only is fine.** `Sentry.captureException(error)`, `console.error(error)`, `logger.error({ err })` are correct; these never reach the user.
- Skip dev-only overlays: Next.js `error.tsx` in dev shows raw stacks via the framework; only fail when raw error renders to **production** UI.
- Skip `<ErrorBoundary fallback={...}>` if the fallback uses sanitized text and the raw error is only passed to `componentDidCatch` for logging.
- Skip files with `// ui-audit-ignore:microcopy-leaked-error-message`.

**Agent-judgment limit:** Distinguishing "shown in UI" from "logged" requires reading the surrounding code. The regex finds candidates; the agent confirms by tracing where the value is used. If unclear, mark `unknown` with the file and line.

## Fix

Catch the error, log the full thing server-side, surface a sanitized user-friendly message keyed off `error.code` or HTTP status. Always provide a fallback for unmapped errors.

```tsx
// before: leaks raw provider message
try {
  await placeOrder(formData);
} catch (e) {
  setError(e.message); // -> "StripeError: card_declined ... req_AbC123"
}

// after: known-codes map + safe fallback + server log
const PAYMENT_ERRORS: Record<string, string> = {
  card_declined: 'Card was declined. Try another card or contact your bank.',
  insufficient_funds: 'Card has insufficient funds. Try another card.',
  expired_card: 'Card has expired. Update or use another card.',
  processing_error: 'Couldn\'t process payment. Try again in a moment.',
};

try {
  await placeOrder(formData);
} catch (e) {
  // Server-side: full structured log with request id, user id, raw error.
  logger.error({ err: e, userId, action: 'placeOrder' });
  // Client-side: sanitized.
  const code = (e as { code?: string }).code;
  setError(
    PAYMENT_ERRORS[code ?? ''] ??
      "Something went wrong on our end, we've been notified. Try again.",
  );
}
```

For Server Actions: log full error server-side, return a structured `{ ok: false, errorCode }`: never raw `e.message`.

Reference:
- OWASP, Improper Error Handling: https://owasp.org/www-community/Improper_Error_Handling
- NN/g, Error Message Guidelines: https://www.nngroup.com/articles/error-message-guidelines/
- React, Error Boundaries: https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary

## Default tier and overrides

**Defaults to:** `release-blocker`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Checkout / payment | release-blocker |
| Sign-in / Sign-up | release-blocker |
| Public marketing | release-blocker (brand + trust) |
| Internal admin tools (employees only) | fix-this-sprint |
| Local dev overlay | not applicable |

This rule **does not** drop below `fix-this-sprint` because even on internal tools, leaked SQL or stack traces is a security smell.

## Examples

**Anti-pattern (fails):**

```tsx
// 1. Direct passthrough
catch (e) { return <p className="error">{e.message}</p>; }

// 2. Stack trace in UI
{error && <pre>{error.stack}</pre>}

// 3. Stringified error object
<Toast>{JSON.stringify(error)}</Toast>

// 4. Concatenated, still leaks
<p>{`Failed: ${err.message}`}</p>

// 5. Provider raw
<p>{stripeError.raw.message}</p>
```

**Applied (passes):**

```tsx
// 1. Mapped + safe fallback
<p role="alert">{PAYMENT_ERRORS[code] ?? "Something went wrong on our end, we've been notified. Try again."}</p>

// 2. Logger gets full detail; UI gets a code only
catch (e) { Sentry.captureException(e); setError({ code: 'GENERIC' }); }

// 3. Error boundary with sanitized fallback
<ErrorBoundary fallback={<RecoverScreen />} onError={(e) => Sentry.captureException(e)}>
  <Checkout />
</ErrorBoundary>
```

## Defer-to (when this is another tool's job)

- **Server-side error logging completeness**: APM tooling (Sentry, Datadog).
- **PII redaction in logs**: log scrubber config, not UX audit.
- **Generic XSS / injection**: security review / SAST tools.

## Suppression

Suppression is **strongly discouraged** for this rule. If you must:

```tsx
{/* ui-audit-ignore:microcopy-leaked-error-message, internal tool, errors include user-controlled query strings only */}
<pre>{error.message}</pre>
```

Reviewers should treat any suppression as a deliberate security trade-off and require sign-off.

---
title: Vague error message, no cause, no recovery
id: microcopy-vague-error
category: microcopy
defaultTier: fix-this-sprint
detect: static
related: microcopy-leaked-error-message, states-no-empty-state, states-no-error-state
---

## Vague error message, no cause, no recovery

When something fails, the copy needs two things: **what went wrong** and **what to do next**. Strings like "Error occurred", "Something went wrong", "Invalid", "Please try again", and "Oops" give neither: placeholder text that shipped. Modern stacks make it worse: `useActionState` and Server Actions invite `return { error: 'Invalid' }` that never gets refined.

## What goes wrong

User submits sign-up; the server rejects it (email already registered); the screen renders "Invalid" in red below the field. The user can't tell if it's a typo, a server bug, or an existing account, reloads, and loses their work. The actionable version ("Email already in use, sign in instead" with a link) rescues them in one click.

## Detection

**Surfaces:** sign-in / sign-up, checkout, form, search, toast/banner, error/404/500.

**This is a candidate-finding rule.** Regex surfaces candidates; the agent reads surrounding JSX and decides whether the string is genuinely vague, or deliberately generic for a known reason (auth security-through-obscurity, or a developer log).

**Static signals:**
1. Grep candidate strings across JSX/TS literals.
2. Per match, Read ~10 surrounding lines to confirm it renders to the user (not console.log, test fixtures, or Sentry tags).
3. Per confirmed UI string, judge whether the surface allows a more specific message.

**Concrete commands:**
```bash
# Candidate matches: every hit needs context review.
rg -n -i 'error occurred|something went wrong|please try again|oops' \
  --type=ts src/

# "Invalid" is noisier: narrow to JSX text or error fields.
rg -n '"Invalid"|>Invalid<|error: ?"Invalid"' --type=ts src/
```

**False-positive guards:**
- **Auth security exception:** "Wrong email or password" / "Incorrect credentials" is intentionally vague to avoid leaking account existence. Pass when the surface is sign-in and the message matches this pattern exactly; document with a comment.
- Skip console.error / Sentry.captureException / logger.warn (not user-facing).
- Skip test files (`*.test.tsx`, `*.spec.tsx`), Storybook fixtures (`*.stories.tsx`), MSW handlers.
- Skip files with `// ui-audit-ignore:microcopy-vague-error` near the match.

**Agent-judgment limit:** judgment-heavy. The regex is a candidate generator, not a verdict. If you can't read enough context to decide, mark the finding `unknown` with a reason rather than guess.

## Fix

Rewrite to **cause + recovery**. Cause is what failed; recovery is the next action.

```tsx
// before
{state.error && <p className="text-red-600">{state.error}</p>}
// state.error is "Invalid" from a Server Action

// after: server returns a code, client maps to specific copy + CTA
const ERRORS: Record<string, { message: string; action?: ReactNode }> = {
  EMAIL_TAKEN: {
    message: 'Email already in use.',
    action: <Link href="/signin">Sign in instead</Link>,
  },
  PASSWORD_TOO_SHORT: { message: 'Password needs at least 12 characters.' },
  RATE_LIMITED: { message: 'Too many attempts. Try again in 5 minutes.' },
};

{state.errorCode && (
  <div role="alert" className="text-red-600">
    {ERRORS[state.errorCode]?.message ?? 'Something failed on our end. Try again.'}
    {ERRORS[state.errorCode]?.action}
  </div>
)}
```

Reference:
- NN/g, Error Message Guidelines: https://www.nngroup.com/articles/error-message-guidelines/
- React: https://react.dev/reference/react/useActionState

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Checkout (payment errors) | release-blocker |
| Sign-up (account creation) | release-blocker |
| Sign-in | fix-this-sprint (with auth-vagueness exception above) |
| Marketing landing | backlog |
| Internal admin | backlog |

## Examples

**Anti-pattern (fails):**

```tsx
// 1. Generic
<p>Error occurred. Please try again.</p>

// 2. Placeholder that shipped
<p>Something went wrong</p>

// 3. Useless validation
<span className="error">Invalid</span>

// 4. Friendly but empty
<Toast>Oops! Try again 🙃</Toast>
```

**Applied (passes):**

```tsx
// 1. Specific + recoverable
<p>Couldn't reach the payment provider. Your card was not charged.
   <button onClick={retry}>Try again</button>
</p>

// 2. Cause + next step
<p>Email already in use: <Link href="/signin">sign in instead</Link>.</p>

// 3. Field-level cause
<span>Phone number must include country code (e.g. +1).</span>

// 4. Save-state preserved
<Toast>Couldn't save, your changes are still here.
  <button onClick={retry}>Try again</button>
</Toast>
```

## Defer-to (when this is another tool's job)

- **Copywriting tone / brand voice review**: content-design tooling, not UX audit.
- **i18n string completeness**: i18n linter (e.g. `i18next-parser`).
- **WCAG: error association with field**: axe / jsx-a11y `aria-describedby` checks.

## Suppression

```tsx
{/* ui-audit-ignore:microcopy-vague-error, security: do not reveal whether email exists */}
<p>Wrong email or password.</p>
```

---
title: Critical actions hidden behind hover-only affordances
id: mobile-hover-only-affordance
category: mobile
defaultTier: fix-this-sprint
detect: static
related: interaction-target-size, focus-on-dynamic-content
---

## Critical actions hidden behind hover-only affordances

Reveal-on-hover quietly disappears on touch: a row exposes "Edit / Delete / Share" only when the cursor enters, but a phone has no cursor. Touch users never discover the actions, or only via a frustrating long-press. The same pattern hides tooltips, secondary CTAs, and meaningful state ("3 unread") behind `:hover`. `@media (hover: hover)` and `@media (pointer: fine)` scope hover-reveal to hover-capable input, but most codebases skip this and ship a desktop-only experience to mobile.

## What goes wrong

A row uses `opacity-0 group-hover:opacity-100` to reveal action buttons. On desktop the cursor enters and they fade in; on mobile the tap navigates to a detail view and the inline actions are never seen. Same pattern hides "X" close buttons on cards, "Copy link" on code blocks, and tooltip content carrying real information.

## Detection

**Surfaces:** list / feed / inbox rows, dashboard widget actions, code-block toolbars, tooltips, modal hover-reveal patterns.

**Static signals:**
1. Grep for hover-only visibility classes: `hover:opacity-100`, `hover:visible`, `group-hover:opacity-`, `peer-hover:opacity-`, `hover:flex`, `hover:block`.
2. For each, find the paired hidden state (`opacity-0`, `invisible`, `hidden`).
3. Check whether the parent has `@media (hover: hover)` scoping (`hover-hover:` plugin or custom CSS).
4. Check whether a click/tap fallback exists (kebab menu, long-press, or always-visible variant).
5. Flag if the element is interactive (button, link, action) **and** no fallback exists.

**Concrete commands:**
```bash
# Tailwind reveal-on-hover patterns
rg -n '(group-hover|peer-hover|\bhover:):(opacity-100|visible|flex|block)' --type=ts

# Pure CSS hover-reveal
rg -n ':hover\s*\{[^}]*(opacity:\s*1|visibility:\s*visible|display:)' --type=css

# Title-only tooltips (carry info, no fallback)
rg -n 'title="[^"]{20,}"' --type=ts
```

**False-positive guards:**
- Skip purely cosmetic hover styling (color shift, scale) where the action stays tappable.
- Skip files that gate the hover-reveal with `@media (hover: hover)`.
- Skip if a touch fallback exists in the same component (kebab menu, `MoreActions` popover, always-visible mobile variant).
- Skip `// ui-audit-ignore:mobile-hover-only-affordance` near the match.

## Fix

Two-layer fix: scope hover to hover-capable input, and provide a touch fallback.

```tsx
// before: actions invisible on touch
<li className="group relative">
  <a href={item.url}>{item.title}</a>
  <div className="absolute right-2 opacity-0 group-hover:opacity-100">
    <button onClick={onEdit}>Edit</button>
    <button onClick={onDelete}>Delete</button>
  </div>
</li>

// after: visible on touch, reveal-on-hover on desktop, focus-visible for keyboard
<li className="group relative">
  <a href={item.url}>{item.title}</a>
  <div
    className="absolute right-2
               opacity-100
               [@media(hover:hover)]:opacity-0
               [@media(hover:hover)]:group-hover:opacity-100
               [@media(hover:hover)]:group-focus-within:opacity-100"
  >
    <button onClick={onEdit}>Edit</button>
    <button onClick={onDelete}>Delete</button>
  </div>
</li>
```

For tooltip content carrying real information, switch to a focus-visible, click-to-toggle popover (e.g. Radix `Popover`, not `Tooltip`):

```tsx
<Popover.Root>
  <Popover.Trigger aria-label="More info">
    <InfoIcon />
  </Popover.Trigger>
  <Popover.Content>{helpText}</Popover.Content>
</Popover.Root>
```

Docs:
- MDN `@media (hover)`: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/hover
- MDN `(pointer: fine|coarse)`: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/pointer
- Tailwind hover-hover variant docs: https://tailwindcss.com/docs/hover-focus-and-other-states#pointer-and-any-pointer

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Sign-up | n/a (rare) |
| Checkout | release-blocker (any "remove item" or "edit address" hidden) |
| List / feed | fix-this-sprint |
| Marketing landing | backlog |
| Internal admin | backlog |

## Defer-to (when this is another tool's job)

- **Playwright** with mobile emulation verifies the action is reachable: https://playwright.dev/docs/emulation#devices
- **eslint-plugin-jsx-a11y** catches some related patterns (`title` carrying critical info); link, don't restate.

## Suppression

```tsx
{/* ui-audit-ignore:mobile-hover-only-affordance, purely cosmetic hover state */}
<div className="hover:bg-muted" />
```

---
title: Missing viewport meta, 100vh on mobile, no safe-area insets
id: mobile-viewport-scaling
category: mobile
defaultTier: backlog
detect: static
related: interaction-target-size, states-layout-shift
---

## Missing viewport meta, 100vh on mobile, no safe-area insets

Three quiet bugs ship together on mobile, each a one-line fix invisible in desktop testing: a missing `<meta name="viewport">` makes iOS Safari render at 980 px and zoom out; `100vh` includes the address bar (~60 px wrong on iOS); a fixed bottom bar covers the home-indicator notch and clips content. Modern CSS fixes these with `100dvh` (dynamic viewport height) and `env(safe-area-inset-*)`.

## What goes wrong

No viewport meta in `app/layout.tsx`: iOS Safari renders at desktop width and the user pinches to zoom. A modal uses `h-screen` (100vh): on iOS the URL bar covers the bottom 60 px and the primary CTA is unreachable. A bottom nav uses `pb-4`: on iPhone X+ the home indicator overlaps the buttons.

## Detection

**Surfaces:** every full-screen surface, modals/sheets, fixed bottom bars, mobile dashboards, sign-in screens with bottom CTAs.

**Static signals:**
1. **Viewport meta:** check `app/layout.tsx` (App Router) or `_document.tsx` (Pages Router) for `<meta name="viewport" content="width=device-width, initial-scale=1">` or the `viewport` export.
2. **`100vh` on mobile surfaces:** grep `h-screen`, `min-h-screen`, `100vh`, `vh` units. Each is a candidate for `100dvh` / `100svh`.
3. **Fixed bottom bars:** grep `fixed bottom-0`, `position: fixed; bottom: 0`; confirm `padding-bottom: env(safe-area-inset-bottom)` or Tailwind `pb-[env(safe-area-inset-bottom)]` is present.
4. **viewport-fit:** if any `safe-area-inset-*` is used, the viewport meta must include `viewport-fit=cover` or it's a no-op.

**Concrete commands:**
```bash
# Viewport meta presence (Next.js App Router)
rg -n 'export const viewport|<meta name="viewport"' app/ src/

# 100vh usage
rg -n '\b(h-screen|min-h-screen|100vh|\bvh\b)' --type=ts --type=css

# Fixed bottom bars
rg -n 'fixed (inset-x-0 )?bottom-0' --type=ts

# Safe-area insets
rg -n 'safe-area-inset|env\(safe-area' --type=css --type=ts
```

**False-positive guards:**
- Skip `100vh` on desktop-only surfaces (`hidden md:block` parent, or media-query gated).
- Skip fixed bottom bars inside a `<dialog>` (modal context manages safe area).
- Skip files with `// ui-audit-ignore:mobile-viewport-scaling` near the match.

## Fix

Three independent fixes; apply each where flagged.

**1. Viewport meta (Next.js App Router):**

```tsx
// app/layout.tsx
import type { Viewport } from 'next';

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  viewportFit: 'cover', // required for env(safe-area-inset-*)
};
```

**2. Replace `100vh` with `100dvh`:**

```tsx
// before: covered by iOS Safari URL bar
<div className="min-h-screen flex flex-col">

// after: dynamic viewport, full height in every state
<div className="min-h-[100dvh] flex flex-col">
```

`100dvh` shrinks/grows with the URL bar; use `100svh` (small viewport) when the layout must stay stable as the bar appears/disappears (avoids scroll reflow). `100lvh` (large) is rarely correct.

**3. Safe-area inset on fixed bars:**

```tsx
// before: clipped by home indicator on iPhone X+
<nav className="fixed inset-x-0 bottom-0 h-14 px-4">

// after: respects safe area
<nav
  className="fixed inset-x-0 bottom-0 px-4
             pb-[env(safe-area-inset-bottom)]
             h-[calc(3.5rem+env(safe-area-inset-bottom))]"
>
```

Reference docs:
- Next.js viewport export: https://nextjs.org/docs/app/api-reference/functions/generate-viewport
- MDN dynamic viewport units: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/length#dynamic_viewport_units
- WebKit safe-area: https://webkit.org/blog/7929/designing-websites-for-iphone-x/

## Default tier and overrides

**Defaults to:** `backlog`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Sign-in / Sign-up | fix-this-sprint (CTA hidden = no conversion) |
| Checkout | release-blocker (place-order button under URL bar) |
| Modal / Sheet | fix-this-sprint |
| Marketing landing | backlog |
| Internal admin | backlog |

## Defer-to (when this is another tool's job)

- **Lighthouse** mobile audit catches missing viewport meta: https://developer.chrome.com/docs/lighthouse/best-practices/viewport
- **Playwright** device emulation reproduces the URL-bar issue on iOS profiles.
- **Chromatic** with mobile viewports catches the visual end of safe-area bugs.

## Suppression

```tsx
{/* ui-audit-ignore:mobile-viewport-scaling, desktop-only embedded admin */}
<div className="h-screen" />
```

---
title: Announce Status Changes with Live Regions
id: nav-live-region-feedback
category: nav
defaultTier: fix-this-sprint
detect: static
---

## Announce Status Changes with Live Regions

Toasts and validation summaries should use polite live regions unless interruption is critical. A toast that is only painted on screen never reaches assistive tech, so the user never learns the action finished.

## Detection

Find toast, snackbar, and notification containers rendered as plain JSX, then keep only the files with no live-region attribute anywhere in them.

```bash
rg -lP 'className="[^"]*\b(toast|snackbar|notification|banner)\b' -g '*.tsx' -g '*.jsx' src/ \
| xargs -r rg --files-without-match -P 'aria-live|role="(status|alert)"'
```

A file that renders its own toast markup but delegates the announcement to a shared `<Toaster />` (sonner, react-hot-toast, Radix Toast) is a false positive: those libraries own the live region. Confirm by checking whether the toast is mounted through the library's provider or painted directly by this component.

**Incorrect (visual-only toast):**

```tsx
<div className="toast">Saved</div>
```

**Correct (announced toast):**

```tsx
<div role="status" aria-live="polite" className="toast">
  Changes saved
</div>
```

---
title: Use Semantic Links for Navigation
id: nav-semantic-links
category: nav
defaultTier: fix-this-sprint
detect: static
---

## Use Semantic Links for Navigation

Navigation should use `<a>` or framework `<Link>`, not click handlers on generic elements. A click handler on a div loses middle-click, open-in-new-tab, copy-link, and the browser's own back behaviour.

## Detection

Find generic elements whose click handler performs a navigation, which is the shape that has no href for the browser to act on.

```bash
rg -nUP '(?s)<(div|span|li)\b[^>]*\bonClick=\{[^}]*(router\.push|navigate\(|location\.href)' -g '*.tsx' -g '*.jsx' src/
```

A card wrapper that widens the hit area around a real nested `<a>` or `<Link>` is legitimate and will not match this pattern, since its handler forwards rather than navigates. If a match does wrap a real link, check whether the handler is a redundant convenience or the only route out.

**Incorrect (non-semantic navigation):**

```tsx
<div onClick={() => router.push('/settings')}>Settings</div>
```

**Correct (semantic navigation):**

```tsx
<Link href="/settings">Settings</Link>
```

---
title: Set Image Dimensions and Priority Intentionally
id: perf-image-dimensions-and-priority
category: perf
defaultTier: release-blocker
detect: static
---

## Set Image Dimensions and Priority Intentionally

Declare `width`/`height` (or aspect ratio) and prioritize only above-the-fold hero images. Undeclared dimensions shift the page as images arrive, and an unprioritized hero delays the largest paint.

## Detection

Search for `<img>` tags with no `width` attribute, which is the layout-shift half of this rule.

```bash
rg -nUP '<img\b(?![^>]*\bwidth=)[^>]*>' -g '*.tsx' -g '*.jsx' src/
```

An image whose box is already reserved in CSS (`aspect-video`, `aspect-[16/9]`, a fixed `h-` plus `w-`, or `<Image fill>` in a sized parent) matches but does not shift. The priority half is not greppable on its own: identify the first-viewport image, then confirm it carries `priority` or `fetchPriority="high"`.

**Incorrect (layout shift risk):**

```tsx
<img src="/hero.jpg" alt="Product screenshot" />
```

**Correct (stable image rendering):**

```tsx
<Image
  src="/hero.jpg"
  alt="Product screenshot"
  width={1600}
  height={900}
  priority
/>
```

---
title: Lazy-Load Offscreen Media, Never the LCP Element
id: perf-lazy-load-offscreen
category: perf
defaultTier: fix-this-sprint
detect: static
---

## Lazy-Load Offscreen Media, Never the LCP Element

Add `loading="lazy"` to offscreen images and iframes so they defer until the user scrolls near. Never lazy-load the LCP/above-the-fold hero; that delays the largest paint. Pair with `eager`/`priority` on the hero.

## Detection

Search for lazy-loaded images whose tag also names a first-viewport role or a priority hint, the combination that delays the largest paint.

```bash
rg -nUP '<(?:img|Image)\b(?=[^>]*loading="lazy")(?=[^>]*(?i:hero|banner|cover|masthead|priority))[^>]*>' -g '*.tsx' -g '*.jsx' src/
```

A "hero" or "cover" inside a below-the-fold component (a card cover in a feed, a banner in a footer CTA) is correctly lazy, so confirm the element renders in the first viewport before reporting. The mirror defect, an offscreen image with no `loading` attribute, needs that same position evidence rather than a grep.

**Incorrect (hero lazy-loaded, offscreen image eager):**

```tsx
<img src="/hero.jpg" alt="..." loading="lazy" />
<img src="/footer-logo.png" alt="..." />
```

**Correct (hero eager, offscreen deferred):**

```tsx
<img src="/hero.jpg" alt="..." fetchPriority="high" />
<img src="/footer-logo.png" alt="..." loading="lazy" />
<iframe src="/map" loading="lazy" title="Location map" />
```

---
title: Virtualize Long Lists
id: perf-virtualize-large-lists
category: perf
defaultTier: fix-this-sprint
detect: static
---

## Virtualize Long Lists

Large lists (roughly >50 visible items) should use virtualization/windowing. Rendering the whole dataset stalls scrolling and grows memory with the list.

## Detection

Search for list containers mapping straight over a collection, in files that import no windowing library.

```bash
rg -lUP '<(?:ul|ol|tbody)\b[^>]*>\s*\{[^}]*\.map\(' -g '*.tsx' -g '*.jsx' src/ \
  | xargs -r rg --files-without-match -P 'react-window|@tanstack/react-virtual|react-virtuoso|virtua'
```

Most matches are short lists that are correct as they stand. Confirm the collection can exceed roughly 50 rows (an unpaginated fetch, no page size, no `.slice`) before reporting.

**Incorrect (renders entire dataset):**

```tsx
<ul>
  {items.map(item => <Row key={item.id} item={item} />)}
</ul>
```

**Correct (windowed rendering):**

```tsx
<VirtualizedList
  itemCount={items.length}
  itemSize={48}
  renderItem={(index) => <Row item={items[index]} />}
/>
```

---
title: Affordance styling with nothing behind it
id: slop-affordance-mismatch
category: slop
defaultTier: backlog
detect: static
related: interaction-keyboard-operable, interaction-focus-visible, nav-semantic-links
---

## Affordance styling with nothing behind it

A card lifts on hover, the cursor turns into a hand, the border brightens, and clicking does nothing. The user has already committed to the click by the time they learn it was a decoration; they click again, assume the page is broken or slow, and then trust the next hover state less. This is worse than a plainly inert card, because a plainly inert card never made a promise. It is especially costly on touch, where the hover state never appears and the user has only the visual weight of the element to go on.

The promise is the problem: styling that says "interactive" on something that has no behaviour.

## Ownership

**This rule detects one thing only: decoration that promises interactivity and does not deliver.** Three adjacent failures are owned elsewhere, and reporting them here is double-reporting:

| Symptom | Owner |
|---|---|
| `onClick` on a `<div>`, no keyboard path | `interaction-keyboard-operable` |
| `href="#"` or a click handler used for navigation | `nav-semantic-links` |
| An interactive element with no visible focus style | `interaction-focus-visible` |

If the element has a handler, it is not this rule. Hand it to the owner above and move on.

## Detection

Find candidate affordance styling, then confirm the element has no behaviour.

```bash
rg -nP 'cursor-pointer|hover:(bg|shadow|scale|border|ring|translate)-' \
   -g '*.tsx' -g '*.jsx' -g '!*.stories.tsx' -g '!*.test.tsx' src/
```

For each hit, read the element and fire only if **all** of these hold:

1. no `onClick`, `onPointerDown`, `onMouseDown`, `onKeyDown`, or `onSubmit`,
2. no `href`, `to`, or `action`,
3. no `role="button"`, `role="link"`, `role="option"`, `role="menuitem"`, or similar,
4. it is not itself a `<button>`, `<a>`, `<label>`, `<summary>`, or form control,
5. it contains no interactive descendant.

Report `file:line`, the element, and the promising class.

## False positives

Every one of these will appear in the raw grep. Confirm against all five before reporting:

- **`cursor-pointer` on a `<label>` is correct.** The label is genuinely clickable: clicking it focuses or toggles its control. Same for `<summary>` and for `<option>`.
- **The handler is frequently not on the line you are reading.** Event delegation puts one `onClick` on a list and styles each row; spread props (`{...props}`, `{...getItemProps()}`) carry handlers invisibly. **Skip when props are spread onto the element, and skip when a parent within 10 lines has an `onClick`, `href`, or `role`.**
- **`group` / `group-hover` reveal patterns are legitimate.** A row styled with `group` that reveals a real `<button>` on hover is correct: the hover affordance belongs to the descendant, and the parent is the hit area for the eye rather than the pointer. If an interactive descendant exists inside the group, do not report.
- **Radix, Headless UI, and Base UI render the interactive element downstream.** `asChild`, `<Slot>`, `<Dialog.Trigger>`, `<Popover.Button>`, `<Menu.Item>`, and every `*Trigger` component attach behaviour to a child or via a hook. There will be no `onClick` in the source and the element is still fully interactive. Skip these.
- **Drag handles and sortable items** get their behaviour from a hook's ref, not from a JSX handler.

When the evidence is ambiguous after these checks, do not report. The whole value of this rule is that its findings are real.

## Fix

Either deliver the interaction or drop the promise.

```tsx
// before: hover says clickable, nothing happens
<div className="cursor-pointer rounded-lg border p-4 hover:shadow-md hover:border-gray-300">
  <h3>Billing</h3>
  <p>Manage your plan and invoices.</p>
</div>

// after (a): make the whole card the link it was pretending to be
<Link href="/settings/billing" className="block rounded-lg border p-4 hover:shadow-md hover:border-gray-300">
  <h3>Billing</h3>
  <p>Manage your plan and invoices.</p>
</Link>

// after (b): it is a static panel, so let it look like one
<div className="rounded-lg border p-4">
  <h3>Billing</h3>
  <p>Manage your plan and invoices.</p>
</div>
```

## Why this needs a rule

Styling and behaviour are usually written in separate passes, and the hover state looks correct in every static rendering, so the mismatch only surfaces when someone actually clicks.

## Default tier and overrides

**Defaults to:** `backlog`

| Surface | Tier |
|---|---|
| Primary navigation, dashboards, list and card grids | fix-this-sprint |
| Checkout or onboarding steps | fix-this-sprint |
| Marketing landing page | backlog |
| Internal admin tools | backlog |

Never a release blocker: nothing is lost or broken, the user is misled and recovers.

## Suppression

```tsx
{/* ui-audit-ignore:slop-affordance-mismatch, handler is attached by the parent list via delegation */}
```

---
title: Stacked decorative layers with no role
id: slop-decoration-no-role
category: slop
defaultTier: backlog
detect: static
related: slop-token-drift, slop-faux-product-chrome
---

## Stacked decorative layers with no role

A blurred blob top-left, a second blob bottom-right, a grid overlay, a noise layer, and a radial glow behind the heading: five absolutely positioned elements that contain nothing, mean nothing, and sit between the user and the content. Each was added to make the section feel less empty, and together they make text harder to read, wash out the contrast the copy needs, cost paint time on every scroll, and, on a low-end phone, drop the frame rate for the sake of atmosphere nobody asked for. Content that has to compete with its own background reads as content nobody was confident in.

Atmosphere is not the problem. Atmosphere with no source is.

## Detection

A **decorative layer** is an element that satisfies all four:

1. positioned `absolute` or `fixed`,
2. `pointer-events-none` or `aria-hidden`,
3. no children and no text,
4. carries a gradient, `blur`, `backdrop-blur`, `mix-blend`, or `opacity` utility.

```bash
rg -cUP '(?s)<(?:div|span)\b(?=[^>]*?(?:\babsolute\b|\bfixed\b))(?=[^>]*?(?:pointer-events-none|aria-hidden))(?=[^>]*?(?:gradient|bg-linear|bg-radial|\bblur|backdrop-blur|mix-blend|opacity-))(?![^>]*?(?:size-\[max\(100%|pointer-fine:hidden|bg-clip-text|\bmask-))[^>]*?/>' \
   -g '*.tsx' -g '*.jsx' -g '!*.stories.tsx' -g '!*.test.tsx' src/ \
| sort -t: -k2 -rn
```

Every condition is a lookahead **inside one element match**, not a stage in a pipeline. That is load-bearing: `prettier-plugin-tailwindcss` wraps long class strings across lines, and these layers have the longest class strings on the page. A chain of line-based filters silently returns zero on a wrapped element, because `absolute` and `blur` end up on different output lines. A threshold rule that undercounts is worse than no rule: it reports "2, warn" on a section with five layers.

**Thresholds:** 3 or more in one component fails. Exactly 2 warns. **One never fires.**

The threshold is doing the work here, and that is deliberate. A single hero gradient wash is normal, frequently good, and one of the cheapest ways to give a section a focal point. Reporting it would train readers to skim this whole category, which costs more than the occasional stray blob. Count first, report second, and always list every layer with `file:line` so the count can be checked.

## False positives

- **The touch-target expander is an empty absolute `aria-hidden` element by design.** `guidelines/buttons.md` mandates `<span class="absolute ... size-[max(100%,3rem)] -translate-1/2 pointer-fine:hidden" aria-hidden="true" />` on small and icon buttons. It carries no gradient so it should not match, but the `size-[max(100%` and `pointer-fine:hidden` exclusions above are there in case it picks up an `opacity` utility. Never count it.
- **Functional layers that happen to look decorative.** Modal and drawer scrims (`inset-0 bg-black/50`) are click-catchers and contrast floors. `bg-clip-text` gradients are the text itself. `mask-` fades mark scrollable overflow, which is real information about what is reachable. Pseudo-element focus rings and selection highlights are state, not atmosphere. None of these are decoration with no role.
- **A shared decorative component used in 3 or more places is a brand system, not a one-off.** Check with `rg -l 'from .*GlowBackground'` before reporting. A `<GridPattern />` that appears on every section of the site is the visual language of the product, and the count that matters is 1 (the component), not the number of call sites. Skip it.
- **Charts, illustrations, and canvas backgrounds** are content rendered as layers.
- **Blur used for a real effect,** such as a frosted sticky header sitting over scrolling content, has an obvious job.
- **One faint grain layer that hides banding** (`guidelines/materials.md`) is a surface treatment, not atmosphere. Count it as the one allowed layer; extra noise stacks still fail.

## Fix

Keep the one layer that has a reason, delete the rest.

```tsx
// before: five layers, no source of light
<section className="relative">
  <div className="absolute -left-40 top-0 size-96 rounded-full bg-purple-500/30 blur-3xl pointer-events-none" />
  <div className="absolute -right-40 bottom-0 size-96 rounded-full bg-cyan-400/30 blur-3xl pointer-events-none" />
  <div className="absolute inset-0 bg-[url(/grid.svg)] opacity-20 pointer-events-none" />
  <div className="absolute inset-0 bg-linear-to-b from-white/0 to-white pointer-events-none" />
  <div className="absolute inset-0 mix-blend-overlay opacity-40 bg-noise pointer-events-none" />
  <h1>...</h1>
</section>

// after: one wash, placed where the eye should land
<section className="relative">
  <div className="absolute inset-x-0 top-0 h-64 bg-linear-to-b from-stone-100 to-transparent pointer-events-none" aria-hidden="true" />
  <h1>...</h1>
</section>
```

If every layer feels necessary, the section usually needs stronger type and spacing rather than more atmosphere.

## Why this needs a rule

Each layer is added in a separate turn and looks defensible on its own, so nothing in the generating context ever counts the stack, which is the only view from which the problem is visible.

## Default tier and overrides

**Defaults to:** `backlog`

| Surface | Tier |
|---|---|
| Any surface where a layer sits over body text at reduced contrast | fix-this-sprint |
| Marketing landing page | backlog |
| Application UI, internal admin | backlog |
| Prototype or spike branch | ignore |

Never a release blocker. If contrast under a layer actually fails, that is a colour-contrast finding and belongs to the accessibility rules, not here.

## Suppression

```tsx
{/* ui-audit-ignore:slop-decoration-no-role, the three layers are the campaign artwork signed off with brand */}
```

---
title: Faux product chrome wrapping nothing
id: slop-faux-product-chrome
category: slop
defaultTier: fix-this-sprint
detect: static
related: slop-unverifiable-proof, slop-decoration-no-role
---

## Faux product chrome wrapping nothing

Three coloured dots in a row, a rounded bar with a URL typed into it, a laptop outline around an empty gradient panel: this is a drawing of a product where the product should be. A visitor reads it as a screenshot, leans in to see what the app actually looks like, and finds there is nothing to see. That is a small betrayal on a page whose whole job is to show what you get, and it is worse than showing no image at all, because it spends the visitor's attention and returns nothing. It also costs real bytes and real layout to render a window frame that will never contain a window.

The failure is the frame with nothing inside it. A browser frame around a genuine product screenshot or video is a normal, well-used device.

## Detection

Three opening signals, and one that only ever corroborates. The finding is confirmed when the chrome demonstrably wraps no real content.

```bash
# 1. Traffic-light dot clusters
rg -nP 'rounded-full[^"`]*\bbg-(red|rose|yellow|amber|green|emerald)-[45]00' -g '*.tsx' src/

# 2. Empty styled panels with a fixed height
rg -nUP '(?s)<div[^>]*className="[^"]*\b(h-\d+|h-\[\d+px\]|aspect-)[^"]*"[^>]*/>' -g '*.tsx' src/

# 3. Device and browser frame components
rg -nP '<(Browser|Safari|Chrome|Mac|Window|Device|Phone|iPhone|Laptop|Tablet)\w*(Frame|Mockup|Window|Chrome|Shell)?\b' -g '*.tsx' src/
```

For signal 1, confirm before reporting: the three dots must be **adjacent siblings** (within about three lines of each other, no element between them) and carry **no adjacent text label**. For signals 2 and 3, open the element and confirm it has no `<img>`, `<video>`, `<Image>`, `children`, or real markup inside.

### Corroborating signal: a URL rendered as text

```bash
rg -nP '>\s*(https?://|www\.)[^<{]+<' -g '*.tsx' src/
```

**This cannot open a finding.** Run it only inside a file one of the three signals above already matched, and only to raise confidence that the frame is a browser rather than a device. A URL printed as text is correct in link previews, copy-to-clipboard fields, CLI output, docs examples, and `<code>` samples, and a repository's own base URLs and config constants are string literals everywhere. Nothing greppable separates those from an address bar; only the surrounding frame does, which is why this signal reports through the others and never on its own.

## False positives

Each of these is a legitimate pattern that the raw greps will hit. Confirm against all four before reporting:

- **A status legend is a real red/amber/green cluster.** Uptime pages, build dashboards, and severity keys all render coloured dots. The discriminator is the label: a legend dot sits beside text ("Operational", "Degraded", "P1"). Traffic-light chrome sits beside nothing. Require adjacency **and** the absence of a label before firing.
- **Skeleton loaders are legitimately empty fixed-height panels.** Skip anything with `animate-pulse`, and skip components named `Skeleton`, `Placeholder`, `Shimmer`, `Loading*`, or rendered inside a `Suspense` fallback. An empty grey box that will be filled in 200ms is doing its job.
- **Some products are browser chrome.** A browser extension, a devtool, a design-system documentation site, a screenshot tool, or a tutorial about the address bar all render window furniture as their subject matter. Only fire when the chrome wraps no real content: if the frame contains a live iframe, a product screenshot, a video, or rendered app markup, it is a presentation device and is fine.
- **A URL as text is often correct.** Displayed link previews, copy-to-clipboard fields, CLI output, docs examples, and `<code>` samples all show URLs as text on purpose, and so do a project's own base URLs and config constants. This is why the URL signal corroborates and never opens a finding.

## Fix

Replace the drawing with the thing, or remove the frame.

```tsx
// before: a window that contains nothing
<div className="rounded-lg border shadow-xl">
  <div className="flex gap-2 border-b p-3">
    <span className="size-3 rounded-full bg-red-500" />
    <span className="size-3 rounded-full bg-yellow-500" />
    <span className="size-3 rounded-full bg-green-500" />
    <div className="ml-4 rounded bg-gray-100 px-3 text-xs">app.example.com</div>
  </div>
  <div className="h-96 bg-linear-to-br from-indigo-50 to-white" />
</div>

// after: the frame earns its place by holding a real screenshot
<div className="rounded-lg border shadow-xl">
  <BrowserBar url={liveDemoUrl} />
  <Image src="/screenshots/dashboard.png" alt="The billing dashboard showing this month's invoices" width={1280} height={800} />
</div>
```

If no real screenshot exists yet, ship the section without the mockup. An honest heading and a link to a live demo beat a picture of a product.

## Why this needs a rule

Window chrome is such a common visual idiom in training data that a model reaches for it as page furniture, and generating it costs nothing, whereas noticing that the frame will ship empty requires asking whether the asset behind it actually exists.

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

| Surface | Tier |
|---|---|
| Marketing landing page or pricing page | fix-this-sprint |
| Public product page or app store listing | fix-this-sprint |
| Internal admin tools | backlog |
| Prototype, spike, or design review branch | backlog |

Never a release blocker: it misleads without breaking anything, and the fix usually waits on a real asset.

## Suppression

```tsx
{/* ui-audit-ignore:slop-faux-product-chrome, this product is a browser extension and the chrome is the subject */}
```

---
title: Near-duplicate of an existing scale step
id: slop-near-duplicate-scale
category: slop
defaultTier: backlog
detect: static
related: slop-token-drift
---

## Near-duplicate of an existing scale step

A scale works because its steps are far enough apart to read as deliberate. `text-[15px]` sitting between `text-sm` (14px) and `text-base` (16px) does not create a new level of hierarchy, it creates a third size that looks like a mistake next to the other two. The same goes for `p-[13px]` beside `p-3`, or `rounded-[7px]` beside `rounded-md`. Users see labels that are almost but not quite aligned, cards whose corners almost but not quite match, and read the surface as sloppy rather than as having more levels. It is the most literal form of generated-then-nudged UI: someone eyeballed a value instead of stepping the scale.

This rule is deliberately narrow. It fires only on an arbitrary pixel value that lands within 1px of a step the theme already defines.

## Not this rule

Using several steps of the same family on one surface is correct practice and must never be reported here:

- **Elevation ramps.** `shadow-sm` on a resting card, `shadow-md` on hover, `shadow-lg` on a popover. That is one system expressing three heights.
- **Nested radii.** An outer `rounded-lg` container with an inner `rounded-md` control. Concentric corners require different radii to look concentric.
- **Type ramps.** `text-sm` caption, `text-base` body, `text-lg` lead in one block.

The failure is a value that is *almost* a step, not the use of multiple steps.

## Detection

**Precondition:** a theme must exist (`@theme` block or `tailwind.config.*`). With no defined scale there is nothing to be a near-duplicate of: report **result unknown** and stop.

```bash
# Arbitrary px values in scale-bearing families, minus optical nudges of 2px or less
rg -noP '\b(text|p|px|py|pt|pb|pl|pr|m|mt|mb|ml|mr|mx|my|gap|gap-[xy]|space-[xy]|rounded(-[a-z]+)?|leading|w|h|size|inset|top|bottom|left|right)-\[-?\d+(\.\d+)?px\](?!:)' \
  -g '*.tsx' -g '*.jsx' -g '!*.stories.tsx' -g '!*.test.tsx' src/ \
| rg -vP '\[-?([01](\.\d+)?|2(\.0+)?)px\]'
```

Compare each hit against the theme's own values. Tailwind's defaults, if the theme has not overridden them:

| Family | Steps (px) |
|---|---|
| `text-*` | 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72 |
| spacing (`p`, `m`, `gap`) | 4, 8, 12, 16, 20, 24, 32, 40, 48, 64 |
| `rounded-*` | 2, 4, 6, 8, 12, 16, 24 |

Fire when `abs(value - nearest step) <= 1`. An exact match (`text-[16px]` where `text-base` exists) is the trivial case and gets the same finding with a one-token fix. A value 4px or more off a step is out of scope here: that is a size the theme does not cover, which belongs to `slop-token-drift`.

**Skip entirely:** `rem`, `%`, `vh`, `vw`, `em`, `ch`, and any value containing a function (`calc(`, `min(`, `max(`, `clamp(`, `round(`). A `rem` font size is the form `guidelines/general.md` explicitly asks for, and a percentage or viewport unit is relative to something the scale cannot know about.

## False positives

- **A near-scale value used consistently across many files** is an unregistered scale step, not a one-off nudge. A 13px UI text size used in twenty components is a decision. The fix is to register it in the theme and give it a name, not to bump every use to 14px. Recurrence across files is the tell: check with `rg -l` before reporting.
- **Values derived from an asset or an external constraint.** `w-[187px]` matching a supplied logo's intrinsic width, or a height matching a third-party embed, is not scale drift.
- **Optical corrections on icons and glyphs.** A 1px shift to make an icon look centred is craft, and the sibling rule `slop-token-drift` already excludes nudges of 2px or less for the same reason.
- **Files with no access to the theme**, such as email templates or embedded widgets that must ship inline styles.

## Fix

Step the scale instead of nudging it.

```tsx
// before
<p className="text-[15px] p-[13px] rounded-[7px]">

// after
<p className="text-sm p-3 rounded-md">
```

If 15px is genuinely required and recurs, make it a real step so the next component can reach it:

```css
@theme {
  --text-ui: 0.9375rem; /* 15px, the dense table row size */
}
```

## Why this needs a rule

A model picks a value that looks right in isolation and has no reason to check whether the theme already defines something 1px away, since the rendered result is indistinguishable in the moment and only reads as wrong beside its neighbours.

## Default tier and overrides

**Defaults to:** `backlog`

| Surface | Tier |
|---|---|
| Design-system package or shared UI primitives | fix-this-sprint |
| Application UI (dashboard, settings, admin) | backlog |
| Marketing landing page | backlog |
| Prototype or spike branch | ignore |


## Suppression

```tsx
{/* ui-audit-ignore:slop-near-duplicate-scale, height matches the embedded player's fixed frame */}
```

---
title: Arbitrary values drifting off the theme
id: slop-token-drift
category: slop
defaultTier: backlog
detect: static
related: slop-near-duplicate-scale
---

## Arbitrary values drifting off the theme

A theme exists so that sizes, colours, and radii repeat across a product and the eye reads them as one system. When a file reaches for five or six one-off bracket values, the surface stops agreeing with the rest of the app: headings land at sizes no other heading uses, a card corner is 3px rounder than every neighbouring card, a blue appears that is close to the brand blue but not it. Users do not name this, they just find the product harder to scan and slightly untrustworthy, the way a page of mixed fonts feels off before you work out why. It is also the single clearest fingerprint of a generated component pasted in next to hand-built ones.

Density is the signal, not any one value. One arbitrary value with a reason is craft. Six in a 90-line file is a component built without ever opening the theme.

## Detection

**Precondition:** a theme must exist. If neither an `@theme` block nor a `tailwind.config.*` is present, there is no scale to drift from: report **result unknown** and stop.

```bash
# 0. Precondition
rg -l '@theme' --glob '*.css' . ; ls tailwind.config.* 2>/dev/null
```

Count **distinct** arbitrary values per file (a token repeated ten times is one decision, not ten):

```bash
rg -l 'className' -g '*.tsx' -g '*.jsx' \
   -g '!*.stories.tsx' -g '!*.test.tsx' -g '!*.spec.tsx' \
   -g '!**/node_modules/**' -g '!**/vendor/**' -g '!**/.next/**' src/ \
| while read -r f; do
    n=$(rg -oP '\b[a-z][a-z0-9-]*-\[[^\]]+\](?!:)' "$f" \
        | rg -v 'ch\]|max\(|min\(|clamp\(|calc\(|round\(|var\(|--' \
        | rg -vP '\[-?([01](\.\d+)?|2(\.0+)?)px\]' \
        | sort -u | wc -l)
    [ "$n" -ge 3 ] && echo "$n  $f"
  done | sort -rn
```

Arbitrary colour literals count toward the same total:

```bash
rg -nP '\b(bg|text|border|ring|fill|stroke|shadow|from|via|to)-\[#[0-9a-fA-F]{3,8}\]' -g '*.tsx' src/
```

**Thresholds:** 5 or more distinct arbitrary values in one file fails. 3 to 4 warns. Report every offending value with `file:line` so the count is auditable.

## False positives

The `(?!:)` in the pattern above is load-bearing: `data-[state=open]:`, `aria-[current=page]:`, `group-data-[open]:`, `has-[input:focus]:`, and `max-[600px]:` are variant selectors, not arbitrary values, and must never be counted.

All of these are legitimate and are excluded by the filters above. Do not report them:

- **`ch` measures.** `max-w-[65ch]`, `max-w-[35ch]` and friends are mandated by `guidelines/heading-groups.md` and `guidelines/prose-content.md`. A theme cannot express a measure in characters.
- **Anything containing `max(`, `min(`, `clamp(`, `calc(`, or `round(`.** `size-[max(100%,3rem)]` is the touch-target expander mandated by `guidelines/buttons.md`; `rounded-[calc(var(--radius)-var(--padding))]` is the nested-radius formula. A function is reasoning, not a magic number.
- **Anything containing `var(` or `--`.** `bg-[var(--brand)]` and `grid-rows-[--spacing(6)_1fr]` reference the theme, which is the opposite of drifting from it.
- **Optical nudges of 2px or less.** `mt-[1px]`, `top-[-2px]`, `translate-y-[0.5px]`. Optical alignment is a real craft move that no spacing scale should absorb.
- **Story, test, and vendored files.** Fixtures exist to pin odd values.

One more judgement call the script cannot make: a single arbitrary value repeated across many files is an unregistered scale step, not drift. The fix there is to add it to the theme, not to snap it to a neighbour.

## Fix

Promote repeated values into the theme, and snap one-offs to the nearest existing step.

```tsx
// before: six decisions, none traceable
<div className="rounded-[10px] bg-[#f7f7f8] p-[18px] text-[15px] shadow-[0_2px_8px_rgba(0,0,0,0.06)] gap-[14px]">

// after: same look, all traceable
<div className="rounded-xl bg-gray-50 p-5 text-sm shadow-sm gap-3.5">
```

If a value genuinely has no home in the theme and recurs, register it:

```css
@theme {
  --radius-card: 10px;
  --color-surface-subtle: #f7f7f8;
}
```

## Why this needs a rule

A model writing one component sees only that component, where every arbitrary value looks locally reasonable; the drift only exists relative to a theme file it was never asked to open.

## Default tier and overrides

**Defaults to:** `backlog`

| Surface | Tier |
|---|---|
| Design-system package or shared UI primitives | fix-this-sprint |
| Marketing landing page | backlog |
| Internal admin tools | backlog |
| Prototype or spike branch | ignore |

Never a release blocker: nothing here breaks a task, it erodes coherence over time.

## Suppression

```tsx
{/* ui-audit-ignore:slop-token-drift, values pinned to a third-party embed's own scale */}
```

---
title: Unverifiable proof standing in for real evidence
id: slop-unverifiable-proof
category: slop
defaultTier: backlog
detect: static
related: slop-faux-product-chrome
---

## Unverifiable proof standing in for real evidence

"99.9% uptime", "10,000+ teams", "3x faster", a testimonial from Jane Doe, CEO at Acme, and a strip of logos nobody has heard of. Every one of these is a claim about the world, and a visitor who cannot check any of them learns that this page's numbers are decoration. The damage is not aesthetic: it is that the true claims on the same page now read as invented too, and the one number you could have proven gets discounted with the rest. Shipping a placeholder testimonial to production is also a straightforward credibility risk, and in some jurisdictions an advertising one.

`direction/aesthetic-direction.md` treats invented proof as absolute rather than count-based, for exactly this reason: it misinforms rather than merely underwhelming.

## Precondition: this rule requires diff scope

**Read this before running anything.** A real company has real logos, real customer counts, and a real uptime number. `99.9%` on a mature marketing page is very likely true and audited. This rule cannot tell a true stat from an invented one by looking at the string.

So it fires only when the string is a **literal in JSX** and either:

1. it matches a **placeholder marker** (see below), which is decisive on its own, or
2. it was **introduced in the diff under audit**, meaning a claim about the world appeared without anyone having gathered evidence for it.

On a full-codebase sweep with no diff, report **result unknown** for the shape-based signals and report only placeholder-marker hits. Do not list a page's existing stats as findings.

## Detection

```bash
# Placeholder markers: decisive with or without a diff
rg -ni 'logoipsum|placehold\.|placeholder\.com|via\.placeholder|dummyimage|lorem ipsum' -g '*.tsx' -g '*.jsx' src/
rg -nP '/logo-[1-9]\.(png|svg|webp)|/(client|partner|customer)-[1-9]\.' -g '*.tsx' src/
rg -ni 'jane doe|john doe|john smith|acme (inc|corp|co\b)|example\.com|@example\.|CEO, Acme|Company Name' -g '*.tsx' src/

# Shape-based signals: diff scope only
git diff --unified=0 origin/main...HEAD -- '*.tsx' '*.jsx' \
  | rg '^\+' \
  | rg -v 'className|class=' \
  | rg -nP '\b\d{1,3}(\.\d+)?%|\b\d{1,3},\d{3}\+|\b\d+(\.\d+)?x (faster|cheaper|more)|\b\d+M\+|\b\d+k\+ '
```

The `className` filter matters: `size-[max(100%,3rem)]` and `w-1/2` are full of numbers and percentages that are not claims about the world. Any hit that survives still needs reading in context, since a percentage inside a `style` object or a chart config is data, not copy.

Every finding must carry `file:line` and the exact literal, so a human can answer one question: is this true, and who can confirm it?

## False positives

- **Anything that is not a string literal in JSX.** `{stats.customerCount}`, `{`${uptime}%`}`, `{t('hero.stat')}`, and values read from a CMS or a config file are data, and the data may well be correct. Never report a rendered expression. This exclusion is doing most of the work.
- **True stats are the normal case.** A funded company genuinely has 10,000 customers and genuinely publishes 99.9%. The round shape of a number is suspicious only when the number is brand new and nobody sourced it.
- **`Acme` and `example.com` are correct in docs, tests, and fixtures.** Documentation examples, Storybook stories, seed data, and API samples are supposed to use reserved placeholder names. Skip `*.stories.tsx`, `*.test.tsx`, `docs/`, `fixtures/`, `mocks/`, and seed scripts.
- **Real people are sometimes named Jane.** Confirm the surrounding testimonial has a real role, company, and ideally a link or photo before reporting a name.
- **Pricing, percentages, and benchmarks with a citation.** A stat next to a footnote, a source link, or a "measured on ..." qualifier has already done the work this rule asks for.

## Fix

Cut the claim, or make it checkable.

```tsx
// before
<p className="text-5xl font-semibold">10,000+</p>
<p className="text-gray-600">teams ship faster with us</p>
<img src="https://logoipsum.com/logo-1.svg" alt="Customer logo" />

// after: a smaller true number beats a big invented one
<p className="text-5xl font-semibold">{customerCount.toLocaleString()}</p>
<p className="text-gray-600">teams on a paid plan as of {asOfDate}</p>
<img src="/logos/northwind.svg" alt="Northwind" />
```

When there is no evidence yet, delete the section. A landing page with one honest sentence outperforms one with five unprovable ones, and the empty slot is a useful reminder to go and get a real quote.

## Why this needs a rule

A model asked for a stats band has no access to the company's real numbers and no way to leave the slot empty, so it fills the shape with a plausible figure, which is exactly the failure mode a reviewer must catch before it ships.

## Default tier and overrides

**Defaults to:** `backlog`

| Surface | Tier |
|---|---|
| Marketing landing, pricing, or home page | fix-this-sprint |
| Public case study or testimonial page | fix-this-sprint |
| Application UI, internal admin, docs | backlog |
| Storybook, tests, fixtures | ignore |

Never a release blocker on its own, but a placeholder-marker hit on a public marketing page should not survive a review cycle.

## Suppression

```tsx
{/* ui-audit-ignore:slop-unverifiable-proof, 99.95% is the contractual SLA, see legal/sla.md */}
```

---
title: Loading state causes layout shift on data arrival
id: states-layout-shift
category: states
defaultTier: fix-this-sprint
detect: rendered
---

## Loading state causes layout shift on data arrival

The skeleton or spinner takes 0x0 (or some height); loaded content takes 200x400; when data arrives every element below it jumps. This is the default Cumulative Layout Shift bug, everywhere: skeletons without `min-height`, images without `width`/`height`, fonts without `font-display: swap` and `size-adjust`. Fix is mechanical, one-time per surface.

## What goes wrong

A user reads a paragraph above a list whose loading state is `<Spinner />` (no fixed height). Data arrives, the list expands to 600px, the paragraph shoves off screen, and the user re-finds their place; CLS regresses on Lighthouse. Same pattern on marketing pages with hero images lacking `width`/`height`.

## Detection

**Surfaces:** every loading state, every image, every web font.

**Static signals (candidates only):**
1. **Skeletons without fixed height.** Verify a declared height (`h-N`, `min-h-N`, `style={{ minHeight }}`, fixed row count).
2. **Images without dimensions.** `<img>` and `<Image>` (next/image): fail if neither `width`+`height` nor `fill` with a sized parent.
3. **Fonts without swap + size-adjust.** In `next/font/google`, `next/font/local`, `@font-face`, verify `display: "swap"` and (ideally) `adjustFontFallback`.
4. **Conditional content above other content.** `{!data && <Skeleton h={4} />}` then a variable-height `<List />` is a CLS bug if heights differ.

**Rendered check (decisive):**

The greps find missing dimensions; the shift itself is a delta between two rendered boxes, so measure it. A skeleton that declares `h-14` still shifts if the loaded row sets 68px, and a skeleton with no declared height does not shift if its parent already reserves the space.

Load the surface with the network throttled so the loading state is observable. Record the bounding box of each skeleton, spinner, or placeholder, then record the same container once data has arrived, and compare heights. Attribute the movement with a `PerformanceObserver` on `layout-shift` entries over that window: each entry names the sources that moved and how far. Flag any container whose height changes on data arrival, and report the element, both heights, and the viewport.

The `ui-verification` skill runs this as its layout-shift probe, holding the data response open rather than throttling the whole network so the shell is not slowed with it. Dispatch to it when an app is running; with no browser the greps below produce candidates and the rule is `unknown`, never a fail.

**Concrete commands:**
```bash
# Skeletons missing min-height
rg -l 'Skeleton' --type=ts src/ | while read f; do
  rg -B 1 -A 3 '<Skeleton' "$f" | rg -q 'h-|height|min-h' \
    || echo "$f: skeleton without explicit height"
done

# <img> without width/height
rg '<img\s' --type=ts --type=js src/ | rg -v 'width=.*height=|height=.*width='

# next/image without width/height/fill
rg '<Image\s' --type=ts src/ | rg -v 'width=|fill'

# Fonts not using swap
rg 'next/font' --type=ts app/ src/ | rg -v 'display: ["\']swap'

# @font-face without font-display
rg -l '@font-face' --type=css | while read f; do
  rg -q 'font-display' "$f" || echo "$f: @font-face without font-display"
done
```

**False-positive guards:**
- Skip files with `// ui-audit-ignore:states-layout-shift`.
- Below-the-fold `content-visibility: auto` may CLS-shift inside its own subtree (acceptable).
- Skip components declaring `min-height` via CSS class (Tailwind `min-h-*`); inspect class strings first.
- Skip Storybook fixtures.

## Fix

Three patches:

```tsx
// 1. Skeletons get fixed dimensions matching loaded layout
function InvoiceRowSkeleton() {
  return <li className="h-14 rounded-md bg-muted animate-pulse" />;
  //                  ^ matches loaded row height
}

function InvoiceListSkeleton() {
  return (
    <ul className="space-y-2">
      {Array.from({ length: 5 }).map((_, i) => <InvoiceRowSkeleton key={i} />)}
    </ul>
  );
}

// 2. Images declare intrinsic dimensions
import Image from "next/image";

<Image
  src="/hero.jpg"
  alt="Product hero"
  width={1280}
  height={720}
  priority
/>

// or fill mode with a sized parent
<div className="relative aspect-video">
  <Image src="/hero.jpg" alt="..." fill />
</div>

// 3. Fonts loaded with swap + size-adjust fallback
// app/layout.tsx
import { Inter } from "next/font/google";

const inter = Inter({
  subsets: ["latin"],
  display: "swap",        // shows fallback immediately, swaps when ready
  adjustFontFallback: true, // Next.js auto-tunes fallback metrics to reduce CLS
});

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  );
}
```

For dynamic-height content (chat bubble, comment), reserve a reasonable minimum in the skeleton and `min-height`-match the real content: close enough not to jolt, not exact.

Docs:
- next/image: https://nextjs.org/docs/app/api-reference/components/image
- next/font: https://nextjs.org/docs/app/api-reference/components/font
- web.dev CLS: https://web.dev/articles/cls

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| Marketing landing (LCP-critical) | release-blocker |
| Checkout (form fields shifting under user's cursor) | release-blocker |
| List / Feed / Inbox | fix-this-sprint |
| Dashboard widget | fix-this-sprint |
| Internal admin | backlog |

A field that shifts under the cursor mid-click causes mis-clicks on destructive actions, so checkout escalates.

## Defer-to (when this is another tool's job)

- Lighthouse / web-vitals report the CLS metric: this rule prevents the bug at write time, Lighthouse confirms it at runtime. Link out, don't restate.
- Vercel Speed Insights for field measurement.

## Suppression

```tsx
{/* ui-audit-ignore:states-layout-shift, content-visibility:auto, expected to expand */}
<details>
```

---
title: Empty state has no call to action
id: states-no-empty-state
category: states
defaultTier: fix-this-sprint
detect: static
related: states-no-error-state
---

## Empty state has no call to action

When a list, table, or feed is empty, "No items" alone is a dead end: the user can't tell whether nothing exists, the filter is too narrow, or they must act to populate it. A good empty state names the situation, explains why, and offers exactly one primary action. Onboarding empty states (first-run inbox, fresh dashboard) are the product's highest-leverage surfaces, and the most commonly skipped.

## What goes wrong

A new user lands on the dashboard. The "Recent invoices" widget reads "No invoices": no button, no link, nothing suggesting they create one. The user assumes the feature is broken and bounces. Or a power user filters their inbox to "starred + label:billing + last 7 days": zero results, same dead-end "No messages" with no "Clear filters" CTA.

## Detection

**Surfaces:** list, feed, inbox, table, dashboard widget, search results, first-run dashboard, onboarding step.

**Static signals:**
1. Find empty branches: `items.length === 0`, `isEmpty`, `data?.length ?? 0 === 0`, `!data?.length`, `data === null && !isLoading`.
2. Inspect the JSX the empty branch returns.
3. Fail if it contains only text: no `<Button>`, `<Link>`, `<a>`, `<button>`, `onClick=` element.
4. Fail if the only "action" is a passive sentence ("Try a different search") with no clickable element.

**Concrete commands:**
```bash
# Empty branches
rg -B 1 -A 6 '\.length === 0|isEmpty|!\w+\.length' --type=ts src/

# Empty branches without an action element
rg -l '\.length === 0|isEmpty' --type=ts src/ | while read f; do
  rg -A 8 '\.length === 0|isEmpty' "$f" | rg -q 'Button|Link|<a |onClick' \
    || echo "$f: empty branch without CTA"
done

# Look for "no .* yet" copy without a sibling button
rg -i 'no .{1,30} yet|nothing here|empty' --type=ts src/
```

**False-positive guards:**
- Skip files with `// ui-audit-ignore:states-no-empty-state`.
- Skip transient empty states during initial type-ahead (picker just opened, nothing typed yet): covered separately.
- Skip nested empty branches inside a parent that already provides a page-level CTA.
- Skip Storybook fixtures.

## Fix

Render a named empty state with one primary action:

```tsx
// before
{items.length === 0 && <p>No invoices</p>}

// after
import { FileText } from "lucide-react";

function EmptyInvoices({ onCreate }: { onCreate: () => void }) {
  return (
    <div className="flex flex-col items-center gap-3 py-12 text-center">
      <FileText className="h-10 w-10 text-muted-foreground" />
      <h3 className="text-lg font-medium">No invoices yet</h3>
      <p className="text-sm text-muted-foreground max-w-sm">
        Create your first invoice to start tracking payments. It takes about a minute.
      </p>
      <Button onClick={onCreate}>Create invoice</Button>
    </div>
  );
}

{items.length === 0 ? <EmptyInvoices onCreate={openInvoiceForm} /> : <List items={items} />}
```

For zero-result searches:

```tsx
{results.length === 0 && (
  <div className="py-8 text-center">
    <p>No results for "{query}".</p>
    <Button variant="ghost" onClick={clearFilters}>Clear filters</Button>
  </div>
)}
```

Docs:
- shadcn/ui empty patterns: https://ui.shadcn.com/docs/components/base/card
- Next.js Link: https://nextjs.org/docs/app/api-reference/components/link

## Default tier and overrides

**Defaults to:** `fix-this-sprint`

**Surface overrides:**
| Surface | Tier |
|---|---|
| First-run dashboard / onboarding step | release-blocker |
| Critical-path picker (e.g. "select a payment method" with zero) | release-blocker |
| List / Feed / Inbox | fix-this-sprint |
| Search results | fix-this-sprint |
| Internal admin | backlog |
| Power-user filter scenarios | backlog |

## Defer-to (when this is another tool's job)

- Copywriting quality on the empty-state body text: defer to copywriting review (this rule only requires a CTA, not perfect copy).

## Suppression

```tsx
{/* ui-audit-ignore:states-no-empty-state, typeahead initial state, CTA would be noise */}
{!query && <p className="text-muted-foreground">Start typing to search</p>}
```

---
title: Async fetch has no inline error state
id: states-no-error-state
category: states
defaultTier: release-blocker
detect: static
related: states-no-empty-state, async-no-error-boundary
---

## Async fetch has no inline error state

Every async op can fail. A happy-path-only component turns a transient 500 into a blank screen, an infinite spinner, or a silent stale render. This rule owns the component's own error branch: the failure renders a message naming what broke plus a way out (retry, go back, contact support), in place, without unmounting the surrounding UI. Structural boundaries (`error.tsx`, `<ErrorBoundary>`) are `async-no-error-boundary`'s job; a component needs both, and a boundary alone still loses the working parts of the page.

## What goes wrong

A list fetch fails; the component has no error branch, so it renders the loading skeleton forever. The user reloads, sees the same skeleton, and assumes the product is broken. Or the fetch resolves to `undefined` and the render reads `data.name`, so the widget throws and the nearest boundary swallows the whole surrounding page along with it.

## Detection

**Surfaces:** every async fetcher.

**Static signals:**
1. Find async calls: `useQuery`, `useSWR`, `fetch(`, `await`, async server components.
2. Per component, look for a render-time error branch: `if (isError|error) return ...`.
3. That branch must carry a retry path (`refetch`, `reset`, `onClick`) and name what failed.
4. Fail if a fetching component has no error branch, or has one with no retry path.

**Concrete commands:**
```bash
# Async fetchers
rg -l 'useQuery|useSWR|await fetch|async function' --type=ts src/ app/

# Files lacking an inline error branch
rg -l 'useQuery|useSWR' --type=ts src/ | while read f; do
  rg -q 'isError|hasError|onError|catch' "$f" \
    || echo "$f: fetcher without an inline error branch"
done

# Inline error branches without retry
rg -l 'isError|hasError' --type=ts src/ | while read f; do
  rg -A 5 'isError|hasError' "$f" | rg -q 'retry|tryAgain|refetch|onClick' \
    || echo "$f: error branch without retry path"
done
```

**False-positive guards:**
- Skip files with `// ui-audit-ignore:states-no-error-state`.
- Static / pre-rendered components with no fetch are exempt.
- A wrapping `<ErrorBoundary>` does not clear this finding: it replaces the subtree instead of the failed part. Report the boundary gap under `async-no-error-boundary` and the missing branch here.

## Fix

Add the error branch with a retry, next to the loading branch:

```tsx
// before
"use client";
export function InvoiceList() {
  const { data, isLoading } = useInvoices();
  if (isLoading) return <InvoiceListSkeleton />;
  return <ul>{data.map(InvoiceRow)}</ul>;
}

// after: inline error branch with retry
"use client";
export function InvoiceList() {
  const { data, isLoading, isError, refetch } = useInvoices();
  if (isLoading) return <InvoiceListSkeleton />;
  if (isError) {
    return (
      <div role="alert" className="rounded-md border p-4">
        <p className="font-medium">Couldn't load invoices.</p>
        <p className="text-sm text-muted-foreground">Check your connection or try again.</p>
        <Button onClick={() => refetch()} variant="outline">Try again</Button>
      </div>
    );
  }
  return <ul>{data.map(InvoiceRow)}</ul>;
}
```

For a server component, the equivalent is a `try`/`catch` around the fetch that returns the same error markup, so the failure stays inside the widget's slot.

Then add the structural boundary underneath it: see `async-no-error-boundary`.

Docs:
- TanStack Query error handling: https://tanstack.com/query/latest/docs/framework/react/guides/query-functions#handling-and-throwing-errors
- SWR error handling: https://swr.vercel.app/docs/error-handling

## Default tier and overrides

**Defaults to:** `release-blocker` on critical paths, `fix-this-sprint` elsewhere.

**Surface overrides:**
| Surface | Tier |
|---|---|
| Checkout / Payment | release-blocker |
| Sign-in / Sign-up | release-blocker |
| Dashboard root | release-blocker (per-widget branch, so one failure keeps the rest usable) |
| First-run onboarding | release-blocker |
| List / Feed / Inbox | fix-this-sprint |
| Search results | fix-this-sprint |
| Marketing landing | backlog |
| Internal admin | fix-this-sprint |

## Defer-to (when this is another tool's job)

- Sentry / observability captures the error itself; this rule covers what the user sees.
- A monitoring rule verifies error rates <= threshold; this rule verifies the UI handles the error.

## Suppression

```tsx
{/* ui-audit-ignore:states-no-error-state, prefetched by the parent route loader, cannot fail here */}
<RevenueWidget />
```

---
title: Do not change font-weight on hover or selected
id: type-hover-weight-shift
category: type
defaultTier: backlog
detect: static
related: states-layout-shift, type-readable-scale
---

## Do not change font-weight on hover or selected

Bumping `font-weight` on hover, focus, or selected nav items makes the label wider, so neighbours shift. The user sees the row jump rather than a state change. Use color, opacity, background, or underline for selected and hover; keep the weight stable.

## Detection

Search for hover or selected variants that set a different font weight.

```bash
rg -nP 'hover:font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)|data-\[(?:state=active|selected)\]:font-|aria-selected:font-|aria-current:font-' -g '*.tsx' -g '*.jsx' -g '*.css' src/
```

Skip a weight change that is the only indication of a selected tab and is paired with a reserved slot (fixed-width item, `tabular-nums`, or a max-width that already contains the bold label). Skip body copy that is not a control.

**Incorrect (selected weight reflows the row):**

```tsx
<Link className="font-medium hover:font-bold data-[active]:font-bold" href="/inbox">
  Inbox
</Link>
```

**Correct (weight stays put):**

```tsx
<Link className="font-medium text-zinc-600 hover:text-zinc-950 data-[active]:text-zinc-950" href="/inbox">
  Inbox
</Link>
```

---
title: Set a Readable Type Scale
id: type-readable-scale
category: type
defaultTier: fix-this-sprint
detect: static
---

## Set a Readable Type Scale

Use body sizes and weights readable across desktop and mobile. Undersized or underweight body text slows scanning and tires readers.

## Detection

Search for a base text rule (`body`, `html`, `:root`, `.prose`) that sets a size below 16px or a weight under 400.

```bash
rg -nUP '(?:\bbody\b|\bhtml\b|:root|\.prose)[^{}/]*\{[^}]*font-(?:size:\s*(?:0?\.\d+rem|(?<![\d.])(?:\d|1[0-5])(?:\.\d+)?px)|weight:\s*[123]00\b)' -g '*.css' -g '*.scss' src/
```

A light weight on a large-format `.prose` variant (marketing body set at 20px and up) matches and reads fine, since weight tolerance rises with size. Read the `font-size` in the same block before reporting.

**Incorrect (too small and too light):**

```css
body {
  font-size: 12px;
  font-weight: 300;
  line-height: 1.2;
}
```

**Correct (readable defaults):**

```css
body {
  font-size: clamp(0.95rem, 0.2vw + 0.9rem, 1.125rem);
  font-weight: 400;
  line-height: 1.45;
}
```

# Sections

The canonical index for `ui-design/rules/`. One heading per category; the id in parentheses is the filename prefix that groups the rules in it (`<prefix>-<slug>.md`) and the value of each rule's `category` key. Category impact is the default; per-rule tiers live in each rule file's `defaultTier`.

Pure design-decision scoring (choice architecture, information hierarchy, mental-model fit, visual polish) is out of the audit's lane; route it to `product-design`, and to the build-side guidance in this skill for visual direction.

---

## One folder, detect key

These rules came from earlier sets: source-reasoned behavior rules and rendered-quality rules. That distinction is now recorded per rule in the `detect` key, not in a folder name:

- `detect: static` reads the source. Grep, AST, file presence.
- `detect: rendered` needs the built output. Screenshot, computed style, a real viewport.
- `detect: rubric` is scored 1-5 against the anchor table in the rule's own file, because the defect does not reduce to a boolean.

Do not reintroduce a second rules folder. A rule that needs the browser says so in `detect`; splitting the corpus by lineage again is what produced three drifting indexes and three templates.

---

## 1. Forms and Validation (forms)

**Impact:** CRITICAL
**Default tier:** release-blocker for submit and data-loss bugs, fix-this-sprint elsewhere
**Rules:** 9
**Description:** Forms are conversion paths, and form-handling bugs are the most common ship-blockers. Labels, autocomplete, paste and IME support, error association, mobile input sizing, and overlaid affixes decide whether users can complete a form at all. React 19's `useActionState`, `useFormStatus`, and `useOptimistic` address the behavior half only if used correctly: form clears on validation error, double-submit, `useFormStatus` misuse with its always-false bug.

## 2. States (states)

**Impact:** CRITICAL
**Default tier:** release-blocker on critical paths, fix-this-sprint elsewhere
**Rules:** 3
**Description:** Missing or broken states is the single highest-impact production UX bug. Every data-fetching component needs empty, error, and a loading placeholder that does not shift layout. The most common bug is happy path only. This category owns those states wherever they appear; the layout rules cover the container, not the state.

## 3. Async (async)

**Impact:** CRITICAL
**Default tier:** mostly release-blocker
**Rules:** 4
**Description:** Async work introduces race conditions, optimistic updates with no rollback, and missing Suspense or error boundaries. Silent until they are not.

## 4. Focus and Keyboard (focus)

**Impact:** CRITICAL
**Default tier:** release-blocker for traps and restoration, fix-this-sprint for dynamic content
**Rules:** 3
**Description:** Focus management is invisible to mouse users and breaks the experience entirely for keyboard and screen reader users. axe checks landmarks but not where focus went after an action.

## 5. Accessibility and Semantics (a11y)

**Impact:** CRITICAL
**Default tier:** mostly release-blocker
**Rules:** 10
**Description:** Semantic structure, accessible names, non-color state cues, media alternatives, document language, and tooltip contracts. Failures exclude assistive-tech users entirely, so run this category first. Contrast ratios are not checked here: axe-core computes them, so run it rather than eyeballing hex values.

## 6. Keyboard and Interaction (interaction)

**Impact:** CRITICAL
**Default tier:** release-blocker for focus and operability, fix-this-sprint for sizing
**Rules:** 3
**Description:** Every interactive element must be keyboard-operable with visible focus and adequate hit targets. A mouse-only control is broken for keyboard, switch, and many touch users.

## 7. Navigation and Feedback (nav)

**Impact:** HIGH
**Default tier:** mostly fix-this-sprint
**Rules:** 2
**Description:** Real links for navigation and live-region announcements. Users need to know where they are and what the system is doing.

## 8. Microcopy (microcopy)

**Impact:** HIGH
**Default tier:** fix-this-sprint, release-blocker for leaked errors
**Rules:** 2
**Description:** Vague errors and leaked exception text with PII or stack traces. Wording of a string that is not an error is `copywriting`.

## 9. Mobile and Touch (mobile)

**Impact:** HIGH
**Default tier:** mostly fix-this-sprint
**Rules:** 2
**Description:** Patterns that work on desktop but fail on touch: hover-only affordances, missing viewport meta, `100vh` on mobile, no safe-area insets. Hover gating and press feedback are `ui-animation`. Lighthouse catches some tap-target failures; these rules add the affordance and viewport patterns.

## 10. Dark Mode and i18n (dark-i18n)

**Impact:** MEDIUM
**Default tier:** mostly backlog
**Rules:** 2
**Description:** Hardcoded light tokens and physical left/right properties that fail in dark theme or RTL. Contrast ratios stay with axe.

## 11. Typography and Readability (type)

**Impact:** HIGH
**Default tier:** mostly fix-this-sprint
**Rules:** 2
**Description:** Surface-level readable floor for body type, plus hover/selected weight shifts that reflow chrome. Pairing, brand, measure, leading, and display type belong to the typography-audit skill.

## 12. Layout and Resilience (layout)

**Impact:** HIGH
**Default tier:** fix-this-sprint
**Rules:** 1
**Description:** Layouts must survive long content, sparse or dense data, and edge states without overflow or collapse. Empty, loading, and error states themselves are owned by the `states` category, not by these rules; report the container failure here and the missing state there.

## 13. Performance and Visual Stability (perf)

**Impact:** HIGH
**Default tier:** fix-this-sprint, release-blocker for image-dimension CLS
**Rules:** 3
**Description:** Prevent layout shift from images, lazy-load offscreen work, and virtualize long lists. Lighthouse measures CWV; these rules catch the static cause.

## 14. Generated-UI Slop (slop)

**Impact:** MEDIUM
**Default tier:** backlog
**Rules:** 6
**Description:** The house style of machine-generated interfaces: default-everything spacing, stock gradient hero, emoji as iconography, filler copy shipped as real copy, and the other tells that make a screen read as unfinished rather than broken. Nothing here blocks a task, which is why it defaults to backlog, but it is what a reviewer means by "this looks AI-made."

---

## Cross-category interactions

These pairings often co-fire. Emit both findings with the same `surface` to make the link explicit, except where a bullet below names a single owner: three findings and three near-identical fixes for one defect read as padding, not thoroughness.

- **States + Layout**: `states` owns the missing empty, loading, or error state. `layout` owns the container that overflows or collapses once that state renders. One defect, one owner, per the `states` category description above.

---

Total: 52 rules across 14 categories.

# Rule template

One template for every rule in this folder. Copy the shape below, delete the sections you do not need, and delete this header block.

Sections marked REQUIRED must be present in every rule file. Everything else is OPTIONAL, and an empty optional section is worse than an absent one.

---

## REQUIRED: frontmatter

Exactly these keys, in this order. No others. `related` is the only omissible one.

```yaml
---
title: Rule title, short and descriptive
id: <category>-<kebab-slug>, identical to the filename without .md
category: a11y | async | dark-i18n | focus | forms | interaction | layout | microcopy | mobile | nav | perf | slop | states | type
defaultTier: release-blocker | fix-this-sprint | backlog
detect: static | rendered | rubric
related: other-rule-id, other-rule-id
---
```

`detect` records how the rule is checked, and replaces the old split into separate rule folders:

- `static`: readable from source with grep, AST, or file presence.
- `rendered`: needs the built output, a real viewport, or computed style.
- `rubric`: scored 1-5 against the anchor table in the rule's own file, because the defect does not reduce to a boolean.

Omit `related` entirely when there is nothing to link. Values are bare ids, never paths and never filenames.

## REQUIRED: H2 matching the title

The first body heading is an H2 whose text is identical to `title`.

## REQUIRED: the failure paragraph

One paragraph immediately under the H2 naming the user-facing failure, not the best practice. What does the user see, and why does it diverge from what the code intended? Put any threshold and its source inline, for example "44x44px per WCAG 2.5.5".

An optional second paragraph carries nuance only: common misreadings, scope limits, or what the rule does not claim.

## REQUIRED: at least one of the three evidence forms

A rule file must carry at least one of the following. Most carry exactly one. Adding all three to a rule that only needs a code pair is padding.

### Form A: an incorrect / correct pair

The default, and the right choice for most rules.

**Incorrect (what is wrong and why):**

```tsx
// Minimal failing example: only the lines that violate the rule.
```

**Correct (what the fix looks like):**

```tsx
// Same example, fixed. The diff against the incorrect block should be obvious.
```

One pair per rule. Never restate the same fix in a second pair.

### Form B: a `## Detection` section

For rules where finding the defect is the hard part and the fix is obvious.

One framing sentence, one command, one paragraph naming the legitimate pattern that also matches:

```markdown
## Detection

Search for <what>, in <where>; a hit is confirmed when <the deciding fact>.

```bash
rg -nP '<pattern>' -g '*.tsx' -g '*.jsx' src/
```

<The correct code this also matches, and how to tell them apart.>
```

Every rule carries this section. The false-positive paragraph is the part that cannot be derived: a pattern without it is a grep anyone could write, and the rule exists because someone already learned which correct code it fires on.

**Put every condition inside one pattern, not in a pipeline.** A `-U` multiline match piped through `rg` or `rg -v` filters output *lines*, so an element whose attributes or class string Prettier wrapped loses the deciding line: the filter either drops a correct element's exemption and reports it, or drops the token that would have confirmed it and reports nothing. Use lookaheads within the element instead. Piping is fine when each output line is already one self-contained value, as after `rg -oP`.

Where a defect genuinely needs the rendered page (a measured width, a computed style, a spatial relationship), say so in this section and set `detect: rendered` rather than writing a grep that cannot decide it.

### Form C: a threshold table

For rules that reduce to a number.

| Tier | Condition | Severity |
|---|---|---|
| pass | observable condition with a number | none |
| warn | observable condition with a number | MEDIUM |
| fail | observable condition with a number | HIGH |

For a `detect: rubric` rule, use anchors instead of thresholds:

| Score | Anchor |
|---|---|
| 5 | Concrete best-in-class anchor. |
| 4 | Clear pass with minor polish available. |
| 3 | Ambiguous or uneven, should be improved. |
| 2 | Clear user-facing friction. |
| 1 | Broken or misleading experience. |

---

## OPTIONAL: `## Fix`

Only when the fix needs more than the correct half of a code pair: a migration path, an API choice, or a link to canonical docs.

## OPTIONAL: `## Default tier and overrides`

Only when the tier genuinely moves by surface. A table that shifts everything one step in the obvious direction is noise.

| Surface | Tier |
|---|---|
| Sign-in / Sign-up | usually one tier higher |
| Checkout | usually one tier higher |
| Marketing landing | usually one tier lower |
| Internal admin | usually one tier lower |

## OPTIONAL: `## Examples`

Only where the wording is the deliverable. A `microcopy-*` rule needs the actual bad and good strings shown, because a prose description of a string is not the string. Everywhere else the code pair already carries it.

## OPTIONAL: `## Defer-to`

Only when another tool owns the finding: Lighthouse for runtime measurement, axe for computed WCAG rules, an ESLint plugin for write-time prevention. Link out rather than duplicating their check.

## OPTIONAL: `## Suppression`

Only when the rule has a meaningful false-positive rate. Show the ignore comment carrying this rule's id and a reason.

---

Never add a `## Contents` index. These headings are the whole file shape, and a rule file long enough to need a table of contents is two rules.