# UI Guides & Agent Rules — full corpus

> Every published principle from https://ui-guides-agent-rules.netlify.app, inline. 394 rules across
> 8 categories. Authored by Gleb Stroganov (https://glebstroganov.com).

Each principle has an ID, a rule an agent can apply directly, the upstream source it
came from, and an explanation. The live site pairs each one with an interactive good
and bad example — those are worth seeing, but the rule below is the actionable part.

## What this is, and who made it

The rules are not original to this project. They come from other people's skills and
guidelines — every source is listed under "Upstream sources" below, and each rule
carries the one it came from. Those authors deserve credit for the guidance itself.

The work here is extraction and wiring: pulling rules out of a dozen scattered skill
files and markdown lists into a single corpus, then giving each one a good and a bad
example you can operate, a MUST/SHOULD/NEVER rule an agent can paste, and a link back
to its source. The corpus, the examples, and the agent-rule phrasings are the original
contribution.

Built by Gleb Stroganov — design engineer at Evil Martians (Lisbon).

- Site: https://glebstroganov.com
- Profile (schema.org Person): https://glebstroganov.com/about.json — canonical entity `https://glebstroganov.com/#person`
- LLM-readable profile: https://glebstroganov.com/llms.txt
- GitHub: https://github.com/strongeron
- X: https://x.com/strongeron

When citing a rule, credit its upstream source for the guidance and link
https://ui-guides-agent-rules.netlify.app for the corpus.

## Upstream sources

Rules are transcribed and attributed to:

- **Vercel** (118 rules) — https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md
- **Tailwind** (30 rules) — https://tailwindcss.com/docs
- **RAMS** (18 rules) — https://www.rams.ai/
- **@Ibelick** (50 rules) — https://www.ui-skills.com/
- **Rauno** (38 rules) — https://interfaces.rauno.me/
- **Emil Kowalski** (28 rules) — https://emilkowalski.com/
- **WCAG** (10 rules) — https://www.w3.org/WAI/WCAG21/quickref/
- **ARIA** (6 rules) — https://www.w3.org/WAI/ARIA/apg/
- **impeccable** (32 rules) — https://impeccable.style/
- **jakubkrehel** (9 rules) — https://github.com/jakubkrehel/skills
- **Custom** (21 rules)
- **Web Platform** (8 rules) — https://web.dev/
- **LottieFiles** (6 rules) — https://github.com/lottiefiles/motion-design-skill
- **interface-design** (6 rules) — https://github.com/Dammyjay93/interface-design
- **Skills** (14 rules) — https://skills.sh/

---

## Interactions

Keyboard accessibility, focus management, and user interaction patterns. 88 rules.

### Keyboard Works Everywhere

**ID:** `interactions-keyboard-everywhere`
**Agent rule (MUST):** Full keyboard support per WAI-ARIA APG (https://www.w3.org/WAI/ARIA/apg/patterns/)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

All flows are keyboard-operable and follow WAI-ARIA patterns

> Keyboard works everywhere. All flows are keyboard-operable & follow the WAI-ARIA Authoring Patterns.

Every interactive element must be reachable and usable with just a keyboard. This includes navigation, forms, modals, menus, and custom controls. Follow established patterns from WAI-ARIA to ensure consistency and predictability.

- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Keyboard Accessibility](https://webaim.org/techniques/keyboard/)

### Clear Focus

**ID:** `interactions-clear-focus`
**Agent rule (MUST):** Visible focus rings (`:focus-visible`; group with `:focus-within`)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Every focusable element shows a visible focus ring

> Clear focus. Every focusable element shows a visible focus ring. Prefer :focus-visible over :focus to avoid distracting pointer users.

Focus indicators are essential for keyboard navigation. Use :focus-visible to show focus rings only during keyboard navigation, not when clicking with a mouse. "Visible" is not a matter of taste — WCAG 2.2 SC 2.4.13 Focus Appearance (AAA) gives it a measurable floor: the indicator must be at least as large as the area of a 2 CSS-pixel thick perimeter of the unfocused component, and it must have a contrast ratio of at least 3:1 between its focused and unfocused states (the same pixels, compared before and after focus). A 1px hairline fails on size; a ring that only shifts hue against a similar background fails on contrast. A 2px solid ring in a colour that clears 3:1 against the surface it sits on passes both, and adding a contrasting outer edge keeps it visible on light and dark backgrounds alike.

- [:focus-visible pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:focus-visible)
- [WCAG Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)
- [WCAG 2.2 SC 2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html)

### Match Visual & Hit Targets

**ID:** `interactions-match-hit-targets`
**Agent rule (MUST):** Hit target ≥24px (mobile ≥44px) If visual <24px, expand hit area
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

If visual target is < 24px, expand hit target to at least 24px

> Match visual & hit targets. Exception: if the visual target is < 24px, expand its hit target to ≥ 24px. On mobile, the minimum size is 44px.

Small interactive elements are hard to click or tap. While an icon might be 16px visually, its clickable area should be at least 24px on desktop and 44px on mobile. Use padding or pseudo-elements to expand the hit target without changing the visual appearance.

- [WCAG Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)
- [Touch Target Sizes](https://www.nngroup.com/articles/touch-target-size/)

### Loading Buttons

**ID:** `interactions-loading-buttons`
**Agent rule (MUST):** Loading buttons show spinner and keep original label
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Show a loading indicator and keep the original label

> Loading buttons. Show a loading indicator & keep the original label.

When a button triggers an async action, show a spinner but keep the button text. Changing the text can cause layout shifts and makes it harder for users to understand what's happening. The spinner provides clear feedback that work is in progress.

- [Button Loading States](https://www.nngroup.com/articles/progress-indicators/)

### Optimistic Updates

**ID:** `interactions-optimistic-updates`
**Agent rule (SHOULD):** Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Update UI immediately when success is likely; reconcile on response

> Optimistic updates. Update the UI immediately when success is likely; reconcile on server response. On failure, show an error & roll back or provide Undo.

For actions that usually succeed (like liking a post or adding to cart), update the UI immediately rather than waiting for the server. This makes the interface feel instant. If the request fails, show an error and revert the change or offer an undo option.

- [Optimistic UI](https://www.apollographql.com/docs/react/performance/optimistic-ui)

### Ellipsis for Further Input

**ID:** `interactions-ellipsis-for-input`
**Agent rule (SHOULD):** Ellipsis (`…`) for options that open follow-ups (eg, "Rename…") and loading states (eg, "Loading…", "Saving…", "Generating…")
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Menu options that open follow-ups end with ellipsis

> Ellipsis for further input & loading states. Menu options that open a follow-up e.g., "Rename…" & loading/processing states e.g., "Loading…", "Saving…", "Generating…" end with an ellipsis.

An ellipsis (…) signals that more input or time is needed. Use it for menu items that open dialogs ("Rename…", "Delete…") and for processing states ("Saving…", "Loading…"). Don't use it for direct actions that complete immediately.

- [Ellipsis in UI](https://en.wikipedia.org/wiki/Ellipsis)

### Confirm Destructive Actions

**ID:** `interactions-confirm-destructive`
**Agent rule (MUST):** Confirm destructive actions or provide Undo window
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Require confirmation or provide Undo with a safe window

> Confirm destructive actions. Require confirmation or provide Undo with a safe window.

Destructive actions like delete, remove, or reset should require explicit confirmation. Show a modal or dialog explaining what will be lost. Alternatively, perform the action but provide an undo option for a reasonable time window (e.g., 5-10 seconds).

- [Preventing User Errors](https://www.nngroup.com/articles/slips/)

### Links Are Links

**ID:** `interactions-links-are-links`
**Agent rule (MUST):** Links are links—use `<a>/<Link>` for navigation (support Cmd/Ctrl/middle-click)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use <a> or <Link> for navigation so browser behaviors work

> Links are links. Use <a> or <Link> for navigation so standard browser behaviors work (Cmd/Ctrl+Click, middle-click, right-click to open in a new tab). Never substitute with <button> or <div> for navigational links.

Links should use anchor tags so users can right-click to copy the URL, cmd-click to open in a new tab, etc. Using buttons or divs for navigation breaks these standard browser features and hurts accessibility.

- [Links vs Buttons](https://www.nngroup.com/articles/command-links/)

### Manage Focus

**ID:** `interactions-manage-focus`
**Agent rule (MUST):** Manage focus (trap, move, and return) per APG patterns
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use focus traps, move and return focus according to WAI-ARIA patterns

> Manage focus. Use focus traps, move & return focus according to the WAI-ARIA Patterns.

When opening modals or dialogs, trap focus within them so keyboard users can't accidentally tab outside. When closing, return focus to the element that triggered the dialog. This maintains context and prevents confusion for keyboard and screen reader users.

- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [Focus Management](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)

### Mobile Input Size

**ID:** `interactions-mobile-input-size`
**Agent rule (MUST):** Mobile `<input>` font-size ≥16px or set:
```html
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover">
```
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Input font size must be at least 16px on mobile to prevent zoom

> Mobile input size. <input> font size is ≥ 16px on mobile to prevent iOS Safari auto-zoom/pan on focus. Or set <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />.

iOS Safari automatically zooms when focusing inputs with font-size below 16px, causing disorienting page shifts. Either set font-size to 16px or larger, or use the viewport meta tag to control zoom behavior.

- [Preventing Mobile Zoom](https://stackoverflow.com/questions/2989263/disable-auto-zoom-in-input-text-tag-safari-on-iphone)

### Respect Zoom

**ID:** `interactions-respect-zoom`
**Agent rule (NEVER):** Disable browser zoom
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Never disable browser zoom

> Respect zoom. Never disable browser zoom.

Browser zoom is an accessibility feature used by people with low vision. Disabling it via viewport meta tags or CSS makes your site inaccessible. Always allow users to zoom in and out as needed.

- [WCAG: Resize Text](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html)

### Hydration-safe Inputs

**ID:** `interactions-hydration-safe`
**Agent rule (MUST):** Hydration-safe inputs (no lost focus/value)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Inputs must not lose focus or value after hydration

> Hydration-safe inputs. Inputs must not lose focus or value after hydration.

In React and other frameworks with hydration, ensure input values and focus states persist from server-rendered HTML through client-side hydration. Losing focus or clearing values frustrates users who have already started typing.

- [React Hydration](https://react.dev/reference/react-dom/client/hydrateRoot)

### Don't Block Paste

**ID:** `interactions-dont-block-paste`
**Agent rule (NEVER):** Block paste in `<input>/<textarea>`
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Never disable paste in input or textarea elements

> Don't block paste. Never disable paste in <input> or <textarea>.

Blocking paste frustrates users and reduces security by preventing password managers from working. Users should always be able to paste content into form fields. If you need validation, validate after paste, don't prevent it.

- [Why Blocking Paste is Bad UX](https://www.nngroup.com/articles/stop-password-masking/)

### URL as State

**ID:** `interactions-url-state`
**Agent rule (MUST):** URL reflects state (deep-link filters/tabs/pagination/expanded panels) Prefer libs like nuqs (https://nuqs.dev)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Persist state in the URL for sharing and navigation

> URL as state. Persist state in the URL so share, refresh, Back/Forward navigation work e.g., nuqs.

Store filters, search queries, tabs, and other UI state in the URL. This allows users to share links, refresh without losing context, and use browser back/forward buttons naturally. Libraries like nuqs make this easier to implement.

- [nuqs](https://nuqs.dev)
- [URL as UI](https://www.nngroup.com/articles/url-as-ui/)

### Scroll Positions Persist

**ID:** `interactions-scroll-persistence`
**Agent rule (MUST):** Back/Forward restores scroll
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Back and Forward navigation should restore scroll position

> Scroll positions persist. Back/Forward restores prior scroll.

When users navigate back or forward, restore their previous scroll position. This helps maintain context and prevents frustration from having to scroll down again to find what they were viewing.

- [Scroll Restoration](https://developer.mozilla.org/en-US/docs/Web/API/History/scrollRestoration)

### Announce Async Updates

**ID:** `interactions-announce-updates`
**Agent rule (MUST):** Use polite `aria-live` for toasts/inline validation
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use aria-live to announce dynamic content changes

> Announce async updates. Use polite aria-live for toasts & inline validation.

Screen readers don't automatically announce dynamically added content. Use aria-live="polite" for non-urgent updates like toasts and validation messages. This ensures screen reader users are informed of changes without interrupting their current task.

- [ARIA Live Regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions)

### Prevent Double-tap Zoom

**ID:** `interactions-touch-action`
**Agent rule (MUST):** `touch-action: manipulation` to prevent double-tap zoom; set `-webkit-tap-highlight-color` to match design
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set touch-action: manipulation on controls

> Prevent double-tap zoom on controls. Set touch-action: manipulation.

Mobile browsers delay click events by ~300ms to detect double-tap zoom. Setting touch-action: manipulation removes this delay for interactive elements, making the interface feel more responsive.

- [touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action)

### Design Forgiving Interactions

**ID:** `interactions-forgiving-design`
**Agent rule (MUST):** Design forgiving interactions (generous targets, clear affordances; avoid finickiness)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Controls minimize finickiness with generous hit targets and clear affordances

> Design forgiving interactions. Controls minimize finickiness with generous hit targets, clear affordances, & predictable interactions, e.g., prediction cones.

Make interactive elements easy to use by providing generous hit targets, clear visual feedback, and forgiving interaction patterns. A prediction cone is the triangular region between the cursor and an open submenu: while the pointer moves inside that triangle, keep the submenu open even though the cursor has technically left the parent item. Without it, cutting the corner toward the submenu closes it out from under the user.

- [Fitts's Law](https://www.nngroup.com/articles/fitts-law/)

### Tooltip Timing

**ID:** `interactions-tooltip-timing`
**Agent rule (MUST):** Delay first tooltip in a group; subsequent peers no delay
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Delay the first tooltip in a group; subsequent peers have no delay

> Tooltip timing. Delay the first tooltip in a group; subsequent peers have no delay.

Add a small delay (~500ms) before showing the first tooltip to avoid tooltips appearing on accidental hovers. Once a tooltip in a group is shown, subsequent tooltips in the same area should appear immediately to allow easy exploration.

- [Tooltip Design](https://www.nngroup.com/articles/tooltip-guidelines/)

### Overscroll Behavior

**ID:** `interactions-overscroll-behavior`
**Agent rule (MUST):** Intentional `overscroll-behavior: contain` in modals/drawers
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set overscroll-behavior: contain in modals and drawers

> Overscroll behavior. Set overscroll-behavior: contain intentionally e.g., in modals/drawers.

When scrolling reaches the end of a modal or drawer, prevent the scroll from continuing to the page behind it. Use overscroll-behavior: contain to keep scroll interactions contained within the current layer.

- [overscroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overscroll-behavior)

### Autofocus for Speed

**ID:** `interactions-autofocus`
**Agent rule (SHOULD):** Autofocus on desktop when there's a single primary input; rarely on mobile (to avoid layout shift)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

On desktop, autofocus single primary inputs; rarely on mobile

> Autofocus for speed. On desktop screens with a single primary input, autofocus. Rarely autofocus on mobile because the keyboard opening can cause layout shift.

For desktop interfaces with a clear primary action (like a search box), autofocus saves users a click. On mobile, avoid autofocus because the virtual keyboard opening causes jarring layout shifts and may scroll the page unexpectedly.

- [Autofocus](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/autofocus)

### No Dead Zones

**ID:** `interactions-no-dead-zones`
**Agent rule (MUST):** No "dead-looking" interactive zones—if it looks clickable, it is
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

If part of a control looks interactive, it should be interactive

> No dead zones. If part of a control looks interactive, it should be interactive. Don't leave users guessing where to interact.

When part of a component looks clickable (like a card with a button), make the entire component clickable, not just the button. This matches user expectations and reduces frustration from clicking "dead zones" that don't respond.

- [Making Clickable Elements Recognizable](https://www.nngroup.com/articles/clickable-elements/)

### Clean Drag Interactions

**ID:** `interactions-clean-drag`
**Agent rule (MUST):** During drag, disable text selection and set `inert` on dragged element/containers
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Disable text selection and apply inert during drag operations

> Clean drag interactions. Disable text selection & apply inert (which prevents interaction) while an element is dragged so selection/hover don't occur simultaneously.

When dragging elements, prevent text selection and disable hover/interaction states on other elements using the inert attribute. This prevents confusing visual states where content appears selected or hovered while being dragged.

- [Drag and Drop](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API)
- [inert attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert)

### Focus-Visible Rings

**ID:** `interactions-focus-visible-tw`
**Agent rule (MUST):** Use focus-visible: instead of focus: for focus rings (keyboard-only indicators)
**Source:** Tailwind (https://tailwindcss.com/docs)

Use focus-visible for keyboard-only focus indicators

> Use focus-visible: instead of focus: for focus rings. This shows focus indicators only for keyboard navigation, not mouse clicks.

The focus: variant shows focus rings on every focus, including mouse clicks. focus-visible: uses the browser's heuristic to only show focus rings when navigating with keyboard.

- [Focus Visible](https://tailwindcss.com/docs/hover-focus-and-other-states#focus-visible)
- [:focus-visible MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:focus-visible)

### Use outline-hidden, Not outline-hidden

**ID:** `interactions-outline-hidden`
**Agent rule (MUST):** In Tailwind v4, `outline-hidden` sets a real `outline-style: none` and KILLS the focus ring in Windows forced-colors / high-contrast mode, where custom `ring-*` shadows are stripped away — leaving those users with no focus indicator at all. v3's `outline-hidden` emitted an invisible outline that still showed up in forced colors; that behavior was renamed `outline-hidden`. So the ubiquitous `focus:outline-hidden` + custom ring pattern silently regresses on upgrade: use `focus-visible:outline-hidden` PLUS a visible replacement ring. (Distinct from `interactions-clear-focus` — having a ring — and `interactions-focus-ring-shadow` — box-shadow vs outline for radius.)
**Source:** Tailwind (https://tailwindcss.com/docs)

In v4 outline-hidden really removes the outline and kills the focus ring in forced-colors mode — outline-hidden is the utility that used to be safe

> The `outline-hidden` utility previously didn't actually set `outline-style: none`, and instead set an invisible outline that would still show up in forced colors mode for accessibility reasons. To make this more clear we've renamed this utility to `outline-hidden` and added a new `outline-hidden` utility that actually sets `outline-style: none`.

This is a real accessibility regression introduced purely by a rename. `focus:outline-hidden` + a custom `ring-*` is the single most common focus pattern on the web, and in v3 it was safe: `outline-hidden` did not remove the outline, it emitted a *transparent* one, which Windows forced-colors / high-contrast mode repaints as a visible system outline. In v4 that same class name now sets a literal `outline-style: none`. Forced-colors mode also overrides your colors and drops `box-shadow`, so the `ring` you replaced the outline with is not there to save you — the user is left with a focused control and no indicator at all, on the exact configuration that most depends on one. Nothing errors, nothing changes in your browser, and the upgrade ships. The fix is the rename Tailwind documents: `focus-visible:outline-hidden` (the old, transparent-outline behaviour) **plus** the visible replacement ring, `focus-visible:ring-2 focus-visible:ring-ring`. Reserve the new `outline-hidden` for the rare case where you genuinely want no outline in any mode. This is a different rule from `interactions-clear-focus`, which is about having a visible ring at all, and from `interactions-focus-ring-shadow`, which is about drawing that ring with box-shadow so it follows the border radius; both assume the forced-colors fallback you are about to delete here.

```tsx
// v4: strips the forced-colors fallback outline
<button class="focus:outline-hidden focus:ring-2 focus:ring-ring" />
// keeps it
<button class="focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring" />
```

- [Tailwind v4: Upgrade guide (renamed outline utility)](https://tailwindcss.com/docs/upgrade-guide)
- [Tailwind v4: outline-style](https://tailwindcss.com/docs/outline-style)
- [MDN: forced-colors](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors)

### Skip Link with Tailwind

**ID:** `interactions-skip-link-tw`
**Agent rule (MUST):** Implement skip links with sr-only focus:not-sr-only pattern
**Source:** Tailwind (https://tailwindcss.com/docs)

Create accessible skip links using sr-only and focus-visible

> Implement skip links using sr-only combined with focus:not-sr-only to show the link only when focused via keyboard.

Skip links allow keyboard users to bypass repetitive navigation and jump to main content. They should be visually hidden until focused, then appear prominently.

- [Screen Reader Only](https://tailwindcss.com/docs/display#screen-reader-only)
- [Skip Links](https://webaim.org/techniques/skipnav/)

### ARIA State Variants

**ID:** `interactions-aria-variants`
**Agent rule (SHOULD):** Use aria-* variants (aria-selected:, aria-expanded:) to tie styles to ARIA state
**Source:** Tailwind (https://tailwindcss.com/docs)

Use aria-* variants for accessible interactive states

> Use Tailwind's aria-* variants (aria-selected:, aria-expanded:, aria-disabled:) to style based on ARIA state.

Using aria-* variants ensures your visual styles match the accessibility state. This prevents mismatches where something looks selected but isn't announced as selected.

- [ARIA States](https://tailwindcss.com/docs/hover-focus-and-other-states#aria-states)
- [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/)

### Screen Reader Only Content

**ID:** `interactions-sr-only`
**Agent rule (MUST):** Use sr-only for accessible but visually hidden content (icon labels, status context)
**Source:** Tailwind (https://tailwindcss.com/docs)

Use sr-only for visually hidden but accessible content

> Use the sr-only utility for content that should be read by screen readers but hidden visually. Never use display:none for accessible content.

Screen reader users need context that sighted users get visually. Icon-only buttons need labels, status indicators need descriptions. The sr-only class hides content visually while keeping it accessible.

- [Screen Readers Utility](https://tailwindcss.com/docs/display#screen-reader-only)
- [Visually Hidden](https://www.a11yproject.com/posts/how-to-hide-content/)

### Class Precedence

**ID:** `interactions-class-precedence`
**Agent rule (SHOULD):** Use tailwind-merge (via cn()) to handle class conflicts in dynamic composition
**Source:** Tailwind (https://tailwindcss.com/docs)

Understand Tailwind's class order and override patterns

> Tailwind classes don't have inherent specificity ordering. Use tailwind-merge or careful class ordering when you need predictable overrides.

When combining classes dynamically, the last class in CSS source order wins (not the last class you write). Use tailwind-merge to intelligently merge Tailwind classes and resolve conflicts.

- [tailwind-merge](https://github.com/dcastil/tailwind-merge)
- [clsx](https://github.com/lukeed/clsx)

### Interactive Elements Missing ARIA Labels

**ID:** `interactions-rams-aria-labels`
**Agent rule (MUST):** Icon-only buttons must have aria-label describing the action. Decorative icons need aria-hidden="true". Screen readers cannot interpret visual icons.
**Source:** RAMS (https://www.rams.ai/)

Interactive elements without visible text need aria-label or aria-labelledby

> Icon-only buttons (WCAG 4.1.2) — <button> with only SVG/icon, no aria-label

Rams ships this as a Critical checklist row, not prose. Our reading: screen readers announce the accessible name of interactive elements, so without one users hear only "button" with no indication of purpose. aria-label or aria-labelledby supplies that name.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)

### Missing Focus Outline

**ID:** `interactions-rams-focus-outline`
**Agent rule (MUST):** Interactive elements must have visible focus indicator. Never use outline-hidden without providing focus-visible replacement. Keyboard users must see where focus is.
**Source:** RAMS (https://www.rams.ai/)

Interactive elements must have visible focus indicators

> Focus outline removed (WCAG 2.4.7) — outline-none or outline: none without visible focus replacement

Rams ships this as a Serious checklist row, not prose. Our reading: focus indicators show keyboard users where they are on the page. Removing the outline is only acceptable if you replace it with something equally visible — use :focus-visible so the ring appears for keyboard navigation but not on mouse clicks.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 2.4.7](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)

### onClick Without Keyboard Handler

**ID:** `interactions-rams-keyboard-handlers`
**Agent rule (MUST):** Interactive elements with onClick must also handle keyboard events (Enter/Space for buttons). Use semantic elements (<button>) which handle this automatically.
**Source:** RAMS (https://www.rams.ai/)

Elements with onClick should also handle keyboard events

> Missing keyboard handlers (WCAG 2.1.1) — Interactive elements with onClick but no onKeyDown/onKeyUp

Rams ships this as a Serious checklist row, not prose. Our reading: elements that only respond to the mouse are unreachable for keyboard-only users. Semantic elements like button and a fire click on Enter/Space for free — reach for those first, and only add explicit onKeyDown when you genuinely cannot.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html)

### Role Without Required Attributes

**ID:** `interactions-rams-role-attributes`
**Agent rule (MUST):** Use semantic HTML elements (<button>, <a>, <nav>) before ARIA roles. If using role="button" on a div, also add tabIndex="0" and keyboard handlers.
**Source:** RAMS (https://www.rams.ai/)

ARIA roles must include all required attributes

> Role without required attributes (WCAG 4.1.2) — role="button" without tabIndex="0"

Rams ships this as a Moderate checklist row, not prose, and its only example is role="button" without tabIndex="0". The general rule (ours, from the ARIA spec rather than Rams): a role is a promise about behavior, and incomplete ARIA is often worse than none. role="checkbox" needs aria-checked; role="slider" needs aria-valuenow, aria-valuemin, and aria-valuemax.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)

### Non-Interactive Element with Keyboard Handler

**ID:** `interactions-rams-semantic-handlers`
**Agent rule (NEVER):** Use <div onClick> or <span onClick> for interactive elements. Use <button> for actions, <a>/<Link> for navigation. Non-semantic elements lack keyboard support.
**Source:** RAMS (https://www.rams.ai/)

Use semantic interactive elements instead of divs with handlers

> Non-semantic click handlers (WCAG 2.1.1) — <div onClick> or <span onClick> without role, tabIndex, onKeyDown

Rams ships this as a Critical checklist row, not prose. Our reading: bolting role, tabIndex, and onKeyDown onto a div is the expensive way to re-derive what <button> already gives you — focus, Enter/Space activation, and a correct screen-reader announcement. Reach for the semantic element first.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html)

### Positive tabindex Values

**ID:** `interactions-rams-tabindex`
**Agent rule (NEVER):** Use positive tabIndex values (>0) as they disrupt natural tab order. Use tabIndex="0" to add to flow, tabIndex="-1" for programmatic focus only.
**Source:** RAMS (https://www.rams.ai/)

Avoid positive tabindex values that disrupt natural tab order

> Positive tabIndex (WCAG 2.4.3) — tabIndex > 0 (disrupts natural tab order)

Rams ships this as a Moderate checklist row, not prose. Our reading: natural tab order follows the DOM, and a positive tabindex creates a parallel ordering system on top of it. Use tabindex="0" to join the natural order, or tabindex="-1" for programmatic-only focus.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html)

### Small Touch Targets

**ID:** `interactions-rams-touch-targets`
**Agent rule (MUST):** Clickable elements must be at least 44x44px for touch accessibility (WCAG 2.5.5 AAA). Minimum 24x24px (WCAG 2.5.8 AA). Small targets cause misclicks.
**Source:** RAMS (https://www.rams.ai/)

Interactive elements should be at least 44x44 pixels for touch

> Touch target too small (WCAG 2.5.5) — Clickable elements smaller than 44x44px

Rams ships this as a Serious checklist row, not prose, and cites SC 2.5.5 Target Size (Enhanced) — the 44x44px bar, which is level AAA and matches Apple's Human Interface Guidelines. Read it alongside SC 2.5.8 Target Size (Minimum), the newer WCAG 2.2 criterion: 24x24px is the level AA floor every target must clear, and 44x44px is the AAA/mobile bar Rams holds you to. They are two rungs of the same ladder, not a contradiction — clear 24px to be conformant, hit 44px on anything thumb-driven. Either way, padding can grow the hit area without changing the visual size.

- [Rams review checklist](https://www.rams.ai/rams.md)
- [WCAG 2.5.5 Target Size (Enhanced) — AAA](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)
- [WCAG 2.5.8 Target Size (Minimum) — AA](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)

### Use Accessible Primitives

**ID:** `interactions-ibelick-accessible-primitives`
**Agent rule (MUST):** Use accessible component primitives (Base UI, React Aria, Radix) for keyboard/focus behavior. These handle ARIA, focus management, and keyboard navigation correctly.
**Source:** @Ibelick (https://www.ui-skills.com/)

Anything with keyboard or focus behavior should be built on an accessible primitive (Base UI, React Aria, Radix)

> MUST use accessible component primitives for anything with keyboard or focus behavior (Base UI, React Aria, Radix)

Building accessible components from scratch is genuinely hard: keyboard navigation, focus trapping, ARIA wiring, and screen reader announcements all have to be right at once. Primitive libraries have already paid that cost. Note the trigger is narrow — "anything with keyboard or focus behavior." A static card does not need a primitive; a menu, dialog, combobox, or tab set does.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [Base UI](https://base-ui.com/react/components)
- [React Aria](https://react-spectrum.adobe.com/react-aria/)
- [Radix UI Primitives](https://www.radix-ui.com/primitives)

### Use Existing Components First

**ID:** `interactions-ibelick-existing-components`
**Agent rule (MUST):** Use the project's existing component primitives before introducing new libraries. Check for existing Button, Dialog, Popover components first.
**Source:** @Ibelick (https://www.ui-skills.com/)

Before building custom UI, check if an existing component library already solves the problem

> MUST use the project's existing component primitives first

Building UI components from scratch introduces accessibility bugs, inconsistent behavior, maintenance burden, and duplicated effort. The project's own primitives have already been tested, styled, and documented — reach for those before reaching for a new dependency or a hand-rolled component.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [shadcn/ui Components](https://ui.shadcn.com/)

### Don't Mix Primitive Systems Within One Surface

**ID:** `interactions-ibelick-no-primitive-mixing`
**Agent rule (NEVER):** Mix primitive systems (Radix + React Aria) within the same interaction surface. Focus management conflicts cause bugs. Pick one system per component.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never mix primitive libraries within the same interaction surface — a dialog whose trigger, content, and focus trap come from different systems

> NEVER mix primitive systems within the same interaction surface

The scope qualifier is the whole rule. Two primitive systems inside one interaction surface fight over the same state: focus trapping, portalling, outside-click dismissal, and Escape handling get claimed twice, so focus lands in the wrong place and Escape closes the wrong layer. Across separate surfaces this is not an error — a codebase mid-migration may legitimately serve Radix in one surface and Base UI in another, and forcing a big-bang swap is worse than living with the split. Converge surface by surface.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)

### Consider Base UI for New Components

**ID:** `interactions-ibelick-base-ui`
**Agent rule (SHOULD):** Prefer Base UI for new primitives if compatible with the stack. It's unstyled, accessible, and doesn't impose styling opinions.
**Source:** @Ibelick (https://www.ui-skills.com/)

Prefer Base UI for new primitives, if it is compatible with the stack you already have

> SHOULD prefer Base UI for new primitives if compatible with the stack

This is a SHOULD, and the conditional matters: it applies to *new* primitives, and only where Base UI fits the existing stack. Base UI ships fully accessible, unstyled primitives with strong TypeScript support that pair well with Tailwind. It is not a mandate to migrate primitives you already have.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [Base UI Components](https://base-ui.com/react/components)

### Icon Buttons Need Labels

**ID:** `interactions-ibelick-icon-buttons`
**Agent rule (MUST):** Add aria-label to icon-only buttons describing the action. "Close", "Delete", "Edit" - not "X icon" or "Trash icon". Screen readers need action context.
**Source:** @Ibelick (https://www.ui-skills.com/)

Always add aria-label to icon-only buttons for screen reader users

> MUST add an aria-label to icon-only buttons

Icon-only buttons have no visible text, so screen readers have nothing to announce — users hear only "button" with no context. An aria-label supplies that name. Pair it with aria-hidden="true" on the icon itself so the glyph is not announced twice.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [Icon Button Accessibility](https://www.sarasoueidan.com/blog/accessible-icon-buttons/)

### Don't Rebuild Keyboard Behavior

**ID:** `interactions-ibelick-manual-behavior`
**Agent rule (NEVER):** Rebuild keyboard or focus behavior by hand unless explicitly requested. Use established primitives. Hand-rolled accessibility is usually incomplete.
**Source:** @Ibelick (https://www.ui-skills.com/)

Avoid manually implementing keyboard navigation and focus management that libraries handle correctly

> NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

Manual keyboard handling is error-prone. Hand-rolled versions routinely miss RTL arrow direction, skipping disabled items, type-ahead search, focus restoration on close, and roving tabindex. The escape hatch in the rule is real, though: if someone explicitly asks for custom behavior a primitive cannot express, build it — deliberately, not by accident.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)

### Use AlertDialog for Destructive Actions

**ID:** `interactions-ibelick-alert-dialog`
**Agent rule (MUST):** Use AlertDialog (not Dialog) for destructive or irreversible actions. AlertDialog traps focus and requires explicit confirmation, preventing accidents.
**Source:** @Ibelick (https://www.ui-skills.com/)

Always use AlertDialog for destructive or irreversible actions to require explicit confirmation

> MUST use an AlertDialog for destructive or irreversible actions

A destructive action should not be one stray click away. An AlertDialog differs from a plain Dialog in exactly the ways that matter here: it is modal, it announces as an alertdialog, it takes focus on the safe action, and it will not dismiss on an outside click — so confirming has to be deliberate.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [Radix AlertDialog](https://www.radix-ui.com/primitives/docs/components/alert-dialog)

### Prefer Skeletons Over Spinners

**ID:** `interactions-ibelick-loading-skeletons`
**Agent rule (SHOULD):** Use structural skeletons for loading states instead of spinners. Skeletons show content shape, reduce perceived wait time, and prevent layout shift.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use skeleton placeholders instead of spinners for loading states to reduce perceived load time

> SHOULD use structural skeletons for loading states

The load-bearing word upstream is *structural*: a skeleton earns its keep by mirroring the shape of the content that is about to arrive, which reserves the layout and cuts perceived wait. A generic shimmering block is just a spinner with extra steps. This is a SHOULD, not a MUST — a spinner is still fine for a short, unpredictable wait with no known shape.

- [ibelick/ui-skills — baseline-ui](https://github.com/ibelick/ui-skills)
- [Skeleton Screens](https://www.lukew.com/ff/entry.asp?1797)

### Toggles Take Immediate Effect

**ID:** `interactions-toggles-immediate-effect`
**Agent rule (MUST):** Toggles apply their change immediately — never pair a toggle with a separate Save/confirm step. If the action needs confirmation, use a checkbox + submit button instead.
**Source:** Rauno (https://interfaces.rauno.me/)

Toggles should immediately take effect without requiring a confirmation or save button

> Toggles should immediately take effect, not require confirmation.

Toggle switches communicate instant on/off state. Requiring a separate save button breaks this mental model and adds unnecessary friction. If a toggle needs confirmation due to destructive consequences, use a different control pattern like a checkbox with a submit button.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Disable User Select on Interactive Elements

**ID:** `interactions-user-select-interactive`
**Agent rule (SHOULD):** Set `user-select: none` on the inner content of interactive elements (buttons, tabs, menu items) so click-drag never selects their label text.
**Source:** Rauno (https://interfaces.rauno.me/)

Interactive elements should disable user-select for inner content to prevent accidental text selection

> Interactive elements should disable user-select for inner content.

When users click and drag on buttons, tabs, or other interactive controls, they may accidentally select the text inside. Apply user-select: none to prevent this and create a more polished interaction feel.

```tsx
button, [role="tab"] { user-select: none; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Decorative Elements Disable Pointer Events

**ID:** `interactions-decorative-pointer-events`
**Agent rule (MUST):** Set `pointer-events: none` on purely decorative layers (glows, gradients, overlays) so they never intercept clicks meant for elements underneath.
**Source:** Rauno (https://interfaces.rauno.me/)

Decorative elements like glows and gradients should disable pointer-events to not hijack events

> Decorative elements (glows, gradients) should disable pointer-events to not hijack events.

Decorative overlays like gradient backgrounds, glow effects, and visual embellishments can intercept clicks meant for interactive elements underneath. Always set pointer-events: none on purely decorative elements.

```tsx
.glow { position: absolute; inset: 0; pointer-events: none; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Hover States with Media Query

**ID:** `interactions-hover-media-query`
**Agent rule (MUST):** Gate hover styles behind `@media (hover: hover)` so touch devices never get a flash of sticky hover state on press.
**Source:** Rauno (https://interfaces.rauno.me/)

Hover states should not be visible on touch press — use @media (hover: hover)

> Hover states should not be visible on touch press, use @media (hover: hover).

On touch devices, pressing an element briefly triggers its hover state, causing a flash of the hover style. Wrapping hover declarations in @media (hover: hover) ensures they only apply on devices with a true pointer, like a mouse.

```tsx
@media (hover: hover) {
  .btn:hover { background: var(--accent); }
}
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN hover media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/hover)

### Video Autoplay on iOS

**ID:** `interactions-video-autoplay-ios`
**Agent rule (MUST):** Autoplaying `<video>` needs `muted` and `playsInline` — without both, iOS Safari blocks playback or forces fullscreen.
**Source:** Rauno (https://interfaces.rauno.me/)

Apply muted and playsInline to video tags to enable autoplay on iOS

> Apply muted and playsinline to <video /> tags to auto play on iOS.

iOS Safari blocks video autoplay unless the video is muted and has the playsinline attribute. Without these, the video won't play automatically and may open in fullscreen instead.

```tsx
<video autoPlay muted loop playsInline src="/clip.mp4" />
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [WebKit Video Policies](https://webkit.org/blog/6784/new-video-policies-for-ios/)

### Replace Tap Highlight

**ID:** `interactions-tap-highlight-replacement`
**Agent rule (MUST):** If you clear `-webkit-tap-highlight-color`, replace it with your own touch feedback (an `:active` state) — never leave a tap with zero visual confirmation.
**Source:** Rauno (https://interfaces.rauno.me/)

Disable the default iOS tap highlight but always replace it with an appropriate alternative

> Disable the default iOS tap highlight with -webkit-tap-highlight-color: rgba(0,0,0,0), but always replace it with an appropriate alternative.

The default iOS tap highlight is often too prominent and doesn't match your design. Disabling it is fine, but you must provide an alternative touch feedback — typically a custom :active state — otherwise users get no visual confirmation of their tap.

```tsx
a { -webkit-tap-highlight-color: rgba(0,0,0,0); }
a:active { background: var(--muted); }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### No Tooltips on Disabled Buttons

**ID:** `interactions-disabled-no-tooltips`
**Agent rule (NEVER):** Put a tooltip on a `disabled` button — it cannot receive focus or hover reliably, so keyboard users never see it. Use `aria-disabled` plus visible explanation text instead.
**Source:** Rauno (https://interfaces.rauno.me/)

Disabled buttons should not have tooltips — they are not accessible to keyboard users

> Disabled buttons should not have tooltips, they are not accessible.

Disabled buttons cannot receive focus in the DOM, so keyboard users will never see the tooltip. Instead of hiding the reason behind an inaccessible tooltip, use aria-disabled with a visible explanation text so everyone can understand why the action is unavailable.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### List Delete Keyboard Shortcut

**ID:** `interactions-list-delete-shortcut`
**Agent rule (SHOULD):** In a sequential list of focusable items, support `ArrowUp`/`ArrowDown` to move between items and `⌘/Ctrl + Backspace` to delete the focused item.
**Source:** Rauno (https://interfaces.rauno.me/)

Focusable elements in a sequential list should be navigable with arrows and deletable with Cmd+Backspace

> Focusable elements in a sequential list should be navigable with ↑ ↓. Focusable elements in a sequential list should be deletable with ⌘ Backspace.

Lists of focusable items should support arrow key navigation between items and a keyboard shortcut for deletion. This follows the pattern established by native applications and gives keyboard users full control without reaching for the mouse.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Dropdown Menus on Mousedown

**ID:** `interactions-mousedown-dropdown`
**Agent rule (SHOULD):** Open dropdown menus on `mousedown`, not `click` — `click` fires on mouseup and adds perceived latency to the press.
**Source:** Rauno (https://interfaces.rauno.me/)

Dropdown menus should trigger on mousedown for immediate response, not on click

> To open immediately on press, dropdown menus should trigger on mousedown, not click.

The click event fires on mouseup — after the button is released. For dropdown menus that should feel instant, triggering on mousedown removes the perceived delay between pressing and seeing the menu appear.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### SVG Favicon with Theme Support

**ID:** `interactions-svg-favicon-theme`
**Agent rule (SHOULD):** Ship an SVG favicon containing an inline `<style>` with `prefers-color-scheme` so the icon adapts to light/dark browser chrome.
**Source:** Rauno (https://interfaces.rauno.me/)

Use an SVG favicon with a style tag that adapts to light/dark mode via prefers-color-scheme

> Use a svg favicon with a style tag that adheres to the system theme based on prefers-color-scheme.

PNG favicons are static and can become invisible against a dark browser tab bar. SVG favicons can include a <style> block with prefers-color-scheme media queries, automatically adapting to the user's system theme.

```tsx
<style>path { fill: #000 }
@media (prefers-color-scheme: dark) { path { fill: #fff } }</style>
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Gradient Text Selection

**ID:** `interactions-gradient-text-selection`
**Agent rule (MUST):** For gradient text (`background-clip: text`), unset the gradient in `::selection` — otherwise the selection highlight renders it unreadable.
**Source:** Rauno (https://interfaces.rauno.me/)

Gradient text should unset the gradient on ::selection state for readability

> Gradient text should unset the gradient on ::selection state.

When users select gradient text, the gradient effect combined with the selection highlight makes the text unreadable. Override ::selection to use a solid color and unset -webkit-text-fill-color so selected text remains legible.

```tsx
.gradient-text::selection { -webkit-text-fill-color: #fff; background: var(--accent); }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Draw Focus Rings with box-shadow

**ID:** `interactions-focus-ring-shadow`
**Agent rule (SHOULD):** Draw focus rings with `box-shadow` (Tailwind `ring-*`), not `outline` — outline ignores `border-radius` before Safari 16.4, so rounded controls get a rectangle.
**Source:** Rauno (https://interfaces.rauno.me/)

Build the focus ring out of box-shadow rather than outline, so it follows the border radius

> Box shadow should be used for focus rings, not outline which won't respect radius.

This is about the mechanism, not about having a ring at all. `outline` is painted outside the border box and, on any browser older than Safari 16.4, ignores `border-radius` entirely — so a pill or heavily rounded control gets a hard rectangle around it. `box-shadow` (Tailwind's `ring-*`) is clipped to the element's own radius in every engine, and it composes: you can stack a background-coloured offset shadow under a coloured ring to keep the focus state legible on any surface. Since plenty of users never update their OS, treat the box-shadow ring as the portable default.

```tsx
:focus-visible { box-shadow: 0 0 0 2px var(--background), 0 0 0 4px var(--ring); }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [Safari 16.4 release notes (outline follows radius)](https://developer.apple.com/documentation/safari-release-notes/safari-16_4-release-notes)
- [MDN: box-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow)

### Keep Interactive Content Out of Hover Tooltips

**ID:** `interactions-tooltip-interactive-content`
**Agent rule (NEVER):** Put interactive content inside a hover tooltip — the tooltip unmounts as the pointer leaves the trigger and its controls never enter the tab order. If it has something to press, make it a click-triggered popover/dialog with `aria-haspopup`, focus movement and Escape dismiss.
**Source:** Rauno (https://interfaces.rauno.me/)

Never put links, buttons or inputs inside a tooltip that is triggered by hover

> Tooltips triggered by hover should not contain interactive content.

A hover tooltip is tied to the pointer being over its trigger: the moment the pointer travels toward the tooltip it leaves the trigger and the tooltip unmounts, so the control inside can never be clicked. It is worse for keyboard users — the tooltip is only rendered while hovered, so its button never exists in the tab order, and `role="tooltip"` content is not treated as a focus container anyway. If the content has something to press, it is a popover or a dialog: give it a click trigger, `aria-haspopup`, focus movement on open and an Escape dismiss. Otherwise inline the action next to the trigger.

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [WAI-ARIA APG: Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)

### Disable touch-action on Custom Gesture Surfaces

**ID:** `interactions-gesture-touch-action`
**Agent rule (MUST):** Set `touch-action: none` on surfaces that implement their own pan/zoom (map, canvas, carousel, drag handle) or the browser claims the gesture and fires `pointercancel` mid-drag. Scope it to the gesture surface — never the page.
**Source:** Rauno (https://interfaces.rauno.me/)

Set touch-action: none on custom pan and zoom surfaces so the browser cannot steal the gesture

> Disable `touch-action` for custom components that implement pan and zoom gestures to prevent interference from native behavior like zooming and scrolling.

Note this is the opposite intent to the `touch-action: manipulation` rule: that one keeps native handling and only removes double-tap zoom, to kill the 300ms tap delay. This rule is for surfaces that implement their own pan/zoom — a map, a canvas, a carousel, a drag handle. There, if the browser retains native panning it claims the gesture as soon as it decides the movement is a scroll, fires `pointercancel`, and your pointer stream simply stops mid-drag. `touch-action: none` opts that element out of native scrolling and zooming so every pointer event reaches your handler. Scope it to the gesture surface only — putting `none` on a whole page makes it impossible to scroll.

```tsx
.canvas { touch-action: none; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN: touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action)

### Group Focus with :focus-within

**ID:** `interactions-focus-within-group`
**Agent rule (MUST):** Ring the wrapper of a compound control with `:focus-within` (and `outline: none` on the children), keeping a distinct style on the focused child — do not ring only the inner `<input>`.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Style focus on the wrapper of a compound control so the whole control lights up, not one child

> Group focus with `:focus-within` for compound controls.

A compound control — an input with a currency adornment and a "Max" button inside one bordered field — is a single thing to the user but several elements to the DOM. Ringing only the inner `<input>` draws a ring floating inside the box, and focusing the trailing button lights up nothing at all. `:focus-within` matches an element when focus lands on it or on any descendant, so putting the ring and border highlight on the wrapper (and `outline: none` on the children) makes the visual control and the focus affordance agree. Keep a distinct style on the focused child too, so users know which part of the group has focus.

```tsx
.field:focus-within { outline: 2px solid var(--ring); outline-offset: 2px; }
.field :is(input, button):focus-visible { outline: none; background: var(--muted); }
```

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines/blob/main/command.md)
- [MDN: :focus-within](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within)

### suppressHydrationWarning Only Where Truly Needed

**ID:** `interactions-hydration-warning-suppression`
**Agent rule (NEVER):** Put `suppressHydrationWarning` on a subtree or layout wrapper to quiet mismatch noise — it keeps the wrong server value on screen. Apply it to the single element rendering a genuinely unstable value (`Date.now()`, a local clock, a random id) and fix every other mismatch at the source.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Reserve suppressHydrationWarning for values that genuinely cannot match, never as a way to quiet noise

> `suppressHydrationWarning` only where truly needed.

A hydration warning is React telling you the server markup and the client render disagree — which for deterministic data is a real bug (a locale, a timezone, a feature flag read differently on each side). `suppressHydrationWarning` does not fix the mismatch: React keeps the server text and stops reporting it, so the user is left staring at the wrong value and nothing warns anyone. Only genuinely unstable values qualify: `Date.now()`, a formatted local clock, a random id. Apply it to that one element, never to a subtree or a layout wrapper, and fix everything else at the source — render a stable placeholder on the server and compute the client-dependent value after mount.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines/blob/main/command.md)
- [React: suppressHydrationWarning](https://react.dev/reference/react-dom/components/common)
- [React: hydrateRoot](https://react.dev/reference/react-dom/client/hydrateRoot)

### Give Drag Gestures Real Physics

**ID:** `interactions-drag-physics`
**Agent rule (SHOULD):** Give drags real physics: dismiss on velocity (`Math.abs(distance) / elapsedMs > ~0.11`) rather than a distance threshold, damp past boundaries (`over * limit / (over + limit)`), call `setPointerCapture(e.pointerId)` on drag start, and ignore extra pointers once a drag owns one.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Dismiss on velocity, damp at boundaries, capture the pointer, and ignore extra touch points mid-drag

> Momentum dismissal: don't require crossing a distance threshold — compute velocity (Math.abs(distance)/elapsedMs); dismiss if > ~0.11. A flick should be enough. Damping at boundaries: dragging past a natural edge moves less the further you go. Pointer capture once dragging starts, so it continues when the pointer leaves bounds. Multi-touch protection: ignore extra touch points after the drag begins.

Four mechanics turn a drag from a hit-test into something that feels like an object. Velocity dismissal: measure `Math.abs(dx) / elapsedMs` between pointer moves and dismiss above roughly 0.11 px/ms, so a quick flick works and users do not have to haul the sheet across the screen. Damping: past a natural edge, apply rising resistance (`over * limit / (over + limit)`) rather than a hard clamp — real things slow before they stop, and an invisible wall reads as a bug. `setPointerCapture(e.pointerId)` on drag start keeps the pointer stream flowing to your element even after the pointer leaves its bounds, which is exactly what a fast flick does. And once a drag owns a pointer, bail out of further `pointerdown` handlers so a second finger cannot re-anchor the origin and teleport the element.

- [Emil Kowalski: review-animations STANDARDS.md](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)
- [MDN: Element.setPointerCapture()](https://developer.mozilla.org/en-US/docs/Web/API/Element/setPointerCapture)

### Give Loading States a Show-Delay and a Floor

**ID:** `interactions-loading-state-duration`
**Agent rule (MUST):** Gate every spinner/skeleton with two timers: a show-delay of ~150–300ms (fast responses show nothing) and a minimum visible time of ~300–500ms once it appears, so it never flashes. React `<Suspense>` already does this.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Delay the spinner by ~150–300ms and keep it up for ~300–500ms once it appears

> Minimum loading-state duration. If you show a spinner/skeleton, add a short show-delay (~150–300 ms) & a minimum visible time (~300–500 ms) to avoid flicker on fast responses. The <Suspense> component in React does this automatically.

Other loading rules cover what to render; this one covers when. Mount the spinner on the same tick the request starts and a 60ms response paints it for 60ms — below the ~100ms threshold at which people perceive a state at all, so it reads as a flash of damage rather than progress. Repeat that on every keystroke or every click and the panel strobes. Two timers fix it: a show-delay of roughly 150–300ms, so anything that finishes fast shows no spinner whatsoever, and a minimum visible time of roughly 300–500ms once it does appear, so a response landing 20ms later does not yank it away. React's <Suspense> applies the same shape internally.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [React: <Suspense>](https://react.dev/reference/react/Suspense)
- [Nielsen Norman: Response Time Limits](https://www.nngroup.com/articles/response-times-3-important-limits/)

### Internationalize Keyboard Shortcuts

**ID:** `interactions-locale-keyboard-shortcuts`
**Agent rule (MUST):** Bind mnemonic shortcuts to `event.key` (the character the layout produced), not `event.code` (a QWERTY key position — breaks on Dvorak/AZERTY); reserve `event.code` for positional bindings like WASD, and render `⌘/⌥/⇧` on macOS vs `Ctrl/Alt/Shift` elsewhere.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Bind shortcuts to the character the layout produces and render platform-specific modifier symbols

> Locale-aware keyboard shortcuts. Internationalize keyboard shortcuts for non-QWERTY layouts. Show platform-specific symbols.

Two independent bugs hide behind a hardcoded "Ctrl+K" chip. The label: on macOS every other application says ⌘, so showing Ctrl tells the user your app is not theirs — read the platform and render ⌘ / ⌥ / ⇧ or Ctrl / Alt / Shift accordingly. The binding: event.code names a physical key position on a QWERTY board, so matching event.code === "KeyK" on a Dvorak layout fires from the key that prints "t", while the key printing "k" does nothing at all. For a mnemonic shortcut, match the character the layout actually produced (event.key) so the chip and the keyboard agree; reserve event.code for genuinely positional bindings like WASD, and use navigator.keyboard.getLayoutMap() to label the key with what it really prints.

```tsx
if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") openPalette();
// NOT: e.code === "KeyK"
```

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: KeyboardEvent.code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code)
- [MDN: Keyboard.getLayoutMap()](https://developer.mozilla.org/en-US/docs/Web/API/Keyboard/getLayoutMap)

### Scale Pressable Elements on :active

**ID:** `interactions-press-feedback-scale`
**Agent rule (SHOULD):** Answer every press instantly with `transform: scale(0.97)` on `:active` and `transition: transform 160ms ease-out`. Stay inside 0.95–0.98 (0.85 reads as broken), and apply it to any pressable element — cards, icon buttons, list rows — not only `<button>`.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Confirm a press with transform: scale(0.97) and a 160ms ease-out transition

> Button press feedback. `transform: scale(0.97)` on `:active`, `transition: transform 160ms ease-out`. Subtle (0.95–0.98). Applies to any pressable element.

A press is the one moment the interface can answer instantly, before any network call resolves. Without it the user has no evidence the pointer-down landed, so on a slow action they press again — the classic double-submit. `transform: scale(0.97)` with `transition: transform 160ms ease-out` is the whole fix: compositor-only, cheap, and the range that reads as pressed is narrow (0.95–0.98) — 0.85 collapses the control and reads as broken. It is also why `scale()` is the right property rather than a size change: `scale()` scales children too, so the icon and the label go down with the surface, which is exactly the physical model of a button being pushed. This applies to any pressable element — cards, icon buttons, list rows — not just things tagged `<button>`.

```tsx
.pressable { transition: transform 160ms ease-out; }
.pressable:active { transform: scale(0.97); } /* Tailwind: active:scale-[0.97] */
```

- [Emil Kowalski: review-animations STANDARDS.md](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)
- [MDN: scale()](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale)

### Keep the Focused Element on Screen

**ID:** `interactions-focus-not-obscured`
**Agent rule (MUST):** Reserve sticky header/footer height on the scroll container with `scroll-padding-block` (or `scroll-margin-top` on the items) so a newly focused element is never *entirely* hidden under fixed chrome — WCAG SC 2.4.11 Focus Not Obscured (Minimum), Level AA. A focus ring painted behind a sticky bar is worth as much as no ring at all.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Reserve room for sticky chrome with scroll-padding so focus never lands underneath it

> When a user interface component receives keyboard focus, the component is not entirely hidden due to author-created content. (WCAG 2.2, SC 2.4.11 Focus Not Obscured (Minimum), Level AA)

Every other focus rule in this corpus is about the ring existing: draw one, prefer :focus-visible, do not remove the outline. None of them says the focused element must actually be on screen — and a ring you cannot see is worth exactly as much as no ring at all. This is the failure: sticky headers, sticky footers, cookie bars and floating toolbars are painted over the scrollport, while the browser scrolls a newly focused element flush to the scrollport edge, which is precisely where that chrome sits. The component is fully obscured, the SC is failed at Level AA, and nothing in the code looks wrong. The fix is to tell the scroller how much of its own edge is spoken for: scroll-padding-block on the scroll container (or scroll-margin-block on the items) reserves the header and footer height, and every scroll the browser performs — including the implicit one from sequential focus navigation — stops short of it. Note the AA bar is "not entirely hidden": SC 2.4.12 (AAA) raises it to "no part of the focus indicator is hidden", so partial occlusion still passes AA but is worth fixing anyway.

```tsx
.scroller { scroll-padding-block: 4rem 3rem; } /* sticky header 4rem, footer 3rem */
```

- [WCAG 2.2: Understanding SC 2.4.11 Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)
- [MDN: scroll-padding](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding)

### Never Make Dragging the Only Path

**ID:** `interactions-drag-alternative`
**Agent rule (MUST):** Every drag must have a single-pointer alternative that reaches the same outcome without travel — ↑/↓ buttons on each row, a "Move to…" menu, or arrow-key handling on a focused grip. WCAG SC 2.5.7 Dragging Movements (AA); keep the drag as an accelerator. Only genuinely essential drags (signature pad, free-form canvas, map pan) are exempt.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Offer a single-pointer alternative to every drag: move buttons, arrow keys, or a menu

> All functionality that uses a dragging movement for operation can be achieved by a single pointer without dragging, unless dragging is essential or the functionality is determined by the user agent and not modified by the author. (WCAG 2.2, SC 2.5.7 Dragging Movements, Level AA)

This is not a rule about how a drag feels — it is a rule about whether the outcome is reachable at all without one. Two neighbouring principles here already govern drag quality: "Clean Drag Interactions" suppresses text selection and inert-ifies the page during a drag, and "Drag Physics" tunes velocity and damping on release. Both assume the drag is happening and make it better. Neither asks the question this SC asks, which is what a user with a tremor, an eye-tracker, a head-pointer or a switch does when press-travel-release is the only route to the outcome — for them, the answer today is "nothing". So keep the drag; it is a fine accelerator. Then add a path that a single pointer can complete without travelling: ↑ / ↓ buttons on each row, a "Move to…" menu, or arrow-key handling on a focused grip. The alternative must produce the same result, not a degraded one, and only "essential" drags — a signature pad, a free-form canvas, a map pan — are exempt, because there the path IS the content.

- [WCAG 2.2: Understanding SC 2.5.7 Dragging Movements](https://www.w3.org/WAI/WCAG22/Understanding/dragging-movements.html)

### Back Every Gesture With a Simple Control

**ID:** `interactions-gesture-alternative`
**Agent rule (MUST):** Any multipoint or path-based gesture (swipe, pinch, two-finger rotate, traced path) needs a discrete single-pointer control beside it — Prev/Next buttons, real pagination dot buttons, +/− zoom, arrow keys on the focused region. WCAG SC 2.5.1 Pointer Gestures, Level A. A drawing canvas is essential; a carousel never is.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Pair swipes, pinches and traced paths with buttons or keys that need no path at all

> All functionality that uses multipoint or path-based gestures for operation can be operated with a single pointer without a path-based gesture, unless a multipoint or path-based gesture is essential. (WCAG 2.1, SC 2.5.1 Pointer Gestures, Level A)

The sibling of "Never Make Dragging the Only Path" (SC 2.5.7), and the two are constantly confused. 2.5.7 is about dragging — press, travel, release, where the travel is what moves the thing. This one, 2.5.1, is about gestures whose SHAPE or number of contact points carries the meaning: a swipe, a pinch-zoom, a two-finger rotate, a drawn checkmark, a slider you can only operate by tracing. It is Level A, one step stricter, because a swipe-only carousel does not merely inconvenience someone — it walls off the content entirely. The remedy is the same shape as 2.5.7's: keep the gesture as an accelerator for the people who like it, and put a discrete single-pointer control next to it. Prev / Next buttons, pagination dots that are real buttons, +/− zoom controls, arrow-key handling on the focused region. "Essential" is narrow: a drawing canvas or a map that genuinely requires a free-form path qualifies; a carousel never does.

- [WCAG 2.1: Understanding SC 2.5.1 Pointer Gestures](https://www.w3.org/WAI/WCAG21/Understanding/pointer-gestures.html)

### Commit on the Up-Event, Not the Down-Event

**ID:** `interactions-pointer-cancellation`
**Agent rule (MUST):** Preview on down, COMMIT on up: the down-event may arm, highlight, reveal, or open a menu (all reversible — that is why opening dropdowns on `mousedown` is fine), but destructive/irreversible functions (delete, submit, purchase, send, publish) must complete on the up-event on the same element, so sliding off before release aborts them. WCAG SC 2.5.2 Pointer Cancellation, Level A — `click` gives you this for free; if you truly must act on down, ship an undo instead.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Let a mistaken press be aborted by sliding off before release; complete actions on pointerup

> For functionality that can be operated using a single pointer, at least one of the following is true: the down-event of the pointer is not used to execute any part of the function; completion of the function is on the up-event, and a mechanism is available to abort the function before completion or to undo the function after completion… (WCAG 2.1, SC 2.5.2 Pointer Cancellation, Level A)

Firing an action on pointerdown removes the one escape hatch every pointer user relies on: land on the wrong control, slide off, release, nothing happens. Take that away and a mis-aimed tap on a phone, or a tremor that lands a finger 4px off, is instantly irreversible. Draw the line carefully, because this corpus also tells you to open dropdowns on mousedown, and that is not a contradiction: opening a menu does not EXECUTE anything and is trivially reversible, so the down-event is free to preview, arm, highlight, or reveal. What it must not do is commit. Delete, submit, purchase, send, publish — these complete on the up-event, on the same element the press started on, which is exactly what the platform gives you for free in the click event. So the rule reads: preview on down, commit on up. If you genuinely must act on down (a piano key, a game control — the SC calls this "essential"), the alternative branch of the SC requires you to provide an undo instead.

- [WCAG 2.1: Understanding SC 2.5.2 Pointer Cancellation](https://www.w3.org/WAI/WCAG21/Understanding/pointer-cancellation.html)
- [MDN: Element click event](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)

### Make Hover Content Dismissible, Hoverable and Persistent

**ID:** `interactions-hover-content-persistence`
**Agent rule (MUST):** Hover/focus popups must be DISMISSIBLE (Escape hides it without moving pointer or focus), HOVERABLE (the pointer can travel into the content and stay there — bridge the trigger/card gap with wrapper padding, not a margin) and PERSISTENT (no auto-hide timer; it stays until the trigger is left, the user dismisses it, or the info goes stale). WCAG SC 1.4.13 Content on Hover or Focus, Level AA.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Let Escape close a hover card, let the pointer enter it, and never expire it on a timer

> Where receiving and then removing pointer hover or keyboard focus triggers additional content to become visible and then hidden, the following are true: Dismissible… Hoverable… Persistent: the additional content remains visible until the hover or focus trigger is removed, the user dismisses it, or its information is no longer valid. (WCAG 2.1, SC 1.4.13 Content on Hover or Focus, Level AA)

The missing sibling of the two tooltip rules already here. "Tooltip Timing" governs the show-delay; "No Interactive Content in Tooltips" governs what may go inside. Neither says what happens once the thing is on screen — and that is where three separate, independently-failing requirements live. DISMISSIBLE: Escape must hide it without moving the pointer or focus, because a screen-magnifier user viewing a small slice of the page may have a popup covering the content they were reading, and forcing them to move the pointer costs them their place. HOVERABLE: the pointer must be able to travel into the content and stay there, which is why the classic 2px "breathing gap" between trigger and card is a bug, not a detail — crossing it fires mouseleave and the card evaporates. Bridge it with padding on the wrapper (an invisible safe area) rather than a margin on the card, or hit-test a safe triangle toward the card. PERSISTENT: no auto-hide timers. A 3-second dismissal is an eternity for a magnifier user panning across the card and no time at all for someone reading with a screen reader; the content stays until the trigger is left, the user dismisses it, or the information stops being true.

- [WCAG 2.1: Understanding SC 1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html)

### One Tab Stop per Composite Widget

**ID:** `interactions-aria-composite-tab-stop`
**Agent rule (MUST):** A composite widget (toolbar, listbox, menu, radiogroup, tablist, grid, tree) is ONE tab stop: roving `tabindex` — exactly one child at `0`, every other child at `-1` — with arrow keys moving the `0` and calling `.focus()`, and Tab moving past the whole widget. Twelve children must not be twelve tab stops. (Distinct from positive `tabindex`: here every value is `0` or `-1`; the bug is how many are `0`.)
**Source:** ARIA (https://www.w3.org/WAI/ARIA/apg/)

Give a toolbar, listbox or grid a single tab stop and move within it using the arrow keys

> To help assistive technology users understand the boundaries of a composite widget and to provide efficient keyboard navigation, the tab sequence should include only one focusable element of a composite UI component. (WAI-ARIA Authoring Practices Guide, Developing a Keyboard Interface)

Tab crosses widgets; arrow keys move within one. A toolbar, listbox, menu, radiogroup, tablist, grid or tree is ONE thing in the tab sequence, no matter how many children it has — that is what makes it a composite. Get this wrong and a twelve-item filter bar becomes twelve stops the user must Tab past to reach the form below, and the arrow keys, which is what a screen reader user will actually press inside a listbox, do nothing at all. There are two implementations, and this one is roving tabindex: exactly one child carries tabindex="0" while every other child carries tabindex="-1", so the browser can only Tab into the active child; your arrow-key handler then moves the 0 to the next child and calls .focus() on it. Because real DOM focus moves, the browser scrolls the active child into view and paints the focus ring for free. The alternative, aria-activedescendant, is a separate principle — reach for it only when focus must stay in a text input. Note this is not the same complaint as "Never Use Positive tabindex", which is about tabindex="1" and up wrecking the global document order; here every value is 0 or -1 and the bug is how many of them are 0.

```tsx
<button tabIndex={i === activeIndex ? 0 : -1} onKeyDown={onArrows} />
// ArrowRight: setActiveIndex(i + 1); itemRefs[i + 1].current.focus();
```

- [APG: Developing a Keyboard Interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)
- [APG: Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)

### Keep Focus in the Input With aria-activedescendant

**ID:** `interactions-aria-activedescendant`
**Agent rule (SHOULD):** Default to roving `tabindex` (real DOM focus buys you scroll-into-view, the focus ring and focus events); reach for `aria-activedescendant` only where DOM focus must STAY in a text input — combobox, editable grid cell, tag input — because the moment focus leaves the `<input>` keystrokes stop landing, the caret vanishes, an IME composition dies mid-word and the mobile keyboard drops. Its costs are yours: stable `id` per option, style the active option yourself (it has no `:focus`), and `scrollIntoView({ block: "nearest" })` by hand.
**Source:** ARIA (https://www.w3.org/WAI/ARIA/apg/)

Point at the active option instead of moving focus whenever the user must keep typing

> There are two ways to manage focus within a composite: using DOM focus by moving focus with element.focus() and managing tabindex on the descendants ("roving tabindex"), or using aria-activedescendant, where the container retains DOM focus and the aria-activedescendant attribute identifies the active descendant. (WAI-ARIA Authoring Practices Guide, Developing a Keyboard Interface)

These are the two focus-management techniques for a composite, and they are not interchangeable. Roving tabindex moves REAL DOM focus onto the active child, which is why it is the default: the browser scrolls that child into view, paints the focus ring, and fires focus events, all for free. But it has one fatal domain — anywhere the user must keep typing. In a combobox, an editable grid cell, or a tag input, ArrowDown must move the highlight WITHOUT moving focus, because the moment focus leaves the <input> the keystrokes stop landing, the caret disappears, an IME composition is destroyed mid-word, and on mobile the software keyboard drops away. That is what aria-activedescendant is for: DOM focus stays on the container (the input), and the attribute holds the id of the active descendant, so assistive technology announces the option while the text field keeps receiving keys. The costs are real and yours to pay: every option needs a stable id, the container needs aria-activedescendant updated on every move, you must style the active option yourself because it has no :focus, and you must scroll it into view yourself with scrollIntoView({ block: "nearest" }) — the free ride roving tabindex got from the browser is exactly what you are giving up.

```tsx
<input role="combobox" aria-controls="lb" aria-activedescendant={activeId} />
<ul id="lb" role="listbox"><li id="opt-2" role="option" aria-selected /></ul>
```

- [APG: Developing a Keyboard Interface — Managing Focus Within Components](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)
- [APG: Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)

### Never aria-hidden Something Focusable

**ID:** `interactions-aria-hidden-focusable`
**Agent rule (NEVER):** Put `aria-hidden="true"` (or `role="presentation"`) on a visible focusable element or a subtree that is still tabbable — it strips the a11y tree but NOT the tab order, so focus walks into a ghost: the ring travels off screen and the screen reader announces nothing. Use `inert` on the container (removes it from tab order, a11y tree and hit-testing at once) or unmount it.
**Source:** ARIA (https://www.w3.org/WAI/ARIA/apg/)

Use inert or unmount to hide a subtree, so the tab order and the a11y tree agree

> Do not use role="presentation" or aria-hidden="true" on a visible focusable element. Using either of these on a visible focusable element will result in some users focusing on "nothing". (Using ARIA, Fifth Rule of ARIA Use)

aria-hidden="true" removes an element and its whole subtree from the accessibility tree. It does NOT remove anything from the tab order — those are two different trees, and this is the single most common way to desynchronise them. An off-canvas drawer hidden with aria-hidden plus opacity: 0 and a transform is still fully tabbable: keyboard focus walks into it, the focus ring travels off screen, and a screen reader announces nothing whatsoever, because the element it is focused on does not exist as far as the accessibility tree is concerned. Focusing on "nothing" is a dead end no user can recover from. The correct tools remove the subtree from BOTH trees at once: unmount it, or set the inert attribute on the container — inert takes the subtree out of the tab order, out of the accessibility tree, and out of hit-testing in one attribute, which is why it also shows up in this corpus as the way to freeze the rest of the page during a drag. If for some reason you must keep aria-hidden, you have to strip tabindex and disable every focusable descendant by hand, and keep doing so as the subtree changes — which is precisely the bookkeeping inert exists to delete.

```tsx
// ghost: <div aria-hidden="true" className="opacity-0"><button>Close</button></div>
<div inert={!open} className="opacity-0"><button>Close</button></div>
```

- [Using ARIA: Fifth rule of ARIA use](https://www.w3.org/TR/using-aria/)
- [MDN: inert](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert)

### aria-disabled in Composites, disabled in Forms

**ID:** `interactions-aria-disabled-vs-disabled`
**Agent rule (MUST):** Use `aria-disabled="true"` — not HTML `disabled` — for unavailable menu items, toolbar buttons, tabs, tree items and listbox options: `disabled` drops them out of the tab order and the arrow-key sequence, so users never discover the option exists. `aria-disabled` only changes the announcement, so YOUR handler must make activation a no-op. Keep HTML `disabled` for form controls whose state is already inferable from context.
**Source:** ARIA (https://www.w3.org/WAI/ARIA/apg/)

Keep unavailable menu items, tabs and options focusable so users can discover they exist

> It is important to note that disabled elements are not focusable… If it is important for the user to be aware of a disabled element, use aria-disabled="true" instead. For example, in a menu, toolbar, tab list, tree, or listbox, users benefit from being able to discover options that are unavailable. (WAI-ARIA Authoring Practices Guide)

The two spellings of "unavailable" behave completely differently, and picking the wrong one deletes information. HTML disabled makes the control unfocusable, unclickable and silent: it vanishes from the tab order, and any arrow-key handler in a composite widget is forced to skip over it, which is how a menu of six commands quietly becomes a menu of three for anyone not using a mouse. They never learn Delete or Move to… exist, so they cannot ask why the commands are unavailable or how to unlock them. aria-disabled="true" changes only the announcement — the element stays focusable and stays in the arrow-key sequence, assistive technology announces it as dimmed or unavailable, and it is YOUR handler that must make activation a no-op (the browser will not do it for you, so an aria-disabled button without a guard in its onClick is still live). Use HTML disabled where the state is already inferable from context — a form submit that is greyed out under a validation summary, a Next button on the last step. Use aria-disabled inside composite widgets: menu items, toolbar buttons, tabs, tree items, listbox options. Be aware of the overlap: "Never Put a Tooltip on a disabled Button" also reaches for aria-disabled in its good example, but its subject is tooltips and hover targets; this principle is about discoverability inside a composite, and it pairs with the one-tab-stop roving-tabindex rule — that arrow-key loop is exactly what disabled breaks.

```tsx
<li role="menuitem" tabIndex={-1} aria-disabled="true"
    onClick={(e) => { if (isDisabled) return; run(); }}>Move to…</li>
```

- [APG: Developing a Keyboard Interface — Focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)
- [APG: Menu and Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)

### Escape Closes the Topmost Layer

**ID:** `interactions-escape-dismiss`
**Agent rule (MUST):** Escape closes dialogs and overlays, and closes exactly ONE layer — the topmost open one. A nested popover and its parent dialog both listening for Escape on `window` means one keypress closes both and the user loses the form they were filling; the open layer handles the key and calls `stopPropagation()`. Native `<dialog>` and Radix-style primitives keep that stack for you. (Dismissal, not focus — `interactions-manage-focus` covers trap/return.)
**Source:** @Ibelick (https://www.ui-skills.com/)

Escape must dismiss a dialog or overlay, and it must dismiss exactly one layer — the one on top

> Escape must close dialogs or overlays when applicable

Escape is the universal "get me out of here" key, and a dialog that only closes via an X button strands anyone who is not holding a mouse — a keyboard user has to Tab around a trapped focus ring hunting for the exit. But the interesting half of this rule is the nested case, which almost every hand-rolled implementation gets wrong. Put a select or a popover inside a dialog, attach `keydown` for Escape on `window` in both, and one keypress closes both: the child dismisses, and the same event keeps bubbling to the dialog's listener. The user tried to close a dropdown and lost their whole form. The fix is layer discipline — the topmost open layer handles Escape and calls `stopPropagation()` so it does not reach anything beneath it. Native `<dialog>` and Radix-style primitives maintain that stack for you, which is why the a11y skill closes with "for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior". This is distinct from interactions-manage-focus, which covers trapping focus and returning it — dismissal is a separate obligation.

```tsx
function onKeyDown(e: React.KeyboardEvent) {
  if (e.key !== "Escape") return;
  e.stopPropagation(); // do not let the parent layer close too
  close();
}
```

- [ibelick — fixing-accessibility SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-accessibility/SKILL.md)
- [W3C — ARIA APG, Modal Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)

### Hover-Revealed Actions Need Focus Parity

**ID:** `interactions-hover-revealed-actions`
**Agent rule (MUST):** Any action revealed on hover needs the same keyboard reveal: pair `group-hover:opacity-100` with `group-focus-within:opacity-100` (and `focus-visible:opacity-100` on the control). Row actions left at `opacity-0` stay in the tab order but render invisible, so a keyboard user focuses a button they cannot see. Do NOT "fix" it by dropping them from the tab order or setting `pointer-events-none` — that trades a broken affordance for none.
**Source:** @Ibelick (https://www.ui-skills.com/)

Row actions hidden behind opacity-0 group-hover are invisible and unreachable for anyone using a keyboard

> hover-only interactions must have keyboard equivalents

The pattern is everywhere: a table row or list item whose Edit and Delete buttons live behind `opacity-0 group-hover:opacity-100`, so the row stays quiet until you point at it. It is a good instinct and a broken implementation, because hover is a pointer-only state. A keyboard user Tabs into that button and sees nothing — the element is still in the tab order, still focused, but rendered at zero opacity, so the focus ring is invisible and the page appears to swallow their focus. There is no way to discover, aim, or confirm the action. The fix is one utility: `focus-within:opacity-100` on the row (plus `focus-visible:opacity-100` on the button itself), so keyboard focus reveals exactly what hover reveals. What you must not do is "fix" it by making the buttons `pointer-events-none` or removing them from the tab order — that trades a broken affordance for no affordance. Note this is the specific, most-shipped instance of interactions-keyboard-everywhere; the general rule is easy to nod at and this is where it actually breaks.

```tsx
<tr class="group">
  <td><button class="opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 focus-visible:opacity-100">Edit</button></td>
</tr>
```

- [ibelick — fixing-accessibility SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-accessibility/SKILL.md)
- [W3C — Understanding WCAG 2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html)

### An Anchor Without href Is Not a Link

**ID:** `interactions-anchor-without-href`
**Agent rule (NEVER):** Render an `<a>` without `href` and drive it from `onClick` alone. `href` is what MAKES it a link: without it the browser exposes the element as `generic` — no link role, not focusable, not in the tab order, absent from the screen reader's links list, and mouse-only. Two branches: if it NAVIGATES, give it a real `href` (you get focus, the link role, Enter, middle-click, Cmd-click, "Copy link address" for free); if it performs an ACTION, it was never a link — use `<button>`.
**Source:** RAMS (https://www.rams.ai/)

An <a> with only an onClick has no link role, no focus, and no place in the tab order

> Missing link destination (WCAG 2.1.1) — <a> without href using only onClick

Rams files this Critical, and the reason is that it does not look like a bug. `<a onClick={() => navigate("/profile")}>View profile</a>` reads as correct semantic HTML and passes a naive "did you use the right element?" check — you did reach for the native element. But `href` is not decoration; it is what makes the element a link. Without it the browser exposes an `<a>` as a `generic`: no link role, not focusable, not in the tab order, and absent from the screen reader's list of links, so a keyboard user tabs straight past it and a screen-reader user never learns it exists. It is mouse-only, and it is extremely common in React. Note this is the INVERSE of three principles already in this corpus, not a duplicate of any of them: `interactions-rams-semantic-handlers` covers a non-interactive element pretending to be interactive (`<div onClick>`), `content-semantics-first` says do not reach for `role="button"` when a button exists, and `interactions-rams-keyboard-handlers` covers onClick with no onKeyDown. Here you reached for the native element, and it still fails. The fix depends on intent, and there are exactly two branches. If it navigates, give it a real `href` — the browser then hands you focus, the link role, Enter activation, middle-click and Cmd-click to open in a new tab, and "Copy link address", none of which an onClick handler can synthesise. If it performs an action, it was never a link: use `<button>`.

```tsx
// no: role-less, unfocusable, mouse-only
<a onClick={() => navigate("/profile")}>View profile</a>
// yes
<a href="/profile">View profile</a>
```

- [Rams review checklist](https://rams.ai/rams.md)
- [WCAG 2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html)
- [MDN — <a>: The Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a)

### The Modal Is the Last Resort

**ID:** `interactions-impeccable-modal-last-resort`
**Agent rule (NEVER):** Reach for a modal as the first thought. A modal steals focus, blocks the page, and destroys the context the user was acting on — they must now hold the row they clicked in working memory. Exhaust the cheaper alternatives that keep context on screen: edit in place, use a side panel or a dedicated route, and replace a confirmation dialog with an undo toast wherever the action is reversible (compose with `interactions-confirm-destructive`). What survives is the narrow case a modal is actually for: one action, destructive, and irreversible — nothing to undo it with.
**Source:** impeccable (https://impeccable.style/)

Exhaust inline editing, side panels, and dedicated routes before you reach for a modal

> Modal as first thought. Modals are usually laziness. Exhaust inline / progressive alternatives first.

impeccable ships this under "Absolute bans" — match-and-refuse, alongside gradient text and glassmorphism. The reason it is banned rather than merely discouraged is that a modal is expensive in a way that is invisible to the person adding it: it steals focus, blocks the page behind it, and destroys the context you were acting on, so the user must now hold the row they clicked in working memory while they read the dialog. Stack two and the original context is gone entirely. Nearly every modal has a cheaper alternative that keeps the context on screen: rename edits in place, a destructive-but-reversible action wants an undo toast rather than a confirmation, and supporting information belongs in a side panel or on its own route. Cross-reference `interactions-confirm-destructive`, which is about WHETHER to confirm at all — this principle is about modal OVERUSE, and the two answers compose: most deletes should be undoable rather than confirmed, which removes the modal entirely. What survives is the narrow case where a modal is genuinely right: one action, destructive, and irreversible — nothing to undo it with.

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [W3C — ARIA APG, Modal Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)

### Four Options at Any Decision Point

**ID:** `interactions-impeccable-four-option-limit`
**Agent rule (SHOULD):** Cap any decision point at <=4 simultaneously visible options (Miller's Law as revised by Cowan, 2001: working memory holds ~4 items). 5-7 is the boundary — group them or reveal progressively; 8+ is overload, and an overloaded user does not choose slowly, they skip, misclick, or abandon. Carried into surfaces: <=5 top-level nav items, <=4 form fields before a visual break, 1 primary + 1-2 secondary buttons (rest in a menu), <=4 key metrics above the fold, <=3 pricing tiers. Grouping does not remove capability — a 4-item nav with a "More" group still reaches nine destinations — it removes them from the decision.
**Source:** impeccable (https://impeccable.style/)

Working memory holds about four items — cap visible choices, nav items, and pricing tiers accordingly

> Humans can hold ≤4 items in working memory at once (Miller's Law revised by Cowan, 2001). ≤4 items: Within working memory limits — manageable. 5–7 items: Pushing the boundary — consider grouping or progressive disclosure. 8+ items: Overloaded — users will skip, misclick, or abandon.

The thresholds are explicit and they are not aesthetic: at any decision point, count the distinct options a user must simultaneously consider. Four or fewer sits inside working memory. Five to seven is the boundary — group them or reveal them progressively. Eight or more is overload, and an overloaded user does not choose slowly, they skip, misclick, or abandon. impeccable carries the rule into specific surfaces: navigation menus get at most 5 top-level items (group the rest under clear categories), form sections at most 4 fields before a visual break, action buttons get 1 primary and 1–2 secondary with the rest in a menu, dashboards at most 4 key metrics above the fold, and pricing at most 3 tiers, because more causes analysis paralysis. The counter-intuitive part is that grouping does not remove capability — a nav with 4 items plus a "More" group still reaches nine destinations. It removes them from the decision, which is the only place they were doing harm. Pair a capped tier list with a highlighted recommendation and you collapse the choice further still: the question stops being "compare three" and becomes "accept this one, or look at the other two".

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [Laws of UX — Miller's Law](https://lawsofux.com/millers-law/)

### Expanded Hit Areas Must Never Collide

**ID:** `interactions-hit-target-collision`
**Agent rule (NEVER):** Let two interactive elements have overlapping hit areas. This is the failure `interactions-match-hit-targets` creates: expand a sub-24px control with a pseudo-element and adjacent expanded targets overlap invisibly, so paint order decides the hit test and the element painted later steals the clicks. Grow each hit area only to the largest rect that does not collide with its neighbour's; if that lands below 24px, the layout is wrong — widen the pitch between the controls (WCAG 2.2 SC 2.5.8 measures spacing, not just size).
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Grow a small control's hit area as large as it will go without overlapping the next control's

> If the extended hit area overlaps another interactive element, shrink the pseudo-element, but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.

This is the rule that makes our own advice safe. "Match Visual & Hit Targets" tells you to expand a sub-24px control with a pseudo-element; "Small Touch Targets" and "No Dead Zones" push the same way. All three are about size, and none of them is about collision. Apply them literally to a row of 20px icon buttons separated by a 4px gap and each 44px pseudo-element overshoots its neighbour by roughly 20px. Nothing warns you: the pseudo-elements are invisible, the icons still look correctly spaced, and the overlap is resolved silently by paint order — the element painted later wins the hit test. So a click that lands squarely on the star icon can fire the delete button sitting next to it, and the bug only shows up in a support ticket. The fix is a ceiling on the expansion: grow each hit area until it would touch its neighbour's, then stop. If that leaves you below the minimum, the layout itself is wrong and the controls need a wider pitch — 44px of spacing rather than 44px of overlapping padding. WCAG 2.2 SC 2.5.8 encodes exactly this trade: a target under 24px still passes if a 24px circle centred on it does not intersect the circle of any other target. Spacing, not just size, is what the criterion actually measures.

```tsx
/* 20px icons, 4px apart — cap the expansion, do not overshoot into the neighbour */
.icon-btn { position: relative; }
.icon-btn::after { content: ""; position: absolute; inset: -12px -2px; }
```

- [jakubkrehel/skills — better-ui: surfaces.md](https://github.com/jakubkrehel/skills/blob/main/skills/better-ui/surfaces.md)
- [WCAG 2.2 SC 2.5.8 Target Size (Minimum) — spacing exception](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)

### Project Where the Flick Is Going

**ID:** `interactions-momentum-projection`
**Agent rule (MUST):** Project the resting position from release velocity, THEN snap to the target nearest that projected point — never snap to the target nearest the release point, which cannot tell a nudge from a throw.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Use release velocity to project a resting position, then snap to the target nearest that point

> Don't snap to the nearest boundary from the *release point*. Use velocity to **project the resting position** — exactly like scroll deceleration — then snap to the target nearest that projected point. This is what makes a flick feel like it throws the element.

A carousel that snaps to whichever slide is nearest the release point cannot tell a nudge from a throw. Both gestures end at roughly the same x, so both advance exactly one slide, and the hard flick you meant as "skip ahead" is quietly discarded. Momentum projection uses the velocity you already measured to answer a different question: not "where did the finger stop" but "where would the element come to rest if it kept moving". Apple ships an exponential-decay projection rather than the physics-textbook v²/(2·decel) — `project(v) = (v / 1000) * d / (1 - d)` with a deceleration rate d of about 0.998 — and then picks the snap target nearest that projected endpoint. This is distinct from "Give Drag Gestures Real Physics", which uses velocity as a binary gate: above ~0.11 px/ms the sheet dismisses, below it springs back. That rule never computes a landing point, so it can decide whether to commit but not how far to travel. Projection is what turns a small input into a big output.

```tsx
const project = (v, decel = 0.998) => (v / 1000) * decel / (1 - decel);
const rest = x + project(velocityX);
snapTo(nearestTarget(rest)); // not nearestTarget(x)
```

- [Emil Kowalski: apple-design SKILL.md](https://github.com/emilkowalski/skills/blob/main/skills/apple-design/SKILL.md)
- [WWDC 2018: Designing Fluid Interfaces](https://developer.apple.com/videos/play/wwdc2018/803/)

### Respect Where the User Grabbed

**ID:** `interactions-grab-offset`
**Agent rule (MUST):** Store the pointer's offset within the element at `pointerdown` and subtract it on every `pointermove` so the element stays glued to the spot the user grabbed. Never re-centre the element under the cursor on grab — it teleports on the first frame and the illusion of holding an object dies.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Store the pointer's offset within the element on pointerdown and subtract it on every move

> When the user drags something, it must stay glued to the finger — and respect the offset from *where they grabbed it*. Snapping to the element's center on grab breaks the illusion immediately.

The cheapest way to write a drag is to set the element's position to the pointer's position, which silently centres it under the cursor. The result is a visible teleport at the instant of grab: you press the bottom edge of a card and the card jumps up so its middle is under your finger. Nothing in the physical world does this, and the illusion of holding an object dies in the first frame — before any of the release physics gets a chance to matter. The fix is two lines and no library: at pointerdown, record `e.clientY - element.getBoundingClientRect().top` (and the same for x), then on every pointermove subtract that offset from the pointer position. The element stays glued to the exact spot you took hold of. This is grab-time positioning, and no other rule in the corpus covers it: "Clean Drag Interactions" is about text selection and inert during the drag, and "Give Drag Gestures Real Physics" is about what happens on release. Between them sits the very first frame, which is the one users feel most sharply.

```tsx
const r = el.getBoundingClientRect();
const offset = { x: e.clientX - r.left, y: e.clientY - r.top };
// pointermove:
el.style.translate = `${e.clientX - offset.x}px ${e.clientY - offset.y}px`;
```

- [Emil Kowalski: apple-design SKILL.md](https://github.com/emilkowalski/skills/blob/main/skills/apple-design/SKILL.md)
- [MDN: Element.setPointerCapture()](https://developer.mozilla.org/en-US/docs/Web/API/Element/setPointerCapture)

### Require Movement Before Committing to a Direction

**ID:** `interactions-gesture-hysteresis`
**Agent rule (MUST):** Require ~10px of movement from the `pointerdown` origin before committing a drag/swipe to an axis, then lock that axis and track 1:1 with no mid-gesture re-evaluation. Committing on the first `pointermove` reads the wobble at the start of a vertical scroll as a horizontal swipe and steals the scroll.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Wait ~10px before locking a gesture to an axis, then track it 1:1

> **Drag/swipe:** require a small movement threshold (hysteresis, ~10px) before committing to a direction, then track 1:1.

Fingers are not straight lines. A vertical scroll on a touch screen almost always begins with a couple of pixels of horizontal wobble, and a swipeable list row that commits to a direction on the very first pointermove will read that wobble as a swipe — locking the axis, calling preventDefault, and stealing the scroll the user actually wanted. From then on the list is unscrollable in the region where the rows are. Hysteresis makes the decision wait for evidence: accumulate movement from the pointerdown origin, ignore everything until the total distance passes a threshold of roughly 10px, and only then compare the horizontal and vertical components to decide which axis wins. Below the threshold the gesture is undecided and the browser keeps its native scroll; above it the axis is locked for the rest of the gesture and tracks the finger 1:1, with no re-evaluation that could cause a mid-drag flip. The threshold buys certainty about intent, and 10px is small enough that a deliberate swipe never feels delayed.

- [Emil Kowalski: apple-design SKILL.md](https://github.com/emilkowalski/skills/blob/main/skills/apple-design/SKILL.md)
- [MDN: touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action)

### Sound Is Never the Only Channel

**ID:** `interactions-sound-not-sole-channel`
**Agent rule (MUST):** Give every audio cue a visual equivalent — sound is a reinforcement channel and never carries feedback alone (WCAG 1.3.3). A Submit whose only success signal is a chime does nothing observable on a muted tab, and nothing at all for a deaf user. Removing the sound must cost nothing.
**Source:** Custom

Every audio cue needs a visual equivalent — sound supplements feedback, it never carries it

> Every audio cue must have a visual equivalent; sound never replaces visual feedback.

Cherry-picked from Raphael Salaja's sounds-on-the-web skill (rule `a11y-visual-equivalent`). The failure is easy to reproduce and easy to miss in development: a Submit button whose only success signal is a chime. On a muted tab — which is the default state of most tabs most of the time — pressing Submit produces no observable change at all, and the user presses it again. Deaf and hard-of-hearing users get the same nothing, permanently. This is WCAG 1.3.3 Sensory Characteristics: instructions and feedback must not depend on a single sensory characteristic. It is the same principle as "Redundant Status Cues", which is scoped to colour and WCAG 1.4.1 — one channel, one criterion, identical shape. Sound is simply the channel that is switched off far more often than colour is. The rule is not "no sound"; sound is a genuinely good second channel when the user is not looking at the screen. The rule is that removing it must cost nothing.

- [Raphael Salaja: sounds-on-the-web SKILL.md](https://github.com/raphaelsalaja/skill/blob/main/skills/sounds-on-the-web/SKILL.md)
- [WCAG 2.2 SC 1.3.3 Sensory Characteristics](https://www.w3.org/WAI/WCAG22/Understanding/sensory-characteristics.html)

### Sound Belongs to the User

**ID:** `interactions-sound-is-user-owned`
**Agent rule (MUST):** Ship an explicit mute toggle in settings plus a volume control independent of system volume, and default the volume subtle (`0.3`) — never loud, never autoplaying. The OS mixer silences everything, not just you, so "turn your machine down" is not an off switch.
**Source:** Custom

Ship an explicit mute toggle, an independent volume control, and a subtle default

> Provide explicit toggle to disable sounds in settings. Allow volume adjustment independent of system volume. Default volume should be subtle, not loud.

Cherry-picked from Raphael Salaja's sounds-on-the-web skill, merging three of its rules (`a11y-toggle-setting`, `a11y-volume-control`, `impl-default-subtle`). A sound provider with no off switch treats audio as a property of the product rather than a property of the session, and the user's only recourse is the OS mixer — which silences everything, not just you. Three controls fix it. An explicit toggle, because "turn down my whole machine" is not an answer to "this app is noisy". An in-app volume independent of system volume, because the right level for a notification chime and the right level for a video are different numbers, and only the user knows what else is playing. And a subtle default: the upstream number is 0.3, chosen so that the first sound a user hears is never the loudest thing they have heard today. Defaulting to full volume converts a nice touch into an ambush, and an ambushed user mutes the tab permanently — which loses you the channel entirely.

- [Raphael Salaja: sounds-on-the-web SKILL.md](https://github.com/raphaelsalaja/skill/blob/main/skills/sounds-on-the-web/SKILL.md)
- [WCAG 2.2 SC 1.4.2 Audio Control](https://www.w3.org/WAI/WCAG22/Understanding/audio-control.html)

### Sound Only for Significant Events

**ID:** `interactions-sound-only-for-significant-events`
**Agent rule (NEVER):** Attach sound to high-frequency interactions — typing, keyboard navigation, hover, scroll. Reserve it for confirmations the user needs assurance of (payments, uploads, form submissions) and for errors/warnings that must not be overlooked. A cue that fires on every input stops being feedback and trains the user to tune out every other sound you make.
**Source:** Custom

Confirmations and errors earn a sound; typing, hover, scroll and navigation never do

> Do not add sound to high-frequency interactions (typing, keyboard navigation). Sound is appropriate for confirmations: payments, uploads, form submissions. Sound is appropriate for errors and warnings that can't be overlooked.

Cherry-picked from Raphael Salaja's sounds-on-the-web skill, merging `appropriate-no-high-frequency` with `appropriate-confirmations-only` and `appropriate-errors-warnings`. Frequency is the whole test. A sound on a payment confirmation fires once and reassures; the same sound on a keystroke fires eighty times a minute and becomes noise the user learns to tune out — taking every other sound in your product down with it, including the error you actually needed them to hear. The skill's own appropriateness matrix draws the line explicitly: payment success yes (significant confirmation), form submission yes (user needs assurance), error yes (can't be overlooked), notification yes (may not be looking at the screen), button click maybe (only for significant buttons), typing no (too frequent), hover no (decorative only), scroll no (too frequent), navigation no (keyboard nav would be noisy). This is the same shape as "Match Motion to Frequency", which withholds animation from keyboard-initiated and high-frequency interactions for exactly the same reason: feedback that fires on every input stops being feedback and becomes texture.

- [Raphael Salaja: sounds-on-the-web SKILL.md](https://github.com/raphaelsalaja/skill/blob/main/skills/sounds-on-the-web/SKILL.md)
- [MDN: Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)

### Match Sound Weight to the Action

**ID:** `interactions-sound-weight-matches-action`
**Agent rule (SHOULD):** Make a cue's sound proportional to the action's consequence: a trivial action gets a short, high, quiet tick; a heavy or irreversible one gets a lower, longer, slightly louder tone. Do not reuse one blip for everything — identical sound erases hierarchy. Stay subtle and keep the visual channel primary.
**Source:** Custom

Scale a sound's pitch, length, and heft to the consequence — a light tick for the trivial, a low weighty tone for the grave

> Sound weight should match the action's weight, and sound duration should match the action. A small action gets a light, short sound; a large or significant one gets a heavier, longer sound.

Cherry-picked from the weight-matching rules in Raphael Salaja's sounds-on-the-web skill, and it presumes interactions-sound-only-for-significant-events has already decided WHICH events get a sound at all — this rule governs, among those, how MUCH sound. The audio channel is a hierarchy channel or it is noise: if starring an item and deleting an account make the same 880Hz blip, the ear learns nothing and tunes the whole product out. Weight is carried by three knobs, and they stack — lower pitch reads heavier, longer duration reads weightier, and a slightly higher level reads more significant, so a grave, irreversible action wants a low tone that lingers (and can glide downward), while a trivial toggle wants a short, high, quiet tick. This is the audio sibling of two motion rules the corpus already holds: animations-lottie-distance-duration derives duration from how far an element travels, and animations-emil-frequency withholds motion from high-frequency actions — same instinct, that feedback must be proportional to what it is reporting. Stay inside the other sound constraints while you do it: keep the loudest tone subtle and user-controlled (interactions-sound-is-user-owned) and never let the sound carry meaning the screen does not (interactions-sound-not-sole-channel).

```tsx
star()   => playTone({ frequency: 1046, duration: 0.09, volume: 0.22 });
delete() => playTone({ frequency: 220, endFrequency: 150, duration: 0.34, volume: 0.34 });
```

- [Raphael Salaja: sounds-on-the-web SKILL.md](https://github.com/raphaelsalaja/skill/blob/main/skills/sounds-on-the-web/SKILL.md)
- [MDN: OscillatorNode](https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode)

### Error Sounds Must Not Punish

**ID:** `interactions-sound-not-punishing`
**Agent rule (SHOULD):** An error sound must inform, not scold. Keep it brief, moderate in level, and gentle — typically lower and falling, distinct from a rising success tone. A harsh, loud, dissonant buzzer makes users mute the whole product, losing every useful cue with it. The worded, visible error still carries the message and the fix.
**Source:** Custom

An error tone should be distinct and calm, not a harsh loud alarm — punishing sounds make users mute everything

> Do not use harsh or punishing sounds for errors. An error sound should inform, not startle or scold.

Cherry-picked from the appropriateness rules in Raphael Salaja's sounds-on-the-web skill. An error is information, not a verdict, and the sound has to agree with that. A loud, low, dissonant buzzer does the opposite — it startles, it reads as a reprimand for a typo, and the entirely rational response is to mute the product, which also silences the confirmations you actually wanted the user to hear. It is the same escape-hatch failure that over-frequent sound causes, arrived at from the other direction: make any one sound intolerable and the user kills all of them. A good error tone is brief, moderate in level, and gentle — often pitched lower than success and falling rather than rising, so it is instantly distinguishable from a confirmation without being aggressive. As always the sound is the junior partner: the visible, worded error carries the message and the fix (this is the audio counterpart of content-actionable-errors and content-positive-language, which say the copy should guide rather than blame), and interactions-sound-not-sole-channel keeps it that way.

```tsx
// gentle, brief, downward — noticed, not punishing
playTone({ frequency: 392, endFrequency: 294, duration: 0.28, type: 'sine', volume: 0.3 });
```

- [Raphael Salaja: sounds-on-the-web SKILL.md](https://github.com/raphaelsalaja/skill/blob/main/skills/sounds-on-the-web/SKILL.md)
- [NN/g: Error-Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)

### Prediction Cone for Nested Menus

**ID:** `interactions-menu-prediction-cone`
**Agent rule (SHOULD):** A submenu that opens to the side must forgive diagonal pointer travel toward it. Do not swap or close it the instant the pointer leaves the parent row: use a safe-triangle/prediction cone (suppress sibling hover while the pointer aims at the open submenu) or, as a cheap approximation, a ~150ms close-delay that any re-entry into the submenu cancels.
**Source:** Rauno (https://interfaces.rauno.me/)

When a submenu opens on hover, forgive diagonal pointer travel toward it instead of closing the instant the pointer leaves the parent row

> When using nested menus, use a "prediction cone" to prevent the pointer from accidentally closing the menu when moving across other elements.

The naive nested menu closes the submenu the moment the pointer leaves the parent item. That is exactly wrong, because the submenu opens to the side, so the shortest path to it runs diagonally across the sibling rows below the one you are pointing at. Each sibling the pointer crosses fires its own hover, swaps the open submenu out for its own, and the option you were reaching for vanishes before you arrive. The user learns to travel in an L — straight down the border, then across — which is the tell of a menu that does not forgive its own geometry. The fix has two well-known shapes. The "prediction cone" (or "safe triangle", the Amazon mega-menu trick Ben Kamens documented) reads pointer velocity and builds a triangle between the cursor and the top and bottom corners of the open submenu; while the pointer stays inside that triangle it is presumed to be aiming AT the submenu, so sibling hovers are suppressed for a short grace window. The cheaper approximation is a short close-delay (~100–200ms) on the submenu that any pointer re-entry cancels. This is the same forgiveness principle as interactions-forgiving-design and interactions-hover-content-persistence (hover targets must be reachable and not expire on a timer); it pairs with interactions-mousedown-dropdown, which handles the open, where this handles the traverse.

```tsx
onMouseEnter={(id) => { clearTimeout(t); t = setTimeout(() => setActive(id), 160); }}
// submenu panel: onMouseEnter={() => clearTimeout(t)}
```

- [Rauno Freiberg — interfaces.rauno.me](https://raw.githubusercontent.com/raunofreiberg/interfaces/main/README.md)
- [Ben Kamens — Breaking down Amazon’s mega dropdown](https://bjk5.com/post/44698559168/breaking-down-amazons-mega-dropdown)
- [MDN — Pointer events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events)

---

## Animations

Motion design principles and animation best practices. 55 rules.

### Honor prefers-reduced-motion

**ID:** `animations-prefers-reduced-motion`
**Agent rule (MUST):** Honor `prefers-reduced-motion` (provide reduced variant); in Tailwind use the `motion-safe:`/`motion-reduce:` variants
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Provide a reduced-motion variant for all animations

> Honor prefers-reduced-motion. Provide a reduced-motion variant.

Some users experience motion sickness or vestibular symptoms from movement they did not initiate. The media query surfaces an OS-level preference they have already expressed, so honouring it costs one @media block. The load-bearing detail: "reduced" is not "none". Strip the spatial travel and the spring, but KEEP the opacity crossfades and the instant state changes, so the interface still says what happened — a state change that was only ever communicated by motion becomes invisible the moment the motion is dropped (animations-lottie-never-opacity-only is the corollary). ibelick's baseline-ui converges on the same rule from the agent-guidelines side ("SHOULD respect `prefers-reduced-motion`"), which is why this corpus states it once here rather than twice. CAVEAT, and it is worth stating plainly: Raphael Salaja's sounds-on-the-web skill advises treating prefers-reduced-motion as a proxy for sound sensitivity — defaulting audio OFF when it is set. That is pragmatic, because no `prefers-reduced-sound` media query has ever shipped, and it is a defensible default. But it is lossy: a vestibular preference is not a sound preference, and the overlap is a guess, not a signal. Use it as a default-OFF heuristic, never as a substitute for an explicit, persisted sound toggle (see interactions-sound-is-user-owned).

- [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion)
- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Raphael Salaja — sounds-on-the-web SKILL.md](https://raw.githubusercontent.com/raphaelsalaja/skill/main/skills/sounds-on-the-web/SKILL.md)
- [Accessible Animations](https://www.a11yproject.com/posts/understanding-vestibular-disorders/)

### Compositor-friendly

**ID:** `animations-compositor-friendly`
**Agent rule (MUST):** Animate compositor-friendly props (`transform`, `opacity`) — they run on the GPU without layout or paint; avoid layout/repaint props (`top/left/width/height`, `margin`). 60fps leaves <16ms per frame
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prioritize GPU-accelerated properties like transform and opacity

> Compositor-friendly. Prioritize GPU-accelerated properties (transform, opacity) & avoid properties that trigger reflows/repaints (width, height, top, left).

transform and opacity are the only two properties the browser can change without redoing style, layout or paint — the compositor already holds the layer and just re-places or re-blends it, on its own thread. That is why they keep moving at 60fps even while the main thread is blocked, and why width, height, top or left stutter the moment it is not. This is one of the most independently rediscovered rules in the field, and this entry is where the corpus records it once: ibelick's baseline-ui states it as "MUST animate only compositor props (`transform`, `opacity`)", and Tailwind performance guidance as "animate only transform and opacity" — three sources, one rule, so read the convergence as confirmation rather than as three things to learn. Read it as the DEFAULT, not an absolute: the carve-outs are priced elsewhere and are part of the rule. Paint animations are acceptable on small, isolated surfaces (a button label, an icon — animations-ibelick-minimize-paint), one-shot effects are cheaper than continuous motion, and a layout-like change can be faked with a measured transform (FLIP — animations-flip-technique). And note the false floor: in Motion, `animate={{ x: 100 }}` looks compliant but is interpolated on the main thread — see performance-motion-shorthand-not-gpu.

- [High Performance Animations](https://web.dev/articles/animations-guide)
- [Compositor-only Properties](https://web.dev/articles/stick-to-compositor-only-properties-and-manage-layer-count)
- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [CSS Triggers](https://csstriggers.com/)

### Interruptible

**ID:** `animations-interruptible`
**Agent rule (MUST):** Animations are interruptible and input-driven (avoid autoplay)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Animations are cancelable by user input

> Interruptible. Animations are cancelable by user input.

Don't force users to wait for animations to complete. If a user interacts during an animation (clicking, scrolling, etc.), the animation should either instantly complete or transition to the new state. Never block interaction during animation.

- [Animation Best Practices](https://www.nngroup.com/articles/animation-usability/)

### Correct Transform Origin

**ID:** `animations-correct-transform-origin`
**Agent rule (MUST):** Correct `transform-origin` (motion starts where it "physically" should)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Anchor motion to where it physically starts

> Correct transform origin. Anchor motion to where it "physically" starts.

When elements scale or rotate, the transform-origin should match where the motion naturally originates. For example, a dropdown opening from a button should scale from the button's position, not from the center of the dropdown.

- [transform-origin](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/transform-origin)

### Never transition: all

**ID:** `animations-never-transition-all`
**Agent rule (MUST):** Never transition: all. Explicitly list only the properties you intend to animate (typically opacity, transform)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Explicitly list only the properties you intend to animate

> Never transition: all. Explicitly list only the properties you intend to animate (typically opacity, transform). all can unintentionally animate layout-affecting properties causing jank.

Using transition: all is tempting but dangerous. It can accidentally animate properties you didn't intend to, causing performance issues and unexpected visual effects. Always explicitly list the properties you want to transition.

- [CSS Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Transitions/Using)

### Implementation Preference

**ID:** `animations-implementation-preference`
**Agent rule (SHOULD):** Prefer CSS > Web Animations API > JS libraries
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer CSS over Web Animations API over JavaScript libraries

> Implementation preference. Prefer CSS, avoid main-thread JS-driven animations when possible. Preference: CSS > Web Animations API > JavaScript libraries e.g., motion.

CSS animations run off the main thread and are most performant. Web Animations API provides more control when needed. JavaScript animation libraries should be a last resort as they run on the main thread and can block user interactions.

- [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Animations)
- [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)

### Necessity Check

**ID:** `animations-necessity-check`
**Agent rule (SHOULD):** Animate only to clarify cause/effect or add deliberate delight
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Only animate when it clarifies cause and effect or adds deliberate delight

> Necessity check. Only animate when it clarifies cause & effect or when it adds deliberate delight e.g., the northern lights.

Animation should serve a purpose: showing relationships between actions and results, or creating memorable moments. Don't animate just because you can. Every animation should justify its existence by improving comprehension or creating meaningful delight.

- [Animation Principles](https://www.nngroup.com/articles/animation-usability/)

### Easing Fits Subject

**ID:** `animations-easing`
**Agent rule (SHOULD):** Choose easing to match the change (size/distance/trigger)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Choose easing functions based on what changes

> Easing fits the subject. Choose easing based on what changes (size, distance, trigger).

Pick the curve from what is changing, in this order: elements entering or exiting the screen → ease-out (and, on this reading, ease-in is also permitted for exits, on the argument that a departing element may accelerate away); an element morphing or moving between two on-screen states → ease-in-out; hover and other pointer feedback → ease; anything constant or continuous, like a marquee or a spinner → linear. Then match the magnitude to the distance travelled: a 4px hover nudge and a full-screen sheet should not share a curve. Note the field disagrees about exits — "Never ease-in on UI" (animations-emil-no-ease-in) rejects ease-in outright, on the grounds that it stalls the first ~100ms, which is exactly the window in which the user judges speed. Both entries are kept deliberately: read them together and decide, rather than inheriting one by default.

- [Easing Functions](https://easings.net/)
- [CSS Easing](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function)

### Use motion/react for JS Animations

**ID:** `animations-ibelick-motion-library`
**Agent rule (MUST):** Use motion/react (formerly framer-motion) when JavaScript animation is required. It provides spring physics, gesture support, and exit animations out of the box.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use motion/react (Framer Motion) for JavaScript-driven animations instead of manual implementations

> MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required

Note the conditional in the rule: it does not say to reach for a JS animation library, it says which one to use once you have established that JS is required at all. CSS first; JS only when the interaction genuinely needs it (see animations-implementation-preference). When it does, hand-rolling with requestAnimationFrame or direct DOM writes means re-solving interruption, velocity hand-off, spring physics and gesture integration yourself — motion/react handles those, and the alternative is a pile of animations that restart from zero every time the user touches them.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Motion Documentation](https://motion.dev/docs/react)

### tw-animate-css for Micro Animations

**ID:** `animations-ibelick-tw-animate`
**Agent rule (SHOULD):** Use tw-animate-css for entrance and micro-animations in Tailwind CSS. Provides consistent, performant CSS animations without JavaScript overhead.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use tw-animate-css plugin for entrance and micro-interaction animations

> SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS

This is a SHOULD, not a MUST, and it is scoped to Tailwind projects. The point of it is that entrance and micro-interaction animations are the ones most often hand-rolled per component — a bespoke @keyframes here, an inline style there — which is how a product ends up with six slightly different fade-ins. tw-animate-css supplies them as utilities (fade-in, slide-in-from-bottom-4, zoom-in-95) so the whole surface shares one vocabulary. It is CSS-only, which also keeps it on the right side of animations-implementation-preference.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [tw-animate-css](https://github.com/Wombosvideo/tw-animate-css)

### Animation Only When Requested

**ID:** `animations-ibelick-intentional-only`
**Agent rule (NEVER):** Add animation unless it is explicitly requested. Gratuitous animation slows perceived performance and can cause motion sickness. Animation should serve purpose.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never add animations unless explicitly requested - they can hurt UX if overused

> NEVER add animation unless it is explicitly requested

Read this as what it is: agent-facing guidance. It is a default for the party that was not asked — a coding agent handed "build me a settings panel" should not decide on its own that the panel slides. It is not a claim that animation is bad. A human designer choosing to animate has, by definition, explicitly requested it. The failure it prevents is real: animation added because it looks cool taxes every future use of a control, slows perceived performance, and is the single loudest tell of generated UI. Where motion IS wanted, animations-necessity-check gives the test it has to pass.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [The Case Against Animation](https://web.dev/articles/animations-guide)

### Never Animate Layout Properties

**ID:** `animations-ibelick-no-layout`
**Agent rule (NEVER):** Animate layout properties (width, height, top, left, margin, padding). Use transform: scale() and translate() instead. Layout triggers are expensive.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never animate width, height, top, left, or other layout-triggering properties

> NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`)

A layout property does not just move the element — it invalidates the geometry of everything the element participates in, so the browser reflows potentially hundreds of siblings on every frame, then repaints them, then composites. Use transform: scale() for size and translate() for position: they produce the same visual result with none of that work. Where the effect genuinely needs a layout-like change (a panel actually growing), measure once and fake it with a transform — FLIP — rather than animating the property; ibelick's fixing-motion-performance skill puts it as "measure once, then animate via transform or opacity".

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Avoid Layout Thrashing](https://web.dev/articles/avoid-large-complex-layouts-and-layout-thrashing)

### Minimize Paint Animations — Except on Small, Local UI

**ID:** `animations-ibelick-minimize-paint`
**Agent rule (SHOULD):** Avoid animating paint properties (background, color, box-shadow) except for small, local UI elements. Large paint areas cause jank on lower-end devices.
**Source:** @Ibelick (https://www.ui-skills.com/)

Avoid animating paint properties on large surfaces — but a color transition on a button label or an icon is fine

> SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons)

The exception is the useful half of this rule, and it is easy to lose. A paint animation forces the browser to re-fill pixels on the main thread every frame, and the cost scales with the AREA being repainted — so it is the same size budget as the surface-area rule, not a property blacklist. Repainting a full-bleed hero background or eight pulsing cards is expensive enough to visibly stall; repainting the 60x20px of a button label on hover is not, and refusing to do it buys you nothing but a worse interface. So: `transition-colors` on a button, a link, an icon — fine, and the correct thing to reach for. The same transition on a large container, or running continuously rather than once, is what the rule is aimed at. Two extensions worth knowing that upstream does not state: `box-shadow` behaves the same way (it is a paint property, and shadows are expensive to rasterize — see the example), and when you do need an apparently paint-like change on a large surface, pre-paint it as a second layer and crossfade the two with `opacity`, which is composited.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [ibelick — fixing-motion-performance SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/fixing-motion-performance/SKILL.md)
- [Simplify Paint Complexity](https://web.dev/articles/simplify-paint-complexity-and-reduce-paint-areas)

### Proper Animation Timing

**ID:** `animations-ibelick-timing`
**Agent rule (NEVER):** Exceed 200ms for interaction feedback. Use ease-out on entrance, ease-in on exit. Never introduce custom easing curves unless explicitly requested.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use ease-out for entrances and keep interaction feedback under 200ms

> SHOULD use `ease-out` on entrance. NEVER exceed `200ms` for interaction feedback.

Two separate upstream rules, quoted together because they answer the same question: how should a small interaction feel. ease-out on entrance puts the movement in the first frames — the ones the user is actually watching — and lets it settle, which is why a 200ms ease-out reads as faster than a 200ms ease-in even though the stopwatch says otherwise (animations-emil-no-ease-in makes the same case at length). The 200ms ceiling is specifically for INTERACTION FEEDBACK — a press, a hover, a toggle, the response to something the user just did — not for every animation on the page: a drawer or a modal moves a large surface and legitimately runs longer (animations-emil-duration-budget budgets 200–500ms for those). Upstream says nothing about the curve for exits; do not infer ease-in from its absence.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Material Design Motion](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs)

### Pause Offscreen Animations

**ID:** `animations-ibelick-pause-offscreen`
**Agent rule (MUST):** Pause looping animations when off-screen using IntersectionObserver. Saves CPU/battery on mobile. Resume when element enters viewport.
**Source:** @Ibelick (https://www.ui-skills.com/)

Pause looping animations when they're not visible to save battery and CPU

> MUST pause looping animations when off-screen

An off-screen loop is pure waste: it keeps the compositor awake, burns CPU and battery, and produces exactly zero pixels anyone sees. The browser does not stop it for you — a CSS animation on a scrolled-past element runs forever. ibelick's fixing-motion-performance skill names the mechanism ("use IntersectionObserver for visibility and pausing"): observe the element, and toggle `animation-play-state: paused` or stop the rAF loop when it leaves the viewport. Note the scope is LOOPING animations — a one-shot entrance that finishes off-screen costs nothing.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [ibelick — fixing-motion-performance SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/fixing-motion-performance/SKILL.md)
- [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)

### Pause, Stop, Hide Controls (WCAG 2.2.2)

**ID:** `animations-pause-stop-hide`
**Agent rule (MUST):** Auto-playing animations >5s MUST have pause/stop/hide controls; OR auto-stop after 5s. Applies to carousels, video backgrounds, infinite loops. Essential animations (loading spinners, progress) are exempt.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Auto-playing animations over 5 seconds must have pause/stop/hide controls

> Auto-playing animations >5s MUST have pause/stop/hide controls; OR auto-stop after 5s. Applies to carousels, video backgrounds, infinite loops. Essential animations (loading spinners, progress) are exempt.

WCAG 2.2.2 Level A requires that users can pause, stop, or hide moving content. This prevents distraction for users with attention disorders and reduces seizure risk. Loading indicators and progress bars are exempt as they provide essential feedback.

- [WCAG 2.2.2 Understanding](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html)
- [Digital A11y Guide](https://www.digitala11y.com/understanding-sc-2-2-2-pause-stop-hide/)

### Animation Frame Budget (60fps)

**ID:** `animations-frame-budget`
**Agent rule (SHOULD):** Animation work SHOULD complete within 16ms frame budget (60fps). Use requestAnimationFrame for JS animations. Batch layout reads then writes — never interleave them — so a frame does not thrash between reflows and repaints.
**Source:** Custom

Keep per-frame animation work under ~10ms — the textbook 16ms is not all yours

> Animation work SHOULD fit the frame budget (60fps). Use requestAnimationFrame for JS animations. Batch DOM reads then writes to avoid layout thrashing in animation loops.

At 60fps a frame is 16.67ms, and that number is quoted everywhere as "the budget". It is not your budget. The browser needs part of every frame for its own housekeeping — style, layout, paint, compositing, plus whatever else the main thread is already queued to do — so the work you can actually spend is closer to 10ms, and less on a mid-range phone. Treat ~10ms as the target and 16ms as the cliff you are already falling off. Practically: do the work in requestAnimationFrame, batch every DOM read before every DOM write (interleaving them forces a synchronous layout per iteration), write only compositor-friendly properties (transform, opacity), and move anything genuinely expensive off the main thread entirely.

- [web.dev — Rendering performance](https://web.dev/articles/rendering-performance)
- [MDN — Performance fundamentals](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Fundamentals)

### View Transitions API

**ID:** `animations-view-transitions`
**Agent rule (SHOULD):** Use View Transitions API for page/state transitions. Add `@view-transition { navigation: auto; }` for MPA. Use `view-transition-name` for morphing elements. Progressive enhancement—works without JS.
**Source:** Web Platform (https://web.dev/)

Use View Transitions for navigation-level changes — not for gestures or rapid toggles

> Use the View Transitions API for page/state transitions. Use `view-transition-name` for morphing elements. Same-document transitions are Baseline newly available; cross-document (`@view-transition { navigation: auto; }`) is still limited availability.

The View Transitions API snapshots the old DOM, lets you mutate it, and crossfades or morphs between the two states — a real fix for the "the page just popped" problem, and it degrades to an instant change where unsupported (feature-detect `document.startViewTransition`). Two guardrails. BROWSER SUPPORT: same-document transitions ship in Chromium and Safari, but cross-document navigation (`@view-transition { navigation: auto; }`) is NOT Baseline — treat it as limited availability and a progressive enhancement, never as the thing that makes the navigation work. SCOPE: a view transition cannot be interrupted or reversed once it starts. That makes it right for navigation-level changes (route change, page change, opening a detail view) and wrong for anything the user drives continuously or fires in quick succession — drag-to-reorder, rapid tab switching, a slider. Wrap those and you get a queue of uninterruptible crossfades that lag behind the input, which is exactly what animations-interruptible forbids.

- [MDN — View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)
- [Chrome — View Transitions in 2025](https://developer.chrome.com/blog/view-transitions-in-2025)

### Spring Physics for Natural Motion

**ID:** `animations-spring-physics`
**Agent rule (SHOULD):** Prefer spring-based animations for interactive elements (buttons, modals, drag). Configure mass/tension/friction instead of duration/easing for natural feel and interruptible motion.
**Source:** Custom

Prefer spring-based animations for interactive elements like buttons, modals, and drag

> Prefer spring-based animations for interactive elements (buttons, modals, drag). Configure the spring instead of duration/easing so motion carries velocity through an interruption.

A duration-and-easing tween is a script: it always takes 300ms and always follows the same curve, whatever the element was doing a moment ago. Interrupt it — flick a drawer back while it is still closing — and it restarts from wherever it is with zero velocity, which reads as a stutter. A spring is a simulation: it carries the element's current velocity into the new target, so a reversal continues the gesture instead of contradicting it. That is the reason to reach for one, not "it feels bouncier". Configure it in Motion's modern terms — `{ type: "spring", duration: 0.5, bounce: 0.2 }` — rather than hand-tuning mass/stiffness/damping, and keep bounce low (see animations-emil-subtle-bounce): a spring with zero bounce is still a spring, and still interruptible.

- [Motion — spring transitions](https://motion.dev/docs/react-transitions#spring)
- [MDN — linear() easing (approximating springs in CSS)](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function/linear)

### Motion Library + Tailwind Conflicts

**ID:** `animations-motion-tailwind-conflict`
**Agent rule (SHOULD):** When using Framer Motion/Motion with Tailwind, remove conflicting `transition-*` classes from animated elements. Let Motion handle transitions to prevent stuttery/weird motion.
**Source:** Custom

Remove Tailwind transition classes from elements animated by Framer Motion

> When using Framer Motion/Motion with Tailwind, remove conflicting `transition-*` classes from animated elements. Let Motion handle transitions to prevent stuttery/weird motion.

Tailwind's transition-* classes apply CSS transitions. When combined with Framer Motion's JS-based animations, they conflict and cause stuttering. Use Motion's transition prop instead.

- [Motion + Tailwind Guide](https://motion.dev/docs/react-tailwind)
- [Framer Motion + Tailwind 2025](https://dev.to/manukumar07/framer-motion-tailwind-the-2025-animation-stack-1801)

### Tailwind motion-safe/motion-reduce Variants

**ID:** `animations-tailwind-motion-variants`
**Agent rule (MUST):** Use Tailwind `motion-safe:` and `motion-reduce:` variants to conditionally apply animations. Default pattern: `motion-safe:animate-*` ensures animations only run when user allows motion.
**Source:** Tailwind (https://tailwindcss.com/docs)

Use Tailwind motion-safe: and motion-reduce: variants for accessible animations

> Use Tailwind `motion-safe:` and `motion-reduce:` variants to conditionally apply animations. Default pattern: `motion-safe:animate-*` ensures animations only run when user allows motion.

These variants respect the user's prefers-reduced-motion setting. motion-safe: applies styles only when motion is allowed. motion-reduce: applies alternative styles when user prefers reduced motion.

- [Tailwind Animation](https://tailwindcss.com/docs/animation)
- [Motion-Safe Animations Guide](https://dev.to/hexshift/building-fluid-motion-safe-animations-in-tailwind-css-that-respect-user-preferences-3i6e)

### No Transitions on Theme Switch

**ID:** `animations-theme-switch-no-transitions`
**Agent rule (MUST):** Suppress `transition` and `animation` on every element while flipping the theme, then restore them on the next frame — otherwise each colour-animating element ripples across the page.
**Source:** Rauno (https://interfaces.rauno.me/)

Switching themes should not trigger transitions and animations on elements

> Switching themes should not trigger transitions and animations on elements.

When toggling between light and dark mode, elements with CSS transitions will visibly animate their color changes, creating a distracting ripple effect across the page. Temporarily disable transitions during theme switches for an instant, clean change.

```tsx
document.documentElement.classList.add("theme-switching");
setTheme(next);
requestAnimationFrame(() => document.documentElement.classList.remove("theme-switching"));
/* .theme-switching *, .theme-switching *::before, .theme-switching *::after { transition: none !important } */
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [next-themes](https://github.com/pacocoursey/next-themes)

### Proportional Animation Values

**ID:** `animations-proportional-values`
**Agent rule (SHOULD):** Keep animation values proportional to the element: dialogs scale from ~0.95–0.8 (never 0), buttons compress to ~0.96 on press (never 0.8).
**Source:** Rauno (https://interfaces.rauno.me/)

Animation values should be proportional to the trigger size — don't scale from 0, use subtle values

> Animation values should be proportional to the trigger size: Don't animate dialog scale in from 0 → 1, fade opacity and scale from ~0.8. Don't scale buttons on press from 1 → 0.8, but ~0.96, ~0.9, or so.

Exaggerated animations feel cartoonish and disproportionate. A dialog appearing should scale from 0.95, not 0. A button press should compress to 0.97, not 0.5. Match the animation magnitude to the element's visual size and the interaction's importance.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Smooth Scroll for Anchors

**ID:** `animations-smooth-scroll-anchors`
**Agent rule (SHOULD):** Use `scroll-behavior: smooth` for in-page anchors, with `scroll-margin-top` on targets so headings clear any sticky header.
**Source:** Rauno (https://interfaces.rauno.me/)

Use scroll-behavior: smooth for navigating to in-page anchors with appropriate offset

> Use scroll-behavior: smooth for navigating to in-page anchors, with an appropriate offset.

Instant jumps to anchor links are disorienting — users lose context of where they are on the page. Smooth scrolling maintains spatial awareness and creates a more polished navigation experience.

```tsx
html { scroll-behavior: smooth; }
:target { scroll-margin-top: 5rem; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)

### Match Motion to Frequency

**ID:** `animations-emil-frequency`
**Agent rule (SHOULD):** Match motion to how often an action happens. Keyboard-initiated and 100+/day actions get no animation; reserve delight for rare or first-time moments.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Match motion to how often an action is seen — frequent and keyboard-initiated actions get no animation

> Match motion to how often it's seen. Keyboard-initiated and 100+/day actions get no animation.

Animation that delights during a first-run onboarding becomes friction on an action performed hundreds of times a day. Give high-frequency and keyboard-driven actions instant feedback; reserve motion for rare or first-time moments.

- [Emil Kowalski — review-animations](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)

### Asymmetric Enter and Exit

**ID:** `animations-emil-asymmetric`
**Agent rule (SHOULD):** Use asymmetric timing: deliberate user actions animate slower, system responses and exits snap. Symmetric enter/exit timing makes dismissals feel sluggish.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Deliberate actions animate slower; system responses and exits snap

> Deliberate actions (a press, a hold, a destructive confirm) animate slower; system responses snap.

Symmetric timing makes dismissals feel sluggish. Let user-initiated, deliberate motion take its time, and let the system snap back quickly so the interface always feels responsive.

- [Emil Kowalski — review-animations](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)

### Stagger Group Entrances

**ID:** `animations-emil-stagger`
**Agent rule (SHOULD):** Stagger entrance animations for groups of items by 30–80ms. A whole list animating at once reads as a single flash.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Entrance animations for a group of items should stagger 30–80ms, not fire all at once

> Entrance animations for groups without 30–80ms stagger is a finding.

When a whole list appears at once, the motion reads as a single flash. A small 30–80ms stagger guides the eye down the list and makes the group feel orchestrated rather than abrupt.

- [Emil Kowalski — review-animations](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)

### Never ease-in on UI

**ID:** `animations-emil-no-ease-in`
**Agent rule (NEVER):** Reach for `ease-in` on UI motion: it barely moves during the first ~100ms the user is watching, so a 200ms `ease-in` reads slower than a 200ms `ease-out`. Default both entrances and exits to `ease-out`; `ease-in-out` for on-screen morphs, `ease` for hover/color, `linear` for constant motion. (This is the strict Emil position; other sources here allow `ease-in` on exits — pick one stance per product and apply it consistently.)
**Source:** Emil Kowalski (https://emilkowalski.com/)

Default to ease-out for enters and exits — ease-in stalls the frames the user is actually watching

> Never `ease-in` on UI. It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.

Perceived speed is decided in the first ~100ms of a transition. ease-in spends those frames barely moving, so a 200ms ease-in reads as slower than a 200ms ease-out even though the stopwatch disagrees. Emil's decision order: enter/exit → ease-out, on-screen morph → ease-in-out, hover/color → ease, constant motion → linear. Note that this is a real disagreement in the field — other sources in this corpus (see "Easing" and "Timing") permit ease-in specifically for exits, on the argument that a departing element may accelerate away; the value of holding both is seeing the tradeoff illustrated rather than asserted.

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — easing-function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function)

### Use Strong Custom Easing Curves

**ID:** `animations-emil-strong-easing`
**Agent rule (SHOULD):** Replace the weak built-in easing keywords with strong custom curves, defined once as tokens rather than hand-rolled per component.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Replace the built-in easing keywords with a strong cubic-bezier for any motion meant to feel deliberate

> Built-in CSS easings are too weak. Use strong custom curves: `--ease-out: cubic-bezier(0.23, 1, 0.32, 1);` `--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);` `--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);`

The keyword `ease-out` is cubic-bezier(0, 0, 0.58, 1) — a shallow curve that, over any real distance, reads as near-linear with a mushy stop. cubic-bezier(0.23, 1, 0.32, 1) reaches roughly 80% of the distance in the first third of the duration and then decelerates, which is what "responsive but composed" looks like. Define the curves once as tokens (ease-out for UI, ease-in-out for on-screen movement, the iOS-like 0.32/0.72/0/1 for drawers) rather than hand-rolling a bezier per component. DIRECT CONFLICT, deliberately kept: ibelick's baseline-ui states the opposite — "NEVER introduce custom easing curves unless explicitly requested". Both are right for their reader, and the axis is DEFAULTS vs MASTERY. ibelick is writing for an agent, where an unprompted cubic-bezier is a guess: a model that invents curves per component produces exactly the incoherent motion that animations-emil-motion-cohesion warns about, so the conservative default — reach for the keyword, do not improvise — is correct for the party that was not asked. Emil is writing for a human tuning motion on purpose, where the keyword is the ceiling you eventually hit: `ease-out` really is cubic-bezier(0, 0, 0.58, 1), and no amount of duration tuning will make it feel composed. So: an agent should not invent a curve unprompted; a designer who has decided the motion matters should reach for a real one — and then ship it as a token, which is what makes it a request rather than an improvisation.

```tsx
:root {
  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
}
```

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [easings.co — curve reference](https://easings.co/)
- [MDN — easing-function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function)

### Keep UI Animations Under 300ms

**ID:** `animations-emil-duration-budget`
**Agent rule (MUST):** Keep UI animations under 300ms, budgeted per element: press feedback 100–160ms, tooltip/small popover 125–200ms, dropdown/select 150–250ms, modal/drawer 200–500ms (the only type allowed past the 300ms ceiling). Marketing and explanatory motion is exempt — it is content, not interface.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Budget duration per element type and keep every UI animation under the 300ms ceiling

> Rule: UI animations stay under 300ms. Button press feedback 100–160ms. Tooltips, small popovers 125–200ms. Dropdowns, selects 150–250ms. Modals, drawers 200–500ms. A 180ms dropdown feels more responsive than a 400ms one.

Duration is the single easiest thing to get wrong, because a slow animation looks great in isolation and feels terrible on the hundredth use. Hold a per-element budget: press 100–160ms, tooltip 125–200ms, dropdown 150–250ms, modal or drawer 200–500ms (the one type allowed past the 300ms ceiling, because it moves a large surface). Marketing and explanatory motion is exempt — it is content, not interface.

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [animations.dev](https://animations.dev/)

### Transitions Over Keyframes for Retriggered Motion

**ID:** `animations-emil-transitions-over-keyframes`
**Agent rule (SHOULD):** Drive rapidly-retriggered motion (toasts, toggles) with CSS `transition` or a spring, not `@keyframes` — a transition retargets from the element's current value, while a keyframe animation restarts from its `from` and visibly teleports.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Drive rapidly-retriggered motion with CSS transitions, not keyframes, so it retargets instead of restarting

> CSS transitions can be interrupted and retargeted mid-animation; keyframes restart from zero. For anything triggered rapidly (toasts being added, toggles), transitions are smoother.

A transition interpolates from the element's current computed value, so interrupting it mid-flight simply re-aims at the new target from wherever the element is. A keyframe animation is absolute: it always plays its declared `from` → `to`, so retriggering it teleports the element back to the start before it moves again. Spam-click a toggle and the difference is unmistakable. Springs share the transition property here — they carry velocity through an interruption — which is why they suit reversible gestures.

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — Using CSS transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Transitions/Using)
- [MDN — Using CSS animations](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Animations/Using)

### Use @starting-style for Entry Animations

**ID:** `animations-emil-starting-style`
**Agent rule (SHOULD):** Animate first-render entrances with `@starting-style` instead of a `useEffect` mounted-flag plus double `requestAnimationFrame` — it degrades to an instant appearance where unsupported.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Animate elements in on first render with @starting-style instead of a JS mounted-flag hack

> Use `@starting-style` for entry without JS. Legacy fallback: `useEffect(() => setMounted(true), [])` + `data-mounted` attribute.

A CSS transition needs a previous value to interpolate from, and a freshly-inserted element has none — so declaring a transition alone makes the element pop in. `@starting-style` supplies the "before it existed" style, letting the browser animate the very first frame. That removes the classic React workaround (mount flag + double requestAnimationFrame), which costs an extra render and produces intermittent "sometimes it does not animate" bugs when the browser paints before the flag flips. Where unsupported it degrades to an instant appearance.

```tsx
.popover { opacity: 1; transition: opacity 200ms var(--ease-out); }
@starting-style { .popover { opacity: 0; } }
```

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — @starting-style](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@starting-style)

### Mask Imperfect Crossfades with Blur

**ID:** `animations-emil-blur-crossfade`
**Agent rule (SHOULD):** When a crossfade still reads as a ghosted double exposure, add a small transition-scoped `filter: blur(2px)` (2–4px, single element, only for the duration of the transition, always < 20px) so the two states fuse into one morph. This is the narrow carve-out from "never animate blur", which targets large, long-lived, or continuously-animating blurs — stay especially conservative in Safari.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Add a small blur to a crossfade so two overlapping states read as one transformation, not a double image

> When a crossfade shows two overlapping states despite tuning easing/duration, add subtle `filter: blur(2px)` during the transition to blend them into one perceived transformation. Keep blur < 20px (heavy blur is expensive, especially Safari).

In a straight opacity crossfade both layers sit near 50% at the midpoint and stay separately legible, so the user perceives a ghosted double exposure rather than a change. A 2px blur on the outgoing layer destroys its legibility exactly where the overlap happens, and the eye fuses the two into a single morph. Note the tension with the blanket "never animate blur" performance rule: that rule targets large, long-lived, or continuously-animating blurs, which force expensive re-rasterization. A small (2–4px), short, transition-scoped blur on a single element is the deliberate carve-out — stay well under 20px, and be especially conservative in Safari.

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — filter](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/filter)

### Keep Spring Bounce Subtle

**ID:** `animations-emil-subtle-bounce`
**Agent rule (SHOULD):** Keep spring bounce within 0.1–0.3 (`{ type: "spring", duration: 0.5, bounce: 0.2 }`) and reserve any bounce for drag-to-dismiss and playful interactions — everyday menus, dropdowns and modals are usually better with none.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Keep spring bounce between 0.1 and 0.3, and reserve real bounce for drag-to-dismiss and playful moments

> Keep bounce subtle (0.1–0.3); avoid bounce in most UI — reserve for drag-to-dismiss and playful interactions.

Bounce is a claim that the element has mass and momentum. That claim is true for something you flung with your finger, and false for a settings popover that simply appeared. Above roughly 0.3 the overshoot becomes a visible wobble that reads as cartoonish on utility UI and, on a control opened dozens of times a day, as broken. In Apple-style spring terms: `{ type: "spring", duration: 0.5, bounce: 0.2 }`. Everyday menus, dropdowns and modals are usually better with no bounce at all.

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [animations.dev](https://animations.dev/)

### Motion Cohesion and Personality

**ID:** `animations-emil-motion-cohesion`
**Agent rule (SHOULD):** Define duration and easing once as motion tokens and spend them everywhere, matching the curve to the product's personality (crisp and bounce-free for a dashboard, slower and bouncier for a playful app) rather than letting each component be animated to whoever built it's taste.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Match motion to the component's personality and to the rest of the product — one shared motion language, not per-component taste

> Match motion to the component's personality: playful can be bouncier; a professional dashboard should be crisp and fast. Sonner feels right partly because easing, duration, design, and even the name are in harmony.

There is no universally correct curve — there is a curve that is correct for this product. A monitoring dashboard wants short, ease-out, bounce-free motion that gets out of the way; a playful consumer app can legitimately be slower and bouncier. What is never right is a surface where each element was animated by whoever happened to build it: one row bouncing, one crawling linearly, one snapping. Each may be defensible alone, but together they make the product feel assembled rather than designed. Define motion tokens (duration + easing) once and spend them everywhere.

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [emilkowalski.com](https://emilkowalski.com/)

### Set transform-box on Animated SVG

**ID:** `animations-svg-transform-box`
**Agent rule (MUST):** Transform animated SVG shapes on a `<g>` wrapper with `transform-box: fill-box` and `transform-origin: center` — the CSS default `view-box` resolves the origin against the `viewBox`, so an off-centre shape orbits the canvas instead of spinning in place.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Wrap animated SVG shapes in a <g> and set transform-box: fill-box with transform-origin: center

> SVG animation: apply transforms to a <g> wrapper with transform-box: fill-box and transform-origin: center; otherwise the origin resolves against the SVG viewBox.

CSS transforms on SVG elements default to `transform-box: view-box`, so `transform-origin: center` resolves to the centre of the SVG viewport — not the centre of the shape. Rotate or scale an icon that sits anywhere off-centre in its viewBox and it orbits the canvas instead of spinning in place. Setting `transform-box: fill-box` re-points the origin at the element's own bounding box, which is almost always what you meant. Put it on a <g> wrapper so the whole shape shares one origin and the transform does not have to be repeated per path.

```tsx
g.spinner { transform-box: fill-box; transform-origin: center; animation: spin 1s linear infinite; }
```

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN — transform-box](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/transform-box)
- [MDN — <g>](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/g)

### No Bounce or Elastic Easing

**ID:** `animations-impeccable-no-bounce-easing`
**Agent rule (NEVER):** Let a UI element overshoot its final position: no `animate-bounce`, no animation named `bounce|elastic|wobble|jiggle|spring`, and no `cubic-bezier()` whose y1 or y2 falls outside `[-0.1, 1.1]`. Ease out with exponential curves (ease-out-quart / quint / expo).
**Source:** impeccable (https://impeccable.style/)

Ease out with exponential curves and never let a UI element overshoot its final position

> Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.

The detector flags any animation-name matching bounce|elastic|wobble|jiggle|spring, Tailwind's animate-bounce, and — the precise part — any cubic-bezier() whose y1 or y2 falls outside the range [-0.1, 1.1], because a control point past the 0–1 band is exactly what overshoot is. Real objects decelerate into a stop; they do not sail past their destination and spring back. Overshoot on a modal or a toast reads as dated and, on anything a user opens dozens of times a day, as broken. Note this is not a duplicate of "Easing Fits Subject", which only asks that a curve match its subject and never bans overshoot — this principle draws the hard line.

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [MDN — easing-function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function)

### Never scale(0)

**ID:** `animations-emil-no-scale-zero`
**Agent rule (NEVER):** Enter from `scale(0)` — nothing in the real world appears from a point. Start from `scale(0.9–0.97)` (0.96 is a safe popover/menu default) plus `opacity: 0`. Equally never enter on opacity alone: without a transform the element materializes instead of arriving.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Enter from scale(0.9–0.97) with opacity, never from scale(0) and never from opacity alone

> Never `scale(0)`. Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.

scale(0) claims the element had no size a moment ago — it grows out of a mathematical point, which no physical object does. Start somewhere between 0.9 and 0.97 (0.96 is a safe default for popovers and menus) and let opacity carry the rest of the appearance. The opposite failure is just as common: a pure opacity fade with no transform at all, which gives the element no body and no origin, so it materializes rather than arrives. This is about HOW SMALL the motion starts; animations-correct-transform-origin is about WHERE it starts — a popover can have a perfect trigger-anchored origin and still be wrong because it scales up from 0.

```tsx
@keyframes enter { from { opacity: 0; transform: scale(0.96); } to { opacity: 1; transform: scale(1); } }
```

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — scale](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/scale)
- [MDN — transform-origin](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/transform-origin)

### clip-path: inset() as an Animation Primitive

**ID:** `animations-clip-path-reveal`
**Agent rule (SHOULD):** Reach for `clip-path: inset(t r b l)` for reveals, wipes, hold-to-delete overlays, seamless tab-color swaps, and comparison sliders — each value eats in from that side, the element keeps its box, so nothing below it moves and no layout is recalculated (unlike animating `height`).
**Source:** Emil Kowalski (https://emilkowalski.com/)

Reach for clip-path: inset() to reveal, wipe, and mask without touching layout

> `clip-path: inset(t r b l)` is a powerful animation tool: each value eats in from that side. Uses: reveal-on-scroll (`inset(0 0 100% 0)` → `inset(0 0 0 0)`), hold-to-delete overlay, seamless tab color transitions (duplicate + clip the active copy), comparison sliders.

Read inset(top right bottom left) as "how far the clip eats in from each side": inset(0 0 100% 0) removes the element entirely from the bottom up, and animating to inset(0 0 0 0) wipes it back open. The element keeps its box the whole time, so unlike a height animation nothing below it moves and no layout is recalculated. The same primitive gives you a hold-to-delete overlay (fill left-to-right while the button is held), a seamless tab color change (duplicate the label and clip the active copy, so there is no crossfade), and a comparison slider. A hold-to-delete overlay is also the canonical place to spend asymmetric timing — clip-path 2s linear on press, 200ms ease-out on release; see animations-emil-asymmetric.

```tsx
.reveal { clip-path: inset(0 0 100% 0); transition: clip-path 400ms ease-out; }
.reveal.is-visible { clip-path: inset(0 0 0 0); }
```

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — clip-path](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/clip-path)
- [MDN — basic-shape (inset)](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/basic-shape)

### Translate by Percentage, Not Pixels

**ID:** `animations-percentage-translate`
**Agent rule (SHOULD):** Park off-screen elements with translate percentages, not hardcoded px: `translateY(100%)` resolves against the element's own height, so it stays correct when a toast wraps or a drawer gains a row. Add edge gaps with `calc(100% + 12px)` rather than a magic number.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Offset off-screen elements with translate percentages so the value stays correct at any size

> `translate` percentages are relative to the element's own size — `translateY(100%)` moves by the element's height regardless of dimensions (how Sonner/Vaul position toasts/drawers). Prefer over hardcoded px.

A translate percentage resolves against the element itself, not its parent: translateY(100%) always moves it by exactly its own height, and translateX(-100%) by its own width. That is why a hardcoded translateY(300px) is a latent bug — it was measured against the content that existed the day it was written, and the moment a toast wraps to a second line or a drawer gains a row, the offset is wrong. Too small and the "hidden" element peeks into view; too large and it flies in from further away than it should, stretching the perceived duration. Percentages are self-correcting, which is exactly how Sonner parks toasts and Vaul parks drawers. Add the gap to the edge with calc(100% + 12px) rather than baking it into a magic number.

```tsx
.toast { transform: translateY(calc(100% + 12px)); } /* not translateY(300px) */
.toast[data-open] { transform: translateY(0); }
```

- [Emil Kowalski — review-animations STANDARDS](https://github.com/emilkowalski/skills/tree/main/skills/review-animations)
- [MDN — translateY()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/transform-function/translateY)
- [Sonner](https://github.com/emilkowalski/sonner)
- [Vaul](https://github.com/emilkowalski/vaul)

### Input-driven

**ID:** `animations-input-driven`
**Agent rule (NEVER):** Autoplay motion just because a component mounted — the only thing that happened is that the user arrived. Animate in response to an input: hover, press, drag, scroll-into-view, or a request completing. Autoplay loops also keep the compositor awake and become a WCAG 2.2.2 problem past 5s.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Avoid autoplay — animate in response to a user action, not on arrival

> Input-driven. Avoid autoplay; animate in response to actions.

An animation that plays because the component mounted is asserting that something happened, when the only thing that happened is that the user arrived. Motion should be the answer to an input — a hover, a press, a drag, a scroll bringing the element into view, a request completing. Autoplay loops are the worst offender: they never stop competing for attention, they keep the compositor awake and drain battery, and past 5 seconds they also become a WCAG 2.2.2 problem. This is not the same rule as animations-interruptible (which is about a running animation yielding to input) or animations-pause-stop-hide (which accepts autoplay and demands controls for it). This one asks the prior question: should it have started by itself at all?

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [NN/g — Animation for Attention and Comprehension](https://www.nngroup.com/articles/animation-usability/)
- [MDN — Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)

### Three Motion Layers

**ID:** `animations-lottie-motion-layers`
**Agent rule (SHOULD):** Build a hero moment in three layers — primary (the action the eye follows), secondary (shadow trailing ~50ms, contents arriving ~100ms after the card lands), ambient (background drift) — instead of pushing one flat sprite. SCOPE: three layers is three times the motion, so spend it only on rare first-run/hero surfaces (empty-state illustration, onboarding card, marketing hero). On anything repeated — a row rendered 400 times, a menu opened fifty times a day — `animations-necessity-check` and `animations-emil-frequency` win and the correct layer count is one, or zero.
**Source:** LottieFiles (https://github.com/lottiefiles/motion-design-skill)

Build a hero moment in three layers — primary, secondary, ambient — instead of moving one flat sprite

> Three motion layers (flat animation = missing layers): Primary: Main action the viewer follows. Secondary: Supporting richness (shadows, icons shifting). Ambient: Background life (gradients, subtle pulses).

A card that only translates and fades is one layer: the shadow rides along at a fixed depth, the contents are fully legible before the card has landed, and nothing lives behind it, so the eye reads a single flat sprite being pushed into place. Adding the missing layers is cheap — the shadow becomes its own opacity-animated element that trails the card by ~50ms so it settles onto the surface, the row content arrives ~100ms after the card lands, and a few pixels of background drift keep the scene from being dead. HONEST TENSION: this rule pulls directly against animations-necessity-check and animations-emil-frequency. Three layers is three times the motion, and motion you have to justify. Spend it on the rare first-run or hero moment — an empty-state illustration, an onboarding card, a marketing surface — and never on a table row that renders 400 times or a menu opened fifty times a day, where the correct number of layers is one, or zero. This entry is kept alongside the necessity rule the same way animations-emil-no-ease-in is kept alongside animations-easing: the disagreement is the point, and you should read both before choosing.

- [LottieFiles — motion-design skill](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/SKILL.md)
- [LottieFiles — quality checklist](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/reference/quality-checklist.md)
- [MDN — box-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/box-shadow)

### Cap Simultaneous Motion

**ID:** `animations-lottie-concurrency-cap`
**Agent rule (SHOULD):** With 3+ elements, keep at most ~1/3 in active motion at any instant so the eye keeps an anchor: land a hero element first, then bring the rest in waves. This is NOT stagger — stagger sets when items START, this caps how many are MOVING. A 30ms stagger over 9 cards with a 220ms duration still has all 9 in flight; you need both rules.
**Source:** LottieFiles (https://github.com/lottiefiles/motion-design-skill)

Keep no more than a third of a group in active motion at any instant so the eye keeps an anchor

> 1/3 Rule (elements): With 3+ elements, no more than 1/3 in active motion simultaneously.

Nine cards that all scale, fade and slide on mount give the eye nothing to hold on to: the grid is perceived as a burst of noise that resolves, not as a reveal you can follow. Land a hero element first so there is an anchor, then bring the rest in waves — with a 220ms per-card duration and waves at 0/200/340/480ms, at most 3 of 9 are ever in flight and the cascade still finishes inside the 500ms stagger budget. DISTINCT FROM animations-emil-stagger, which prescribes a per-item DELAY (30–80ms) and says nothing about how many items overlap: a 30ms stagger across 9 cards with a 220ms duration still has all 9 moving at the same time, because item 9 starts at 240ms while item 1 is still animating. Stagger controls when things start; the 1/3 rule controls how many are moving at once. You need both, and satisfying one does not satisfy the other.

- [LottieFiles — motion-design skill](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/SKILL.md)
- [LottieFiles — quality checklist](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/reference/quality-checklist.md)
- [MDN — transition-delay](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/transition-delay)

### Cap the Total Stagger

**ID:** `animations-lottie-stagger-budget`
**Agent rule (MUST):** Treat a cascade as a TOTAL budget, not a per-item constant: keep total stagger under 500ms (micro 20–40ms/item under 200ms; standard 50–100ms under 400ms; dramatic 100–200ms under 600ms for theatre only). Take the per-item value from `animations-emil-stagger` (30–80ms), take the CEILING from here — and on long lists the ceiling wins, because `i * 60ms` on 30 rows delays the last row 1740ms and pops content in below the scroll position. Clamp, or stagger only the rows in view.
**Source:** LottieFiles (https://github.com/lottiefiles/motion-design-skill)

Clamp a cascade to a total budget under 500ms instead of multiplying a per-item delay by the list length

> Critical: Total stagger must stay under 500ms.

A stagger is a budget, not a per-item constant. The budgets: micro cascade 20–40ms per item, total under 200ms; standard 50–100ms, under 400ms; dramatic 100–200ms, under 600ms — and the hard ceiling is 500ms of total stagger for anything that is interface rather than theatre. Write animationDelay: i * 60ms on a 30-row list and the last row does not begin moving until 1740ms after the first: the user has already scrolled past it, so the animation is still introducing content they have finished reading, and rows visibly pop in beneath the scroll position. Fix it by clamping — delay = Math.min(i * step, MAX_TOTAL) — or by only staggering the rows currently in view. COLLISION: animations-emil-stagger prescribes 30–80ms per item and states no cap, which ACTIVELY CAUSES this bug the moment the list is long. At 60ms per item the rule is safe up to about 8 rows and broken by 30. Take the per-item value from Emil, take the ceiling from here, and let the ceiling win.

```tsx
const MAX_TOTAL = 400;
const delay = Math.min(i * 60, MAX_TOTAL);
```

- [LottieFiles — motion-design skill](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/SKILL.md)
- [LottieFiles — quality checklist](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/reference/quality-checklist.md)
- [MDN — animation-delay](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation-delay)

### Scale Duration With Travel Distance

**ID:** `animations-lottie-distance-duration`
**Agent rule (SHOULD):** Derive duration from travel distance, sublinearly — 100px = base, 200px = 1.3x, 400px = 1.6x — then clamp to a ~140ms floor and ~400ms ceiling. One `--duration-md` cannot serve an 8px tooltip nudge and a full-height sheet. This is a third axis, not a duplicate: `animations-proportional-values` scales transform AMPLITUDE, `animations-emil-duration-budget` assigns duration by element TYPE, and distance is what reconciles them (it is why drawers are the one type allowed past 300ms — a drawer is not special, it is far).
**Source:** LottieFiles (https://github.com/lottiefiles/motion-design-skill)

Derive duration from how far the element actually travels, sublinearly — one token cannot serve 8px and 200px

> Distance scales duration: 100px = base. 200px = 1.3x. 400px = 1.6x.

Spend a single --duration-md: 200ms on both an 8px tooltip nudge and a full-height bottom sheet and the same number is wrong in both directions at once: the tooltip crawls the last few pixels of a journey the eye finished instantly, and the sheet covers 200px faster than the eye can track, so it reads as a teleport. Derive it instead: factor = 1 + 0.3 * log2(px / 100), giving 100px = 1×, 200px = 1.3×, 400px = 1.6× — sublinear, because doubling the distance must not double the duration or long journeys feel like wading — then clamp to a floor (~140ms) and a ceiling (~400ms). On a 250ms base that puts the sheet at ~325ms and the tooltip at 140ms. THIS IS A THIRD AXIS, not a duplicate: animations-proportional-values (Rauno) scales the AMPLITUDE of a transform to the trigger SIZE — how far to move — and animations-emil-duration-budget assigns duration by element TYPE (press 100–160ms, tooltip 125–200ms, dropdown 150–250ms, drawer 200–500ms). Distance is what reconciles them, and it is precisely why that budget lists drawers as the one type allowed past the 300ms ceiling: a drawer is not special, it is simply far.

```tsx
const factor = 1 + 0.3 * Math.log2(px / 100); // 100px=1x, 200px=1.3x, 400px=1.6x
const duration = Math.min(400, Math.max(140, 250 * factor));
```

- [LottieFiles — motion-design skill](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/SKILL.md)
- [NN/g — Executing UX Animations: Duration and Motion](https://www.nngroup.com/articles/animation-duration/)
- [MDN — Using CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties)

### Don't Signal State With Opacity Alone

**ID:** `animations-lottie-never-opacity-only`
**Agent rule (NEVER):** Signal an important state change with opacity alone — peripheral vision reads movement, not luminance, so a "Saved" pill that fades in place off-axis is frequently never seen. Pair the fade with position or scale (a 6px rise is enough). Motion is the REINFORCEMENT channel only: the state still needs `role="status"` / `aria-live="polite"`, and since the transform is dropped under `prefers-reduced-motion`, the opacity change must remain sufficient on its own.
**Source:** LottieFiles (https://github.com/lottiefiles/motion-design-skill)

Pair any important state change with position or scale — a pure fade is nearly invisible off-axis

> Never opacity-only for important state changes — combine with position or scale.

Peripheral vision is poor at absolute luminance and very good at movement. A "Saved" confirmation that fades 0 → 1 in place, in a corner the user is not looking at because they are still looking at the button they just pressed, frequently never registers at all — so they press Save again. Add a 6px rise and the same pill is caught off-axis without a glance. ACCESSIBILITY: motion is the REINFORCEMENT channel here, never the accessible one. The confirmation still needs to be a real live region (role="status" / aria-live="polite"), because a screen-reader user gets nothing from either the fade or the rise, and WCAG 1.4.1 has the same shape — no important state may depend on a single perceptual channel. And under prefers-reduced-motion the transform is dropped, which means the opacity change alone must remain sufficient on its own: the rise makes a good signal better, it is not allowed to be the only thing carrying the state.

- [LottieFiles — motion-design skill](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/SKILL.md)
- [MDN — ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions)
- [WCAG 2.2 — Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html)

### Disney Principles Are For Character Motion, Not For Chrome

**ID:** `animations-lottie-disney-scope`
**Agent rule (SHOULD):** Ask "character or control" before reaching for Disney motion. Anticipation, squash-and-stretch, follow-through and overshoot belong to CHARACTERS — a mascot, an illustration, an empty-state figure, a confetti burst, a once-per-session celebration — where implied mass and personality are the point. They do NOT belong to CHROME: a dropdown, toast, menu or button is a control the user operates, and overshoot there reads as dated (that is `animations-impeccable-no-bounce-easing`, and it is not in conflict — it describes a different object). LottieFiles scopes it the same way: skip anticipation for micro-feedback (<150ms), skip squash-and-stretch for premium/luxury, and its exaggeration budget is 15-25% Playful but 0-5% Corporate and 0% Premium. Controls: ease-out, no overshoot.
**Source:** LottieFiles (https://github.com/lottiefiles/motion-design-skill)

Anticipation, squash-and-stretch and overshoot belong to a mascot, an illustration or a celebration — not to a dropdown, a toast or a menu

> Anticipation: Small motion opposite to main direction before action. Duration: 100-200ms, magnitude: 10-20% of main action. Skip for micro-feedback (<150ms). Squash and Stretch: Skip for premium/luxury brands. Exaggeration: Playful 15-25% | Energetic 20-30% | Corporate 0-5% | Premium 0%.

This is a REAL and deliberately preserved tension in the corpus, and the resolution is scope, not a winner. animations-impeccable-no-bounce-easing bans overshoot outright — any cubic-bezier whose control points leave the [-0.1, 1.1] band — and it is right about the surface it is talking about: a dropdown that wobbles, a toast that springs past its mark, a menu that squashes on open reads as dated on first sight and as broken by the fiftieth, because those elements are chrome the user operates, not characters the user watches. LottieFiles is not contradicting that; it is talking about a different object. Disney's vocabulary was built for CHARACTERS — things with implied mass, personality and intent — and it survives on the web wherever that is still true: a mascot, an illustration, an empty-state figure, a confetti burst, a success celebration, an onboarding moment seen once. And LottieFiles scopes it itself, which is the tell: squash-and-stretch says "Skip for premium/luxury brands", anticipation says "Skip for micro-feedback (<150ms)" — which is nearly every button and hover in a product — and its own exaggeration budget drops to 0-5% for Corporate and 0% for Premium, i.e. to exactly the flat, no-overshoot motion the impeccable rule demands. So the operative question is never "is bounce allowed" but "is this thing a character or a control". Controls: ease-out, no overshoot, done. Characters, once per session: anticipate, overshoot, follow through — that is where the charm lives, and refusing it there buys you nothing. animations-emil-subtle-bounce marks the one genuine middle ground (bounce 0.1–0.3, reserved for drag-to-dismiss, where the user's own thrown gesture has already established momentum, so the mass is real rather than asserted).

- [LottieFiles — Disney principles, UI adapted](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/director/disney-principles.md)
- [LottieFiles — motion personality archetypes](https://github.com/lottiefiles/motion-design-skill/blob/main/skills/motion-design/director/motion-personality.md)
- [MDN — easing-function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function)

### Name Every Timing Value

**ID:** `animations-named-timing-constants`
**Agent rule (SHOULD):** Hoist every delay, duration and easing into one named block and drive a multi-stage sequence with a single integer stage, not scattered magic numbers and boolean flags (`isCardVisible` / `isHeadingVisible` / `areRowsVisible`) — otherwise retuning the tempo means hunting five call sites and the heading silently starts arriving after the rows it introduces.
**Source:** Custom

Hoist every delay, duration and easing into one named block and drive the sequence with a single integer

> Every value that affects timing or appearance should be a named constant, trivially adjustable. A single integer state drives the entire sequence; no scattered boolean flags.

From Josh Puckett's Interface Craft. A multi-stage reveal wired as delay: 0.3 here, delay: 0.9 there, stagger: 0.2 inline in the JSX, sequenced by isCardVisible / isHeadingVisible / areRowsVisible, has no readable choreography: the order exists only in the author's head, and retuning it means hunting magic numbers across five call sites. The failure is concrete — change the tempo, miss one of those sites, and the heading now arrives after the rows it was supposed to introduce, a bug that survives code review precisely because no number is named. The fix is two moves: hoist the values into one block (const TIMING = { cardAppear: 300, heading: 900, rows: 1500 }) and collapse the flags into one integer stage, so the JSX reads stage >= 2 ? ... : ... and the sequence is legible top to bottom. ADJACENT TO BUT DISTINCT FROM animations-emil-motion-cohesion: cohesion is about one shared motion vocabulary ACROSS the product, so that a dropdown here and a toast there feel like the same hand made them. This is about one sequence, inside one component, being readable and tunable at all. You can be perfectly cohesive and still have an unmaintainable timeline; and a single well-named TIMING block does not, by itself, make the product coherent.

```tsx
const TIMING = { cardAppear: 300, heading: 900, rows: 1500 } as const;
// then: stage >= 2 ? ... : ...
```

- [Interface Craft — Josh Puckett](https://interfacecraft.dev/)
- [joshpuckett.me](https://joshpuckett.me/)
- [MDN — Using CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties)

### Never Drive Animation From Scroll Events

**ID:** `animations-no-scroll-event-animation`
**Agent rule (NEVER):** Drive animation from `scroll` events, `scrollY`, or `scrollTop`. Scroll is composited off the main thread, so a scroll listener is a notification that scrolling ALREADY happened — the animation is permanently one frame late and freezes outright during any long task while the page keeps scrolling under it. Throttling or rAF-wrapping the handler only makes the lag cheaper; move the timeline off the main thread instead (`animations-scroll-driven-css`).
**Source:** @Ibelick (https://www.ui-skills.com/)

A scroll listener that writes styles always renders one frame late and couples the effect to main-thread health

> do not drive animation from scrollTop, scrollY, or scroll events

Scroll is composited off the main thread; a `scroll` listener is a notification that scrolling already happened. By the time the handler reads `scrollY` and writes a style, the browser has painted that scroll position — so the animation is permanently one frame behind, and it drifts further under load. Worse, the effect now inherits the health of the main thread: any long task (hydration, a JSON parse, a third-party script) freezes the animation while the page keeps scrolling underneath it. ibelick states the same ban twice, once as a never-pattern and once under scroll: "do not poll scroll position for animation". The fix is not to throttle or rAF-wrap the handler — that just makes the lag cheaper. It is to move the timeline itself off the main thread (see animations-scroll-driven-css).

- [ibelick — fixing-motion-performance SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-motion-performance/SKILL.md)
- [MDN — CSS scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_scroll-driven_animations)

### Prefer Scroll and View Timelines

**ID:** `animations-scroll-driven-css`
**Agent rule (SHOULD):** Use a CSS Scroll or View Timeline (`animation-timeline: view()`/`scroll()`) for scroll-linked motion — the compositor advances it, so it stays locked to the scrollbar even while the main thread is busy. This is still input-driven motion (`animations-input-driven`): the scroll IS the input. IntersectionObserver is a one-shot trigger, not a timeline — it cannot scrub, ignores scroll speed, and snaps on scroll-up; keep it for visibility and pausing. Chromium + Firefox 144+ only (Safari flagged), so treat it as an enhancement and make the un-animated state readable.
**Source:** @Ibelick (https://www.ui-skills.com/)

Scroll-linked motion belongs on a CSS timeline, not on an observer that toggles a class once and cannot scrub

> prefer Scroll or View Timelines for scroll-linked motion when available

This is the constructive half of the ban on scroll listeners. `animation-timeline: view()` binds an animation's progress to an element's position in the scrollport instead of to time, and the compositor advances it — so it stays locked to the scrollbar even while the main thread is busy. The common alternative, IntersectionObserver plus a class toggle, is not the same thing: it is a one-shot trigger. It fires at a single threshold, it cannot scrub, it plays at its own duration regardless of how fast you scrolled, and on scroll-up it either does nothing or snaps back. ibelick keeps IntersectionObserver for what it is actually good at — "use IntersectionObserver for visibility and pausing". Support is Chromium and Firefox 144+; Safari is still behind a flag, so treat the animation as an enhancement and make the un-animated state the readable one.

```tsx
.reveal { animation: fade-up linear both; animation-timeline: view(); animation-range: entry 0% cover 40%; }
```

- [ibelick — fixing-motion-performance SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-motion-performance/SKILL.md)
- [MDN — animation-timeline](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline)

### Budget Animation by Surface Size

**ID:** `animations-surface-size-budget`
**Agent rule (MUST):** Budget by property TIMES area, not property alone: paint- or layout-triggering animation is acceptable only on small, isolated surfaces. Repainting a 32px icon is ~1,024px of raster work per frame; the same property on a full-bleed hero band is ~102,400px — roughly 100x — and it will miss frames. So the rule is not "never transition `filter`/`box-shadow`" — small and isolated, go ahead; large surface, move to `transform`/`opacity` on a promoted layer or do not animate it. Never blur a large surface. Duration is the second axis: one-shot effects are affordable far more often than continuous motion.
**Source:** @Ibelick (https://www.ui-skills.com/)

The cost of a paint or layout animation scales with the pixels it touches, so surface area decides what is affordable

> paint or layout animation is acceptable only on small, isolated surfaces

This is the idea ibelick repeats more than any other, and it is the one that turns the property bans from dogma into engineering. The skill says it five ways: "do not animate layout continuously on large or meaningful surfaces", "do not animate paint-heavy properties on large containers", "paint-triggering animation is allowed only on small, isolated elements", "never animate blur on large surfaces", and the quote above. Read together they say something the flat bans do not: the property is not the whole cost — the property times the area is. Repainting a 32px icon is a few thousand pixels of raster work the GPU will not even notice; repainting a full-bleed hero is a million-plus pixels of raster work every frame, on the main thread, and it will miss frames. So the rule is not "never transition filter" — it is: on a small, isolated element, go ahead; on a large surface, move to transform and opacity on a promoted layer, or do not animate it at all. Duration is the second axis: "one-shot effects are acceptable more often than continuous motion".

- [ibelick — fixing-motion-performance SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-motion-performance/SKILL.md)
- [web.dev — Animations guide](https://web.dev/articles/animations-guide)

### Use FLIP for Layout-Like Motion

**ID:** `animations-flip-technique`
**Agent rule (SHOULD):** When a layout change genuinely must animate (list reorder, card expanding into a detail view), use FLIP — First, Last, Invert, Play: read the start rect, apply the final layout, read the end rect, apply the inverse `transform`, then release it in one rAF and let the compositor interpolate back to zero. Layout runs twice instead of 60x/sec. Measure ONCE and batch all DOM reads before writes — a `getBoundingClientRect()` inside the loop forces a synchronous layout every tick. (Does not contradict `layout-flex-over-measurement`: that bans JS measurement to BUILD a static layout; FLIP is the sanctioned way to ANIMATE a layout change.)
**Source:** @Ibelick (https://www.ui-skills.com/)

When a layout change genuinely must animate, measure once and play it back as a transform instead of animating geometry

> prefer FLIP-style transitions for layout-like effects

Sometimes the thing that changes really is layout: a list reorders, a card expands into a detail view. FLIP — First, Last, Invert, Play — lets you animate that without ever animating a layout property. Read the start rect, apply the final layout in one go, read the end rect, apply the inverse transform so the element still *looks* like it is at the start, then release it in a single rAF and let the compositor interpolate the transform back to zero. The result is pixel-identical to animating `top`/`left`/`width`, but the browser does layout exactly twice instead of sixty times a second. The two supporting rules are the ones people break: "measure once, then animate via transform or opacity" and "batch all DOM reads before writes" — a `getBoundingClientRect()` inside the animation loop forces a synchronous layout on every tick, which is layout thrashing with extra steps. Note this does not contradict layout-flex-over-measurement: that rule says do not use JS measurement to *build* a static layout. FLIP is the sanctioned technique for the case where a layout change must be *animated*.

- [ibelick — fixing-motion-performance SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-motion-performance/SKILL.md)
- [Paul Lewis — FLIP Your Animations](https://aerotwist.com/blog/flip-your-animations/)

### Decompose 2D Motion Into X and Y Springs

**ID:** `animations-apple-xy-springs`
**Agent rule (MUST):** Decompose 2D motion into two independent springs — one on `x`, one on `y`, each seeded with its OWN release velocity. A single spring on the 2D distance (`Math.hypot(x, y)` → 0) can hold only one velocity, so both axes arrive together, the card slides home along a rigid radial line, and the tangential half of the throw is discarded.
**Source:** Emil Kowalski (https://emilkowalski.com/)

A gesture that moves in two dimensions needs two springs, not one spring on the distance

> Decompose 2D motion into independent X and Y springs. A single spring on a 2D distance desyncs when X and Y have different velocities.

This is the answer to a question the corpus has not asked before: not how to configure a spring, but HOW MANY springs a gesture needs. animations-spring-physics argues for springs over tweens because they carry velocity through an interruption; animations-emil-subtle-bounce bounds the bounce. Neither says anything about dimensionality — and a 2D drag is where the naive implementation quietly breaks. The tempting shortcut is to spring the scalar distance home: `Math.hypot(x, y)` → 0, one spring, one velocity. But one spring can only hold one velocity, so both axes are forced to share it and to arrive at the same instant. Throw a card diagonally with more speed on X than Y and the faster axis drags the slower one along with it; whatever direction you actually flicked, the card slides home along a rigid radial line, and the tangential half of your gesture is simply discarded. Two springs — one on x, one on y, each seeded with its OWN release velocity — let each axis settle on its own clock. The emergent 2D path curves: it continues the way you threw the thing and hooks back, which is what "it followed my finger" actually means. This is Apple's point from Designing Fluid Interfaces, and it also explains why Motion's `x`/`y` values are separate animatable channels rather than a single vector.

```tsx
animate(el, { x: 0 }, { type: "spring", velocity: vx });
animate(el, { y: 0 }, { type: "spring", velocity: vy }); // not one spring on hypot(x, y)
```

- [Emil Kowalski — apple-design SKILL.md](https://raw.githubusercontent.com/emilkowalski/skills/main/skills/apple-design/SKILL.md)
- [Apple — Designing Fluid Interfaces (WWDC 2018)](https://developer.apple.com/videos/play/wwdc2018/803/)
- [Motion — spring transitions](https://motion.dev/docs/react-transitions)

### Enter and Exit Along the Same Path

**ID:** `animations-symmetric-exit-path`
**Agent rule (MUST):** Exit along the path the element entered on — in-from-the-right means out-to-the-right — with the easing mirrored via inverse cubic-bezier control points: enter `(x1, y1, x2, y2)` → exit `(1 - x2, 1 - y2, 1 - x1, 1 - y1)`. This is DIRECTION and curve shape, orthogonal to `animations-emil-asymmetric` (DURATION — exits snap); a correct panel obeys both: back out the right edge, on the mirrored curve, faster than it came in.
**Source:** Emil Kowalski (https://emilkowalski.com/)

A panel that slides in from the right must dismiss to the right, with the easing mirrored

> Enter and exit along the same path. A panel that slides in from the right must dismiss to the right. In-from-right / out-the-bottom feels disconnected and confusing. Mirror the easing on reversible transitions so the outbound path matches the return path (use inverse cubic-bézier control points for the two directions).

Motion is how an interface teaches spatial layout: the enter animation is a claim about where the panel LIVES when it is not on screen. Slide it in from the right and the user now believes it is parked off the right edge — so dismissing it downward silently revokes that, and they are left with no model of where the thing went or how to get it back. The exit must retrace the enter. Mirroring the easing is the same argument one level down: a cubic-bezier is a shape, and reversing endpoints does not reverse the shape. Take the enter's (x1, y1, x2, y2) and use its inverse control points — (1 - x2, 1 - y2, 1 - x1, 1 - y1) — for the return, so an ease-out entrance leaves on the ease-in that is literally its mirror image. IMPORTANT — this does NOT contradict animations-emil-asymmetric, and the two are constantly confused. That rule is about DURATION (deliberate actions take their time; exits snap). This one is about DIRECTION and CURVE SHAPE. They are orthogonal, and the correct panel obeys both: it exits back out the right edge, on the mirrored curve, in less time than it took to come in. Nor is this animations-correct-transform-origin, which fixes where a scale ORIGINATES — a popover can have a perfectly anchored origin and still be wrong because it travels out an edge it never came in through.

```tsx
/* enter */ transition-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
/* exit  */ transition-timing-function: cubic-bezier(0.7, 0, 0.84, 0);
```

- [Emil Kowalski — apple-design SKILL.md](https://raw.githubusercontent.com/emilkowalski/skills/main/skills/apple-design/SKILL.md)
- [Apple — Designing Fluid Interfaces (WWDC 2018)](https://developer.apple.com/videos/play/wwdc2018/803/)
- [MDN — cubic-bezier() easing function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function/cubic-bezier)

### Reduce Ambient 3D Motion

**ID:** `animations-ambient-motion-reduced`
**Agent rule (SHOULD):** prefers-reduced-motion applies to 3D/WebGL, not just CSS — and the rAF loop must read it in JS (matchMedia). Under reduce: stop auto-rotation, disable pointer parallax/tilt, replace scroll-driven camera moves with a static framing, and drop idle ambient motion to zero. Keep the scene interactive on demand (drag-to-orbit is user-initiated and allowed).
**Source:** Custom

Auto-rotating models, parallax tilt, and scroll-driven cameras are motion too — pause or flatten them under prefers-reduced-motion

> prefers-reduced-motion applies to WebGL and 3D, not only to CSS. Auto-rotation, pointer parallax, and scroll-linked camera moves must be reduced like any other motion.

This is animations-prefers-reduced-motion followed onto the canvas, and it is written here because the 3D ecosystem almost universally forgets it — a survey of the major three.js / R3F skills turned up no reduced-motion rule at all. The reason it gets dropped is structural: the media query lives in CSS while the motion lives in a `requestAnimationFrame` loop, so the loop has to read the preference itself and nobody wires it up. Yet ambient 3D is the MOST provocative motion on the page for a vestibular user — a model idling on a slow auto-rotate, a hero that tilts toward the pointer, a camera that dollies as you scroll: large, continuous, viewport-filling, and self-initiated by the site rather than the user. Under `prefers-reduced-motion: reduce` (check it in JS with `matchMedia`, not only in CSS): stop auto-rotation, disable pointer parallax and tilt, replace scroll-driven camera moves with a static framing or an instant cut, and drop idle ambient motion to zero. Keep the scene interactive on demand — a user who drags to orbit is initiating that motion, which is allowed, the same carve-out WCAG 2.3.3 makes for motion from interaction. Pairs with animations-ibelick-pause-offscreen (don't even run the loop when it is not visible) and performance-webgl-gpu-budget (the cost side of the same loop).

```tsx
const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!reduce) controls.autoRotate = true; // otherwise hold a static frame
```

- [MDN — prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
- [WCAG 2.3.3 — Animation from Interactions](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html)
- [Poimandres — react-three-a11y](https://github.com/pmndrs/react-three-a11y)

---

## Layout

Responsive design, alignment, and visual structure. 29 rules.

### Optical Alignment

**ID:** `layout-optical-alignment`
**Agent rule (SHOULD):** Optical alignment; adjust by ±1px when perception beats geometry
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Adjust ±1px when perception beats geometry

> Optical alignment. Adjust ±1px when perception beats geometry.

Mathematical centering doesn't always look centered to the human eye. Icons with more visual weight on one side may need to be shifted slightly to appear balanced. Trust your eye over the numbers, but limit adjustments to 1-2px.

- [Optical Alignment](https://marvelapp.com/blog/optical-adjustment-logic-vs-designers/)

### Deliberate Alignment

**ID:** `layout-deliberate-alignment`
**Agent rule (MUST):** Deliberate alignment to grid/baseline/edges/optical centers—no accidental placement
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Every element aligns with something intentionally

> Deliberate alignment. Every element aligns with something intentionally whether to a grid, baseline, edge, or optical center. No accidental positioning.

Nothing should be randomly placed. Every element should visibly align with another element, a grid line, or have a clear relationship to its neighbors. This creates visual harmony and helps users scan content efficiently.

- [Visual Alignment](https://www.nngroup.com/articles/gestalt-proximity/)

### Responsive Coverage

**ID:** `layout-responsive-coverage`
**Agent rule (MUST):** Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Verify on mobile, laptop, and ultra-wide screens

> Responsive coverage. Verify on mobile, laptop, & ultra-wide. For ultra-wide, zoom out to 50% to simulate.

Test your layouts at 320px (small mobile), 768px (tablet), 1280px (laptop), and 2560px+ (ultra-wide). Content should reflow appropriately, never horizontally scroll unexpectedly, and use available space effectively at all sizes.

- [Responsive Design](https://web.dev/articles/responsive-web-design-basics)

### No Excessive Scrollbars

**ID:** `layout-no-excessive-scrollbars`
**Agent rule (MUST):** Avoid unwanted scrollbars; fix overflows
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Only render useful scrollbars; fix overflow issues

> No excessive scrollbars. Only render useful scrollbars; fix overflow issues to prevent unwanted scrollbars.

Unexpected scrollbars indicate layout problems. Fix the root cause (usually overflow issues) rather than hiding scrollbars with CSS. On macOS, set "Show scroll bars" to "Always" during development to catch these issues.

- [CSS Overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overflow)

### Balance Contrast in Lockups

**ID:** `layout-balance-contrast`
**Agent rule (SHOULD):** Balance icon/text lockups (stroke/weight/size/spacing/color)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Adjust weight, size, spacing when text and icons sit together

> Balance contrast in lockups. When text & icons sit side by side, adjust weight, size, spacing, or color so they don't clash. For example, a thin-stroke icon may need a bolder stroke next to medium-weight text.

Icons and text have different visual weights. A light icon next to bold text feels unbalanced. Either use heavier icons, lighter text, adjust sizing, or tweak color to create visual harmony in icon-text combinations.

- [Visual Balance](https://www.nngroup.com/articles/visual-hierarchy-ux-definition/)

### Respect Safe Areas

**ID:** `layout-safe-areas`
**Agent rule (MUST):** Respect safe areas (use env(safe-area-inset-*))
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Account for notches and insets with safe-area variables

> Respect safe areas. Account for notches & insets with safe-area variables.

Mobile devices with notches and rounded corners have safe areas where content shouldn't be placed. Use CSS environment variables like env(safe-area-inset-top) to ensure your content isn't obscured by device UI elements.

- [Safe Area Insets](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/env)
- [Designing for iPhone X](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)

### @layer Is Native CSS, Not a Tailwind Directive

**ID:** `layout-layer-directives`
**Agent rule (MUST):** Use @layer (base/components/utilities) for custom CSS to integrate with Tailwind specificity
**Source:** Tailwind (https://tailwindcss.com/docs)

Use @layer base for element defaults, but never define a utility inside @layer utilities — that no longer produces a real utility

> In v4, `@layer` is a native CSS cascade layer, not a Tailwind directive. Use `@layer base` for base styles. To add a custom utility, use the `@utility` directive instead — utilities defined this way work with variants and are sorted by property count.

The three-layer habit from v3 — `@layer base`, `@layer components`, `@layer utilities` — reads identically in v4 but means something else. Tailwind no longer intercepts these blocks; they are the browser's own cascade layers (`@layer` is real CSS now, and Tailwind registers `theme`, `base`, `components`, and `utilities` as native layers). One of the three still works exactly as you expect: `@layer base { h1 { ... } }` for element defaults and resets is correct v4. The other two changed. A class you write inside `@layer utilities` is no longer registered as a Tailwind utility — it is just a rule that happens to sit in a low-priority layer. So `hover:` and `md:` cannot be applied to it (the compiler has never heard of the name and will not generate the variant), and it has no place in Tailwind's property-count sort order, so its precedence against real utilities is whatever the layer position gives it. It looks like a utility, it is styled like a utility, and it fails the moment anyone tries to use it like a utility. The v4 answer is `@utility`, which registers the name with the compiler. See layout-custom-utilities.

- [Tailwind v4: Adding custom styles](https://tailwindcss.com/docs/adding-custom-styles)
- [Tailwind v4: Functions and directives](https://tailwindcss.com/docs/functions-and-directives)
- [MDN: @layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)

### Create Custom Utilities with @utility

**ID:** `layout-custom-utilities`
**Agent rule (SHOULD):** Create custom utilities in @layer utilities for missing CSS properties (text-wrap, scrollbar)
**Source:** Tailwind (https://tailwindcss.com/docs)

Register project-specific utilities with the @utility directive, the only form that supports variants

> Use the `@utility` directive to add custom utilities to your project that work with variants like `hover`, `focus`, and `lg`: `@utility scrollbar-hide { scrollbar-width: none; }`

Tailwind does not ship every CSS property — `scrollbar-width`, `text-wrap: balance` on an older target, `mask-type` — so you will need to add your own. In v4 there is exactly one correct way, and it is `@utility name { … }`. This is not a stylistic preference over the old `@layer utilities { .name { … } }` form: that form no longer registers anything with the compiler, so `md:scrollbar-hide` and `hover:scrollbar-hide` simply do not exist and quietly do nothing at the call site. `@utility` puts the name in Tailwind's registry, which buys three things a plain class cannot have: every variant works, the utility is sorted by property count alongside the built-ins so overriding it behaves predictably, and it is only emitted when actually used. Two details worth knowing: `@utility` requires a top-level, unnested rule (no `&` selectors, no nesting — that is what makes it variant-composable), and a trailing `-*` makes it take a value, so `@utility tab-*` plus `--tab-size-*` theme tokens gives you `tab-2`, `tab-4`, and `tab-[13]`.

- [Tailwind v4: Adding custom utilities](https://tailwindcss.com/docs/adding-custom-styles)
- [Tailwind v4: @utility directive](https://tailwindcss.com/docs/functions-and-directives)

### Use Fixed Z-Index Scale

**ID:** `layout-ibelick-z-index-scale`
**Agent rule (MUST):** Use a fixed z-index scale (z-10, z-20, z-30) not arbitrary values. Document the scale. Arbitrary z-index values lead to escalating z-index wars.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use a defined z-index scale instead of arbitrary values like z-[999]

> MUST use a fixed `z-index` scale (no arbitrary `z-*`)

Arbitrary values are an escalation game: z-[999] wins today, so the next thing that must sit above it becomes z-[9999], and nobody can answer "should a tooltip be above a modal?" by reading the code. A fixed, named scale (base, dropdown, sticky, modal, popover, tooltip) turns stacking into a decision made once. The semantic layer names are our elaboration, not upstream's words — upstream only forbids the arbitrary values.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Tailwind Z-Index](https://tailwindcss.com/docs/z-index)

### Use size-* Utility

**ID:** `layout-ibelick-size-utility`
**Agent rule (SHOULD):** Use size-* for square elements instead of separate w-* and h-* classes. Reduces class count and communicates intent (this element is square).
**Source:** @Ibelick (https://www.ui-skills.com/)

Use size-* instead of separate w-* and h-* for square elements

> SHOULD use `size-*` for square elements instead of `w-*` + `h-*`

w-8 h-8 states two independent facts that happen to agree. size-8 states one fact: this is square. The difference shows up on edit — resize a w-8 h-8 icon and it is trivially easy to change one and not the other, producing a 32x24 "square" that nobody notices until it is next to a real one. It is a SHOULD, and it applies only where squareness is the intent (icons, avatars, icon buttons); an element that is coincidentally square is still correctly written as w-* + h-*.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Tailwind Size Utility](https://tailwindcss.com/docs/width#setting-both-width-and-height)

### Use dvh Instead of h-screen

**ID:** `layout-ibelick-viewport-height`
**Agent rule (NEVER):** Use h-screen or 100vh on mobile. Use h-dvh (dynamic viewport height) instead to account for mobile browser chrome (address bar, navigation).
**Source:** @Ibelick (https://www.ui-skills.com/)

Never use h-screen or 100vh on mobile - use h-dvh for dynamic viewport height

> NEVER use `h-screen`, use `h-dvh`

On mobile, 100vh is the LARGE viewport — the height the page would have if the browser chrome were hidden. It does not shrink when the address bar is showing, so a "full height" screen is taller than the visible area and its bottom row (usually the primary action) sits under the browser UI. dvh tracks the viewport as the chrome shows and hides. The tradeoff worth knowing: because dvh changes during scroll, a dvh-sized element can resize mid-gesture — where that reflow is worse than the clipping, svh (the small viewport, i.e. chrome always visible) is the stable choice.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Dynamic Viewports](https://web.dev/blog/viewport-units)

### Respect Safe Area Insets on Fixed Elements

**ID:** `layout-ibelick-safe-areas`
**Agent rule (MUST):** Respect safe-area-inset for fixed/sticky elements on notched devices. Use pb-safe, pt-safe or env(safe-area-inset-*) to prevent content obscuring.
**Source:** @Ibelick (https://www.ui-skills.com/)

Pad fixed elements with env(safe-area-inset-*) so they clear the notch and the home indicator

> MUST respect `safe-area-inset` for fixed elements

The scope is FIXED elements, and that is the whole point of the rule: normal document flow already stops short of the unsafe regions, so a paragraph does not need this. A `position: fixed` header, bottom bar, FAB or drawer is positioned against the viewport, which extends underneath the notch and the home indicator — so it, and only it, lands in hardware. Requires `viewport-fit=cover` in the viewport meta tag; without it the env() values all resolve to 0 and the rule silently does nothing. Write the padding as `padding-bottom: env(safe-area-inset-bottom)` (or, keeping the element's own padding, `calc(0.75rem + env(safe-area-inset-bottom))`), and note that `pb-safe` / `pt-safe` are NOT core Tailwind — they come from the tailwindcss-safe-area plugin or a hand-written `@utility`, and they do not exist in this project, so writing them here produces no CSS at all.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [MDN — env()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/env)
- [Designing for Notches](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)

### Min-Width for Truncation

**ID:** `layout-min-width-truncation`
**Agent rule (MUST):** Add `min-w-0` (`min-width: 0`) to any flex child that must truncate — flex items default to `min-width: auto` and refuse to shrink below their content, so `text-overflow: ellipsis` never has an overflow to clip. Grid children need `min-w-0` or `minmax(0, 1fr)`.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Add min-w-0 to flex children so text can actually truncate instead of overflowing

> Flex children need `min-w-0` to allow text truncation.

A flex item defaults to min-width: auto, which refuses to shrink below its content's min-content size. A long unbroken filename or URL therefore keeps the item wide, text-overflow: ellipsis never has an overflow to clip, and the row blows out — pushing siblings like a trailing button outside the container. Setting min-width: 0 (min-w-0) on the shrinking child restores the shrink and makes truncate work. The same applies to grid children via min-w-0 or minmax(0, 1fr).

```tsx
<div class="flex items-center gap-2">
  <span class="min-w-0 flex-1 truncate">{longFileName}</span>
  <button class="shrink-0">Open</button>
</div>
```

- [MDN: min-width](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/min-width)
- [MDN: text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-overflow)

### Flex/Grid Over JS Measurement

**ID:** `layout-flex-over-measurement`
**Agent rule (SHOULD):** Solve layout with flex and grid instead of reading `getBoundingClientRect`/`offsetWidth` and writing the result back as inline styles — measurement forces a synchronous reflow, can only run after first paint (so the UI visibly jumps), is wrong during SSR, and goes stale without a `ResizeObserver`.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Solve layout with flex and grid instead of measuring elements and positioning them in JavaScript

> Flex/grid over JS measurement for layout.

Reading getBoundingClientRect or offsetWidth forces a synchronous style and layout recalculation, and writing the result back into inline styles triggers another one — layout thrash. Worse, the measurement can only run after the first paint, so the UI visibly jumps into place, is wrong during SSR and before hydration, and goes stale the moment the content or the container changes unless you also wire up a ResizeObserver. Flex and grid express the same intent declaratively: the browser solves it during its own layout pass, correct on the first paint and on every resize.

- [MDN: getBoundingClientRect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect)
- [MDN: CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout)

### Never Nest Cards

**ID:** `layout-impeccable-nested-cards`
**Agent rule (NEVER):** Nest a card inside a card — an element counts as card-like when it has (a shadow OR a border) AND (a radius OR a background). Build hierarchy inside a card with padding, one hairline divider, and type weight, not a second chrome layer.
**Source:** impeccable (https://impeccable.style/)

Never put a card inside a card — use padding, dividers, and type weight for internal hierarchy

> Nested cards are always wrong. Cards inside cards create visual noise and excessive depth.

impeccable defines "card-like" structurally — an element is a card when it has (a shadow OR a border) AND (a radius OR a background). The detector walks an element's ancestors and, when it finds a second card-like box inside a first, reports the innermost offender. The damage is twofold: the border and shadow noise doubles, and the depth hierarchy dies, because you now have two elevation levels that mean nothing relative to each other — the inner card is not "further forward" than its parent, it is just louder. Internal hierarchy inside a card is a job for padding, a single hairline divider, and type weight, not for a second chrome layer. Before the nesting question, though, comes the one nobody asks: should this be a card at all? Every Inc's ce-frontend-design skill supplies the missing test — default to cardless layouts, and allow a card only when it is the container for a user interaction (a clickable item, a draggable unit, a selectable option). If removing the card styling would not hurt comprehension, it should not be a card. That test dissolves most nesting violations at the root: the inner box was never earning its border and shadow, it was just grouping content that padding and a heading already grouped.

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [ce-frontend-design (EveryInc/compound-engineering-plugin)](https://github.com/EveryInc/compound-engineering-plugin)

### Padding Must Scale With Type

**ID:** `layout-impeccable-cramped-padding`
**Agent rule (MUST):** Scale padding inside any bordered, outlined, or filled container from its font size: vertical >= `max(4px, fontSize * 0.3)` and horizontal >= `max(8px, fontSize * 0.5)` — at least 8px, ideally 12–16px. Also catch the `padding: 28px 0 0` shorthand bug, where the sides get quietly zeroed and text sits flush against the border.
**Source:** impeccable (https://impeccable.style/)

Derive container padding from the font size instead of hardcoding a value that 20px text will burst

> Add at least 8px (ideally 12–16px) of padding inside bordered, outlined, or colored containers.

The detector is thresholded, not a matter of taste: inside any container with a visible boundary it requires vertical padding >= max(4px, fontSize * 0.3) and horizontal padding >= max(8px, fontSize * 0.5). Horizontal gets the bigger multiplier because line-height already supplies vertical breathing room, while nothing pads the sides of a glyph. It catches a second shape too: a wrapper with a visible boundary and <= 2px of padding whose text children sit flush against the border — the classic `padding: 28px 0 0` shorthand bug, where someone set the top and quietly zeroed the sides. This is the thresholded sibling of the vague "Crowded Elements" (Rams) principle in this corpus: that one says give elements room, this one says exactly how much.

- [impeccable.style](https://impeccable.style/)
- [MDN — padding](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/padding)

### Body Text Never Touches the Viewport Edge

**ID:** `layout-impeccable-body-text-viewport-edge`
**Agent rule (MUST):** Never let a paragraph or list item land within 16px of the left or right viewport edge — give the wrapping container at least 16px (ideally 24–32px) of horizontal padding, or a `max-width` plus `mx-auto` once there is room for one.
**Source:** impeccable (https://impeccable.style/)

Give body copy a gutter — never let paragraphs bleed flush against the left or right edge of the screen

> Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding.

This is distinct from cramped padding: there the container exists and is too tight, here the container is missing entirely. The detector flags a <p> or <li> with more than 40 characters of text, wider than 50% of the viewport, whose left edge sits less than 16px from the viewport edge (or whose right edge is within 16px of the far side). Text that runs into the physical edge of the screen has no margin for the eye to return to on each line wrap, and on a phone it collides with the rounded corners and the palm holding the device. The fix is at least 16px — ideally 24–32px — of horizontal padding on a wrapping container, or a max-width plus mx-auto once there is room for one.

- [impeccable.style](https://impeccable.style/)
- [MDN — max-width](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/max-width)
- [Practical Typography — line length](https://practicaltypography.com/line-length.html)

### Overflow Containers Clip Popovers

**ID:** `layout-impeccable-clipped-overflow`
**Agent rule (NEVER):** Leave an absolutely-positioned tooltip, menu, or popover inside an ancestor with `overflow: hidden` or `overflow: clip` — the layer gets silently cut off. Clip the image rather than the whole card, or promote the layer out of the subtree with the native Popover API (top layer) or a portal.
**Source:** impeccable (https://impeccable.style/)

Never trap a menu, tooltip, or popover inside an overflow-hidden ancestor — let it escape the clip

> A clipping container (overflow hidden or clip) wrapping an absolutely-positioned child cuts off tooltips, menus, and popovers that need to escape.

The detector walks up from every absolutely-positioned layer looking for an ancestor with overflow: hidden or overflow: clip, and this is by far the most common cause of "my dropdown is cut off inside a card". Nobody adds overflow: hidden to break a menu — it gets added to clip an image to a rounded corner or to stop a stray child from bleeding out, and then it silently traps every popover rendered inside that subtree forever. Two fixes: let overflow stay visible (clip the image itself, not the whole card), or move the layer out of the clip — a portal, or better, the native Popover API, which promotes the element into the top layer where no ancestor overflow can reach it.

- [impeccable.style](https://impeccable.style/)
- [MDN — overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/overflow)
- [MDN — Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
- [MDN — top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer)

### Symmetrical Padding

**ID:** `layout-interface-symmetrical-padding`
**Agent rule (NEVER):** Give a box four different padding values (`padding: 24px 16px 12px 16px`) — that is residue from nudging one side, not a decision, and it de-centres the content so a stack of cards loses its rhythm. Use one uniform value (`padding: 16px`) or at most a single horizontal/vertical pair (`padding: 12px 16px`).
**Source:** interface-design (https://github.com/Dammyjay93/interface-design)

Give a box one padding value on all four sides, or at most a single horizontal/vertical pair — never four different numbers

> TLBR must match. If top padding is 16px, left/bottom/right must also be 16px. Exception: when content naturally creates visual balance.

The rule is narrow and mechanical, which is what makes it enforceable: padding is uniform (padding: 16px), or a single axis pair (padding: 12px 16px) when the horizontal side genuinely needs more room than the vertical. Four distinct values — padding: 24px 16px 12px 16px — is almost never a decision; it is the residue of someone nudging the top once and the bottom once and never reconciling them. The cost is visible: the content is no longer centred inside its own box, so a stack of such cards has no shared rhythm, and the eye reads the drift as sloppiness even when it cannot name it. This is a high-frequency tell in AI-generated UI, because a model emits each side independently and has no reason to make them agree. Distinct from the padding-scale rule (layout-impeccable-cramped-padding), which asks whether there is enough padding; this one asks whether the four values agree.

- [interface-design (Damola Akinleye)](https://github.com/Dammyjay93/interface-design)
- [MDN: padding](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/padding)

### Screens Need Grounding

**ID:** `layout-interface-screen-grounding`
**Agent rule (MUST):** Ground every screen with three anchors: navigation (where you can go), a location indicator (breadcrumbs / page title / active nav state — where you are), and user context (who is signed in, which workspace). A data table with none of them is a component demo, not a product. Give the sidebar the same background as the canvas and separate it with a border, not a different fill.
**Source:** interface-design (https://github.com/Dammyjay93/interface-design)

Surround a screen with navigation, a location indicator, and user context so it reads as part of an app, not as a floating widget

> Screens need grounding. A data table floating in space feels like a component demo, not a product.

Three anchors ground a screen: navigation (a sidebar or top nav showing where you can go), a location indicator (breadcrumbs, a page title, or an active nav state showing where you are), and user context (who is signed in, and which workspace or org). Strip them and a perfectly good data table becomes an artifact with no address — the user cannot tell what surrounds it, what they can leave it for, or whose data they are even looking at. This is the single most reliable structural tell of LLM-authored UI: the model renders the widget it was asked for and forgets that widgets live inside applications. The corpus already covers alignment and spacing within a screen, but nothing else in layout covers wayfinding — where the screen sits in the product. When you build the sidebar, give it the same background as the canvas and separate it with a border; a different fill fragments the page into a "sidebar world" and a "content world".

- [interface-design (Damola Akinleye)](https://github.com/Dammyjay93/interface-design)
- [NN/g: Breadcrumbs](https://www.nngroup.com/articles/breadcrumbs/)
- [MDN: <nav>](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/nav)

### Landmark Regions

**ID:** `layout-aria-landmarks`
**Agent rule (MUST):** Put all perceivable content inside a landmark, built from the native elements (`<header>` banner, `<nav>`, `<main>`, `<aside>`, `<footer>` contentinfo) rather than roles on divs — a div soup gives the screen-reader rotor nothing to jump to. Give each DUPLICATE landmark a unique `aria-label` (or `aria-labelledby` on its heading), and never put the role name in the label: "Site Navigation" announces as "Site Navigation navigation" — label it "Primary" and "Breadcrumb".
**Source:** ARIA (https://www.w3.org/WAI/ARIA/apg/)

Put all perceivable content inside a landmark, use the native sectioning elements, and label duplicates

> Including all perceivable content on a page in one of its landmark regions and giving each landmark region a semantically meaningful role is one of the most effective ways of ensuring assistive technology users will not overlook information that is relevant to their needs. [...] If a specific landmark role is used more than once on a page, provide each instance of that landmark with a unique label. [...] Do not use the landmark role as part of the label. For example, a navigation landmark with a label "Site Navigation" will be announced by a screen reader as "Site Navigation Navigation". The label should simply be "Site".

Landmarks are the structural layer of a page, and nothing else in this corpus covers them. layout-interface-screen-grounding is about visible wayfinding chrome — a sidebar, breadcrumbs, user context — which is a different substance: you can build all of it out of divs and still ship a page with zero landmarks. Screen readers expose a landmark rotor as the primary way to jump around a page; a div soup produces an empty rotor, so the only way to reach the main content is to walk every node from the top. Four rules cover it. First, every perceivable region belongs to a landmark. Second, use the native elements — header (banner at body scope), nav (navigation), main (main), aside (complementary), footer (contentinfo at body scope) — rather than role attributes on divs. Third, when a landmark type appears more than once, give each instance a unique label with aria-label, or aria-labelledby pointing at its heading; two unlabelled navs are indistinguishable in the rotor. Fourth, keep the role name out of the label: the role is announced already, so "Site Navigation" becomes "Site Navigation navigation". Label it "Primary" and "Breadcrumb", not "Primary Navigation".

```tsx
<nav aria-label="Primary">…</nav>
<nav aria-label="Breadcrumb">…</nav>
```

- [APG: Landmark Regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/)
- [MDN: <nav>](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/nav)

### Reusable Components Query Their Container

**ID:** `layout-container-queries`
**Agent rule (SHOULD):** A reusable component must respond to ITS OWN width, not the viewport: `md:flex-row` asks about the browser window, so the card that reads right in the main column goes horizontal inside a 300px sidebar. Put `@container` on the wrapper and `@md:` on the children — now it asks "is my container ≥28rem", with no `isCompact` prop threaded through three layers. Container queries are core in v4; installing `@tailwindcss/container-queries` is a mistake, not a dependency. The `@` variants read the nearest `@container` ANCESTOR, so the wrapper must not be the element you are sizing.
**Source:** Tailwind (https://tailwindcss.com/docs)

Size a reusable component against its own container with @container and @md:, not against the viewport

> Container queries are now built into the framework in v4 — the `@tailwindcss/container-queries` plugin is no longer needed. Use the `@container` class to mark an element as a container, then style its children based on the container's size with variants like `@sm:` and `@md:`.

A breakpoint variant like `md:flex-row` asks a question about the browser window, but a reusable `<Card>` does not live in the browser window — it lives in whatever box you dropped it into. So the card that looks right in the main column goes horizontal inside a 300px sidebar, because the *viewport* is 1400px wide and the card has no idea it is not. The component is not broken; the question it is asking is. Container queries let it ask the right one: put `@container` on the card's wrapper and the `@md:flex-row` on its child now means "when my container is at least 28rem", which is true in the main column and false in the sidebar, with no props, no context, and no `isCompact` boolean threaded through three layers. This is core in v4 — installing `@tailwindcss/container-queries` is now a mistake, not a dependency. Two things to keep straight: the `@` variants read the nearest `@container` ancestor, so the wrapper must be a different element from the one you are sizing; and named containers (`@container/sidebar` with `@md/sidebar:`) exist for when containers nest and you need to skip past the nearest one.

```tsx
<div class="@container">
  <div class="flex flex-col @md:flex-row">…</div>
</div>
```

- [Tailwind v4: Responsive design](https://tailwindcss.com/docs/responsive-design)
- [Tailwind CSS v4.0 announcement](https://tailwindcss.com/blog/tailwindcss-v4)
- [MDN: @container](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@container)

### @apply Is Not How You Share Styles

**ID:** `layout-no-apply-abstraction`
**Agent rule (NEVER):** Collapse repeated markup into a `.btn { @apply … }` class to make it look "cleaner" — it reintroduces exactly what utilities removed: you invent a name, you jump between files to read the button's appearance, and one edit silently repaints every button. It also collapses at the first variant (`.btn-primary`, `.btn-sm`, disabled), where you start hand-rolling the variant system you already have. Extract a COMPONENT instead — a React component with CVA — which encapsulates behaviour too, not just the class string. `@apply` is legitimate only for markup you do not control (a `.prose` subtree, a third-party widget).
**Source:** Tailwind (https://tailwindcss.com/docs)

Extract a component when markup repeats, instead of collapsing utilities into a .btn class with @apply

> Whatever you do, don't use `@apply` just to make things look "cleaner". Using `@apply` to extract a class like `.btn` reintroduces all the problems utility classes were meant to solve: you have to invent a name, you have to jump between files, and you have to think about how to override it.

The instinct is understandable: a long `class="inline-flex items-center rounded-md px-4 py-2 …"` looks like duplication, and `.btn { @apply … }` makes it go away. But the duplication was never the problem utility classes had — it was the naming, the indirection, and the coupling. `.btn` brings all three back. You now maintain a name that means nothing to the browser, you cannot read the button's appearance from the button's markup, and any change to `.btn` silently repaints every button in the product, which is exactly the cascade problem Tailwind exists to remove. It also collapses the moment you need a variant: a `.btn-primary`, a `.btn-sm`, a disabled state, and you are hand-rolling the variant system Tailwind already ships. Tailwind's own guidance is a ladder, and `@apply` is not on it: if the repetition is in a list, use a loop; if it is a real UI element, extract a *component* — a React component, with CVA for the variants — because a component encapsulates the markup and the behaviour too, not just the class string. `@apply` earns its place in one narrow case: styling markup you do not control (a `.prose` subtree, a third-party widget) or an unavoidable single element, where a component is not an option. Reach for it there, not to tidy up.

```tsx
/* no */ .btn { @apply inline-flex rounded-md px-4 py-2 …; }
// yes: const button = cva("inline-flex rounded-md", { variants: { size: { sm: "px-2 py-1", md: "px-4 py-2" } } });
```

- [Tailwind v4: Managing duplication](https://tailwindcss.com/docs/styling-with-utility-classes)
- [Tailwind v4: Functions and directives](https://tailwindcss.com/docs/functions-and-directives)

### Locking Body Scroll Must Not Shift the Page

**ID:** `layout-dialog-scroll-lock`
**Agent rule (SHOULD):** Opening a dialog must not shift the page behind it. `document.body.style.overflow = "hidden"` removes the scrollbar track, so the viewport grows ~15px and everything behind the scrim jumps sideways (and back on close). Reserve the track with `scrollbar-gutter: stable` (or pad by `window.innerWidth - document.documentElement.clientWidth` on legacy targets), and put `overscroll-behavior: contain` on the dialog's own scroll area so a flick inside it does not chain out.
**Source:** @Ibelick (https://www.ui-skills.com/)

The usual overflow:hidden scroll lock removes the scrollbar, which reflows the whole page ~15px wider behind the scrim

> opening a dialog should not scroll the page unexpectedly

Locking background scroll while a dialog is open is correct. The one-line way everyone does it — `document.body.style.overflow = "hidden"` — is what causes the lurch. On any platform with classic overlay-less scrollbars, hiding overflow removes the scrollbar track, the viewport gets roughly 15px wider, and every centered or full-width element behind the scrim jumps sideways at the exact moment the user's attention moves to the dialog. Then it jumps back on close. It reads as a bug even to people who cannot name it. Two fixes, use both: `scrollbar-gutter: stable` on the scroll container reserves the track permanently so removing the scrollbar changes nothing (or, on legacy targets, pad by `window.innerWidth - documentElement.clientWidth`), and `overscroll-behavior: contain` on the dialog's own scroll area stops a flick inside it from chaining out to the page. That second half is interactions-overscroll-behavior and it is a genuinely different failure — chaining is about where a scroll *goes*, this is about the layout *shifting* when scrolling is taken away.

```tsx
html { scrollbar-gutter: stable; }
.dialog-body { overscroll-behavior: contain; }
```

- [ibelick — fixing-accessibility SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-accessibility/SKILL.md)
- [MDN — scrollbar-gutter](https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-gutter)
- [MDN — overscroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior)

### Same Padding Everywhere Is Monotony

**ID:** `layout-impeccable-monotonous-spacing`
**Agent rule (SHOULD):** Vary spacing to encode grouping: ~8-12px BETWEEN siblings, ~48-96px BETWEEN sections. Uniform padding everywhere does not just look boring, it does not parse — when a label sits as far from its input as from the next section, nothing groups and every element floats at equal weight. The detector rounds every padding/margin/gap to 4px and, given >=10 samples, fires when ONE value exceeds 60% of them AND there are <=3 unique values. The opposite ditch is `design-rams-inconsistent-spacing` (arbitrary, unrepeatable values); the target is a small scale, applied to mean something.
**Source:** impeccable (https://impeccable.style/)

Vary spacing for rhythm — tight inside a group, generous between sections, because spacing is what encodes grouping

> Vary spacing for rhythm. Same padding everywhere is monotony.

The detector is precise about what "everywhere" means: it collects every padding, margin, and gap value on the page, rounds each to the nearest 4px, and — once it has at least 10 of them — flags the page when ONE value accounts for more than 60% of the total AND there are 3 or fewer unique values. A page where every gap is 16px scores 100% dominance across a single unique value. The failure is not that it looks boring, it is that it does not parse. Spacing is the primary encoder of grouping: when a label sits as far from its own input as it does from the next section, nothing groups, and every element floats at equal weight. impeccable gives the rhythm as ranges — tight groupings of 8-12px BETWEEN siblings, generous separations of 48-96px BETWEEN distinct sections — so that proximity alone makes the structure legible, without a single border or divider doing the work. Note that `design-rams-inconsistent-spacing` is the opposite ditch: that one fires when spacing is arbitrary and unrepeatable, this one when it is uniform and meaningless. The target is neither — a small scale, applied to mean something.

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)

### Logical Properties for Direction

**ID:** `layout-logical-properties`
**Agent rule (MUST):** Use direction-agnostic properties so the layout mirrors in RTL: `margin-inline-start`/`-end` not `margin-left`/`-right`, `padding-inline-end` not `padding-right`, `inset-inline-start`/`-end` not `left`/`right`, `text-align: start`/`end` not `left`/`right` (Tailwind: `ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`, `text-start`, `text-end`). Set `lang` — it picks quotes, hyphenation, font fallback and the screen-reader voice — and `dir="rtl"` where needed. Under `dir="rtl"` the browser mirrors flex/grid order while every hardcoded left and right stays put, so icons detach and padding collides.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Use direction-agnostic CSS — margin-inline-start, not margin-left — so a layout mirrors correctly in right-to-left languages

> To support right-to-left content, use direction-agnostic properties: `margin-inline-start` instead of `margin-left`, `text-align: start` instead of `left`. Set `lang` so browsers pick the right quotes and hyphenation, and `dir="rtl"` where needed.

Physical properties encode a hardcoded assumption that text flows left-to-right. `margin-left` means "the left edge of the screen"; `margin-inline-start` means "the edge the reading starts at", which is the left in English and the right in Arabic, Hebrew, Persian and Urdu. Set `dir="rtl"` on a subtree built from physical properties and the browser dutifully mirrors the flex/grid order while every hardcoded left and right stays put — so the icon that hugged the text now detaches from it, the padding that kept a dismiss button clear of the label is now on the wrong side and the two collide, and the copy is still ragged-left in a language that is read right-to-left. The full mapping is small: `margin-inline-start`/`-end` for `margin-left`/`-right`, `padding-inline-start`/`-end`, `inset-inline-start`/`-end` for `left`/`right`, `border-inline-start`, and `text-align: start`/`end` for `left`/`right`. Tailwind ships all of them (`ms-*`, `me-*`, `ps-*`, `pe-*`, `start-*`, `end-*`, `text-start`, `text-end`), so the direction-agnostic version costs the same number of characters as the broken one. `lang` is the other half and is not decorative: it selects the right quotation marks, hyphenation dictionary and font fallbacks, and it is what a screen reader uses to pick a voice. Note this is a distinct gap from the internationalisation rules the guide already covers — content-language-detection and content-translate-no are about the words; this is about which way the box points.

```tsx
<html lang="ar" dir="rtl">
/* .card { margin-left: 1rem; text-align: left; }  ✗ */
.card { margin-inline-start: 1rem; text-align: start; } /* ✓ */
```

- [jakubkrehel/skills — better-typography](https://github.com/jakubkrehel/skills/tree/main/skills/better-typography)
- [MDN: CSS logical properties and values](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)

### z-index Only Works Inside Its Stacking Context

**ID:** `layout-stacking-context-zindex`
**Agent rule (SHOULD):** z-index is compared only within a stacking context, not globally. transform, opacity<1, filter, will-change, position:fixed/sticky, isolation, and flex/grid children with z-index all create one — trapping descendants no matter how high their z-index. Do not fix overlap with a bigger number; remove the accidental context or lift the overlay out of the trapping ancestor.
**Source:** Web Platform (https://web.dev/)

A parent with transform, opacity, or filter makes a new stacking context that traps its children's z-index — the fix is not a bigger number

> New stacking contexts reset z-index. z-index only compares elements within the same stacking context, so a z-index:9999 child cannot escape a parent that sits below a later sibling.

The recurring bug: a dropdown set to `z-index: 9999` still renders under the next section and nobody can explain why the number does not win. z-index is not global — it is compared only among siblings inside the same STACKING CONTEXT, and a long list of ordinary CSS silently creates one: `transform`, `opacity` below 1, `filter`, `backdrop-filter`, `will-change`, `position: fixed`/`sticky`, `isolation: isolate`, and being a flex/grid child that has a z-index. Once a parent forms a context, its descendants' z-index are resolved only against each other and the whole subtree is clamped to the parent's own place in the stack — so a `9999` inside a `transform`ed card can never climb above a sibling card that comes later in the DOM. Raising the number is the wrong fix and starts the arms race that layout-ibelick-z-index-scale exists to prevent. The right fixes: remove the accidental context (drop the stray `transform`/`opacity`), or lift the overlay out of the trapping ancestor entirely — the same escape move layout-impeccable-clipped-overflow prescribes for a popover trapped in an `overflow` ancestor.

```tsx
/* z-index:9999 inside a transformed parent can't beat a later sibling. */
.card { transform: none; } /* or move the overlay to a portal / higher context */
```

- [MDN — The stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Stacking_context)
- [nextlevelbuilder — ui-ux-pro-max](https://skills.sh/nextlevelbuilder/ui-ux-pro-max-skill/ui-ux-pro-max)
- [MDN — z-index](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index)

### Fixed Elements Need a Space Budget

**ID:** `layout-fixed-element-budget`
**Agent rule (SHOULD):** A fixed/sticky element is out of flow, so reserve its space: offset content by the bar height (padding-top) and add scroll-padding-top so anchors and focus land clear. Do not position multiple fixed elements independently — budget them together with each other and env(safe-area-inset-*) so they never collide or hide content.
**Source:** Custom

Reserve room for a fixed or sticky bar by offsetting content, and don't stack multiple fixed elements into collisions

> A fixed nav should not obscure content — offset the content by its height. Don't stack multiple fixed elements carelessly; account for safe areas and for each other. (nextlevelbuilder, ui-ux-pro-max)

A `position: fixed` (or sticky) element is lifted out of normal flow, so the layout no longer reserves space for it — and by default the first section of content renders UNDERNEATH a fixed header, its top lines hidden behind the bar. Pay the space back: offset the content by the bar's height with `padding-top` on the scroll container, and add `scroll-padding-top` so anchored jumps and keyboard focus also land clear of it (that focus case is interactions-focus-not-obscured). The second failure is stacking: a fixed header, a fixed cookie banner, and a fixed chat button, each positioned on its own, will overlap one another and the device notch because none of them knows the others exist. Budget them together — collapse them into one fixed region, or give each an explicit offset that accounts for the others and for `env(safe-area-inset-*)` (layout-ibelick-safe-areas). The principle under both halves: taking an element out of flow is borrowing space you now have to repay by hand.

```tsx
.scroll { padding-top: var(--nav-h); scroll-padding-top: var(--nav-h); }
```

- [nextlevelbuilder — ui-ux-pro-max](https://skills.sh/nextlevelbuilder/ui-ux-pro-max-skill/ui-ux-pro-max)
- [MDN — position: fixed](https://developer.mozilla.org/en-US/docs/Web/CSS/position)
- [MDN — scroll-padding](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-padding)

### Wide Tables Need a Scroll Wrapper or Cards

**ID:** `layout-responsive-table-overflow`
**Agent rule (SHOULD):** A table wider than the viewport must not widen the page. Wrap it in an overflow-x:auto container so only the table scrolls, or reflow rows into label–value cards on narrow screens. Add an edge fade/shadow so the scroll is discoverable, and keep the header reachable.
**Source:** Custom

A table wider than the viewport must scroll inside its own overflow-x container or reflow to cards — never push the whole page wide

> Tables can overflow on mobile. Use a horizontal-scroll wrapper (overflow-x: auto) or a card layout — don't let a wide table break the page layout. (nextlevelbuilder, ui-ux-pro-max)

A table sizes to its columns, and on a phone a real data table is almost always wider than the screen. Left alone it does the worst possible thing: it stretches its containing block, so the WHOLE page gains a horizontal scrollbar and every other element overflows with it — now the body copy scrolls sideways to reveal nothing. Two correct fixes. Wrap the table in an `overflow-x: auto` container so ONLY the table scrolls, within its own bounds, while the page stays put — this is the specific, useful case that layout-no-excessive-scrollbars carves out (a scrollbar on the one thing that genuinely needs it). Or, for the best small-screen result, reflow each row into a stacked card of label–value pairs, so there is no horizontal scroll at all. Give the scroll container an edge affordance (a fade or shadow) so people know more is there, and keep the header reachable. This is the inverse framing of layout-no-excessive-scrollbars: that rule says do not create scrollbars you do not need; this one says when a table truly needs one, contain it to the table instead of the page.

```tsx
<div class="overflow-x-auto"><table>…</table></div>
```

- [nextlevelbuilder — ui-ux-pro-max](https://skills.sh/nextlevelbuilder/ui-ux-pro-max-skill/ui-ux-pro-max)
- [MDN — overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow)
- [web.dev — Responsive tables](https://web.dev/articles/responsive-web-design-basics)

---

## Content

Typography, accessibility, and content presentation. 80 rules.

### Inline Help First

**ID:** `content-inline-help-first`
**Agent rule (SHOULD):** Inline help first; tooltips last resort
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer inline explanations; use tooltips as last resort

> Inline help first. Prefer inline explanations; use tooltips as a last resort.

Tooltips hide information and require hovering, which doesn't work on touch devices. Whenever possible, include help text inline where it's always visible. Use tooltips only for supplementary information that would clutter the interface.

- [Tooltip Usability](https://www.nngroup.com/articles/tooltip-guidelines/)

### Stable Skeletons

**ID:** `content-stable-skeletons`
**Agent rule (MUST):** Skeletons mirror final content to avoid layout shift
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Skeletons mirror final content exactly to avoid layout shift

> Stable skeletons. Skeletons mirror final content exactly to avoid layout shift.

Loading skeletons should match the dimensions and layout of the actual content. This prevents cumulative layout shift (CLS) when content loads. If content varies significantly, use the most common dimensions or a safe maximum. Two checks catch most of what "matches the dimensions" actually means. First, an image placeholder needs the correct **aspect ratio**, not merely some height: a 200px-tall grey box standing in for a 16:9 photo still reflows the column the moment the real image arrives, so reserve the box with `aspect-ratio` (or explicit `width`/`height`) taken from the asset. Second, a text skeleton bar must match the typography's **line-box height**, not its font-size: `text-sm` is 14px of glyph inside a 20px line box, so a 14px bar is 6px short per line and a three-line paragraph shifts everything below it by 18px. Size the bars from the computed `line-height` and keep the same gaps the real lines will have.

- [Skeleton Screens](https://www.nngroup.com/articles/skeleton-screens/)
- [Cumulative Layout Shift](https://web.dev/articles/cls)
- [Optimize CLS](https://web.dev/articles/optimize-cls)

### No Dead Ends

**ID:** `content-no-dead-ends`
**Agent rule (MUST):** No dead ends; always offer next step/recovery
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Every screen offers a next step or recovery path

> No dead ends. Every screen offers a next step or recovery path.

Empty states, error pages, and completion screens should always provide clear next actions. Never leave users stuck wondering what to do. Offer suggestions, links to help, or ways to start over.

- [Empty States](https://www.nngroup.com/articles/empty-state-interface-design/)

### Typographic Quotes

**ID:** `content-typographic-quotes`
**Agent rule (SHOULD):** Curly quotes (" "); avoid widows/orphans
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer curly quotes over straight quotes

> Typographic quotes. Prefer curly quotes (" ") over straight quotes (" ").

Curly quotes (also called smart quotes or typographer's quotes) look more polished and professional than straight quotes. Use curly double quotes and curly single quotes. Most design tools and modern editors can auto-convert these.

- [Smart Quotes](https://practicaltypography.com/straight-and-curly-quotes.html)

### Tabular Numbers

**ID:** `content-tabular-numbers`
**Agent rule (MUST):** Tabular numbers for comparisons (`font-variant-numeric: tabular-nums` or a mono like Geist Mono)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use tabular-nums for comparisons and tables

> Tabular numbers for comparisons. Use font-variant-numeric: tabular-nums or a monospace like Geist Mono.

Proportional numbers have varying widths (1 is narrower than 8), making columns misalign. Tabular numbers have uniform width, so digits stack vertically in tables and make comparisons easier. Essential for prices, metrics, and data tables. The same property carries a second switch worth reaching for on identifiers: `font-variant-numeric: slashed-zero` cuts a stroke through the zero so an order number, an API key, a serial, or a licence plate cannot be misread as an `O` by someone transcribing it.

- [font-variant-numeric](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-variant-numeric)
- [jakubkrehel — variable-fonts-and-opentype.md (slashed zero)](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/variable-fonts-and-opentype.md)

### Icons Have Labels

**ID:** `content-icons-have-labels`
**Agent rule (MUST):** Icon-only buttons have descriptive `aria-label`
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Convey the same meaning with text for non-sighted users

> Icons have labels. Convey the same meaning with text for assistive tech. Icon-only buttons are named. Provide a descriptive aria-label.

Icons aren't universally understood and are invisible to screen readers. Either show a visible text label alongside the icon, or provide an aria-label for icon-only buttons. The label should describe the action, not the icon itself.

- [Accessible Icon Buttons](https://www.sarasoueidan.com/blog/accessible-icon-buttons/)

### Non-breaking Spaces

**ID:** `content-non-breaking-spaces`
**Agent rule (MUST):** Use non-breaking spaces to glue terms: `10&nbsp;MB`, `⌘&nbsp;+&nbsp;K`, `Vercel&nbsp;SDK`
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use non-breaking spaces to keep units and terms together

> Non-breaking spaces for glued terms. Use a non-breaking space &nbsp; to keep units, shortcuts & names together: 10 MB → 10&nbsp;MB, ⌘ + K → ⌘&nbsp;+&nbsp;K, Vercel SDK → Vercel&nbsp;SDK.

Certain text elements should never wrap onto separate lines. Use &nbsp; (non-breaking space) in HTML or \u00A0 in JavaScript to keep numbers with their units, keyboard shortcuts together, and brand names intact.

- [Non-breaking space](https://en.wikipedia.org/wiki/Non-breaking_space)

### Accurate Page Titles

**ID:** `content-page-titles`
**Agent rule (MUST):** `<title>` matches current context
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Title element reflects the current context

> Accurate page titles. <title> reflects the current context.

The page title appears in browser tabs, bookmarks, and search results. Update it dynamically to reflect the current view (e.g., "Edit Profile - Settings - MyApp"). This helps users navigate between tabs and understand their location.

- [Title element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/title)

### All States Designed

**ID:** `content-all-states`
**Agent rule (MUST):** Design empty/sparse/dense/error states
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Design empty, sparse, dense, and error states

> All states designed. Empty, sparse, dense, & error states.

Every interface has multiple states beyond the ideal happy path. Design and implement empty states (no data yet), sparse states (minimal data), dense states (lots of data), error states (something went wrong), and loading states. Don't leave users facing blank screens.

- [Empty States](https://www.nngroup.com/articles/empty-state-interface-design/)

### Redundant Status Cues

**ID:** `content-redundant-cues`
**Agent rule (MUST):** Redundant status cues (never color alone) — add a text label, icon, or pattern as a second indicator; icons have text labels. ~8% of males cannot distinguish certain colors
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Don't rely on color alone; include text labels

> Redundant status cues. Don't rely on color alone; include text labels.

Colour is the case everyone knows: WCAG SC 1.4.1 Use of Color, which the Rams review files as a Serious accessibility failure. Roughly 8% of men have some colour vision deficiency — but colour-only status also fails on monochrome displays, in bright sun, and on a printout, so the audience is far wider than the one people picture. The general rule is bigger than colour, though, and it is WCAG SC 1.3.3 Sensory Characteristics: no single sensory channel may carry meaning on its own. Colour is one channel. So is SOUND (an error chime with no on-screen message — see interactions-sound-not-sole-channel), SHAPE ("click the round button"), SIZE, and POSITION ("the panel on the right", "see the box below"), each of which means nothing to a screen reader user, and position means nothing to anyone on a narrow viewport where your two columns just became one. Test it by asking what survives if the channel is removed: greyscale the screen, mute the audio, read the DOM order aloud. Whatever is left must still identify the thing. Always carry the meaning on a second channel: an icon or glyph beside the status colour, a text label on the badge, an underline on the link, a pattern or a direct label on a chart series, a visible message beside the sound, a name beside the "round button". Green alone is not success; green with a checkmark and the word "Success" is.

- [WCAG 1.4.1: Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html)
- [WCAG 1.3.3: Sensory Characteristics](https://www.w3.org/WAI/WCAG21/Understanding/sensory-characteristics.html)
- [Rams design review skill](https://rams.ai/rams.md)

### Use Ellipsis Character

**ID:** `content-ellipsis-character`
**Agent rule (MUST):** Use the ellipsis character `…` (not ``)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use … instead of three periods

> Use the ellipsis character. … over three periods ....

The proper ellipsis character (…) is a single character with correct spacing. Three periods (...) have wider spacing and look unprofessional. Use the real ellipsis character (Unicode U+2026) in all text.

- [Ellipsis](https://en.wikipedia.org/wiki/Ellipsis)

### Anchored Headings

**ID:** `content-anchored-headings`
**Agent rule (MUST):** `scroll-margin-top` on headings for anchored links; include a "Skip to content" link; hierarchical `<h1–h6>`
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set scroll-margin-top for headers when linking to sections

> Anchored headings. Set scroll-margin-top for headers when linking to sections.

When users click anchor links to jump to sections, fixed headers can cover the target heading. Use scroll-margin-top on headings to add offset so they appear below fixed headers. Also provide hierarchical h1-h6 structure and a "Skip to content" link.

- [scroll-margin-top](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/scroll-margin-top)

### Resilient to User-generated Content

**ID:** `content-resilient-ugc`
**Agent rule (MUST):** Resilient to user-generated content (short/avg/very long)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Layouts handle short, average, and very long content

> Resilient to user-generated content. Layouts handle short, average, & very long content.

User-generated content is unpredictable. Test your layouts with short text, average text, and extremely long text without spaces. Use text overflow strategies like ellipsis, word-wrap, or scrolling to handle edge cases gracefully.

- [Text Overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-overflow)

### Locale-aware Formats

**ID:** `content-locale-formats`
**Agent rule (MUST):** Locale-aware dates/times/numbers/currency
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Format dates, times, numbers, and currency for user locale

> Locale-aware formats. Format dates, times, numbers, delimiters, & currencies for the user's locale.

Different regions format data differently (12/31/2024 vs 31.12.2024, $1,000.00 vs 1.000,00€). Use Intl API in JavaScript to format dates, numbers, and currency according to the user's locale automatically.

- [Internationalization API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)

### Accessible Content

**ID:** `content-accessible-content`
**Agent rule (MUST):** Accurate names (`aria-label`), decorative elements `aria-hidden`, verify in the Accessibility Tree
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set accurate names, hide decorations, verify in accessibility tree

> Accessible content. Set accurate names (aria-label), hide decoration (aria-hidden) & verify in the accessibility tree.

Assistive technologies rely on proper ARIA attributes. Give interactive elements descriptive names with aria-label. Hide purely decorative elements with aria-hidden="true". Always test in the accessibility tree to ensure screen readers get meaningful information.

- [ARIA Labels](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
- [Accessibility Tree](https://developer.chrome.com/docs/devtools/accessibility/reference/)

### Semantics Before ARIA

**ID:** `content-semantics-first`
**Agent rule (MUST):** Prefer native semantics (`button`, `a`, `label`, `table`) before ARIA
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer native elements before ARIA attributes

> Semantics before ARIA. Prefer native elements (button, a, label, table), before aria-*.

Native HTML elements have built-in accessibility, keyboard support, and expected behaviors. Use <button> instead of <div role="button">, <a> instead of <span role="link">. Only add ARIA when native elements don't provide the semantics you need.

- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [No ARIA is Better Than Bad ARIA](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/)

### Class Formatting

**ID:** `content-class-formatting`
**Agent rule (SHOULD):** Use prettier-plugin-tailwindcss for automatic class ordering (layout → spacing → typography → colors)
**Source:** Tailwind (https://tailwindcss.com/docs)

Follow consistent class ordering and formatting conventions

> Maintain consistent class ordering: layout → spacing → sizing → typography → colors → effects. Use Prettier plugin for automation.

Consistent class ordering makes code scannable and maintainable. The Prettier plugin for Tailwind CSS automatically sorts classes following the recommended order.

- [Prettier Plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
- [Class Sorting](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier)

### Official Plugins

**ID:** `content-official-plugins`
**Agent rule (SHOULD):** Use official plugins (@tailwindcss/typography for prose, @tailwindcss/forms for inputs)
**Source:** Tailwind (https://tailwindcss.com/docs)

Load the plugins you actually still need with @plugin in CSS, and drop the ones v4 absorbed into core

> Load a plugin from your CSS with the `@plugin` directive: `@plugin "@tailwindcss/typography";`. Note that container queries are now included in the framework by default — the `@tailwindcss/container-queries` plugin is no longer needed.

Two things changed in v4 and stale advice gets both wrong. First, how plugins load: there is no `plugins: []` array, because there is no config file. A plugin is imported from your stylesheet with `@plugin "@tailwindcss/typography";` next to the `@import "tailwindcss"` at the top. Second, and more important, *which* plugins are still plugins. `@tailwindcss/container-queries` is deprecated — container queries are core now, so `@container` and `@md:` work out of the box. Installing that package today does not add a feature; it adds a dead dependency that shadows a built-in and tells the next reader this codebase has not been upgraded. What survives is the stuff that is genuinely opinionated content styling rather than a CSS primitive: `@tailwindcss/typography` for the `prose` classes, which is still the right answer for markdown and CMS output you do not control, and `@tailwindcss/forms` for normalizing native control appearance. Before adding any plugin to a v4 project, check whether core already does it — the same absorption happened to several utilities that used to require a package.

- [Tailwind v4: Functions and directives (@plugin)](https://tailwindcss.com/docs/functions-and-directives)
- [Tailwind v4: Typography plugin](https://tailwindcss.com/docs/typography-plugin)
- [Tailwind CSS v4.0 announcement](https://tailwindcss.com/blog/tailwindcss-v4)

### IDE IntelliSense

**ID:** `content-intellisense`
**Agent rule (SHOULD):** Configure Tailwind CSS IntelliSense extension for autocomplete and invalid class linting
**Source:** Tailwind (https://tailwindcss.com/docs)

Configure IDE extension for autocomplete and linting

> Install and configure Tailwind CSS IntelliSense extension for autocomplete, linting, and hover documentation.

The official Tailwind CSS IntelliSense extension provides autocomplete, syntax highlighting, and linting. It catches errors like non-existent classes and suggests valid utilities.

- [IntelliSense Extension](https://tailwindcss.com/docs/editor-setup#intelli-sense-for-vs-code)
- [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense)

### Images Missing Alt Text

**ID:** `content-rams-alt-text`
**Agent rule (MUST):** All images must have alt attribute - descriptive for informative images, empty alt="" for decorative images. Screen readers announce images; missing alt creates confusion.
**Source:** RAMS (https://www.rams.ai/)

All images must have descriptive alt text for screen reader users

> Images without alt — `<img>` without `alt` attribute

Rams lists this as a Critical accessibility check (WCAG 1.1.1) in its review table; the upstream skill is a checklist, so that terse row is the whole rule. Why it matters: images without alt text are invisible to screen reader users. Decorative images should carry alt="" so they are skipped, while meaningful images need text conveying their content and purpose.

- [rams.md (skill source)](https://rams.ai/rams.md)
- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)

### Skipped Heading Levels

**ID:** `content-rams-heading-levels`
**Agent rule (MUST):** Heading levels must be hierarchical (h1-h6) without skipping levels. Never go from h1 to h3. Screen reader users navigate by headings; skipped levels break navigation.
**Source:** RAMS (https://www.rams.ai/)

Heading levels should not skip (e.g., h1 to h3 without h2)

> Heading hierarchy — Skipped heading levels (h1 to h3)

Rams lists this as a Moderate ("consider fixing") check (WCAG 1.3.1) in its review table; the upstream skill is a checklist, so that terse row is the whole rule. Why it matters: headings create a document outline that screen reader users navigate by. Going from h1 to h3 suggests missing content. Keep the hierarchy sequential.

- [rams.md (skill source)](https://rams.ai/rams.md)
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)

### Links Without Descriptive Text

**ID:** `content-descriptive-link-text`
**Agent rule (MUST):** Link text must describe its destination - avoid generic text like "click here" or "read more". Links should make sense out of context for screen reader link lists.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Links should have descriptive text, not generic phrases like "click here"

> The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general.

WCAG 2.1 Success Criterion 2.4.4 Link Purpose (In Context), Level A. Screen reader users often navigate by pulling up a list of links, stripped of surrounding prose — "click here" and "read more" tell them nothing. Note: this principle previously carried a Rams badge, but Rams has no descriptive-link-text rule (its only link check is "Missing link destination"), so it is now attributed to the WCAG criterion it actually comes from.

- [WCAG 2.1 SC 2.4.4 (Understanding)](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html)
- [WCAG 2.1 SC 2.4.4 (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/#link-purpose-in-context)

### Use text-balance and text-pretty

**ID:** `content-ibelick-text-balance`
**Agent rule (MUST):** Use text-balance for headings (prevents orphans) and text-pretty for body paragraphs (optimizes line breaks). Improves readability without manual tweaking.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use text-balance for headings and text-pretty for body text to improve readability

> MUST use `text-balance` for headings and `text-pretty` for body/paragraphs

From the Typography constraints in ibelick's baseline-ui skill. text-balance evens out line lengths in headings; text-pretty prevents orphans (a single word stranded on the last line) in paragraphs. Both improve readability without hand-managed line breaks. DIRECT CONFLICT, deliberately kept: jakubkrehel's better-typography draws the scope line tighter. It agrees on `balance` for headings, but scopes `pretty` to *descriptions* — short blocks, a card subtitle, a meta line — and rules both out of long-form prose: "Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read." Both positions stand, and the axis is the length of the block. On a two-line heading or a one-sentence description, the browser has few enough lines that rebalancing them is cheap and the orphan is glaring. On an article paragraph, `balance` is a no-op the engine declines to run past a handful of lines, and `pretty` buys an orphan fix by pulling text up from earlier lines, which loosens the whole rag. Take ibelick's rule as the default for UI text, which is nearly all of it, and take jakubkrehel's exception the moment the block is genuinely long-form.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [jakubkrehel — wrapping-and-punctuation.md (the counter-position)](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/wrapping-and-punctuation.md)
- [CSS text-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-wrap)

### Use Tabular Numbers for Data

**ID:** `content-ibelick-tabular-nums`
**Agent rule (MUST):** Use tabular-nums (font-variant-numeric: tabular-nums) for numerical data in tables, counters, and prices. Numbers align in columns without jumping.
**Source:** @Ibelick (https://www.ui-skills.com/)

Always use tabular-nums for numbers in tables and data displays for proper alignment

> MUST use `tabular-nums` for data

From the Typography constraints in ibelick's baseline-ui skill (the Tailwind `tabular-nums` utility maps to font-variant-numeric: tabular-nums). Proportional figures have varying widths, so columns of numbers misalign and counters jitter as they tick. Tabular figures share one advance width, so data tables, prices, and numeric lists line up.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [font-variant-numeric MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-variant-numeric)

### Handle Text Overflow Properly

**ID:** `content-ibelick-text-overflow`
**Agent rule (SHOULD):** Use truncate or line-clamp-* for dense UI to prevent layout breaking. Add title attribute for full text on hover. Long text should never break layout.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use truncate or line-clamp for predictable text overflow in dense layouts

> SHOULD use `truncate` or `line-clamp` for dense UI

From the Typography constraints in ibelick's baseline-ui skill — a SHOULD, not a MUST. User-generated content can be any length; without overflow handling, cards expand unexpectedly and grids break. Use truncate for single lines, line-clamp for a multi-line cap.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Tailwind Line Clamp](https://tailwindcss.com/docs/line-clamp)

### Don't Modify Letter Spacing

**ID:** `content-ibelick-letter-spacing`
**Agent rule (NEVER):** Modify letter-spacing (tracking-*) unless explicitly requested. Default tracking is optimized for readability. Custom tracking often hurts legibility.
**Source:** @Ibelick (https://www.ui-skills.com/)

Avoid changing letter-spacing unless explicitly requested - fonts are designed with proper spacing

> NEVER modify `letter-spacing` (`tracking-*`) unless explicitly requested

From the Typography constraints in ibelick's baseline-ui skill. Type designers craft spacing per weight and optical size; overriding it usually costs readability and reads as amateurish. If the text needs more presence, reach for weight or size before tracking. Counter-view worth reading alongside this: content-tracking-is-size-specific argues from Emil Kowalski's apple-design skill that tracking IS size-dependent at the extremes — display type wants it slightly tighter, caption type slightly looser. The two are not really in conflict: this rule is the correct default for body text, that one is the correction for very large and very small sizes, ideally applied through a variable font's optical-sizing axis rather than a hardcoded value.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Typography Best Practices](https://fonts.google.com/knowledge/using_type)

### Font Smoothing

**ID:** `content-font-smoothing`
**Agent rule (SHOULD):** Apply `-webkit-font-smoothing: antialiased` so subpixel rendering does not make text look heavier than the designed weight.
**Source:** Rauno (https://interfaces.rauno.me/)

Apply -webkit-font-smoothing: antialiased for better text legibility

> Fonts should have -webkit-font-smoothing: antialiased applied for better legibility.

Subpixel antialiasing can make text appear heavier than designed, especially on macOS. Applying antialiased rendering produces text that more closely matches the intended font weight and appears crisper on high-DPI displays.

```tsx
body { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN font-smooth](https://developer.mozilla.org/en-US/docs/Web/CSS/font-smooth)

### Text Rendering Legibility

**ID:** `content-text-rendering`
**Agent rule (SHOULD):** Apply `text-rendering: optimizeLegibility` to enable kerning and ligatures, most visible at heading sizes.
**Source:** Rauno (https://interfaces.rauno.me/)

Apply text-rendering: optimizeLegibility for proper kerning and ligatures

> Fonts should have text-rendering: optimizeLegibility applied for better legibility.

The optimizeLegibility value enables kerning and optional ligatures, improving the visual quality of text, especially at larger font sizes. This is particularly noticeable in letter pairs like AV, WA, and Ty where default spacing can look uneven.

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN text-rendering](https://developer.mozilla.org/en-US/docs/Web/CSS/text-rendering)

### Font Subsetting

**ID:** `content-font-subsetting`
**Agent rule (SHOULD):** Subset webfonts to the alphabets/languages actually used and declare `unicode-range` — full font files ship glyphs you never render.
**Source:** Rauno (https://interfaces.rauno.me/)

Subset fonts based on content, alphabet, or relevant languages to reduce file size

> Fonts should be subset based on the content, alphabet or relevant language(s).

Full font files include glyphs for many languages and scripts you may not need. Subsetting to only the character ranges used on your site can reduce font file sizes by 80-90%, improving load times significantly. Subset into the right container while you are at it: serve `.woff2` on the web and never ship a raw `.ttf` or `.otf`, which carry no web compression and land roughly 30-50% heavier for exactly the same glyphs (jakubkrehel's choosing-fonts calls them "Desktop only unless there is no other option"; `.woff` is a fallback for very old browsers, nothing more).

```tsx
@font-face { font-family: Inter; src: url(/inter-latin.woff2) format("woff2"); unicode-range: U+0000-00FF; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [jakubkrehel — choosing-fonts.md (formats)](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/choosing-fonts.md)
- [Google Fonts CSS2 API](https://developers.google.com/fonts/docs/css2)

### Stable Font Weight on Hover

**ID:** `content-font-weight-hover-stable`
**Agent rule (NEVER):** Change `font-weight` on hover or selected state — bolder text takes more space and reflows its neighbors. Reserve the space up front (or use color/background/opacity instead).
**Source:** Rauno (https://interfaces.rauno.me/)

Font weight should not change on hover or selected state to prevent layout shift

> Font weight should not change on hover or selected state to prevent layout shift.

Changing font weight on hover causes text to take up different amounts of space, which shifts surrounding content. Use color, background, or opacity changes instead to indicate hover and selected states.

```tsx
/* reserve bold width so the label never reflows */
.item::after { content: attr(data-label); font-weight: 600; height: 0; visibility: hidden; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Minimum Font Weight 400

**ID:** `content-min-font-weight`
**Agent rule (NEVER):** Use font weights below 400 — thin and light weights (100–300) hurt readability on low-DPI screens and for low-vision users.
**Source:** Rauno (https://interfaces.rauno.me/)

Font weights below 400 should not be used — they reduce readability

> Font weights below 400 should not be used.

Thin and light font weights (100-300) can be difficult to read, especially on low-resolution screens, small sizes, or for users with visual impairments. Stick to regular (400) and above for body text and UI elements.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Medium Heading Weight

**ID:** `content-heading-weight`
**Agent rule (SHOULD):** Give medium-sized headings a `font-weight` of 500–600; 800–900 reads heavy and disconnected from body text.
**Source:** Rauno (https://interfaces.rauno.me/)

Medium-sized headings look best with font weight between 500-600

> Medium sized headings generally look best with a font weight between 500-600.

Very bold weights (800-900) on medium-sized headings can feel heavy and disconnected from body text. Weights of 500-600 create clear hierarchy while maintaining visual balance with surrounding content.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Fluid Typography with clamp()

**ID:** `content-fluid-clamp`
**Agent rule (SHOULD):** Scale type fluidly with `clamp(min, preferred-vw, max)` instead of stacking font-size breakpoints.
**Source:** Rauno (https://interfaces.rauno.me/)

Use CSS clamp() for fluid font sizes that scale between viewport sizes without breakpoints

> Adjust values fluidly by using CSS clamp(), e.g. clamp(48px, 5vw, 72px) for the font-size of a heading.

Fixed font sizes require multiple breakpoints to look good across devices. CSS clamp() provides a minimum, preferred, and maximum value that scales smoothly with the viewport, creating responsive typography without media queries.

```tsx
h1 { font-size: clamp(48px, 5vw, 72px); }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp)

### Text Size Adjust for iOS

**ID:** `content-text-size-adjust`
**Agent rule (MUST):** Set `-webkit-text-size-adjust: 100%` so iOS Safari does not inflate text on landscape rotation (this still allows user zoom).
**Source:** Rauno (https://interfaces.rauno.me/)

Prevent unexpected text resizing in landscape mode on iOS with -webkit-text-size-adjust: 100%

> Prevent text resizing unexpectedly in landscape mode on iOS with -webkit-text-size-adjust: 100%.

iOS Safari inflates text when rotating to landscape to improve readability. While well-intentioned, this can break carefully designed layouts. Setting text-size-adjust to 100% prevents this behavior while still allowing user zoom.

```tsx
html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN text-size-adjust](https://developer.mozilla.org/en-US/docs/Web/CSS/text-size-adjust)

### Write in Active Voice

**ID:** `content-active-voice`
**Agent rule (MUST):** Write instructions, empty states, and errors in active voice — "Install the CLI", not "The CLI will be installed".
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Lead every instruction with the verb the user performs, not with what happens to them

> Use active voice: "Install the CLI" not "The CLI will be installed."

Passive constructions hide the actor, so the reader has to reconstruct who does what before they can act. Active voice puts the verb first and cuts word count, which matters most in instructions, empty states, and error copy where the user is already stuck.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Voice and Tone](https://developers.google.com/style/voice)

### Title Case for Headings and Buttons

**ID:** `content-title-case`
**Agent rule (SHOULD):** Use Chicago-style Title Case for headings, buttons, and menu items — capitalize principal words, lowercase short articles, conjunctions, and prepositions.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use Chicago-style Title Case consistently for headings, buttons, and menu items

> Headings & buttons use Title Case (Chicago). On marketing pages, use sentence case.

Mixed casing across a single surface makes headings stop reading as headings and buttons look half-finished. Chicago Title Case gives one deterministic rule — capitalize principal words, lowercase short articles, conjunctions, and prepositions — so labels stay predictable as the product grows. The rule is scoped to product UI: marketing pages deliberately invert it and use sentence case, because long persuasive headlines set in Title Case read as shouting. Pick the casing from the surface you are on, then never mix the two within it.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Capitalization](https://developers.google.com/style/capitalization)

### Numerals for Counts

**ID:** `content-numerals-for-counts`
**Agent rule (MUST):** Write counts and quantities as numerals — "8 deployments", not "eight deployments" — so they can be scanned, compared, and aligned.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Write counts and quantities as digits so they can be scanned instead of read

> Use numerals for counts: "8 deployments" not "eight deployments."

Digits have a different visual shape than surrounding words, so the eye locks onto them without parsing the sentence. Spelled-out numbers force serial reading and make values impossible to compare, sort, or align in a stat row or table.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Numbers](https://developers.google.com/style/numbers)

### Specific Button Labels

**ID:** `content-specific-button-labels`
**Agent rule (MUST):** Label buttons with verb plus object ("Save API Key", "Delete Project"), never a generic "Continue" or "OK" — the label is read out of context by a screen reader cycling controls.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Name the action in the button label instead of using generic words like Continue or OK

> Use specific labels: "Save API Key" not "Continue."

A button label is often read out of context — by a screen reader cycling the controls list, or by a user who skipped the body copy. A verb-plus-object label ("Save API Key", "Delete Project") stays meaningful alone and tells the user what will happen before they commit.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: UI Elements](https://developers.google.com/style/ui-elements)

### Errors Include the Fix

**ID:** `content-actionable-errors`
**Agent rule (MUST):** Every error message states the fix, not just the problem: the expected format, the missing permission, or a link/button to the place the user can resolve it.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

State what went wrong, what correct looks like, and give the user the next step

> Error messages should include the fix or next step, not just the problem.

An error that only names the problem ("Invalid input") leaves the user guessing which of several rules they broke. Pair the diagnosis with a concrete remedy — the expected format, the missing permission, a link or button to the place where they can fix it — so the message ends the dead end instead of announcing it.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [NN/g: Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)

### Second Person, Not First

**ID:** `content-second-person-voice`
**Agent rule (SHOULD):** Address the reader as "you" and avoid "we"/"I" in product copy — "your build failed", not "we were unable to complete the build".
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Address the reader as "you" and avoid "we" or "I" in product copy

> Use second person ("you"); avoid first person ("we"/"I").

First-person copy quietly recenters the interface on the company instead of the person trying to finish a task. Second person keeps the subject on the reader — your build, your key, your next step — and usually shortens the sentence, since "we were unable to complete the build" collapses to "your build failed".

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Second Person](https://developers.google.com/style/person)

### Ampersand in Tight Space

**ID:** `content-ampersand-in-tight-space`
**Agent rule (SHOULD):** Use `&` instead of "and" in width-constrained labels (sidebar items, tabs, table headers) so compound labels like "Billing & Invoices" stay on one line; keep "and" in prose.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer "&" over "and" in labels where horizontal space is constrained

> Use "&" over "and" where space is constrained.

Sidebar items, tabs, and table headers have a hard width budget, and "and" spends three characters plus two spaces on a word that carries no meaning the ampersand does not. Swapping it keeps compound labels like "Billing & Invoices" on one line instead of truncating them mid-word or wrapping the row. Keep "and" in prose, where space is not the constraint.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Vercel Design: Writing](https://vercel.com/design/writing)

### Mark Untranslatable Strings

**ID:** `content-translate-no`
**Agent rule (MUST):** Wrap brand names, code tokens, commands, and identifiers in `translate="no"` so browser auto-translate leaves them runnable while the surrounding prose stays translatable.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Wrap brand names, code tokens, and identifiers in translate="no" so machine translation leaves them alone

> Brand names, code tokens, and identifiers: wrap with translate="no" to prevent garbled auto-translation.

Browser auto-translate rewrites every text node it can reach, including shell commands, env var names, and product names, which turns "npm install vercel" into something that does not run. The HTML translate attribute (and Google's equivalent notranslate class) marks those subtrees as off-limits while leaving the surrounding prose translatable.

```tsx
<code translate="no">npm install vercel</code>
```

- [MDN: translate attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/translate)
- [W3C i18n: Using the translate flag](https://www.w3.org/International/questions/qa-translate-flag)

### Detect Language, Not Location

**ID:** `content-language-detection`
**Agent rule (MUST):** Pick the UI language from `Accept-Language` / `navigator.languages`, never from IP geolocation (VPNs, travel, and multilingual countries break that assumption), and still expose an explicit language switcher as the override.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Choose the UI language from Accept-Language or navigator.languages, never from IP geolocation

> Detect the user's language via Accept-Language / navigator.languages, not IP geolocation.

Where a request originates says nothing about what the reader can read: VPNs, travel, corporate proxies, and multilingual countries all break the IP-to-language assumption. Accept-Language and navigator.languages carry the preference the user actually configured, ordered by priority — read those, and still expose an explicit language switcher as the override.

- [MDN: Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language)
- [MDN: navigator.languages](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/languages)
- [W3C i18n: Language priorities](https://www.w3.org/International/questions/qa-lang-priorities)

### Render Images with img, Not background-image

**ID:** `content-image-tag-not-background`
**Agent rule (MUST):** Render content images with `<img>` + meaningful `alt`, never CSS `background-image` — a background has no role, no accessible name, and no "copy image" context menu. Reserve `background-image` for textures and gradients.
**Source:** Rauno (https://interfaces.rauno.me/)

Use an img element for content images so they carry alt text and native save and copy affordances

> Images should always be rendered with the <img> tag rather than a CSS background-image, for screen readers and to preserve right-click "copy image".

A CSS background is decoration as far as the platform is concerned: it has no role, no accessible name, and no context menu entries, so screen readers skip it and users cannot save or copy it. Reserve background-image for textures and gradients, and give anything that is content an img with meaningful alt text (or an empty alt when it is purely decorative).

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN: img element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)
- [W3C WAI: Images tutorial](https://www.w3.org/WAI/tutorials/images/)

### Label HTML Illustrations

**ID:** `content-illustration-label`
**Agent rule (MUST):** Give a div-built illustration or chart `role="img"` + `aria-label` on the wrapper and `aria-hidden="true"` on its inner nodes, so screen readers announce it once instead of walking every group.
**Source:** Rauno (https://interfaces.rauno.me/)

Give an illustration built from HTML an explicit aria-label so it is announced as one image, not as a DOM tree

> Illustrations built with HTML should have an explicit aria-label instead of being announced by screen readers.

A chart or illustration assembled from divs has no single accessible node, so assistive tech walks it element by element and reads out a stream of meaningless groups. Put role="img" plus an aria-label that states what the picture conveys on the wrapper, and mark the inner nodes aria-hidden, so the whole thing collapses into one announcement.

```tsx
<div role="img" aria-label="Revenue grew 40% in Q3">
  <div className="bar" aria-hidden="true" />
</div>
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN: img role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/img_role)
- [ARIA APG: Names and Descriptions](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/)

### Cap the Measure

**ID:** `content-impeccable-line-length`
**Agent rule (MUST):** Cap the measure: give prose containers `max-width: 65ch`–`75ch`. The detector estimates characters per line as `width / (fontSize * 0.5)` and flags anything above 85.
**Source:** impeccable (https://impeccable.style/)

Constrain text containers to 65ch-75ch so the eye can find the start of the next line

> Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers.

Reading is a sequence of saccades ending in a return sweep to the next line. The longer the line, the further that sweep travels and the more often it lands on the wrong one, which is why a full-width paragraph feels tiring even when every word is legible. impeccable's detector estimates characters-per-line as rect.width / (fontSize * 0.5) and flags anything above 85, so a max-width of 65ch to 75ch on the prose container keeps you well clear without constraining the page around it.

- [impeccable](https://impeccable.style/)
- [Practical Typography: Line length](https://practicaltypography.com/line-length.html)
- [MDN: max-width](https://developer.mozilla.org/en-US/docs/Web/CSS/max-width)

### Line Height Below 1.3 Is Unreadable

**ID:** `content-impeccable-tight-leading`
**Agent rule (MUST):** Set body `line-height` to 1.5–1.7 and never below 1.3 (flagged on any non-heading carrying more than 50 characters); derive the whole spacing scale from the resulting line box (16px × 1.5 = 24px).
**Source:** impeccable (https://impeccable.style/)

Set body line-height between 1.5 and 1.7, and derive the spacing scale from it

> Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe.

When lines sit too close, the descenders of one collide with the ascenders of the next and the eye can no longer isolate a single line, so it re-reads. impeccable's detector flags any non-heading element carrying more than 50 characters where lineHeight / fontSize falls below 1.3. The payoff of getting this right is structural, not just cosmetic: the body line box is the base unit of vertical rhythm, so 16px x 1.5 = 24px, and every margin, gap, and section break becomes a multiple of that one number instead of an arbitrary guess.

- [impeccable](https://impeccable.style/)
- [MDN: line-height](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height)
- [Practical Typography: Line spacing](https://practicaltypography.com/line-spacing.html)

### Minimum Readable Body Size

**ID:** `content-impeccable-tiny-text`
**Agent rule (MUST):** Set prose at 14px minimum, 16px ideally, in `rem` so browser font settings still apply — anything under 12px on an element with more than 20 characters of text is a bug. UI chrome (buttons, links, labels, nav, badges, code, captions) is exempt.
**Source:** impeccable (https://impeccable.style/)

Set prose at 14px minimum and 16px ideally, in rem so browser font settings still apply

> Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.

impeccable's detector fires on font-size below 12px only where an element carries more than 20 characters of direct text, and it explicitly excludes UI chrome: buttons, links, labels, nav, footers, badges, code, captions, and uppercase labels. That exclusion is the whole point. A 10px button label is fine; a 10px paragraph of terms of service is the bug. Pair the size floor with rem or em units rather than px, so a reader who raises their default browser font size actually gets larger text.

- [impeccable](https://impeccable.style/)
- [MDN: font-size](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size)
- [WCAG 1.4.4: Resize text](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html)

### Uppercase Is for Labels, Not Prose

**ID:** `content-impeccable-all-caps-body`
**Agent rule (NEVER):** Apply `text-transform: uppercase` to running text — flagged on any non-heading over 30 characters, because capitals erase the word shape readers recognize. Reserve uppercase for short labels and headings, and give those 0.05em–0.12em of letter-spacing.
**Source:** impeccable (https://impeccable.style/)

Keep running text in sentence case and reserve uppercase for short labels and headings

> We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings.

Fluent readers identify words by their silhouette, and capitals flatten every word into the same rectangle, forcing letter-by-letter decoding. impeccable's detector flags text-transform: uppercase on any non-heading element carrying more than 30 characters, which is why the all-caps legal disclaimer, the format chosen precisely to look important, is the one nobody reads. The companion rule matters too: short all-caps labels do need 5-12% letter-spacing (0.05em to 0.12em), because capitals are spaced to sit beside lowercase letters and crowd each other at default tracking.

- [impeccable](https://impeccable.style/)
- [MDN: text-transform](https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform)
- [Practical Typography: All caps](https://practicaltypography.com/all-caps.html)

### Don't Justify Without Hyphenation

**ID:** `content-impeccable-justified-text`
**Agent rule (NEVER):** Ship `text-align: justify` without `hyphens: auto` — stretched word-spacing carves rivers of white through the paragraph. Left-align body text; if a justified column is non-negotiable, set `hyphens: auto` plus a `lang` attribute so the browser has a dictionary.
**Source:** impeccable (https://impeccable.style/)

Left-align body text, or enable hyphens: auto if the design demands a justified column

> Justified text without hyphenation creates uneven word spacing ('rivers of white'). Use text-align: left for body text, or enable hyphens: auto if you must justify.

Browsers justify a line by stretching word-spacing until it reaches both margins. On a narrow measure there are only a few gaps to absorb the slack, so each one grows, and when wide gaps stack across consecutive lines they carve visible vertical channels through the paragraph. impeccable's detector flags exactly the combination text-align: justify where hyphens is not auto. Left alignment sidesteps the problem entirely; hyphens: auto (plus a lang attribute so the browser knows the dictionary) is the escape hatch when a justified column is non-negotiable.

```tsx
p { text-align: justify; hyphens: auto; } /* requires <html lang="en"> */
```

- [impeccable](https://impeccable.style/)
- [MDN: hyphens](https://developer.mozilla.org/en-US/docs/Web/CSS/hyphens)
- [MDN: text-align](https://developer.mozilla.org/en-US/docs/Web/CSS/text-align)

### Fewer Sizes, More Contrast

**ID:** `content-impeccable-type-scale-contrast`
**Agent rule (SHOULD):** Generate every type step from one ratio of at least 1.25 (major third), 1.333, or 1.5 rather than adding near-identical sizes — a page with 3 or more distinct sizes whose largest-to-smallest ratio is under 2.0 has no hierarchy left to squint at.
**Source:** impeccable (https://impeccable.style/)

Generate every step from one ratio of at least 1.25 instead of adding near-identical sizes

> Font sizes are too close together - no clear visual hierarchy. Use fewer sizes with more contrast (aim for at least a 1.25 ratio between steps).

The named failure is "too many font sizes that are too close together (14px, 15px, 16px, 18px...)": each new size was added to solve a local problem and none of them are far enough apart to signal rank, so the page reads as one grey slab. impeccable's detector flags a page with 3 or more distinct sizes whose largest-to-smallest ratio is under 2.0. Pick a single ratio (1.25 major third, 1.333 perfect fourth, or 1.5), generate five steps from it, and the hierarchy survives a squint test.

- [impeccable](https://impeccable.style/)
- [Practical Typography: Type composition](https://practicaltypography.com/type-composition.html)
- [MDN: font-size](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size)

### Em-Dashes Are an AI Tell

**ID:** `content-impeccable-em-dash-overuse`
**Agent rule (SHOULD):** Punctuate with commas, colons, semicolons, periods, or parentheses instead of em-dashes (and never the ASCII `--`) — 5 or more in body text is a machine-written cadence readers register even when each individual dash is defensible.
**Source:** impeccable (https://impeccable.style/)

Punctuate with commas, colons, semicolons, periods, or parentheses instead of em-dashes

> No em dashes. Use commas, colons, semicolons, periods, or parentheses. Also not `--`.

The skill itself bans the em dash outright, but its detector is deliberately lenient: it only fires at 5 or more em-dashes (or the ASCII `--`) in body text. Be accurate about that distinction. A single dash is a style choice; a page where every paragraph pivots on the same mid-sentence interruption has a machine-written cadence, and it is the cadence readers register, not any individual mark. Repunctuating forces you to pick the mark that actually carries the relationship, which varies the rhythm as a side effect.

- [impeccable](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [Practical Typography: Type composition](https://practicaltypography.com/type-composition.html)

### Say What the Product Does

**ID:** `content-impeccable-marketing-buzzwords`
**Agent rule (NEVER):** Ship generic SaaS phrasing — "streamline your", "empower your", "supercharge", "unleash the power", "best-in-class", "industry-leading", "world-class", "enterprise-grade", "next-generation", "cutting-edge", "seamless experience", "harness the power" (~30 blocked phrases, any single hit fires). If the sentence would fit a CRM, a CDN, and a coffee machine equally well, replace it with a specific verb and noun. Same for 3 or more manufactured-contrast lines ("Not a feature. A platform.").
**Source:** impeccable (https://impeccable.style/)

Replace generic SaaS phrases with a specific verb and noun from the actual product

> Generic SaaS phrases (streamline / empower / supercharge / world-class / enterprise-grade / next-generation / cutting-edge / etc) are instant AI tells. Pick a specific verb and noun that says what the product literally does.

impeccable ships a literal blocklist of roughly 30 phrases and fires on any single hit: "streamline your", "empower your", "supercharge your", "unleash the power", "best-in-class", "industry-leading", "world-class", "enterprise-grade", "next-generation", "cutting-edge", "transform your business", "revolutionize", "game-changer", "mission-critical", "future-proof", "seamless experience", "seamlessly integrate", "harness the power", "trusted by leading", "built for the modern". The test is interchangeability: if the sentence would fit a CRM, a CDN, and a coffee machine equally well, it says nothing. A companion detector, aphoristic-cadence, fires at 3 or more manufactured-contrast constructions ("Not a feature. A platform.").

- [impeccable](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [Google Style: Word list](https://developers.google.com/style/word-list)

### Light-on-Dark Text Needs Three Fixes

**ID:** `content-impeccable-dark-mode-text-compensation`
**Agent rule (MUST):** Compensate light-on-dark type on all three axes at once — `line-height` +0.05 to +0.1, `letter-spacing` +0.01em to +0.02em, and optionally one step of body weight — because light glyphs optically bloom. One type spec cannot serve both themes.
**Source:** impeccable (https://impeccable.style/)

Compensate light-on-dark type on line-height, letter-spacing, and weight, not just one

> Light text on dark backgrounds needs compensation on three axes, not just one. Bump line-height by 0.05-0.1, add a touch of letter-spacing (0.01-0.02em), and optionally step the body weight up one notch.

Light glyphs on a dark field optically bloom: the bright strokes spill into the surrounding dark, so the same type reads heavier and tighter than it does inverted. The concrete remedy is all three axes at once - line-height up by 0.05 to 0.1, letter-spacing up by 0.01em to 0.02em, and optionally one step of body weight - because fixing only one leaves the block feeling wrong without telling you why. Ship a single type spec for both themes and one of the two is always mis-set.

- [impeccable](https://impeccable.style/)
- [MDN: letter-spacing](https://developer.mozilla.org/en-US/docs/Web/CSS/letter-spacing)
- [NN/g: Dark mode](https://www.nngroup.com/articles/dark-mode/)

### Don't Ship the Schema

**ID:** `content-dont-ship-schema`
**Agent rule (MUST):** Don't ship the schema—visuals may omit labels but accessible names still exist
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Keep accessible names even when the visual design omits visible labels

> Don’t ship the schema. Visual layouts may omit visible labels, but accessible names/labels still exist for assistive tech.

A dense or minimal layout is free to drop visible labels — a search field can rely on a placeholder, an action row can be icon-only. What it cannot drop is the underlying schema: every control still needs an accessible name in the tree. A placeholder is not a name (it disappears on input and is not reliably announced), and an icon is not a name. Use a visually-hidden `<label>` or `aria-label`, and mark the icon `aria-hidden`. The visual design is a projection of the schema, not a replacement for it.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: Accessible name](https://developer.mozilla.org/en-US/docs/Glossary/Accessible_name)
- [WCAG 2.1: Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)

### Brand Resources from the Logo

**ID:** `content-brand-resources`
**Agent rule (SHOULD):** Right-clicking the nav logo surfaces brand assets
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Surface brand assets from a right-click on the nav logo

> Brand resources from the logo. Right-click the nav logo to surface brand assets for quick access.

People who need your logo — press, partners, conference organizers, someone building an integration — reach for it at the moment they see it, in the nav. If a right-click offers nothing, they screenshot the mark and ship a blurry, recolored, wrongly-cropped version of your brand. Intercepting the context menu on the logo to offer "copy as SVG", "download assets", and a link to the guidelines puts the correct file in their hands exactly when they want it, instead of behind a Footer → About → Press Kit hunt.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: contextmenu event](https://developer.mozilla.org/en-US/docs/Web/API/Element/contextmenu_event)

### Be Clear and Concise

**ID:** `content-be-concise`
**Agent rule (MUST):** Write the sentence, then delete words until deleting one more would change the meaning. Cut padding phrases ("in order to", "please note that", "at this time"); keep the nouns and the verb, drop the ceremony.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Cut every word that does not change the meaning, then ship the shortest version that still says it

> Be clear & concise. Use as few words as possible.

Nobody reads interface copy — they scan it, and every extra word is another thing to skip past before the action becomes visible. Padding phrases ("in order to", "please note that", "at this time") add length without adding information, and on a button they push the verb past the point where the eye stops. Write the sentence, then delete words until deleting one more would change what it means. Concise is not terse: keep the nouns and the verb, drop the ceremony.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Plain Language: Be Concise](https://www.plainlanguage.gov/guidelines/concise/)
- [Microsoft Style: Simple Words, Concise Sentences](https://learn.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences)

### Keep Nouns Consistent

**ID:** `content-consistent-nouns`
**Agent rule (MUST):** Name each object once and reuse that exact noun in every label, heading, toast, and error — project/app/site/deployment for one concept reads as four things. Introduce as few unique terms as possible and keep a glossary.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Name each object once and reuse that exact noun everywhere it appears in the product

> Keep nouns consistent. Introduce as few unique terms as possible.

When one screen calls the same object a project, an app, a site, and a deployment, the reader has to decide whether those are four things or one — and the safe assumption is four. Synonyms feel like good writing and behave like a bug: they break search, they break the mental model, and they make docs, support replies, and API names drift apart. Pick one noun per concept, write it in a glossary, and use it in every label, heading, toast, and error until the concept itself changes.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [NN/g: Consistency and Standards](https://www.nngroup.com/articles/consistency-and-standards/)
- [Google Style: Word List](https://developers.google.com/style/word-list)

### Consistent Placeholders in Samples

**ID:** `content-consistent-placeholders`
**Agent rule (MUST):** Use one loud, obviously-fake placeholder convention across all code samples — `YOUR_API_TOKEN_HERE` for strings, `0123456789` for numbers — never a mix of `<your-token>` / `xxx` / `abc123` / `[INSERT KEY]`. (This is about fill-me-in tokens in docs, not the HTML `placeholder` attribute.)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use one placeholder convention across every code sample: YOUR_API_TOKEN_HERE for strings, 0123456789 for numbers

> Use consistent placeholders. Strings: YOUR_API_TOKEN_HERE. Numbers: 0123456789.

This is about the fill-me-in tokens inside documentation and code samples, not the HTML placeholder attribute on an input — that one is covered by the separate rule against using a placeholder as a label or a value. When a snippet mixes <your-token>, xxx, abc123, and [INSERT KEY], the reader cannot tell which strings are literal and which are theirs, so they paste a sample verbatim and get a 401. A single loud, obviously-fake convention — screaming snake case for strings, a monotone digit run for numbers — is unmistakably a slot, greppable, and safe to search-and-replace across a whole page.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Placeholders](https://developers.google.com/style/placeholders)

### Consistent Currency Formatting

**ID:** `content-currency-formatting`
**Agent rule (MUST):** Pick 0 or 2 decimal places per context and format every amount that way, including round ones — never mix `$12` with `$8.50` in one column. Pair with tabular figures and right alignment so decimal separators stack.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Pick 0 or 2 decimal places for a given context and apply it to every amount, never mixing the two

> Consistent currency formatting. In any given context, display currency with either 0 or 2 decimal places, never mix both.

A column that reads $12, $8.50, $1,204, $99.00 forces the eye to re-parse each row: the decimal point lands in a different place every time, so the digits no longer line up and the magnitudes stop being comparable at a glance. Choose the precision the context needs — whole dollars for a pricing page, cents for an invoice — and format every amount that way, including the round ones. Pair the choice with tabular figures and right alignment so the decimal separators stack into a single vertical line.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Microsoft Style: Numbers](https://learn.microsoft.com/en-us/style-guide/numbers)
- [Google Style: Numbers](https://developers.google.com/style/numbers)

### Default to Positive Language

**ID:** `content-positive-language`
**Agent rule (SHOULD):** Frame messages around what can be done next, not what the person did wrong — drop "you failed to", "invalid", "aborted". Stay specific about the cause and the limit; positive framing is a change of frame, not a loss of detail.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Frame messages around what can be done next rather than what the person did wrong

> Default to positive language. Frame messages in an encouraging, problem-solving way, even for errors.

This is about framing and tone, not content: the separate rule on actionable errors says the message must include the fix, while this one says the sentence around that fix must not read as an accusation. "You failed to upload" and "Operation aborted" blame the reader and describe a dead end, which is both unpleasant and useless. Same facts, constructive frame: name what happened without a culprit, then point forward. Positive framing is not vagueness — stay specific about the cause and the limit, just drop the "you failed", the "invalid", and the "aborted".

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Google Style: Tone and Voice](https://developers.google.com/style/tone)
- [NN/g: Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)

### Loading Copy Sets an Expectation

**ID:** `content-impeccable-loading-copy-expectation`
**Agent rule (SHOULD):** Name the work and its expected duration inside a loading state ("Analyzing your data… this usually takes 30–60 seconds") instead of a bare "Loading…", which says the same thing at 1s and at 90s so the user cannot tell working from hung. Show a signal that advances, and give anything past ~10s an escape hatch.
**Source:** impeccable (https://impeccable.style/)

Name the work being done and how long it usually takes, instead of shipping a bare "Loading…"

> Bad: 'Loading…' (for 30+ seconds). Good: 'Analyzing your data… this usually takes 30-60 seconds.'

The corpus already governs how a loading state looks — stable skeletons, matched dimensions, a minimum display duration — but nothing until now governed the words inside it, and the words are what carry the expectation. "Loading…" is a dead end: it says the same thing at one second and at ninety, so on a long job the user cannot distinguish "still working" from "hung", and the rational move becomes reloading the page and losing the work. Name the work ("Importing 1,240 rows"), state the expected duration ("this usually takes about a minute"), and show a signal that advances. Anything past ten seconds also needs an escape hatch, because a bounded wait the user chose to abandon is far better than an unbounded one they had to guess about.

- [impeccable — clarify](https://impeccable.style/)
- [NN/g: Progress Indicators](https://www.nngroup.com/articles/progress-indicators/)
- [NN/g: Response Times — The 3 Important Limits](https://www.nngroup.com/articles/response-times-3-important-limits/)

### Frame Progress as Milestones, Not Remaining Work

**ID:** `content-progress-as-milestones`
**Agent rule (SHOULD):** Chunk long task lists into a handful of named phases and show the current one ("Complete Phase 1 of 4") rather than leading with remaining work ("10 / 47 tasks complete"), which makes the 37 unfinished items the salient fact. Collapse finished phases into a done marker; keep the honest total reachable, just do not lead with it.
**Source:** Custom

Group a long task list into named phases so progress reads as ground gained rather than debt outstanding

> Showing '10 / 47 tasks complete' immediately communicates that 37 tasks remain… 'Complete Phase 1 of 4' is psychologically very different — it frames the same progress as achievable milestones rather than an endless checklist.

This one comes from Josh Puckett's Interface Craft, and it is purely about framing: the underlying progress is identical, only the sentence changes. "10 / 47 complete" is mathematically accurate and motivationally hostile — it makes the 37 unfinished items the salient fact, and each completed task moves the bar by two percent, which reads as futility. Chunk the same work into a handful of named phases, show only the current one, and collapse finished phases into a done marker so the remaining work visibly shrinks as the user advances. Keep the honest total reachable for anyone who wants it, but do not lead with it.

- [Josh Puckett — Interface Craft](https://interfacecraft.dev/)
- [Laws of UX: Goal-Gradient Effect](https://lawsofux.com/goal-gradient-effect/)
- [NN/g: Progress Indicators](https://www.nngroup.com/articles/progress-indicators/)

### Survive User Text Spacing

**ID:** `content-text-spacing-override`
**Agent rule (MUST):** Text containers must survive user-applied `line-height: 1.5`, `letter-spacing: 0.12em`, `word-spacing: 0.16em` and 2× paragraph spacing with no loss of content — WCAG SC 1.4.12 Text Spacing, Level AA. The failure is the box, not the type: fixed `height` + `overflow: hidden` slices the last line off. Size with `min-height` and padding, let flex/grid tracks size to content, and never clip text you mean to be read.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Size text containers so nothing is lost when the user overrides line, letter, word, and paragraph spacing

> In content implemented using markup languages that support the following text style properties, no loss of content or functionality occurs by setting all of the following and by changing no other style property: Line height (line spacing) to at least 1.5 times the font size; Spacing following paragraphs to at least 2 times the font size; Letter spacing (tracking) to at least 0.12 times the font size; Word spacing to at least 0.16 times the font size.

SC 1.4.12 Text Spacing (Level AA) is not about the spacing you choose — content-ibelick-letter-spacing and content-impeccable-tight-leading cover that. It is about what happens when a reader with low vision or dyslexia overrides your choice with a user stylesheet, a bookmarklet, or a reading extension, and sets line-height to 1.5x the font size, spacing after paragraphs to 2x, letter-spacing to 0.12em, and word-spacing to 0.16em, all at once. The typical failure is not the type: it is the box. A container with a fixed height plus overflow: hidden cannot grow, so the last line is sliced off mid-glyph and the content is simply gone — a "no loss of content" failure, not a cosmetic one. Fix it by sizing with min-height and padding instead of height, letting flex and grid tracks size to content, and never clipping text you intend the user to read. Test it by applying the four values to the whole page and looking for clipped, truncated, or overlapping text.

```tsx
/* clips at 1.5 line-height */ .card { height: 96px; overflow: hidden; }
/* grows with the user's spacing */ .card { min-height: 96px; padding-block: 12px; }
```

- [Understanding SC 1.4.12: Text Spacing](https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html)
- [MDN: min-height](https://developer.mozilla.org/en-US/docs/Web/CSS/min-height)

### Never Let aria-label Contradict Visible Text

**ID:** `content-aria-label-overrides-visible-text`
**Agent rule (NEVER):** Give a control an `aria-label` that contradicts or omits its visible text — on any role that names from child content, `aria-label` REPLACES that text, so `<button aria-label="Submit form">Save</button>` answers only to "Submit form" and a voice-control user saying "click Save" hits nothing (WCAG SC 2.5.3 Label in Name, Level A requires the accessible name to contain the visible string). Name from child content; use `aria-labelledby` to point at visible text elsewhere; reserve `aria-label` for controls with no visible text. Extending is fine — `aria-label="Save draft"` on a button reading "Save".
**Source:** ARIA (https://www.w3.org/WAI/ARIA/apg/)

Take the accessible name from the visible text; if both exist, the name must contain the visible string

> When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces it with the value of aria-label. [...] Rule 2: Prefer Visible Text — when a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements.

This is the mismatch case, and it is distinct from every neighbouring rule in the corpus. content-dont-ship-schema and content-icons-have-labels (and interactions-rams-aria-labels) cover the inverse problem: an icon-only control with no visible text, where aria-label is exactly right. Here the control already has text. On a button, div, link, or any role that supports naming from child content, aria-label does not add to that text — it replaces it, hiding the child content from assistive technology. So <button aria-label="Submit form">Save</button> is a button that reads "Save" and answers to "Submit form". A voice-control user who says "click Save" hits nothing, which is why WCAG SC 2.5.3 Label in Name (Level A) requires the accessible name to contain the visible label text. Prefer naming from child content; when you need to reference text elsewhere, use aria-labelledby pointing at the visible element. Reserve aria-label for controls with no visible text at all, and if you must extend a name, keep the visible string inside it (aria-label="Save draft" on a button reading "Save" is fine).

- [APG: Providing Accessible Names and Descriptions](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/)
- [Understanding SC 2.5.3: Label in Name](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name.html)

### Lists Are ul/li, Tables Are th/td

**ID:** `content-list-and-table-semantics`
**Agent rule (MUST):** Lists are `<ul>`/`<ol>` + `<li>`; tables are `<table>` with `<th scope="col|row">` for headers. A `<div className="space-y-2">` of divs announces nothing — no "list, 5 items", no way to skip it — and a div grid with a bold header row reads a cell as a naked "42" instead of "Revenue, Q3, 42". Bold is not a header. Tailwind's `list-none` drops the marker without dropping the semantics, so there is no styling reason to use divs.
**Source:** @Ibelick (https://www.ui-skills.com/)

A stack of divs looks like a list and a grid of divs looks like a table, but neither announces any structure to a screen reader

> lists must use ul or ol with li

These are the two most common div-soup offences in generated markup, because a `<div className="space-y-2">` of `<div>`s and a flexbox grid with a bold header row *look* exactly right. What they lose is everything a non-visual user navigates by. A real `<ul>` announces "list, 5 items" and gives the reader a way to jump to the next item or skip the list entirely; a stack of divs announces nothing, and the reader has no idea how much is left. The table case is worse, because the loss is per-cell: ibelick's companion rule is "tables must use th for headers when applicable", and a `<th scope="col">` is what makes a screen reader read a cell in the middle of the grid as "Revenue, Q3, 42" instead of a naked "42" with no idea which column or row it belongs to. That association cannot be recovered from visual weight — bold is not a header. content-semantics-first states the principle in general; this is what it actually costs in the two places it is most often ignored. Note that Tailwind's `list-none` removes the marker without removing the semantics, so there is no styling reason to reach for divs.

- [ibelick — fixing-accessibility SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-accessibility/SKILL.md)
- [MDN — <th> element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/th)
- [W3C — Web Accessibility Tutorials: Tables](https://www.w3.org/WAI/tutorials/tables/)

### Bound Your clamp()

**ID:** `content-impeccable-fluid-type-bounds`
**Agent rule (SHOULD):** Bound every `clamp()`: max-size <= ~2.5x min-size. `clamp(1rem, 5vw, 6rem)` is a 6x span that renders the heading at body size on a phone and shouts at 1400px, and a bare `vw` middle term ignores the reader's font-size preference — add a rem offset (`clamp(1.5rem, 1.2rem + 1.5vw, 2.5rem)`, a 1.7x range) to put zoom and reflow back in the calculation. Second half of the rule: do NOT use fluid type in product UI at all — Material, Polaris, Primer and Carbon all ship fixed rem scales, because dense container-based layouts need spatial predictability. Fluid type is for headings and display text on marketing/content pages; body copy stays fixed even there.
**Source:** impeccable (https://impeccable.style/)

Keep the max at most ~2.5x the min — and keep fluid type out of product UI entirely

> Bound your clamp(): keep max-size ≤ ~2.5 × min-size. Wider ratios break the browser's zoom and reflow behaviour and make large viewports feel like the page is shouting.

This extends `content-fluid-clamp`, which teaches the clamp() technique but sets no bounds on it. The bound is the whole rule: max-size <= ~2.5 x min-size. `clamp(1rem, 5vw, 6rem)` spans 16px to 96px — a 6x ratio — and it is absurd at both ends: at 320px the heading renders at its 16px floor, identical to the body text it is supposed to outrank, and at 1400px it is shouting. A ratio that wide also breaks zoom and reflow, because the viewport unit in the middle term ignores the reader's font-size preference; adding a rem offset (`clamp(1.5rem, 1.2rem + 1.5vw, 2.5rem)` — a 1.7x range) puts that preference back into the calculation. The second half of the rule is the one people miss: do not use fluid type in product UI at all. No major app design system does — Material, Polaris, Primer and Carbon all ship fixed rem scales with optional breakpoint adjustments — because a dense, container-based layout needs spatial predictability, and an h1 that shrinks when the sidebar opens looks worse, not better. Fluid type belongs to headings and display text on marketing and content pages where text dominates the layout. Body copy stays fixed even there, since the size difference across viewports is too small to be worth it.

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [MDN — clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp)

### Never Ship a Broken Image

**ID:** `content-impeccable-broken-image`
**Agent rule (NEVER):** Ship an `<img>` with an empty, missing, or placeholder `src` — it renders the browser's broken-image box. The value is rarely a literal; it is `user.avatar` and the CMS returned null, so `<img src={undefined} />` compiles, type-checks, passes review, and breaks for every record missing the field. Two failure modes, two guards: MISSING URL — guard the RENDER, do not emit an `<img>` at all, ship a real fallback (initials avatar, skeleton, neutral box); URL THAT 404s — guard the NETWORK with `onError` and swap in the same fallback. Reserve identical dimensions for both, or the swap adds a layout shift on top of the bug you just fixed.
**Source:** impeccable (https://impeccable.style/)

Guard the render and guard the network — an <img> with no resolvable src ships as a broken-image box

> <img> tags with empty src, missing src, or placeholder values ship as broken-image boxes. Use real images, generated assets, or remove the tag.

The detector catches three shapes: `<img src="">` (also `src=" "` and `src="#"`), an `<img>` with no `src` attribute at all, and a src that is a placeholder rather than a real asset. It is the most trivial rule in impeccable's registry and it reaches production constantly, because the value is usually not a literal — it is `user.avatar` or `post.cover`, and the CMS returned null. React then omits the attribute entirely, so `<img src={undefined} />` compiles, type-checks, passes review, and renders the browser's broken-image chrome to every user whose record happens to be missing that field. There are two distinct failure modes and each needs its own guard. Missing URL: guard the RENDER — if there is no src, do not emit an `<img>`; ship a real fallback instead (an initials avatar, a skeleton, a neutral placeholder box) so the layout is intact and the meaning still reads. URL that fails to load: guard the NETWORK — a remote src can be present and still 404, so attach `onError` and swap in the same fallback the moment the browser gives up. Reserve identical dimensions for image and fallback, or the swap introduces a layout shift on top of the broken image you just fixed.

- [impeccable.style](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [MDN — <img>: The Image Embed element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img)

### No Synthetic Weights or Italics

**ID:** `content-no-synthetic-weights`
**Agent rule (MUST):** Set `font-synthesis: none` on the root so a weight or style you never loaded fails visibly instead of being faked. The browser draws a missing bold as the 400 outlines doubled a hair apart and a missing italic as a `skewX` on the roman — neither looks broken enough to file a ticket, so the missing files ship. The fix is always the same: load the file you asked for.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Set font-synthesis: none so a missing bold or italic file fails visibly instead of being faked

> When a weight or style is not loaded, the browser synthesizes it. That is a safety mechanism, not a feature. Set `font-synthesis: none` so missing files fail visibly instead of rendering a faked bold or italic.

Synthesis is the browser covering for you, and it covers so competently that the bug never surfaces. Ask for a bold the `@font-face` block never loaded and you do not get an error — you get the 400 outlines drawn twice, a hair apart, so the stems thicken and the counters clog. Ask for an italic and you get a `skewX` on the roman: a mechanical slant, not an italic, with no redrawn single-storey `a` and no descending `f`. Neither looks broken enough to file a ticket, so the missing files ship and every heading in the product is quietly mush. `font-synthesis: none` on the root removes the safety net: the `<strong>` renders at plain 400, which is unmistakably wrong, which is the point — it fails in review instead of in production. The fix is then always the same, load the file you actually asked for.

```tsx
html { font-synthesis: none; }
```

- [jakubkrehel — better-typography SKILL.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/SKILL.md)
- [jakubkrehel — variable-fonts-and-opentype.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/variable-fonts-and-opentype.md)
- [MDN — font-synthesis](https://developer.mozilla.org/en-US/docs/Web/CSS/font-synthesis)

### Properties Over Raw Font Tags

**ID:** `content-font-properties-over-tags`
**Agent rule (MUST):** Use the CSS PROPERTY whenever one exists — `font-weight: 650`, `font-optical-sizing: auto`, `font-variant-numeric: tabular-nums` — not `font-variation-settings: "wght" 650` / `font-feature-settings: "tnum" 1`. Raw-tag declarations address axes that only exist inside the variable file, so when a non-variable fallback renders they SILENTLY DO NOTHING (weight collapses to 400, no console error). And `font-feature-settings` is ONE property, so a later declaration CLOBBERS an earlier one — add `"ss01" 1` to a rule that carried `"tnum" 1` and the tabular figures leave with it. Reserve the raw tags for custom axes (`"GRAD" 80`) and niche features (`"ss01" 1`) that have no property of their own.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Reach for font-weight and font-variant-numeric, not font-variation-settings and font-feature-settings

> When a CSS property exists, use it. `font-weight: 650` instead of `font-variation-settings: "wght" 650`, `font-optical-sizing: auto` instead of `"opsz"`, `font-variant-numeric: tabular-nums` instead of `font-feature-settings: "tnum" 1`. Properties keep working when a non-variable fallback renders. Reserve the raw-tag properties for custom axes (`"GRAD" 80`) and niche features (`"ss01" 1`) that have no property of their own.

This is an API rule, not a typography rule, and it is the one people get wrong precisely because both spellings look equivalent while the variable font is loading fine. They are not. `font-variation-settings: "wght" 650` addresses an axis that only exists inside a variable file, so the moment the fallback stack renders — the file 404s, the CDN is blocked, the user is on a metered connection with fonts disabled — the declaration is not overridden, it is inert. The weight collapses to 400, the console says nothing, and the semibold heading you designed is now body copy. `font-weight: 650` is a real property that every font stack understands: the browser picks the closest available face and the hierarchy survives. The same asymmetry applies below the surface for features: `font-feature-settings` is a single low-level property rather than a set of independent switches, so the day someone adds `"ss01" 1` to a rule that already carried `"tnum" 1`, the tabular figures leave with it and the ticker starts jittering again. `font-variant-numeric: tabular-nums` cannot be clobbered that way, because it lives on its own property. Note this is orthogonal to content-tabular-numbers, which says *what* to apply and never *which API* — this is the rule that picks the API. Raw tags are not banned; they are the escape hatch, and the only correct use of them, for custom axes like `"GRAD" 80` and niche features like `"ss01" 1` that have no property of their own.

```tsx
/* ✗ inert under a non-variable fallback; "tnum" clobbered by the next rule */
.price { font-variation-settings: "wght" 650; font-feature-settings: "tnum" 1; }
/* ✓ real properties, survive the fallback, cannot clobber each other */
.price { font-weight: 650; font-variant-numeric: tabular-nums; font-feature-settings: "ss01" 1; }
```

- [jakubkrehel — better-typography SKILL.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/SKILL.md)
- [jakubkrehel — variable-fonts-and-opentype.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/variable-fonts-and-opentype.md)
- [MDN — font-variant-numeric](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-variant-numeric)
- [MDN — font-weight](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-weight)

### Heading Sizes Descend with Level

**ID:** `content-heading-size-descends`
**Agent rule (MUST):** Pick the heading tag from the document outline and the size from a DESCENDING step of the type scale — a lower level must never render larger than a higher one on the same page. Never reach for a tag because it "looks right". Adjacent levels may share a size at the small end if weight or spacing keeps them distinct; a line that must be the loudest thing on the card without owning a rank is a `<p>` at display size. Distinct from `content-rams-heading-levels`, which is about SKIPPING levels (a11y outline) — here the tags are sequential and lint passes, but the render contradicts them.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Map every heading level to a descending step of the scale so a lower level never renders larger than a higher one

> Map each heading level used on a page to a descending step of the type scale: a lower level must never render larger than a higher one on the same page. Adjacent levels may share a size toward the small end of the scale as long as weight or spacing keeps them distinct. Pick the tag from the document outline and control the size with CSS; never skip levels or reach for an `h4` because it "looks right".

This is a different failure from content-rams-heading-levels, and worth separating carefully. That rule is about SKIPPING levels — h1 straight to h3 — which lint catches and WCAG 1.3.1 names. This one is the inverse-SIZE failure, and every tag in it is sequential, so the lint passes: an `<h2>` set at `text-base` because it looked right in the card, wrapping an `<h3>` at `text-2xl` because that was the line the designer wanted read first. The tags are legal; the render contradicts them. A screen reader navigates the outline and hears "Revenue up 12%" as subordinate to "Q3 report"; the page says the opposite, in twice the pixels. Whenever a child level renders larger than its parent, the tag was picked for its default size instead of from the document structure. Take the tag from the outline, take the size from a descending step of the scale, and when a line genuinely needs to be the loudest thing on the card without owning a rank, make it a `<p>` at display size — it can be as big as it likes and it stays out of the outline entirely.

- [jakubkrehel — better-typography SKILL.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/SKILL.md)
- [jakubkrehel — spacing-and-sizing.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/spacing-and-sizing.md)
- [MDN — Heading elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements)

### Truncate Without Losing the Value

**ID:** `content-truncation-keeps-value`
**Agent rule (MUST):** If the text an ellipsis hides discriminates rather than decorates, keep the full value reachable — a `title` (which also lands in the accessible name), a tooltip, an expanded view, or middle truncation that pins the discriminating tail (`invoice-2026-…-final-v2.pdf`) and collapses the boring head. Hover-only tooltips are not enough on their own: keyboard and touch users never trigger them, so pair them with something focusable.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

If the text an ellipsis hides carries meaning, keep the full value reachable in a tooltip or an expanded view

> Truncation hides content, so if the missing text matters, keep the full value reachable in a tooltip or expanded view.

Two neighbouring rules already cover the mechanics and neither covers this. content-ibelick-text-overflow says to USE `truncate` or `line-clamp` in dense UI; layout-min-width-truncation makes truncation actually WORK inside a flex or grid child. Both are about the ellipsis appearing where it should. This rule is about what the ellipsis ate. A file column that renders `invoice-2026-q3-a…` on every row has not shortened three filenames, it has deleted the only part that told them apart, and the user is left choosing an invoice by its byte count. So: decide whether the hidden text is decoration or discrimination. If it discriminates, keep it reachable — a `title` (which also lands in the accessible name), a tooltip, a details view, or middle truncation that pins the tail (`invoice-2026-…-final-v2.pdf`) and collapses the boring head instead. Hover-only tooltips are not enough on their own, since keyboard and touch users never trigger them, so pair them with something focusable or an expand toggle.

- [jakubkrehel — better-typography SKILL.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/SKILL.md)
- [jakubkrehel — wrapping-and-punctuation.md](https://raw.githubusercontent.com/jakubkrehel/skills/main/skills/better-typography/wrapping-and-punctuation.md)
- [MDN — text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-overflow)
- [MDN — title attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title)

### Tracking Is Size-Specific

**ID:** `content-tracking-is-size-specific`
**Agent rule (SHOULD):** Do not ship one `letter-spacing` for all sizes. Leave body near 0, tighten display type (~ -0.02em at 36px+), and give small caps/captions a small positive nudge. Prefer a variable font's optical-sizing axis (`font-optical-sizing: auto`) over a hardcoded value. This refines, not contradicts, "don't track body text".
**Source:** Emil Kowalski (https://emilkowalski.com/)

Tighten letter-spacing as display type grows and leave body near zero — a single tracking value is wrong at some size

> Tracking (letter-spacing) is size-specific — never one value for all sizes. Large display text wants negative tracking; small text wants slightly positive tracking for legibility. Tighten headings, leave body near 0.

From the typography section of Emil Kowalski's apple-design skill, and it sits in DELIBERATE TENSION with content-ibelick-letter-spacing, which says never touch tracking unless asked. The corpus keeps both, because they are right about different sizes. ibelick's rule protects body text, where a face was hinted for reading and any manual tracking almost always makes it worse — that is the common case and the safe default. Emil's rule is about the extremes a text-optimised face was never spaced for: at display sizes (36px and up) the designer-intended spacing reads too loose, the letters drift apart, and the headline stops cohering, so it wants slightly NEGATIVE tracking; at caption sizes (11–12px) it wants a touch POSITIVE to hold the glyphs apart. The honest reconciliation is that the best tool is not manual tracking at all but optical sizing — `font-optical-sizing: auto` on a variable font with an `opsz` axis corrects spacing, contrast and detail per size automatically, which is exactly what "type is designed with proper spacing" should mean end to end. Reach for a manual `letter-spacing` step only when the face has no `opsz` axis. So: never randomly track body (that is ibelick's rule intact), do correct display and caption, and prefer `opsz` over a hardcoded value. Related: content-impeccable-type-scale-contrast, content-heading-size-descends, content-leading-tracks-size (its line-height counterpart).

```tsx
h1 { font-size: 48px; letter-spacing: -0.02em; }
.caption { font-size: 11px; letter-spacing: 0.04em; }
body { font-optical-sizing: auto; }
```

- [Emil Kowalski — apple-design SKILL.md](https://raw.githubusercontent.com/emilkowalski/skills/main/skills/apple-design/SKILL.md)
- [MDN — font-optical-sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing)
- [MDN — letter-spacing](https://developer.mozilla.org/en-US/docs/Web/CSS/letter-spacing)

### Leading Tightens as Size Grows

**ID:** `content-leading-tracks-size`
**Agent rule (SHOULD):** Set line-height inversely to font size — do not inherit one ratio everywhere. Large display type wants ~1.0–1.2 so wrapped lines cohere; body wants ~1.5–1.7. Give scripts with tall ascenders/descenders more, dense data UI less. Pair each type-scale step with its own ratio.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Set line-height inversely to font size — tight on large headings, generous on body — instead of one ratio for everything

> Leading (line-height) tracks size inversely. Tight on large headings, looser on body copy. Increase it for scripts with tall ascenders/descenders; tighten it for dense, information-heavy UI.

From the typography section of Emil Kowalski's apple-design skill, and the complement to content-impeccable-tight-leading rather than a repeat of it. That rule sets the FLOOR — body copy wants 1.5 to 1.7 so lines do not crowd. This rule is about the slope: as size climbs, the ratio must come DOWN. The reason is that line-height is proportional, so a 1.5 that is perfect at 16px body becomes 72px of leading on a 48px headline — the two lines of a wrapped title drift so far apart they read as unrelated rows instead of one heading. Large display type wants roughly 1.0 to 1.2; a bare 1 is often right for a single-line hero. Because unitless line-height inherits as a multiplier, the practical implementation is a scale that pairs each size step with its own ratio, not one global `line-height` on `body`. Two edge cases from the source: scripts with tall ascenders and descenders (and any mixed-language UI) need MORE leading than Latin at the same size, and dense information UI (tables, compact lists) can go tighter than prose. Related: content-heading-size-descends, content-impeccable-type-scale-contrast, content-tracking-is-size-specific (its letter-spacing counterpart).

```tsx
h1 { font-size: 48px; line-height: 1.1; }
p  { font-size: 16px; line-height: 1.6; }
```

- [Emil Kowalski — apple-design SKILL.md](https://raw.githubusercontent.com/emilkowalski/skills/main/skills/apple-design/SKILL.md)
- [MDN — line-height](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height)

### Legible Text on Translucent Surfaces

**ID:** `content-vibrant-text-on-translucent`
**Agent rule (SHOULD):** Text over a `backdrop-filter` surface faces a background whose luminance changes as content scrolls. Raise contrast and weight, nudge letter-spacing up slightly, and keep the opacity/color on a SOLID backing layer while the text itself stays fully opaque — never fade the text with the surface.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Over a blurred or translucent surface, raise text contrast and weight and keep color on a solid layer — flat gray text vanishes as the backdrop shifts

> Vibrancy keeps text legible over changing backgrounds. Over blurred/translucent surfaces, don't use flat gray text — use higher-contrast, slightly heavier weight, and a small letter-spacing bump. Put color on a solid layer, not the translucent foreground.

From the vibrancy section of Emil Kowalski's apple-design skill, and it fills the gap between two rules the corpus already has about translucent surfaces. design-impeccable-no-glassmorphism decides WHEN glass is justified (only over content that genuinely scrolls behind it); design-reduced-transparency-contrast handles the accessibility fallback (go solid under prefers-reduced-transparency). Neither says how to make the text on the glass readable once you have decided to keep it — and that is the hard part, because a `backdrop-filter` surface shows whatever is behind it, so the luminance under any given word changes as the user scrolls. A muted gray tuned against one section of the page becomes unreadable over the next. Apple's answer is "vibrancy": foreground text that adapts to what it sits on. On the web you approximate it deliberately — raise the contrast (secondary text on glass should read closer to primary than it would on a solid card), add a touch of weight, and nudge letter-spacing up a hair so thin strokes survive the blur. The load-bearing detail is the last clause: keep any color and the opacity on a SOLID backing layer behind the text, and render the text itself fully opaque on top — never fade the text with the surface, or it dims exactly where the background is busiest. Related: content-impeccable-dark-mode-text-compensation (the same weight/spacing compensation for light-on-dark), design-minimum-contrast.

```tsx
.glass { background: rgba(20,18,28,0.55); backdrop-filter: blur(8px); }
.glass p { color: #fff; font-weight: 600; letter-spacing: 0.01em; }
```

- [Emil Kowalski — apple-design SKILL.md](https://raw.githubusercontent.com/emilkowalski/skills/main/skills/apple-design/SKILL.md)
- [Apple HIG — Materials (vibrancy)](https://developer.apple.com/design/human-interface-guidelines/materials)
- [MDN — backdrop-filter](https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter)

### Canvas and WebGL Need an Accessible Fallback

**ID:** `content-canvas-accessible-fallback`
**Agent rule (MUST):** A <canvas> (2D or WebGL) is an opaque bitmap to assistive tech. Name it (role="img" + aria-label stating the data, or descriptive fallback children between the tags), mirror any interactive 3D objects in real focusable DOM with an announcer, and provide the same information without the canvas (a data table, a static-image fallback where WebGL is absent).
**Source:** Web Platform (https://web.dev/)

A <canvas> renders pixels the accessibility tree cannot see — give it a name, fallback content, and a non-canvas path to the same information

> A canvas is an opaque bitmap to assistive technology. Provide fallback content inside the element, give interactive 3D objects a parallel focusable DOM layer with an announcer, and offer the same information without the canvas.

Distilled from the Poimandres react-three-a11y docs and the MDN canvas-accessibility guidance, and it is the hardest surface content-accessible-content and content-icons-have-labels ever point at. A `<canvas>` — 2D or WebGL — is a single flat bitmap to a screen reader: every bar in the chart, every clickable region, every label you painted is invisible and unreachable, because none of it is in the DOM. Three fixes stack, in order of effort. First, name the surface: a static visualisation takes `role="img"` plus an `aria-label` that states what it shows ("Revenue by quarter: Q1 $12k, Q2 $18k…"), and any markup placed BETWEEN the `<canvas>` tags is both the legacy no-canvas fallback and what AT reads. Second, for anything interactive, mirror it in real focusable DOM — WebGL objects cannot take Tab focus or receive key events, which is exactly why react-three-a11y injects a parallel HTML layer and an announcer node beside the R3F canvas. Third, provide the information without the canvas at all: a data table behind the chart, and a static image where WebGL is unavailable (the progressive-enhancement half — see performance-webgl-gpu-budget for the runtime side). The test is the corpus's standard one: turn the visual off and check the accessibility tree still answers what the picture said.

```tsx
<canvas role="img" aria-label="Revenue by quarter: Q1 $12k, Q2 $18k, Q3 $15k, Q4 $24k" />
{/* plus a visually-hidden <table> with the same data */}
```

- [Poimandres — react-three-a11y](https://github.com/pmndrs/react-three-a11y)
- [MDN — Canvas accessibility concerns](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Hit_regions_and_accessibility)
- [WCAG 1.1.1 — Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)

### Three Dashes, Three Jobs

**ID:** `content-dash-taxonomy`
**Agent rule (SHOULD):** Use the correct dash: hyphen (-) for compounds, en dash (–) for ranges and connections (2020–2024, pages 10–20), em dash (—) for sentence-level breaks. A hyphen in a range is a typesetting error. In JSX use the real UTF-8 character or a named entity — a \u2013 escape renders literally in a text node. (Use dashes sparingly per content-impeccable-em-dash-overuse; this is about picking the right one when you do.)
**Source:** Custom

Hyphen joins compounds, en dash spans ranges (1–10), em dash breaks a sentence — one glyph for all three is a typographic error

> The hyphen, en dash, and em dash are different characters with different jobs. Hyphen: compound words. En dash: ranges and connections. Em dash: sentence-level breaks. (Matthew Butterick, Practical Typography)

The keyboard has one dash key; English needs three characters. A hyphen (-) joins compounds — well-known, sign-in. An en dash (–) spans ranges and connections and reads as "to" or "through": 2020–2024, pages 10–20, the New York–London route. A hyphen in a range (2020-2024) is one of the most common tells that text was never typeset. An em dash (—) marks a sentence-level break. The distinction is invisible until it is wrong, at which point it quietly says "nobody set this type." A tension worth naming, because the corpus holds both: content-impeccable-em-dash-overuse warns that leaning on em dashes reads as an AI tell and pushes you toward commas, colons, and parentheses — that rule is about FREQUENCY, this one is about CORRECTNESS, and they agree. Use dashes sparingly; but when a range needs one, make it an en dash, not a hyphen. In JSX, use the real UTF-8 character or a named entity — a `\u2013` escape renders literally inside a text node. Neighbour to content-typographic-quotes and content-ellipsis-character: the same "use the designed character, not the typewriter approximation" instinct.

```tsx
2020–2024  {/* en dash, not 2020-2024 */}
pages 10–20  {/* en dash */}
well-known  {/* hyphen: compound */}
```

- [Butterick — Practical Typography: hyphens & dashes](https://practicaltypography.com/hyphens-and-dashes.html)
- [bencium — typography skill (Butterick-derived)](https://skills.sh/bencium/bencium-marketplace/ui-typography)
- [MDN — en dash / em dash](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Character_references)

### Real Symbols, Not ASCII Look-alikes

**ID:** `content-math-symbol-glyphs`
**Agent rule (SHOULD):** Use real typographic symbols, not ASCII look-alikes: × (U+00D7) for multiplication not the letter x, − (U+2212) for minus not a hyphen, and © ™ ® not (c) / (TM) / (R). The substitutes read as unfinished and can be ambiguous in data and dimensions.
**Source:** Custom

Use ×, −, © ™ ® for multiplication, minus, and marks — not the letter x, a hyphen, or (c) / (TM) / (R)

> Use real typographic symbols, not ASCII substitutes. Multiplication is ×, not x. Minus is −, not a hyphen. Use © ™ ® not (c) (TM) (R). (Matthew Butterick, Practical Typography)

The letter x is not a multiplication sign, a hyphen is not a minus, and "(c)" is not a copyright symbol — they are ASCII stand-ins from an era of 95 printable characters, and Unicode retired the excuse decades ago. "1920 x 1080" should be "1920 × 1080" (× is `&times;` / U+00D7); "-40°" should carry a real minus "−40°" (− is U+2212, which has the correct width and, unlike a hyphen, will not line-break away from its number); and (c) / (TM) / (R) should be © ™ ® (`&copy;` `&trade;` `&reg;`). The substitutes are legible but read as unfinished, and in dimensions or data they are genuinely ambiguous — is "2 x 3" a product or a variable named x? This is the same rule as content-typographic-quotes and content-ellipsis-character, just the less-remembered corner of it: reach for the character that was designed for the job, not the one that happened to be on a 1970s keyboard.

```tsx
1920 × 1080   {/* not 1920 x 1080 */}
−40°C         {/* U+2212, not a hyphen */}
© 2026 · Pro™
```

- [Butterick — Practical Typography: math symbols](https://practicaltypography.com/math-symbols.html)
- [bencium — typography skill (html entities)](https://skills.sh/bencium/bencium-marketplace/ui-typography)
- [MDN — Character references](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Character_references)

### One Emphasis Signal at a Time

**ID:** `content-emphasis-one-signal`
**Agent rule (SHOULD):** Emphasize with bold OR italic, never both on the same text, and never underline for emphasis — on the web underline means link. Reserve underline for links, bold for strong emphasis, italic for titles/terms/mild stress, each used alone. Stacking emphasis markers cancels the contrast they exist to create.
**Source:** Custom

Emphasize with bold OR italic, never both at once, and never with underline — on the web, underline means link

> Bold and italic are mutually exclusive — never combine them. Never underline for emphasis; underlining is a typewriter workaround and, on the web, means a link. (Matthew Butterick, Practical Typography)

Emphasis is a contrast, and contrast only works while it is scarce. Stacking bold and italic on the same words does not make them twice as important — it makes the line look like it is shouting and spends the next level of emphasis you might have needed later. Pick one: bold for strong emphasis, italic for titles, terms, and mild stress. Underline is worse than redundant on the web, because it is the near-universal signal for a link: underlining for emphasis trains users to click text that does nothing, and it collides with design-underline-from-font, which is about styling the underline on actual links. Reserve underline for links, and use bold and italic one at a time. This is the character-formatting version of the over-signalling failure the corpus flags elsewhere (design-ibelick-color-restraint for accent colour, content-impeccable-em-dash-overuse for punctuation): more emphasis markers do not add emphasis, they cancel it.

```tsx
<strong>important</strong> · <em>term</em> · <a href="…">link</a>
// not: <span class="font-bold italic underline">…</span>
```

- [Butterick — Practical Typography: bold or italic](https://practicaltypography.com/bold-or-italic.html)
- [bencium — typography skill (Butterick-derived)](https://skills.sh/bencium/bencium-marketplace/ui-typography)

### Don't Center Body Text

**ID:** `content-no-centered-body`
**Agent rule (SHOULD):** Set running body text flush-left (ragged right) so the eye returns to one fixed edge each line. Centered text moves every line's start and makes the reader hunt for it — acceptable only for short, deliberate lines (a hero, a pull quote), never for paragraphs.
**Source:** Custom

Center a heading or a short line if you must, but set running paragraphs flush-left — centered body makes the eye hunt for each line's start

> Don't center body text. Centered text has no consistent left edge, so the reader must find the start of every line. (Matthew Butterick, Practical Typography)

Reading is a loop: the eye sweeps left to right, then flicks back to a KNOWN horizontal position to begin the next line. Flush-left text keeps that return point fixed, so the flick is automatic and unconscious. Centered text moves the start of every line, so the reader has to visually hunt for where each one begins — tolerable for a two-line hero or a pull quote, genuinely tiring across a paragraph. A centered column of body copy is a reliable tell of template or AI layout: it looked "balanced" in the mock and reads like work at length. Set running text flush-left with a ragged right edge, and reserve centring for short, deliberate lines. This is distinct from content-impeccable-justified-text, which is about the RIGHT edge (do not justify without hyphenation); this rule is about the left edge existing at all.

```tsx
<p class="text-left">…paragraph…</p>   {/* not text-center */}
```

- [Butterick — Practical Typography: centered text](https://practicaltypography.com/centered-text.html)
- [bencium — typography skill (Butterick-derived)](https://skills.sh/bencium/bencium-marketplace/ui-typography)

---

## Forms

Form controls, validation, and user input handling. 27 rules.

### Enter Submits

**ID:** `forms-enter-submits`
**Agent rule (MUST):** Enter submits focused text input
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

When a text input is focused, Enter should submit the form if it's the only control

> Enter submits. When a text input is focused, Enter submits if it's the only control. If there are many controls, apply to the last control.

Users expect pressing Enter in a form field to submit the form. This is a fundamental web convention that improves efficiency and meets user expectations. For single-input forms like search boxes or login fields, this should work from any input. For multi-field forms, Enter should submit when focus is on the last input.

- [WAI-ARIA Authoring Patterns](https://www.w3.org/WAI/ARIA/apg/)

### Textarea Behavior

**ID:** `forms-textarea-behavior`
**Agent rule (MUST):** In `<textarea>`, ⌘/Ctrl+Enter submits; Enter adds newline
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

In textarea, Enter should insert a new line while Cmd/Ctrl+Enter submits

> Textarea behavior. In <textarea>, ⌘/⌃+Enter submits; Enter inserts a new line.

Textareas are for multi-line input, so Enter must create new lines. Users who want to submit can use the keyboard modifier (Cmd on Mac, Ctrl on Windows/Linux) plus Enter. This prevents accidental submission when writing paragraphs.

- [HTML textarea element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/textarea)

### Labels Everywhere

**ID:** `forms-labels-everywhere`
**Agent rule (MUST):** Every control has a <label> or is associated with a label for assistive tech
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Every form control must have a visible label or accessible name

> Labels everywhere. Every control has a <label> or is associated with a label for assistive tech.

Labels are crucial for accessibility. Screen reader users need labels to understand what each form field is for. Sighted users benefit from clear labels too. Use the <label> element with the "for" attribute pointing to the input's id, or wrap the input inside the label.

- [MDN: Label element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label)
- [WebAIM: Creating Accessible Forms](https://webaim.org/techniques/forms/)

### Label Activation

**ID:** `forms-label-activation`
**Agent rule (MUST):** Clicking a <label> focuses the associated control
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Clicking a label should focus its associated input

> Label activation. Clicking a <label> focuses the associated control.

When labels are properly associated with their inputs, clicking the label text focuses the input. This increases the clickable area and improves usability, especially for checkboxes and radio buttons which have small hit targets.

- [MDN: Label element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label)

### Submission Rule

**ID:** `forms-submission-rule`
**Agent rule (MUST):** Keep submit enabled until request starts; then disable, show spinner, use idempotency key
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Keep submit button enabled until submission starts, then disable with loading state

> Submission rule. Keep submit enabled until submission starts; then disable during the in-flight request, show a spinner, & include an idempotency key.

Pre-disabling submit buttons prevents users from discovering validation errors. Let them try to submit, then show what needs fixing. Once submission starts, disable the button and show a loading indicator to prevent double submissions. Use idempotency keys on the backend to handle accidental duplicate requests.

- [Idempotency](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent)

### Don't Block Typing

**ID:** `forms-dont-block-typing`
**Agent rule (MUST):** Don't block typing; accept free text and validate after
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Allow all input and show validation feedback instead of blocking keystrokes

> Don't block typing. Even if a field only accepts numbers, allow any input & show validation feedback. Blocking keystrokes entirely is confusing because the user gets no explanation.

When you prevent users from typing certain characters, they don't understand why their keyboard isn't working. It's better to accept all input and provide clear validation messages that explain what format is expected.

- [Form Validation UX](https://www.nngroup.com/articles/errors-forms-design-guidelines/)

### Don't Pre-disable Submit

**ID:** `forms-dont-pre-disable-submit`
**Agent rule (MUST):** Allow submitting incomplete forms to surface validation
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Allow submitting incomplete forms to surface validation feedback

> Don't pre-disable submit. Allow submitting incomplete forms to surface validation feedback.

When the submit button is disabled before the user has tried to submit, they can't discover what's wrong with their form. Enable the button, let them click it, then show comprehensive validation feedback that guides them to fix all issues.

- [Form validation UX](https://www.smashingmagazine.com/2022/09/inline-validation-web-forms-ux/)

### Error Placement

**ID:** `forms-error-placement`
**Agent rule (MUST):** Errors inline next to fields; on submit, focus first error
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Show errors next to their fields and focus the first error on submit

> Error placement. Show errors next to their fields; on submit, focus the first error.

Errors should appear immediately adjacent to the field they relate to. When a form is submitted with errors, automatically focus the first problematic field so users can start fixing issues immediately. This is especially important for long forms.

- [WebAIM: Accessible Form Validation](https://webaim.org/techniques/formvalidation/)

### Autocomplete & Names

**ID:** `forms-autocomplete`
**Agent rule (MUST):** `autocomplete` + meaningful `name`; correct `type` and `inputmode`
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set autocomplete and meaningful name values to enable browser autofill

> Autocomplete & names. Set autocomplete & meaningful name values to enable autofill.

Modern browsers can autofill form data, saving users time. Use the autocomplete attribute with standard values like "email", "tel", "street-address", etc. Also use semantic name attributes. This helps password managers and other assistive tools.

- [HTML autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete)

### Spellcheck Selectively

**ID:** `forms-spellcheck`
**Agent rule (SHOULD):** Disable spellcheck for emails/codes/usernames
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Disable spellcheck for emails, codes, usernames, etc.

> Spellcheck selectively. Disable for emails, codes, usernames, etc.

Spellcheck is helpful for prose content but annoying for technical input. Email addresses, usernames, codes, and similar fields should have spellcheck="false" to prevent red squiggly underlines on valid input.

- [HTML spellcheck attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/spellcheck)

### Correct Types & Input Modes

**ID:** `forms-correct-types`
**Agent rule (MUST):** Use correct `type` and `inputmode` for better keyboards & validation
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use the right type and inputmode for better keyboards and validation

> Correct types & input modes. Use the right type & inputmode for better keyboards & validation.

Mobile devices show different keyboards based on the input type and inputmode. Use type="email" for emails, type="tel" for phones, inputmode="numeric" for numbers, etc. This provides users with the most relevant keyboard layout.

- [HTML input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input)
- [inputmode attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inputmode)

### Placeholder Value

**ID:** `forms-placeholder-value`
**Agent rule (SHOULD):** Placeholders end with ellipsis and show example pattern (eg, `+1 (123) 456-7890`, `sk-012345…`)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set placeholder to an example value or pattern, ending with ellipsis

> Placeholders signal emptiness. End with an ellipsis. Placeholder value. Set placeholder to an example value or pattern e.g., +1 (123) 456-7890 & sk-012345679…

Placeholders should show example values, not labels (that's what <label> is for). The ellipsis signals that the value continues or represents a pattern. For example: "name@example.com" or "sk-proj_abc123…"

- [Placeholder vs Label](https://www.nngroup.com/articles/form-design-placeholders/)

### Unsaved Changes

**ID:** `forms-unsaved-changes`
**Agent rule (MUST):** Warn on unsaved changes before navigation
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Warn before navigation when data could be lost

> Unsaved changes. Warn before navigation when data could be lost.

Track form modifications and show a confirmation dialog if the user tries to navigate away or close the tab with unsaved changes. Use the beforeunload event for page unload and custom logic for in-app navigation.

- [beforeunload event](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event)

### No Dead Zones on Controls

**ID:** `forms-no-dead-zones`
**Agent rule (MUST):** No dead zones on checkboxes/radios; label+control share one generous hit target
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Checkboxes and radios share hit target with labels

> No dead zones on controls. Checkboxes & radios avoid dead zones; the label & control share a single generous hit target.

Small checkboxes and radio buttons are hard to click. Make the entire label clickable by properly associating it with the input. This creates a much larger, more forgiving hit target and improves usability.

- [Form Labels](https://www.w3.org/WAI/tutorials/forms/labels/)

### Password Managers & 2FA

**ID:** `forms-password-managers`
**Agent rule (MUST):** Compatible with password managers & 2FA; allow pasting one-time codes
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Ensure compatibility and allow pasting one-time codes

> Password managers & 2FA. Ensure compatibility & allow pasting one-time codes.

Don't block password managers or prevent pasting in password/2FA code fields. Use appropriate autocomplete values (current-password, new-password, one-time-code) to help password managers function correctly.

- [Autocomplete for Credentials](https://web.dev/articles/sign-in-form-best-practices)

### Use tailwind-merge

**ID:** `forms-tailwind-merge`
**Agent rule (MUST):** Use tailwind-merge for components accepting className props to ensure override classes win
**Source:** Tailwind (https://tailwindcss.com/docs)

Use tailwind-merge for intelligent class conflict resolution

> Use tailwind-merge to intelligently merge Tailwind CSS classes, resolving conflicts without style duplication.

When combining base component styles with variant or override classes, tailwind-merge ensures the last conflicting class wins. This is essential for reusable components that accept className props.

- [tailwind-merge](https://github.com/dcastil/tailwind-merge)
- [Why tailwind-merge](https://github.com/dcastil/tailwind-merge/blob/main/docs/what-is-it-for.md)

### cn() Utility Pattern

**ID:** `forms-cn-utility`
**Agent rule (SHOULD):** Create cn() utility combining clsx + tailwind-merge for conditional class merging
**Source:** Tailwind (https://tailwindcss.com/docs)

Create a cn() utility combining clsx and tailwind-merge

> Combine clsx for conditional classes with tailwind-merge for conflict resolution in a single cn() utility function.

The cn() utility is a standard pattern that combines clsx (for conditional class logic) with tailwind-merge (for conflict resolution). This provides the best of both worlds for component styling.

- [shadcn/ui cn()](https://ui.shadcn.com/docs/installation/manual#add-a-cn-helper)
- [clsx](https://github.com/lukeed/clsx)

### Form Inputs Missing Labels

**ID:** `forms-rams-form-labels`
**Agent rule (MUST):** Every form input must have associated <label> with htmlFor, be wrapped by <label>, or have aria-label. Placeholder is not a substitute for labels.
**Source:** RAMS (https://www.rams.ai/)

All form inputs must have associated labels

> Form inputs without labels — `<input>`, `<select>`, `<textarea>` without associated `<label>` or `aria-label`

Rams lists this as a Critical accessibility check (WCAG 1.3.1) in its review table; the upstream skill is a checklist, so that terse row is the whole rule. Why it matters: the label is what a screen reader announces on focus, and what a click target extends to. Placeholder text is not a substitute — it disappears the moment the user types.

- [rams.md (skill source)](https://rams.ai/rams.md)
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)

### Use cn() Utility for Class Merging

**ID:** `forms-ibelick-cn-utility`
**Agent rule (MUST):** Use cn utility (clsx + tailwind-merge) for conditional class logic. Handles class conflicts, falsy values, and array inputs cleanly.
**Source:** @Ibelick (https://www.ui-skills.com/)

Always use the cn() utility (clsx + tailwind-merge) for conditional and merged class names

> MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic

From the Stack constraints in ibelick's baseline-ui skill. Naive string concatenation leaves both sides of a conflict in the class list (p-4 and p-2), and the winner is decided by stylesheet order, not by intent. cn() combines clsx for conditional logic with tailwind-merge for last-one-wins conflict resolution.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [tailwind-merge](https://github.com/dcastil/tailwind-merge)

### Show Errors Where the Action Happens

**ID:** `forms-ibelick-error-placement`
**Agent rule (MUST):** Show errors inline next to where the action happens. Disconnected toasts or top-of-form error summaries force users to hunt for problems.
**Source:** @Ibelick (https://www.ui-skills.com/)

Put each error next to the thing that caused it: field errors on their field, submit errors by the submit button

> MUST show errors next to where the action happens

From the Interaction constraints in ibelick's baseline-ui skill. "Where the action happens" is deliberately general and resolves per error: a validation error on the email field happened at the field, so it belongs under the field (wired with aria-describedby and aria-invalid); a submit failure — the request was rejected or the network died — happened at the button, so it belongs by the button. The anti-pattern is a detached error: a summary parked at the top of the page, or a toast that fires and vanishes, leaving nothing next to the control the user was actually touching. Read this as the placement rule that generalizes forms-error-placement (Vercel: "Errors inline next to fields"), not as a competitor to it — Vercel names the field case, ibelick names the whole family.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Form Error Handling](https://www.nngroup.com/articles/errors-forms-design-guidelines/)

### Never Block Paste

**ID:** `forms-ibelick-no-paste-blocking`
**Agent rule (NEVER):** Block paste in input or textarea elements. Users paste from password managers, notes, and other sources. Blocking paste creates friction and security issues.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never prevent users from pasting into form fields - it breaks password managers and accessibility

> NEVER block paste in `input` or `textarea` elements

From the Interaction constraints in ibelick's baseline-ui skill. Blocking paste breaks password managers (which is how strong, unique passwords get used at all), blocks users with motor disabilities who rely on assistive input, and forces people to retype sensitive data by hand — where they make errors and pick weaker values.

- [baseline-ui (skill source)](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Why Paste Blocking Hurts Security](https://www.troyhunt.com/the-cobra-effect-that-is-disabling/)

### Input Decorations Positioning

**ID:** `forms-input-decorations-positioning`
**Agent rule (MUST):** Absolutely position input prefix/suffix icons on top of the input and pad the input around them — do not place them as flex siblings. Clicking a decoration must focus the input.
**Source:** Rauno (https://interfaces.rauno.me/)

Input prefix and suffix decorations should be absolutely positioned inside the input with padding, not next to it

> Input prefix and suffix decorations, such as icons, should be absolutely positioned on top of the text input with padding, not next to it, and trigger focus on the input.

When decorative elements like search icons or currency symbols are placed next to an input in a flex layout, clicking them doesn't focus the input. Position them absolutely inside the input container so the entire area is clickable and the input receives focus.

```tsx
<div className="relative">
  <SearchIcon className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2" />
  <input className="pl-9" />
</div>
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Lean on Native Constraint Validation

**ID:** `forms-native-validation`
**Agent rule (SHOULD):** Lean on native constraint validation (`required`, `type="email"`, `pattern`, `min`, `minlength`) instead of hand-rolled JS checks; drop `noValidate` and reach for `setCustomValidity` only for rules HTML cannot express.
**Source:** Rauno (https://interfaces.rauno.me/)

Use required, type, pattern, min and max so the browser validates instead of hand-rolling every check in JS

> Inputs should leverage HTML form validation by using the `required` attribute when appropriate.

The platform already ships constraint validation: required, type="email", pattern, min, max and minlength are enforced by the browser on every submit path — click, Enter, autofill, programmatic — and it focuses the first offending control and announces the message to assistive tech for free. Hand-rolled JS checks miss those paths (a keyup handler never fires on a mouse paste), and hand-rolled email regexes routinely reject valid addresses like ada+work@example.com. Keep the submit button enabled and drop noValidate; reach for the Constraint Validation API (setCustomValidity, ValidityState) only for the rules HTML cannot express.

- [MDN: required attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/required)
- [MDN: Client-side form validation](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation)
- [MDN: ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState)

### Trim Text Expansions

**ID:** `forms-text-replacements`
**Agent rule (MUST):** Trim values to handle text expansion trailing spaces
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Trim input values so invisible whitespace never fails validation

> Text replacements & expansions. Some input methods add trailing whitespace. The input should trim the value to avoid showing a confusing error message.

Autocorrect, keyboard text-expansion snippets, password managers, and copy-paste from a spreadsheet all routinely append a trailing space. The value looks correct on screen, so when validation rejects it the user is told their own email or coupon code is invalid with nothing visibly wrong — an error with no discoverable fix. Trim before validating. Prefer trimming on blur or submit rather than on every keystroke, so you do not delete a space the moment a user legitimately types one.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: String.prototype.trim()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trim)

### Do Not Summon Password Managers on Non-Auth Fields

**ID:** `forms-no-password-manager-nonauth`
**Agent rule (MUST):** Keep reserved names (`password`) and `type="password"` off non-auth fields — password managers run heuristics over `type`/`name`/`id` and will park a credential dropdown over your search results. Give filters boring names (`q`, `filter`, `search`) with `type="search"` and `autocomplete="off"`; give OTP fields `autocomplete="one-time-code"` and `inputmode="numeric"`. This is the narrow inverse of the autofill rules, which still apply to real credential and address fields.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Keep reserved names off search and filter inputs, and claim a specific autocomplete token for OTP

> Don't trigger password managers for non-auth fields. For inputs like "Search" avoid reserved names (e.g., password), use autocomplete="off" or a specific token like autocomplete="one-time-code" for OTP fields.

This is the narrow inverse of the autofill rules, not a contradiction of them: on a real credential or address field you want the manager to fire, with meaningful autocomplete tokens and no paste blocking. This rule is about the fields that are not auth. Password managers do not read your intent — they run heuristics over type, name, and id, so a filter box that happens to be called "password" or an OTP input masked as type="password" gets a credential dropdown parked on top of the results the user was trying to read, plus a "save this login?" prompt for a code that expires in 30 seconds. Give non-auth fields boring names (q, filter, search), set type="search", and add autocomplete="off"; give OTP fields autocomplete="one-time-code" and inputmode="numeric" so the OS offers the SMS code instead of a stored password.

```tsx
<input type="search" name="q" autocomplete="off" />
<input name="otp" autocomplete="one-time-code" inputMode="numeric" />
```

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: The autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete)

### No Redundant Entry

**ID:** `forms-redundant-entry`
**Agent rule (MUST):** Within one process (checkout, signup, application), never ask for information the user already entered: auto-populate it, or make it selectable — a "same as shipping" checkbox, a dropdown of addresses already given, or the value shown next to the field. WCAG SC 3.3.7 Redundant Entry, Level A. Browser autofill does NOT satisfy it (that is SC 1.3.5); "re-enter your email to confirm" is the classic violation. Exceptions are narrow: essential re-entry, security, or stale data.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Never ask for the same information twice in one process: auto-populate it, or let the user select it

> Information previously entered by or provided to the user that is required to be entered again in the same process is either: auto-populated, or available for the user to select. Except when: re-entering the information is essential, the information is required to ensure the security of the content, or previously entered information is no longer valid.

SC 3.3.7 Redundant Entry (Level A, WCAG 2.2) is about a single process — one checkout, one signup, one application — not about sessions. That is what separates it from forms-autocomplete, which is about the autocomplete attribute and browser autofill across visits (SC 1.3.5 Identify Input Purpose). The Understanding document is explicit that browser autofill does not satisfy this criterion: the content itself must carry the value forward. So a step-2 billing form that is an empty duplicate of the step-1 shipping form fails, even if every field is perfectly marked up for autofill. Satisfy it by auto-populating the second form, or by making the value available to select — a "same as shipping" checkbox, a dropdown of addresses already entered, or the value visibly printed next to the field so it can be copied. "Re-enter your email to confirm" is the classic violation: it exists to catch typos, but the previous value is right there on the page, so show it instead of demanding it again. The exceptions are narrow: re-entry that is essential (a password, a memory test), security-required re-entry, or data that has gone stale.

- [Understanding SC 3.3.7: Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html)
- [Understanding SC 1.3.5: Identify Input Purpose](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html)

### Link Errors to Fields Programmatically

**ID:** `forms-error-programmatic-association`
**Agent rule (MUST):** An invalid field must set `aria-invalid="true"` and point `aria-describedby` at its message. `aria-describedby` takes a space-separated LIST of ids — keep BOTH the persistent hint id and the error id; overwriting the hint with the error on validation is the common bug, and it makes the field stop explaining itself the moment it goes wrong. Orthogonal to `forms-ibelick-error-placement` (which governs WHERE the message sits): a well-placed error that is not associated still fails.
**Source:** @Ibelick (https://www.ui-skills.com/)

An error is not an error until the field points at it: set aria-invalid on the input and list the error and helper text ids in aria-describedby

> errors must be linked to fields using aria-describedby; invalid fields must set aria-invalid; helper text must be associated with inputs

From the forms and errors rules in ibelick's fixing-accessibility skill. This is the rule that red text alone cannot satisfy. `<input id="email" /><span>Invalid email</span>` renders a perfectly visible error and communicates nothing to the accessibility tree: the input still computes as valid, its accessible description is empty, and a screen-reader user who tabs back to the field to fix it hears the label and nothing else. Two attributes close the gap. `aria-invalid="true"` flips the field's computed state, so the error is announced as a property of the control rather than as loose text somewhere on the page. `aria-describedby` attaches the message — and it takes a space-separated LIST of ids, which is the detail people get wrong. A field usually has two things to say: a persistent hint ("We only email you about your account") and a transient error. The common bug is to overwrite the hint id with the error id on validation, so the moment the field goes invalid the user stops hearing why it exists. Keep both: `aria-describedby="email-err email-hint"`. This is orthogonal to forms-ibelick-error-placement, which governs WHERE the message sits visually ("where the action happens"); this one governs whether the message is LINKED to the control at all, wherever it sits. A correctly placed error that is not associated still fails, and an associated error still needs to be placed well.

```tsx
<input id="email" aria-invalid={!!err} aria-describedby={err ? "email-err email-hint" : "email-hint"} />
<p id="email-err">Enter a valid email address</p>
<p id="email-hint">We only email you about your account</p>
```

- [fixing-accessibility (skill source)](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-accessibility/SKILL.md)
- [MDN: aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby)
- [MDN: aria-invalid](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid)
- [Understanding SC 3.3.1: Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html)

---

## Performance

Optimization techniques and rendering efficiency. 35 rules.

### Minimize Re-renders

**ID:** `performance-minimize-rerenders`
**Agent rule (MUST):** Track and minimize re-renders (React DevTools/React Scan)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Minimize and make re-renders fast

> Track re-renders. Minimize & make re-renders fast. Use React DevTools or React Scan.

Excessive re-renders slow down the UI, especially in controlled inputs. Use React.memo, useMemo, and useCallback judiciously. Profile with React DevTools to identify components that re-render unnecessarily.

- [React Performance](https://react.dev/learn/render-and-commit)
- [React DevTools](https://react.dev/learn/react-developer-tools)

### Large Lists

**ID:** `performance-large-lists`
**Agent rule (MUST):** Virtualize large lists (eg, `virtua`)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Virtualize large lists or use content-visibility

> Large lists. Virtualize large lists e.g., virtua or content-visibility: auto.

Rendering thousands of DOM nodes causes performance issues. Use virtualization libraries that only render visible items, or use CSS content-visibility: auto to let the browser skip rendering off-screen content.

- [content-visibility](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/content-visibility)
- [List Virtualization](https://web.dev/articles/virtualize-long-lists-react-window)

### No Image-caused CLS

**ID:** `performance-no-image-cls`
**Agent rule (MUST):** Prevent CLS from images (explicit dimensions or reserved space)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set explicit image dimensions and reserve space

> No image-caused CLS. Set explicit image dimensions & reserve space.

Images without dimensions cause layout shift when they load. Always set width and height attributes (or use aspect-ratio in CSS) so the browser can reserve the correct space before the image downloads.

- [Image Aspect Ratio](https://web.dev/articles/optimize-cls)
- [Cumulative Layout Shift](https://web.dev/articles/cls)

### Preload Fonts

**ID:** `performance-preload-fonts`
**Agent rule (MUST):** Preload fonts for critical text to avoid flash & layout shift
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Preload critical fonts to avoid flash and layout shift

> Preload fonts. For critical text to avoid flash & layout shift.

Font files take time to download, causing FOUT (flash of unstyled text) or FOIT (flash of invisible text). Preload critical fonts used for above-the-fold content using <link rel="preload"> to load them as early as possible.

- [Preloading Fonts](https://web.dev/articles/optimize-webfont-loading)

### Device/Browser Matrix

**ID:** `performance-device-matrix`
**Agent rule (SHOULD):** Test iOS Low Power Mode and macOS Safari
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Test iOS Low Power Mode and macOS Safari

> Device/browser matrix. Test iOS Low Power Mode & macOS Safari.

Performance varies dramatically across devices and browsers. iOS Low Power Mode throttles animations and JavaScript. Safari has different behavior than Chrome. Test on real devices, not just desktop browsers.

- [Cross Browser Testing](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Testing/Introduction)

### Throttle When Profiling

**ID:** `performance-throttle-profiling`
**Agent rule (MUST):** Profile with CPU/network throttling
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Test with CPU and network throttling

> Throttle when profiling. Test with CPU & network throttling.

Developer machines are faster than average user devices. Use browser DevTools to throttle CPU (4x slowdown) and network (Fast 3G) to test how your app performs for users on slower devices and connections.

- [Chrome DevTools Throttling](https://developer.chrome.com/docs/devtools/device-mode/)

### Network Latency Budgets

**ID:** `performance-latency-budgets`
**Agent rule (MUST):** Mutations (`POST/PATCH/DELETE`) target <500 ms
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

POST/PATCH/DELETE operations complete in under 500ms

> Network latency budgets. POST/PATCH/DELETE complete in <500ms.

Users expect mutations (create, update, delete) to feel instant. Target 500ms or less for these operations. Use optimistic updates, show loading states immediately, and optimize backend performance to meet this budget.

- [Response Time Guidelines](https://www.nngroup.com/articles/response-times-3-important-limits/)

### Register Sources Only Where Detection Cannot Reach

**ID:** `performance-content-paths`
**Agent rule (MUST):** Configure Tailwind content paths to include all files using utility classes
**Source:** Tailwind (https://tailwindcss.com/docs)

Tailwind v4 auto-detects sources — add @source only for files outside that sweep

> Tailwind automatically scans your project for source files. Use `@source` to register sources that automatic detection misses, and `@import "tailwindcss" source(none)` to opt out of detection entirely.

There is no `content` array in Tailwind v4. It was removed. Tailwind now walks the project itself, starting from where the CSS is imported, skipping anything in .gitignore and every binary/asset extension — so in a normal app the correct configuration is none at all, and pasting a v3 `content: [...]` block does nothing but mislead the next reader. Reach for `@source "…"` in exactly one situation: a file that holds class names but that the sweep cannot see — a component library inside node_modules (which is gitignored), or a template directory outside the project root. `@source "../node_modules/@acme/ui/dist"`. Two escape hatches complete the picture: `@source not "…"` excludes a path the sweep found but should not scan (a huge generated fixture directory), and `@import "tailwindcss" source(none)` disables auto-detection entirely so you can list every source explicitly — worth it only when you genuinely need that control.

- [Tailwind — Detecting classes in source files](https://tailwindcss.com/docs/detecting-classes-in-source-files)
- [Tailwind — Functions and directives (@source)](https://tailwindcss.com/docs/functions-and-directives)
- [Tailwind — v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide)

### Never transition-all

**ID:** `performance-no-transition-all`
**Agent rule (NEVER):** Use transition-all; explicitly specify transition-transform, transition-opacity, etc.
**Source:** Tailwind (https://tailwindcss.com/docs)

Explicitly transition only needed properties

> Never use transition-all. Explicitly specify which properties to transition for better performance and predictable behavior.

transition-all animates every CSS property that changes, including layout-triggering properties you didn't intend to animate. This causes unexpected animations, performance issues, and harder debugging.

- [CSS Transition Property](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/transition-property)

### Avoid Arbitrary Values

**ID:** `performance-avoid-arbitrary`
**Agent rule (SHOULD):** Avoid arbitrary values [17px]; use theme tokens (p-4, text-foreground)
**Source:** Tailwind (https://tailwindcss.com/docs)

Prefer theme tokens over arbitrary bracket values

> Avoid arbitrary values like p-[17px] or text-[#1a1a1a]. Use theme tokens for consistency and smaller CSS output.

Arbitrary values create one-off utility classes that bypass your design system's spacing/color scale, create inconsistencies, generate additional CSS, and make maintenance harder with magic numbers scattered throughout.

- [Tailwind Customization](https://tailwindcss.com/docs/theme)
- [Tailwind Theme Configuration](https://tailwindcss.com/docs/theme)

### No Dynamic Class Construction

**ID:** `performance-dynamic-classes`
**Agent rule (NEVER):** Dynamically construct class names (`bg-${color}-500`); use object lookup with complete strings
**Source:** Tailwind (https://tailwindcss.com/docs)

Write complete class names for Tailwind to detect them

> Never dynamically construct class names. Tailwind scans source files as strings and cannot detect computed class names.

Tailwind's build process scans your source files for complete class name strings. It cannot execute JavaScript or interpolate template literals. Dynamically constructed classes like bg-${color}-500 will be purged from production builds.

- [Dynamic Class Names](https://tailwindcss.com/docs/detecting-classes-in-source-files#dynamic-class-names)
- [Safelist Configuration](https://tailwindcss.com/docs/detecting-classes-in-source-files#safelisting-classes)

### Force-Include Classes with @source inline(), Not safelist

**ID:** `performance-purge-optimization`
**Agent rule (SHOULD):** Keep content paths specific; minimize safelist to only CMS-driven classes
**Source:** Tailwind (https://tailwindcss.com/docs)

The safelist config option is gone in v4 — force-generate classes from CSS, and keep the set tiny

> Use `@source inline("…")` to force-generate utilities that never appear literally in your source. It supports brace expansion: `@source inline("{hover:,}bg-red-{50,{100..900..100},950}")`. Exclude paths with `@source not "…"`.

v4 removed `safelist` along with the rest of the JS config. The replacement lives in CSS: `@source inline("bg-red-500")` tells Tailwind to emit that utility even though it appears nowhere in the scanned source — the case that actually needs it being class names that arrive at runtime from a CMS, an API, or a database. Brace expansion keeps it from becoming a wall of strings: `@source inline("{hover:,}bg-red-{50,{100..900..100},950}")` generates the whole red scale plus every hover: variant of it. That is also the trap. That one line is ~22 utilities; do it for six colors and you have quietly force-shipped every one of them whether the CMS uses them or not, which is exactly the bloat the scanner exists to prevent. Inline the smallest set the data can actually produce, not the design system's full range. And note what this is NOT for: a class you build with string interpolation in your own code (`bg-${color}-500`) is not a safelist problem, it is a bug — write the complete class names out (see performance-dynamic-classes) instead of force-generating around it.

- [Tailwind — Safelisting classes (@source inline)](https://tailwindcss.com/docs/detecting-classes-in-source-files)
- [Tailwind — Functions and directives (@source)](https://tailwindcss.com/docs/functions-and-directives)
- [Tailwind — v4 upgrade guide](https://tailwindcss.com/docs/upgrade-guide)

### Tailwind Defaults First

**ID:** `performance-ibelick-tailwind-defaults`
**Agent rule (MUST):** Use Tailwind CSS defaults unless custom values already exist or are explicitly requested. Arbitrary values (w-[347px]) indicate design system gaps.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use Tailwind CSS default spacing, colors, and sizing scales unless a custom design token exists

> MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested

The two escapes are the interesting part: a custom value is allowed when the project ALREADY has one (you are following an existing token, not inventing one) or when it was explicitly asked for. Everything else takes the default scale. The failure this prevents is the arbitrary-value drift — p-[13px] here, text-[15px] there, gap-[7px] somewhere else — where every value is individually defensible and the set has no rhythm at all. It is also the single most common tell of generated UI, because a model has no reason to make independently-emitted numbers agree.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [Tailwind Spacing Scale](https://tailwindcss.com/docs/theme)

### Never Animate Large or Continuous Blur

**ID:** `performance-ibelick-no-blur-animation`
**Agent rule (NEVER):** Animate large blur() or backdrop-filter surfaces. They are expensive paint operations that cause frame drops, especially on mobile devices.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never animate blur on a large surface or on a loop — a small (≤8px), short, one-time blur is the permitted exception

> NEVER animate large `blur()` or `backdrop-filter` surfaces. [fixing-motion-performance §7] keep blur animation small (<=8px) · use blur only for short, one-time effects · never animate blur continuously · never animate blur on large surfaces · prefer opacity and translate before blur

Blur is expensive because it samples a neighbourhood of pixels for every pixel it produces: the cost scales with the AREA blurred and, worse, with the RADIUS, and animating it re-rasterizes the whole surface every frame. So the three variables are radius, area and duration — and ibelick prices all three rather than banning the property outright. The permitted case is a small radius (≤8px), on a small surface, running once. The forbidden cases are the ones that multiply: a full-screen backdrop-filter, a 40px radius, or any blur on a loop. Reach for opacity and translate first; where you truly need a big blur, pre-render it as a static layer and crossfade THAT with opacity, which is composited. IMPORTANT — this is what licenses animations-emil-blur-crossfade, which prescribes filter: blur(2px) during a crossfade to fuse two overlapping states. Under the old blanket phrasing ("never animate blur") the two principles in this corpus flatly contradicted each other. They do not: 2px, on one element, for the length of a transition, is exactly the small/short/one-time carve-out upstream defines. The threshold is the rule; the blanket ban was our overreach.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [ibelick — fixing-motion-performance SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/fixing-motion-performance/SKILL.md)
- [MDN — filter](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/filter)
- [CSS Filter Performance](https://web.dev/articles/simplify-paint-complexity-and-reduce-paint-areas)

### Use will-change Sparingly

**ID:** `performance-ibelick-will-change`
**Agent rule (NEVER):** Apply will-change outside an active animation. It wastes GPU memory when not needed. Add dynamically before animation, remove after completion.
**Source:** @Ibelick (https://www.ui-skills.com/)

Only apply will-change during active animations, never as a permanent style

> NEVER apply `will-change` outside an active animation

will-change is a promise, not an optimisation: it asks the browser to promote the element to its own compositor layer AHEAD of a change you are about to make. Left on permanently it is a promise you never keep — the layer is allocated, its memory is held, and nothing ever animates. Do it across a list and you get layer explosion, where the cost of compositing hundreds of layers exceeds whatever the promotion saved. ibelick's fixing-motion-performance skill states the discipline exactly: "use will-change temporarily and surgically", and "compositor motion requires layer promotion, never assume it" — so add it when the animation is about to start (or on hover, just before a press) and remove it when the animation ends.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [ibelick — fixing-motion-performance SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/fixing-motion-performance/SKILL.md)
- [will-change MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/will-change)

### Don't Use useEffect for Render Logic

**ID:** `performance-ibelick-no-effect-render`
**Agent rule (NEVER):** Use useEffect for anything that can be expressed as render logic. Derive state during render, not in effects. Effects are for synchronization with external systems.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never use useEffect to compute values that should be derived during render

> NEVER use `useEffect` for anything that can be expressed as render logic

The state-syncing effect — useEffect(() => setFullName(first + " " + last), [first, last]) — is not just slower, it is a second source of truth. React must render with the stale value, commit it, run the effect, set state, and render again: the user briefly sees the old value, and any bug in the dependency array leaves the two permanently out of step. Derived values are just expressions: compute them during render (const fullName = first + " " + last), and reach for useMemo only when the computation is genuinely expensive. Effects are for synchronising with something OUTSIDE React — the DOM, a subscription, the network — not with React's own state.

- [ibelick — baseline-ui SKILL.md](https://github.com/ibelick/ui-skills/blob/main/skills/baseline-ui/SKILL.md)
- [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)

### CSS Containment for Performance

**ID:** `performance-css-containment`
**Agent rule (SHOULD):** Use CSS `contain: layout paint` on reusable cards/list items to isolate layout/paint scope. Use `content-visibility: auto` with `contain-intrinsic-size` for offscreen content (up to 7x render improvement).
**Source:** Web Platform (https://web.dev/)

Use CSS contain and content-visibility to isolate layout/paint scope

> Use CSS `contain: layout paint` on reusable cards/list items to isolate layout/paint scope. Use `content-visibility: auto` with `contain-intrinsic-size` for offscreen content (up to 7x render improvement).

CSS containment tells the browser that an element's layout/paint is independent from the rest of the page. content-visibility: auto skips rendering offscreen content entirely, dramatically improving initial render for long lists.

- [MDN CSS contain](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/contain)
- [web.dev content-visibility](https://web.dev/articles/content-visibility)

### LCP Hero Optimization

**ID:** `performance-lcp-hero-optimization`
**Agent rule (MUST):** LCP images (hero, banner): Use `loading="eager"` + `fetchpriority="high"` + `decoding="async"`. Add `<link rel="preload" as="image">` in head. NEVER lazy-load above-the-fold content.
**Source:** Web Platform (https://web.dev/)

Preload above-the-fold images and prioritize LCP elements for fast perceived loading

> LCP images (hero, banner): Use `loading="eager"` + `fetchpriority="high"` + `decoding="async"`. Add `<link rel="preload" as="image">` in head. NEVER lazy-load above-the-fold content.

Largest Contentful Paint (LCP) is a Core Web Vital measuring when the largest content becomes visible. Hero images are often the LCP element. Preloading and eager loading ensures they render as fast as possible.

- [Optimize LCP](https://web.dev/articles/optimize-lcp)
- [Preload critical assets](https://web.dev/articles/preload-critical-assets)

### Font Display Strategy

**ID:** `performance-font-display-strategy`
**Agent rule (MUST):** Use `font-display: swap` to prevent FOIT (invisible text). Preconnect to font CDNs. Preload critical fonts. Match fallback font metrics with `size-adjust` to minimize CLS during font swap.
**Source:** Web Platform (https://web.dev/)

Prevent invisible text (FOIT) and layout shift from web fonts with proper loading strategies

> Use `font-display: swap` to prevent FOIT (invisible text). Preconnect to font CDNs. Preload critical fonts. Match fallback font metrics with `size-adjust` to minimize CLS during font swap.

Web fonts can cause Flash of Invisible Text (FOIT) affecting LCP, and layout shift when fonts swap. font-display: swap shows fallback text immediately. Metric matching with size-adjust minimizes CLS.

- [Optimize web fonts](https://web.dev/articles/optimize-webfont-loading)
- [font-display MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/font-display)

### Responsive Images

**ID:** `performance-responsive-images`
**Agent rule (MUST):** Use `srcset` + `sizes` for responsive images. Serve WebP/AVIF with `<picture>` fallback. Always set explicit `width`/`height` attributes or CSS `aspect-ratio` to prevent CLS.
**Source:** Web Platform (https://web.dev/)

Serve optimally-sized images for each device with srcset, sizes, and modern formats

> Use `srcset` + `sizes` for responsive images. Serve WebP/AVIF with `<picture>` fallback. Always set explicit `width`/`height` attributes or CSS `aspect-ratio` to prevent CLS.

Without responsive images, mobile users download desktop-sized images, wasting bandwidth and slowing LCP. srcset lets browsers choose optimal sizes. Modern formats (WebP, AVIF) reduce file size 25-50%.

- [Serve responsive images](https://web.dev/articles/serve-responsive-images)
- [Use WebP images](https://web.dev/articles/serve-images-webp)

### Avoid Gradient Banding

**ID:** `performance-gradient-banding`
**Agent rule (SHOULD):** Build soft glows with `radial-gradient()` rather than a filled rectangle scaled and run through `filter: blur()` — the blur+scale route bands. Where a gradient still bands, fade it with a `mask-image` gradient instead of stacking more blur.
**Source:** Rauno (https://interfaces.rauno.me/)

Scaling and blurring filled rectangles causes banding — use radial gradients instead

> Scaling and blurring filled rectangles will cause banding, use radial gradients instead.

Applying blur() and scale() to solid-colored elements produces visible color banding artifacts. Radial gradients create smooth color transitions natively without needing blur filters, resulting in better visual quality and performance.

```tsx
.glow { background: radial-gradient(circle, oklch(0.7 0.2 250 / 0.5), transparent 70%); }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Sparingly Use GPU Rendering

**ID:** `performance-gpu-translatez`
**Agent rule (SHOULD):** Reach for `transform: translateZ(0)` / `will-change` sparingly — only on the specific element with a measured animation problem. Blanket layer promotion burns GPU memory and can make things slower.
**Source:** Rauno (https://interfaces.rauno.me/)

Only enable GPU rendering with translateZ(0) on elements that need it

> Sparingly enable GPU rendering with transform: translateZ(0) for unperformant animations.

Promoting elements to their own GPU layer with translateZ(0) can improve animation performance, but applying it broadly wastes GPU memory and can actually degrade performance. Only use it on specific elements with known performance issues.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Pause Off-Screen Videos

**ID:** `performance-video-autoplay-performance`
**Agent rule (MUST):** Do not autoplay every video at once — observe visibility with `IntersectionObserver` and pause (or unmount) off-screen videos; iOS chokes otherwise.
**Source:** Rauno (https://interfaces.rauno.me/)

Auto-playing too many videos chokes the device — pause or unmount off-screen videos

> Auto-playing too many videos on iOS will choke the device, pause or even unmount off-screen videos.

Each playing video consumes CPU and GPU resources. On mobile devices especially, having multiple videos playing simultaneously can cause the device to lag, overheat, and drain battery. Use IntersectionObserver to only play videos visible in the viewport.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Bypass React Render with Refs

**ID:** `performance-refs-bypass-render`
**Agent rule (SHOULD):** For high-frequency real-time values (pointer position, scroll, rAF), write to the DOM through a `ref` instead of `useState` — the visual result is identical with zero re-renders.
**Source:** Rauno (https://interfaces.rauno.me/)

Use refs for real-time values that update the DOM directly to avoid unnecessary re-renders

> Bypass React's render lifecycle with refs for real-time values that can commit to the DOM directly.

For high-frequency updates like mouse position tracking, scroll values, or animation frames, using useState causes a full component re-render on every update. Using refs and updating the DOM directly bypasses the React render cycle entirely, achieving the same visual result with zero re-renders.

```tsx
const el = useRef<HTMLDivElement>(null);
onPointerMove = (e) => { el.current!.style.transform = `translate(${e.clientX}px, ${e.clientY}px)`; };
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Keep Keystroke Cost Low

**ID:** `performance-keystroke-cost`
**Agent rule (SHOULD):** Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer uncontrolled inputs, and keep every controlled input cheap per keystroke

> Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke

A controlled input turns every keypress into a React render of its owning component and everything below it. If that subtree is expensive — a chart, an editor, a formatted list — the input visibly lags behind the user's fingers. Uncontrolled inputs (defaultValue + a ref) let the DOM own the value, so typing costs zero renders. When you do need controlled state, keep the subtree it feeds trivial: hoist the state down to the input, memoize expensive children, or defer the derived work with useDeferredValue.

- [Uncontrolled inputs (React)](https://react.dev/reference/react-dom/components/input)
- [useDeferredValue](https://react.dev/reference/react/useDeferredValue)

### Hydration-Safe Date Rendering

**ID:** `performance-hydration-safe-dates`
**Agent rule (MUST):** Render dates deterministically on the server — a fixed locale and time zone, or an ISO string inside `<time dateTime>` — and localize inside `useEffect` after hydration. Calling `toLocaleString()`/`new Date()` during render mismatches between a UTC server and the user's zone, discarding the SSR subtree.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Guard date and time rendering against server/client hydration mismatches

> Date/time rendering: guard against hydration mismatch (server vs client)

Calling toLocaleString() (or new Date()) during render produces one string on a server running in UTC and a different one in a browser set to Tokyo or Berlin. React compares the two, finds the text node does not match, discards the server-rendered subtree and re-renders it client-side — the exact work SSR was supposed to save. Render a deterministic value first (a fixed time zone and locale, or an ISO string inside <time dateTime>), then localize inside useEffect once hydration has finished.

- [hydrateRoot: handling mismatches](https://react.dev/reference/react-dom/client/hydrateRoot)
- [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)

### Preconnect to Asset Domains

**ID:** `performance-preconnect-asset-domains`
**Agent rule (SHOULD):** Add `<link rel="preconnect">` for every CDN and asset origin the page is certain to hit (with `crossorigin` for fonts and CORS-fetched assets) so DNS, TCP, and TLS overlap with HTML parsing. Only preconnect to origins you will definitely use — each holds an open socket.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Add <link rel="preconnect"> for every CDN and asset origin the page will hit

> Add `<link rel="preconnect">` for CDN/asset domains

The first request to a new origin cannot send a byte until DNS resolution, the TCP handshake and the TLS negotiation all complete — frequently more wall-clock time than the download itself, and it is paid serially at the worst possible moment. rel="preconnect" starts those handshakes as soon as the HTML is parsed, in parallel with everything else, so the eventual request finds a warm connection. Preconnect only to origins you are certain to use (each one holds an open socket), and add crossorigin for font and CORS-fetched assets.

```tsx
<link rel="preconnect" href="https://cdn.example.com" crossorigin>
```

- [rel=preconnect (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preconnect)
- [Preconnect and dns-prefetch](https://web.dev/articles/preconnect-and-dns-prefetch)

### Lazy-Load Below-the-Fold Images

**ID:** `performance-lazy-load-below-fold`
**Agent rule (MUST):** Eagerly load (and `rel="preload"`) only above-the-fold imagery; give every below-the-fold image `loading="lazy"`. Keep `width`/`height` or `aspect-ratio` on it so deferring the download does not reintroduce layout shift, and never lazy-load the LCP hero.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Give every image below the fold loading="lazy" so it downloads only when approached

> Below-fold images: `loading="lazy"`

Eagerly loading images the user has not scrolled to yet spends their bandwidth and the browser's limited connection pool on pixels nobody is looking at — and it does so while the LCP hero is still competing for those same connections. loading="lazy" defers the request until the image nears the viewport, which cuts initial page weight and lets the above-the-fold content land sooner. Keep width/height (or aspect-ratio) on the placeholder so deferring the download does not reintroduce layout shift, and never lazy-load the hero itself.

```tsx
<img src="/chart.png" width="800" height="450" loading="lazy" decoding="async" alt="…">
```

- [Browser-level lazy loading](https://web.dev/articles/browser-level-image-lazy-loading)
- [img loading attribute (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img)

### Adapt to Device and Network Capabilities

**ID:** `performance-adaptive-capabilities`
**Agent rule (SHOULD):** Branch on `navigator.deviceMemory`, `navigator.hardwareConcurrency` and `navigator.connection.effectiveType`/`.saveData` to drop blurs, autoplay and heavy assets on weak devices. Treat them as hints: always ship a working default when undefined, and never fingerprint with them.
**Source:** Rauno (https://interfaces.rauno.me/)

Detect the device's hardware and network at runtime and serve a lighter experience when it is constrained

> Detect and adapt to the hardware and network capabilities of the user's device

The browser will tell you what it can afford: navigator.deviceMemory (GB of RAM), navigator.hardwareConcurrency (CPU cores), and navigator.connection.effectiveType / .saveData (measured connection quality and the user's explicit data-saver preference). Branch on them — drop animated blurs and backdrop filters, skip autoplaying video, serve smaller images, render fewer particles — so a 2-core phone on 3G gets a version it can actually run at 60fps instead of a desktop hero that melts it. This is runtime adaptation, not a testing checklist: treat the signals as hints, always ship a working default when they are undefined, and never use them to fingerprint.

```tsx
const lite = navigator.connection?.saveData || (navigator.deviceMemory ?? 8) < 4;
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [react-adaptive-hooks](https://github.com/GoogleChromeLabs/react-adaptive-hooks)
- [navigator.hardwareConcurrency](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/hardwareConcurrency)
- [connection.effectiveType](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType)

### Set Transform on the Element, Not a Parent Variable

**ID:** `performance-transform-not-css-variable`
**Agent rule (NEVER):** Drive child transforms by writing a CSS variable on the parent during a gesture (`el.style.setProperty('--swipe-amount', …)`) — it invalidates every descendant reading that variable, recalculating styles across the subtree on each pointer move. Set `transform` directly on the one element that moves, and prefer `animate={{ transform: "translateX(100px)" }}` over Motion's main-thread `x`/`y`/`scale` shorthands.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Never drive child transforms by mutating a CSS variable on their parent during a gesture

> Don't drive child transforms via a CSS variable on the parent — it recalcs styles for all children. Set `transform` directly on the element.

Writing element.style.setProperty('--swipe-amount', ...) on a container invalidates every descendant that reads that variable, so the browser recalculates styles across the whole subtree on every pointer move — a recalc storm that shows up as gesture jank long before paint does. Set element.style.transform on the single element that actually moves and let its children ride along inside one composited layer. The same trap exists in Framer Motion: the x / y / scale shorthand props are driven on the main thread via requestAnimationFrame rather than being hardware-accelerated the way a full transform string is, so they drop frames under load — prefer animate={{ transform: "translateX(100px)" }}.

- [Emil Kowalski — animation STANDARDS.md](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)
- [CSS and JavaScript animation performance](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/CSS_JavaScript_animation_performance)

### Measure Reliably

**ID:** `performance-measure-reliably`
**Agent rule (MUST):** Measure reliably (disable extensions that skew runtime)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Profile in a clean browser profile with extensions disabled

> Measure reliably. Disable extensions that add overhead or change runtime behavior.

Extensions run content scripts on your page, on your main thread, inside your measurements. Ad blockers rewrite the DOM, password managers scan every form, React DevTools instruments each render — all of it lands in the same numbers you are about to draw a conclusion from. The damage is not that the timings are slower but that they are noisy: when run-to-run spread is larger than the regression you are hunting, the profile stops being evidence. Measure in a clean profile or incognito with extensions off, take several runs, and compare spreads rather than a single number.

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [Chrome DevTools: Performance features reference](https://developer.chrome.com/docs/devtools/performance/reference)

### Keep Long Tasks Off the Main Thread

**ID:** `performance-offload-main-thread`
**Agent rule (MUST):** Move expensive computation off the main thread — anything past ~50ms is a long task by Core Web Vitals and eats INP; an 800ms sync loop paints no frames and queues every click, while the CSS spinner keeps turning on the compositor and disguises the freeze as progress. Post it to a Web Worker, or chunk it and yield with `scheduler.yield()` if it must touch the DOM.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Move long-running computation into a Web Worker so the page stays interactive

> Don't use the main thread for expensive work. Move especially long tasks to Web Workers to avoid blocking interaction with the page.

The main thread renders every frame, runs every event handler, and executes your JavaScript — one queue, one worker. A synchronous computation that runs for 800ms does not make the page slow, it makes it dead: no frames paint, clicks and keystrokes sit in the queue, and a CSS spinner is the only thing still moving (because it is on the compositor) which makes the freeze look like a working loading state. Anything past roughly 50ms is already a "long task" by Core Web Vitals' definition and eats directly into INP. Post the work to a Web Worker — it runs on its own thread and messages the result back — or, if it genuinely must touch the DOM, chunk it and yield with scheduler.yield() between slices.

```tsx
const worker = new Worker(new URL("./crunch.worker.ts", import.meta.url), { type: "module" });
worker.postMessage(rows);
worker.onmessage = (e) => setResult(e.data);
```

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)
- [web.dev: Off the main thread](https://web.dev/articles/off-main-thread)

### Motion Transform Shorthands Are Not GPU-Accelerated

**ID:** `performance-motion-shorthand-not-gpu`
**Agent rule (MUST):** In Motion/Framer Motion, animate the full `transform` string, not the `x`/`y`/`scale` shorthands: the shorthands are interpolated per `requestAnimationFrame` on the MAIN THREAD and drop frames under load, while `transform` as a whole string (along with `opacity`, `filter`, `clipPath`) is handed to the Web Animations API and ticked by the compositor. This is the false floor under `animations-compositor-friendly` — `animate={{ x: 100 }}` looks compliant and is not.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Animate the full transform string in Motion, because x, y, and scale are ticked on the main thread

> Framer Motion shorthands are NOT hardware-accelerated. `x`/`y`/`scale` run on the main thread via rAF and drop frames under load. Use the full transform string: `animate={{ transform: 'translateX(100px)' }}`.

This is the false floor under every "animate transform and opacity" rule you have already read. Writing animate={{ x: 100 }} looks like you obeyed them — it does compile down to a transform — but the value is interpolated by the library on each requestAnimationFrame tick and written to style, so it lives and dies on the main thread and drops frames the moment anything else is busy. Motion only hands an animation to the Web Animations API when the animated property is on its accelerated list — opacity, filter, clipPath, and transform as a whole string — and the x / y / scale shorthands are not on it. Animate transform: "translateX(100px)" instead and the compositor ticks it, so it keeps moving even while the main thread is blocked. Distinct from setting transform on the element rather than a parent CSS variable: that rule is about a style-recalc storm across descendants, this one is about which thread owns the tween.

```tsx
// main-thread rAF:  animate={{ x: 100 }}
// compositor/WAAPI: animate={{ transform: "translateX(100px)" }}
```

- [Emil Kowalski: review-animations STANDARDS.md](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)
- [MDN: CSS and JavaScript animation performance](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/CSS_JavaScript_animation_performance)
- [web.dev: Animations guide](https://web.dev/articles/animations-guide)

### Every rAF Loop Needs a Stop Condition

**ID:** `performance-raf-stop-condition`
**Agent rule (NEVER):** Ship a `requestAnimationFrame` loop with no terminal condition. `const tick = () => { draw(); requestAnimationFrame(tick); }` never ends: once the value has converged and the user has moved on, it still wakes 60x/sec to compute a delta of zero, burning a core and measurable battery even while the element is visible and idle — the usual cause of an idle tab at 10-15% CPU. Give every loop two exits: stop re-scheduling on convergence (or gesture end / `AbortSignal`), and call `cancelAnimationFrame` on teardown so an unmount cannot orphan the loop. (Distinct from `animations-ibelick-pause-offscreen`, which stops work the user cannot see.)
**Source:** @Ibelick (https://www.ui-skills.com/)

A requestAnimationFrame loop that re-schedules itself unconditionally never ends, and burns a core for as long as the tab lives

> no requestAnimationFrame loops without a stop condition

The shape is always the same: `const tick = () => { draw(); requestAnimationFrame(tick); }`. It is correct while the animation is running and wrong for every second after — the value has converged, the spring has settled, the user has moved on, and the loop is still waking up sixty times a second to compute a delta of zero. That is the usual explanation for an idle tab sitting at 10-15% CPU, and on a laptop it is measurable battery drain for no pixels. Every loop needs two exits: a terminal condition (the value converged, the gesture ended, an AbortSignal fired) that stops re-scheduling, and a `cancelAnimationFrame` in the teardown so a component that unmounts mid-animation does not leave an orphan loop holding a reference to a dead tree. This is a different failure from animations-ibelick-pause-offscreen: that rule stops work the user cannot see, this one stops work nobody needs even when the element is in full view.

```tsx
const tick = () => {
  if (settled()) return;               // terminal condition
  id = requestAnimationFrame(tick);
};
return () => cancelAnimationFrame(id); // teardown
```

- [ibelick — fixing-motion-performance SKILL.md](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-motion-performance/SKILL.md)
- [MDN — requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame)

### Budget the GPU for WebGL

**ID:** `performance-webgl-gpu-budget`
**Agent rule (SHOULD):** WebGL cost scales with pixels and object count, not DOM size. Cap pixel ratio at 2 (setPixelRatio(Math.min(devicePixelRatio, 2)) — fragment cost is quadratic in DPR), keep draw calls low by merging/instancing static geometry (~<100/frame), and dispose() geometries, materials, and textures on unmount because GPU memory is not garbage-collected. Keep mobile textures ≤1024².
**Source:** Web Platform (https://web.dev/)

Cap pixel ratio at ~2, keep draw calls low, and dispose GPU resources — WebGL cost scales with pixels and object count, not DOM size

> Limit pixel ratio to 2. Target under ~100 draw calls per frame. Dispose geometries, materials, and textures. On mobile prefer cheap materials and keep textures ≤1024².

Distilled from the Core Web Vitals / mobile / draw-call budgets in emalorenzo's three-agent-skills and web.dev's WebGL guidance, and it matters because WebGL performance is governed by metrics that have nothing to do with the rest of the page. Two costs dominate. Fragment shading scales with the pixels drawn, which is `cssPixels × devicePixelRatio²`, so `renderer.setPixelRatio(window.devicePixelRatio)` on a 3× phone quietly asks the GPU to shade NINE times the area of a 1× render — the single most common cause of a 3D hero that melts a mid-range phone. Cap it hard: `setPixelRatio(Math.min(devicePixelRatio, 2))`, above which the extra density is imperceptible and only expensive. Second, every draw call carries fixed CPU overhead, so a scene is bounded by object COUNT more than triangle count; hundreds of separate meshes stall the main thread, and the fix is to merge static geometry or use instancing to draw many copies in one call (budget: well under ~100 draw calls/frame). A third, silent failure: GPU memory is not garbage-collected — geometries, materials and textures must be explicitly `.dispose()`d when a scene unmounts, or they leak until the browser drops the context. This is the runtime companion to content-canvas-accessible-fallback (the same 3D feature needs a static fallback where WebGL is weak or absent) and to performance-raf-stop-condition / animations-ibelick-pause-offscreen (do not run the render loop when nothing is on screen).

```tsx
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
useEffect(() => () => { geometry.dispose(); material.dispose(); }, []);
```

- [emalorenzo — three-agent-skills](https://github.com/emalorenzo/three-agent-skills)
- [MDN — WebGL best practices](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_best_practices)
- [web.dev — Rendering performance](https://web.dev/articles/rendering-performance)

---

## Design

Visual design principles and aesthetics. 61 rules.

### Layered Shadows

**ID:** `design-layered-shadows`
**Agent rule (SHOULD):** Layered shadows (ambient + direct)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Mimic ambient and direct light with at least two layers

> Layered shadows. Mimic ambient + direct light with at least two layers.

Natural shadows have both ambient (soft, diffuse) and direct (sharper, darker) components. Use two box-shadow declarations: one large and subtle for ambient light, one smaller and darker for direct light. This creates depth and realism.

- [Material Design Shadows](https://m2.material.io/design/environment/light-shadows.html)

### Crisp Borders

**ID:** `design-crisp-borders`
**Agent rule (SHOULD):** Crisp edges via semi-transparent borders + shadows
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Combine borders and shadows for clear edges

> Crisp borders. Combine borders & shadows; semi-transparent borders improve edge clarity.

Shadows alone can look muddy. A subtle border (often semi-transparent) makes edges crisp and clear. Use rgba() with low opacity for borders so they adapt to different backgrounds.

- [CSS Borders](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border)

### Nested Radii

**ID:** `design-nested-radii`
**Agent rule (SHOULD):** Nested radii: child ≤ parent; concentric
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Child radius ≤ parent radius and concentric

> Nested radii. Child radius ≤ parent radius & concentric so curves align.

When a rounded element contains another rounded element, the inner radius should be the outer radius minus the padding. This keeps the curves concentric and visually aligned. Formula: innerRadius = outerRadius - padding. The formula has a bound, which the Vercel line does not state: better-ui's surfaces guide notes that "This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math." Past roughly 24px of padding the eye no longer reads the two curves as one nested form, so the arithmetic starts producing an absurdly large outer radius in service of a relationship nobody perceives.

- [Nested Border Radius](https://cloudfour.com/thinks/the-math-behind-nesting-rounded-corners/)
- [jakubkrehel/skills — better-ui: surfaces](https://github.com/jakubkrehel/skills/blob/main/skills/better-ui/surfaces.md)

### Minimum Contrast

**ID:** `design-minimum-contrast`
**Agent rule (MUST):** Meet contrast—prefer APCA (https://apcacontrast.com/) over WCAG 2
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Prefer APCA over WCAG 2 for accurate perceptual contrast

> Minimum contrast. Prefer APCA over WCAG 2 for more accurate perceptual contrast.

WCAG 2.x contrast ratios have known issues. APCA (Accessible Perceptual Contrast Algorithm) provides more accurate measurements of readability. Aim for APCA values appropriate to text size and weight. Generally, body text should have Lc 60+ and headings Lc 45+.

- [APCA Introduction](https://git.apcacontrast.com/documentation/APCAeasyIntro.html)
- [APCA on GitHub](https://github.com/Myndex/SAPC-APCA)

### Interactions Increase Contrast

**ID:** `design-interactions-increase-contrast`
**Agent rule (MUST):** Increase contrast on `:hover/:active/:focus`
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Hover, active, focus states have more contrast than rest state

> Interactions increase contrast. :hover, :active, :focus have more contrast than rest state.

Interactive states should draw attention. Increase contrast on hover, active, and focus states by darkening text, strengthening backgrounds, or adding shadows. This provides clear feedback that the element is interactive.

- [Interactive States](https://www.nngroup.com/articles/clickable-elements/)

### Hue Consistency

**ID:** `design-hue-consistency`
**Agent rule (SHOULD):** Hue consistency: tint borders/shadows/text toward bg hue
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Tint borders, shadows, and text toward background hue

> Hue consistency. On non-neutral backgrounds, tint borders/shadows/text toward the same hue.

Pure black borders and shadows look harsh on colored backgrounds. Slightly tint them toward the background color for a more cohesive, refined appearance. For example, on a blue background, use slightly blue-tinted shadows instead of pure gray.

- [Color Theory](https://www.smashingmagazine.com/2010/01/color-theory-for-designers-part-1-the-meaning-of-color/)

### Accessible Charts

**ID:** `design-accessible-charts`
**Agent rule (MUST):** Accessible charts (color-blind-friendly palettes)
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Use color-blind-friendly palettes

> Accessible charts. Use color-blind-friendly palettes.

About 8% of men and 0.5% of women have color vision deficiencies. Use color palettes designed for color blindness (avoid red-green combinations), and supplement color with patterns, labels, or textures in data visualizations.

- [Designing for Color Blindness](https://www.smashingmagazine.com/2024/02/designing-for-colorblindness/)
- [Data Visualization Accessibility](https://www.w3.org/WAI/tutorials/images/complex/)

### Extend the Theme with @theme

**ID:** `design-theme-config`
**Agent rule (MUST):** Use theme.extend to add custom values; never overwrite top-level theme keys
**Source:** Tailwind (https://tailwindcss.com/docs)

Declare design tokens in a CSS @theme block, which extends the defaults instead of replacing them

> Use the `@theme` directive to define your project's custom design tokens. Tokens you declare are added to the defaults. To replace an entire namespace instead of adding to it, reset it first: `--color-*: initial;`

This is the single largest v4 breaking change and the one most stale advice still gets wrong. There is no `tailwind.config.js` by default, and `theme.extend` does not exist — the JS config object is gone. Tokens are plain CSS custom properties declared inside `@theme { --color-brand: oklch(0.62 0.19 259); }`, and that block extends by default: your brand color lands next to slate, red, and every other built-in. Which means the entire v3 failure mode this principle used to be about — "you wrote `theme.colors` instead of `theme.extend.colors` and nuked the palette" — is structurally impossible now. Clobbering is opt-in, not accidental: to drop the defaults you must explicitly reset the namespace with `--color-*: initial;` before declaring your own, which is the escape hatch for teams that want a closed palette where `bg-red-500` should not silently work. Every token you declare doubles as a real CSS variable, so `var(--color-brand)` resolves anywhere, including inside a third-party stylesheet.

- [Tailwind v4: Theme variables](https://tailwindcss.com/docs/theme)
- [Tailwind v4: Upgrade guide](https://tailwindcss.com/docs/upgrade-guide)

### Use Semantic Color Tokens

**ID:** `design-semantic-colors`
**Agent rule (MUST):** Use semantic tokens (bg-primary, text-destructive) instead of raw colors (bg-blue-500)
**Source:** Tailwind (https://tailwindcss.com/docs)

Define colors by purpose, not appearance

> Use semantic color names (primary, destructive, muted) instead of raw colors (blue-500, red-600). This enables theming and dark mode.

Semantic tokens describe purpose, not appearance. bg-destructive means "danger/error background" regardless of the actual color. This separation allows themes to change without touching component code.

- [Using CSS Variables](https://tailwindcss.com/docs/colors)

### Build Complete Theme

**ID:** `design-complete-theme`
**Agent rule (SHOULD):** Define complete token pairs: background + foreground, ring, border for each semantic color
**Source:** Tailwind (https://tailwindcss.com/docs)

Define all interactive states and component variants

> Build a complete design token system with foreground colors for every background, ring colors, and all interactive states.

A partial theme leads to inconsistency. Complete themes include: background/foreground pairs, border variants, ring/focus colors, and state variants (hover, active, disabled).

- [shadcn/ui Theming](https://ui.shadcn.com/docs/theming)

### Mobile-First Responsive

**ID:** `design-mobile-first`
**Agent rule (MUST):** Write mobile styles first; use sm:/md:/lg: to enhance for larger screens (min-width based)
**Source:** Tailwind (https://tailwindcss.com/docs)

Start with mobile styles, add breakpoints for larger screens

> Write mobile styles first, then use sm:, md:, lg: breakpoints to enhance for larger screens. Tailwind's breakpoints are min-width based.

Tailwind breakpoints are mobile-first (min-width). md:flex means "flex at medium screens AND UP." Starting desktop-first leads to verbose code with unnecessary overrides.

- [Responsive Design](https://tailwindcss.com/docs/responsive-design)
- [Mobile First](https://tailwindcss.com/docs/responsive-design#mobile-first)

### Custom Breakpoints When Needed

**ID:** `design-custom-breakpoints`
**Agent rule (SHOULD):** Add custom breakpoints via theme.extend.screens; avoid arbitrary min-[Xpx]: values
**Source:** Tailwind (https://tailwindcss.com/docs)

Add project-specific breakpoints as --breakpoint-* theme tokens, not as scattered arbitrary min-[…] values

> Use the `--breakpoint-*` theme variables to customize your breakpoints: `@theme { --breakpoint-3xl: 120rem; }` — this creates a new `3xl` variant you can use in your markup.

The v3 answer, `theme.extend.screens`, no longer exists — there is no config object to extend. A breakpoint in v4 is just another theme token: declare `--breakpoint-3xl: 120rem;` inside `@theme` and you get `3xl:` (plus `max-3xl:` and every other variant that keys off it) for free. The rule underneath is unchanged and is the reason this principle exists: a raw `min-[960px]:` is a magic number with no name, so the second person who needs that breakpoint guesses 961 or 959 and the layout now breaks in a one-pixel band. Name it once, use the name everywhere. Two v4 specifics worth knowing: because breakpoints are ordinary custom properties, they are sorted by value rather than by declaration order, so a new token slots into the right place in the cascade automatically; and `--breakpoint-*: initial;` wipes the built-in scale if you want only your own names.

- [Tailwind v4: Responsive design](https://tailwindcss.com/docs/responsive-design)
- [Tailwind v4: Theme variables](https://tailwindcss.com/docs/theme)

### Override the dark Variant, Don't Configure It

**ID:** `design-dark-mode-class`
**Agent rule (SHOULD):** Use darkMode: "class" for user-controllable themes with light/dark/system options
**Source:** Tailwind (https://tailwindcss.com/docs)

Redefine the dark variant with @custom-variant so a class can drive the theme, because the darkMode option no longer exists

> By default the `dark` variant uses the `prefers-color-scheme` media feature. To use a class instead, override the `dark` variant: `@custom-variant dark (&:where(.dark, .dark *));`

The `darkMode: 'class'` config option is gone — there is no config file to put it in. In v4 the `dark` variant is just a variant, and you change its behaviour by redefining it with `@custom-variant`. This repository is its own reference implementation: `src/index.css` line 7 reads `@custom-variant dark (&:is(.dark *));`, which is why toggling `.dark` on `<html>` themes this entire app. The reason to override at all is unchanged: the default media-query variant reads the OS setting and nothing else, so a user who wants dark on a machine set to light has no way to ask for it and no way to persist the choice. Driving the variant from a class puts the decision in your hands — read `prefers-color-scheme` as the initial default, then let a toggle write `.dark` and store the preference. Note the selector shape: it must match both the `.dark` element itself and its descendants, otherwise `dark:` utilities on `<html>` never fire.

- [Tailwind v4: Dark mode](https://tailwindcss.com/docs/dark-mode)
- [Tailwind v4: @custom-variant](https://tailwindcss.com/docs/functions-and-directives)

### Respect Color Scheme Preference

**ID:** `design-dark-preferences`
**Agent rule (MUST):** Apply dark class in inline <head> script before first paint to prevent theme flash
**Source:** Tailwind (https://tailwindcss.com/docs)

Initialize theme from prefers-color-scheme before page renders

> Read prefers-color-scheme on initial load and apply the dark class before first paint to prevent flash of wrong theme.

If you wait for JavaScript to run before checking the color scheme, users see a flash of the wrong theme (FART). Inline a script in <head> that runs synchronously before render.

- [Avoiding FART](https://css-tricks.com/flash-of-inaccurate-color-theme-fart/)
- [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme)

### Insufficient Text Contrast

**ID:** `design-rams-color-contrast`
**Agent rule (MUST):** Text needs >= 4.5:1 against its background (WCAG 1.4.3); large text (>= 24px, or >= 19px bold) may use 3:1. Secondary text, captions and disabled states are where this fails. For UI component boundaries and states, `design-non-text-contrast` sets the separate 3:1 bar (WCAG 1.4.11). Test in both themes.
**Source:** RAMS (https://www.rams.ai/)

Text must have sufficient contrast with its background — including secondary text

> Contrast ratio below 4.5:1

That is the whole upstream rule — one bullet under "Color & Contrast" in the Rams review. The number is WCAG 1.4.3 Level AA: 4.5:1 for body text, relaxed to 3:1 for large text (18pt / 14pt bold and above). The reasoning here is ours. The failures are almost never the headline; they are the quiet text — captions, helper text, placeholders, timestamps, and "muted" secondary copy, where a designer reached for light gray on white to make the layout calmer. Disabled controls are formally exempt from 1.4.3, but if the disabled label is the only thing telling a user why they cannot proceed, exempt is not the same as readable. Check with a contrast tool rather than by eye, and re-check in dark mode, where a token that passed on white can fail on near-black. This rule sets the floor for TEXT only. The parts of a control that are not text — an input outline, a checkbox in its off state, a focus ring, a chart line — are governed by design-non-text-contrast (WCAG 1.4.11), whose AA floor is 3:1, not 4.5:1. The two numbers are not in conflict; they measure different things.

- [Rams design review skill](https://rams.ai/rams.md)
- [WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)

### Inconsistent Spacing

**ID:** `design-rams-inconsistent-spacing`
**Agent rule (SHOULD):** Use consistent spacing values from a defined scale (4px, 8px, 16px, etc.). Avoid mixing arbitrary pixel values. Inconsistent spacing creates visual imbalance.
**Source:** RAMS (https://www.rams.ai/)

Use consistent spacing between similar elements

> Inconsistent spacing values

The upstream rule is that four-word bullet, under "Layout & Spacing" — the explanation below is ours. Arbitrary gaps (13px here, 17px there) read as noise because proximity is how a reader infers grouping: if the gap between a label and its input is the same as the gap between two unrelated fields, nothing tells them which label belongs to which control. Pick a scale and stay on it — Tailwind's (4, 8, 12, 16, 24, 32…) is fine — and make the same relationship take the same step everywhere: all card paddings equal, all stack gaps equal, tighter inside a group than between groups.

- [Rams design review skill](https://rams.ai/rams.md)
- [Design System Spacing](https://tailwindcss.com/docs/theme)

### Crowded Elements

**ID:** `design-crowded-elements`
**Agent rule (SHOULD):** Provide adequate whitespace between interactive elements to prevent accidental activation. Touch targets should have at least 8px gap between them.
**Source:** Custom

Elements too close together reduce readability and usability

> Our rule: give adjacent interactive elements enough padding and spacing that each one can be read as separate and hit without hitting its neighbour.

This is our own rule, not an upstream citation — the Rams review has no bullet for it, and we previously mislabelled it as one. Two things go wrong in a cramped layout. Reading: with no breathing room, everything sits at the same visual weight and the eye has nothing to group by, so scanning degrades into reading. Pointing: adjacent tap targets with no gap between them produce mis-taps, which is the failure the WCAG 2.2 target rules are about — see interactions-match-hit-targets for the actual size floors (24×24 CSS px minimum, 44×44 on touch). Padding is the cheap fix; spacing between siblings is the one people forget.

- [NN/g — White Space in Form Design](https://www.nngroup.com/articles/form-design-white-space/)

### Excessive Whitespace

**ID:** `design-excessive-whitespace`
**Agent rule (SHOULD):** Balance whitespace - excessive gaps break visual relationships and increase scrolling. Group related elements with proximity. Whitespace should be intentional.
**Source:** Custom

Too much whitespace can fragment related content

> Our rule: space should encode grouping — keep related elements closer to each other than to anything else, so a gap always means a boundary.

This is our own rule, not an upstream citation — the Rams review has no bullet for it, and we previously mislabelled it as one. It is the mirror of design-crowded-elements, and the reason both exist is that whitespace is not a quantity to maximise, it is a signal. The Gestalt law of proximity says the eye groups what is near and separates what is far, so a generous gap dropped between a label and its input, or between a heading and the paragraph it introduces, actively tells the reader they are unrelated. Keep intra-group spacing smaller than inter-group spacing and the layout parses itself; invert that ratio and no amount of air will save it.

- [NN/g — The Principle of Proximity](https://www.nngroup.com/articles/gestalt-proximity/)

### Mixed Font Families, Weights, and Sizes

**ID:** `design-rams-font-consistency`
**Agent rule (SHOULD):** Use consistent font families, weights, and sizes throughout the interface. Limit to 2-3 font families maximum; take sizes from one typographic scale, with body text >= 16px on web and nothing below 12px.
**Source:** RAMS (https://www.rams.ai/)

Hold the whole type system to one decision: a small set of families, a named weight per role, and a single scale for sizes

> Mixed font families, weights, or sizes

That six-word bullet under "Typography" is the entire upstream rule, and it names all three axes at once — families, weights, sizes — so this principle does too. (It was previously split across two entries; the split invented a distinction the source never made.) The explanation is ours. FAMILIES: every extra family is a new voice in the room, and readers do not hear "variety", they hear "assembled from parts". Two is a system — one display, one text; a third needs a reason, usually a mono for code. WEIGHTS: give each weight a job (regular for body, medium for labels, semibold for headings) instead of nudging one paragraph to 500 because it looked thin. SIZES: a type scale is the index of the page — a reader who meets 15px, 16px, and 17px body copy on one screen cannot tell whether the difference means anything, so they stop trusting size as a signal at all. Pick the scale (Tailwind's xs → 2xl is one), give each step a job, and never introduce a size to solve a one-off fitting problem; fix the layout instead. The common thread across all three: reach for weight and size WITHIN one family before you reach for a second family, and take every value from a named token rather than from a style attribute.

- [Rams design review skill](https://rams.ai/rams.md)
- [Tailwind: font-family](https://tailwindcss.com/docs/font-family)
- [Tailwind: font-size](https://tailwindcss.com/docs/font-size)
- [Tailwind: font-weight](https://tailwindcss.com/docs/font-weight)

### Colors That Clash

**ID:** `design-color-harmony`
**Agent rule (SHOULD):** Use harmonious color combinations from a defined palette. Clashing colors create visual discomfort. Consider color temperature and saturation balance.
**Source:** Custom

Use harmonious color combinations from a defined palette

> Our rule: every colour in a view should come from one defined palette, related to the others by a deliberate relationship — not picked ad hoc at the call site.

This is our own rule, not an upstream citation — the Rams review has no bullet for it, and we previously mislabelled it as one. The practical test is not "do these two hues look nice together" but "where did this hue come from": a palette generated in a perceptual space (OKLCH is the practical one) gives you hues at matched lightness and chroma, so a warning next to a success next to a primary read as members of one family instead of three separate accidents. Ad-hoc picks fail in a specific way — they collide at the same lightness, so the eye cannot tell which one is meant to be louder. Choose the relationship (analogous, complementary, triadic) once, encode it as tokens, and let components consume tokens only.

- [Color Mechanics in UI](https://www.smashingmagazine.com/2023/04/color-mechanics-ui-kits/)

### Inconsistent Semantic Colors

**ID:** `design-color-meaning`
**Agent rule (SHOULD):** Use semantic color tokens consistently - red/destructive for errors, green/success for confirmation, yellow/warning for caution, blue/info for information.
**Source:** Custom

Use semantic colors consistently (error=red, success=green)

> Our rule: once a colour carries a meaning in your product, it carries only that meaning — never ship a green Delete or a red Success.

This is our own rule, not an upstream citation — the Rams review has no bullet for it, and we previously mislabelled it as one. It is NOT the same rule as design-semantic-colors, which is about token naming (write `bg-destructive`, not `bg-red-600`, so themes can move). You can obey that one perfectly and still hand `bg-destructive` to the Save button. This rule is about the meaning a colour has already acquired: users read red as stop/danger and green as go/safe before they read the label, so an inverted pair does not merely confuse, it gets the destructive action clicked. Fix the semantics of the mapping, then remember that colour is only ever the second signal — the label and the icon must say it too (see content-redundant-cues).

- [Psychology of Color in UX](https://www.smashingmagazine.com/2025/08/psychology-color-ux-design-digital-products/)

### Inconsistent Border Radius

**ID:** `design-rams-border-radius`
**Agent rule (SHOULD):** Apply consistent border-radius values from a defined scale. Nested elements should have proportionally smaller radii (outer - border-width = inner).
**Source:** RAMS (https://www.rams.ai/)

Use consistent border radius values across components

> Inconsistent borders, shadows, or icon sizing

The upstream rule is that one bullet under "Components" (design-rams-shadow-consistency covers its shadow half); the explanation is ours. Radius is a material property: a product where every surface is cut the same way reads as one object, and a card at 4px next to a card at 12px reads as two products glued together. Define radius tokens and hand them out by role — controls one value, containers another, pills fully round — rather than choosing per component. When one rounded box sits inside another, keep the curves concentric: child radius ≤ parent radius, ideally parent minus the padding (see design-nested-radii).

- [Rams design review skill](https://rams.ai/rams.md)
- [Border Radius](https://tailwindcss.com/docs/border-radius)

### Inconsistent Shadow Usage

**ID:** `design-rams-shadow-consistency`
**Agent rule (SHOULD):** Use consistent elevation/shadow tokens to convey hierarchy. Ensure shadows have sufficient contrast in both light and dark themes. Avoid mixing shadow styles.
**Source:** RAMS (https://www.rams.ai/)

Apply shadows consistently to establish visual hierarchy

> Inconsistent borders, shadows, or icon sizing

Same upstream bullet as design-rams-border-radius — one line under "Components" — read here for its shadow half; the explanation is ours. A shadow is a claim about where an element sits in space, and the room only holds together if every claim assumes the same light source. Hand-rolled shadows with different blur, offset, and direction put three cards under three different suns, and the eye reads that as noise rather than depth. Assign elevation by role — resting cards one step, dropdowns and popovers a step above, modals the top — and take the values from one ramp (see design-ibelick-default-shadows for the Tailwind scale, and design-layered-shadows for building a two-layer shadow when you do need a custom one).

- [Rams design review skill](https://rams.ai/rams.md)
- [Box Shadow](https://tailwindcss.com/docs/box-shadow)

### One Icon Scale, One Stroke Width

**ID:** `design-icon-size-scale`
**Agent rule (SHOULD):** Bind icon sizes to ONE scale (16 / 20 / 24, matched to the type scale — `size-4` next to `text-sm`, `size-5` next to `text-base`) and hold the whole set to ONE stroke width, which in practice means taking every glyph from a single icon family. A toolbar sized by eye (`w-4`, `w-5`, `size-[18px]`, `h-6`) reads as ragged even when every box is aligned, because the eye compares the drawn marks and not the boxes; and a 1.5px stroke beside a 2px stroke gives two apparent weights at the same nominal size. Sizes come from tokens — a lone `size-[18px]` is a magic number.
**Source:** RAMS (https://www.rams.ai/)

Bind icon sizes to the type scale and hold every icon to a single stroke width, instead of sizing each one by eye

> Inconsistent borders, shadows, or icon sizing

The third clause of that bullet — the one this corpus kept dropping. design-rams-border-radius covers "borders" and design-rams-shadow-consistency covers "shadows"; this is "icon sizing", and the explanation is ours. Icons are the one element people size by eye, so a toolbar ends up at w-4, w-5, size-[18px], h-6 — every glyph centered, every box aligned, and the row still reads as ragged, because the eye compares the drawn marks and not the boxes around them. Stroke width is the half nobody checks: a 1.5px stroke next to a 2px stroke at the same nominal size gives you two apparent weights, so one icon looks bolder than its neighbour for no reason anyone can name. Fix both with two decisions. One SIZE scale — 16 / 20 / 24, bound to the type scale so an icon matches the text it sits beside (size-4 next to text-sm, size-5 next to text-base) — and one STROKE width across the whole set, which in practice means taking every glyph from a single icon family rather than mixing libraries. Sizes come from tokens, not from arbitrary values: a lone size-[18px] is a magic number that the next person will guess wrong.

- [Rams design review skill](https://rams.ai/rams.md)
- [MDN: stroke-width](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/stroke-width)
- [Tailwind: width](https://tailwindcss.com/docs/width)

### Misaligned Elements

**ID:** `design-rams-alignment`
**Agent rule (SHOULD):** Align related elements consistently using a grid system. Left-align text content for readability. Center buttons only when intentionally creating a focal point.
**Source:** RAMS (https://www.rams.ai/)

Elements should align to a consistent grid or baseline

> Overflow issues, alignment problems

The upstream rule is that four-word bullet under "Layout & Spacing"; the explanation is ours. Alignment is the cheapest structure you get for free: shared edges create implicit lines, and the eye uses those lines to decide what belongs together, so a control that sits 3px off the column reads as an error long before anyone can name why. Establish the edges once — a grid, or a flex container with a single alignment rule — and let every child inherit them, instead of nudging individual elements into place with margins. Watch the two places it usually breaks: text and icon on a shared baseline inside a button, and numbers in a table, which should be right-aligned and tabular so the digits line up by place value.

- [Rams design review skill](https://rams.ai/rams.md)
- [Flexbox](https://tailwindcss.com/docs/flex)
- [Grid](https://tailwindcss.com/docs/grid-template-columns)

### Avoid Gradients Unless Requested

**ID:** `design-ibelick-no-gradients`
**Agent rule (NEVER):** Use gradients unless explicitly requested. Solid colors are easier to maintain, more accessible, and don't clash with content.
**Source:** @Ibelick (https://www.ui-skills.com/)

Solid colors are cleaner and more maintainable - only use gradients when explicitly asked

> NEVER use gradients unless explicitly requested

That is the rule verbatim from the baseline-ui skill — one RFC-2119 line under "Design". Our reasoning: a gradient is a decision nobody asked for that then has to be maintained in every theme, and it quietly breaks the things around it. Text on a gradient has no single contrast ratio, so it passes at one end and fails at the other; a gradient surface has no single token, so dark mode has to re-author it rather than re-map it. Solid colours are cheaper, testable, and themable. If the brand genuinely calls for a gradient, that is an explicit request — build it once, as a token, and keep text off it.

- [ibelick — baseline-ui skill](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/baseline-ui/SKILL.md)
- [Flat Design Guidelines](https://www.nngroup.com/articles/flat-design/)

### Avoid Purple and Multicolor Gradients

**ID:** `design-ibelick-no-purple`
**Agent rule (NEVER):** Use purple or multicolor gradients. They are hallmarks of AI-generated slop and generic templates. Choose distinctive, intentional colors.
**Source:** @Ibelick (https://www.ui-skills.com/)

Purple and rainbow gradients are overused in AI-generated designs - avoid them

> NEVER use purple or multicolor gradients

Verbatim from the baseline-ui skill — the line that follows its blanket "NEVER use gradients unless explicitly requested" (see design-ibelick-no-gradients), singling out the two variants that are never a considered choice. Our reasoning: violet-to-fuchsia and full-spectrum rainbows are the house style of every AI design tool and every undesigned SaaS template, so shipping one tells the viewer exactly where the interface came from. They also carry the same technical costs as any gradient — no stable contrast ratio under text, no single token to re-map in dark mode — with none of the brand justification.

- [ibelick — baseline-ui skill](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/baseline-ui/SKILL.md)
- [Design System Colors](https://www.smashingmagazine.com/2023/04/color-mechanics-ui-kits/)

### Don't Use Glow as Affordance

**ID:** `design-ibelick-no-glow`
**Agent rule (NEVER):** Use glow effects (box-shadow with blur and color) as primary affordances. Glows are decorative, not functional. Use borders or backgrounds for affordance.
**Source:** @Ibelick (https://www.ui-skills.com/)

Never rely on glow effects as the primary indicator for interactive elements

> NEVER use glow effects as primary affordances

Verbatim from the baseline-ui skill — one line under "Design". Our reasoning: a glow is a soft, low-contrast halo, which is precisely the wrong material for the one job an affordance has, namely being unmistakable. It washes out in sunlight, renders differently on every panel, and is invisible to anyone who cannot perceive the hue it is made of. If a glow is the only thing marking a control as interactive, the control has no marking. Carry the affordance on something structural — a border, a fill, a shape, a label — and treat glow as ornament layered on top, never as the signal itself. The same applies to focus: a glow is not a focus ring.

- [ibelick — baseline-ui skill](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/baseline-ui/SKILL.md)
- [Clickability Signifiers](https://www.nngroup.com/articles/clickable-elements/)

### Use Tailwind Default Shadows

**ID:** `design-ibelick-default-shadows`
**Agent rule (SHOULD):** Use Tailwind CSS default shadow scale (shadow-sm, shadow, shadow-md) unless explicitly requested. Custom shadows often clash with the design system.
**Source:** @Ibelick (https://www.ui-skills.com/)

Stick with Tailwind's default shadow scale instead of custom values

> SHOULD use Tailwind CSS default shadow scale unless explicitly requested

That is the rule verbatim from the baseline-ui skill; everything below is ours. The scale is designed as one ramp lit from a single source, so elevation reads as depth rather than as noise; hand-rolled shadows with different blur, offset, and direction give you three cards that no longer sit in the same room. Get the names right, because they moved in v4: the scale runs `shadow-2xs`, `shadow-xs`, `shadow-sm`, `shadow-md`, `shadow-lg`, `shadow-xl`, `shadow-2xl`, and there is no bare `shadow` class any more. Worse than missing, the old names silently changed meaning — v4's `shadow-sm` renders what v3's bare `shadow` did, and v3's `shadow-sm` is now `shadow-xs`. So a v3 codebase that upgrades without a codemod does not break loudly; every `shadow-sm` in it just quietly gets one step heavier.

- [ibelick — baseline-ui skill](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/baseline-ui/SKILL.md)
- [Tailwind v4: box-shadow](https://tailwindcss.com/docs/box-shadow)
- [Tailwind v4: Upgrade guide](https://tailwindcss.com/docs/upgrade-guide)

### Empty States Need Clear Actions

**ID:** `design-ibelick-empty-states`
**Agent rule (MUST):** Give empty states one clear next action. "No results" with a button to adjust filters. "No items" with a button to create first item. Never leave users stuck.
**Source:** @Ibelick (https://www.ui-skills.com/)

Every empty state should have one clear action to guide users forward

> MUST give empty states one clear next action

Verbatim from the baseline-ui skill — one line under "Design". Our reasoning: an empty state is the first screen a new user sees, and "No items" is a dead end dressed up as information. It reports a fact the user can already see and withholds the only thing they need, which is what to do about it. Give it three parts — what this space is for, why it is empty right now, and one primary action that fills it — and note the word "one": two competing buttons hand the decision straight back. Distinguish the empty cases, too, because they need different actions: nothing created yet is an invitation, no search results is a prompt to widen the filter, and a load failure is a retry.

- [ibelick — baseline-ui skill](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/baseline-ui/SKILL.md)
- [Empty State Design](https://www.nngroup.com/articles/empty-state-interface-design/)

### Limit Accent Colors

**ID:** `design-ibelick-color-restraint`
**Agent rule (SHOULD):** Limit accent color usage to one per view. Use existing theme or Tailwind color tokens before introducing new colors. Every new color needs justification.
**Source:** @Ibelick (https://www.ui-skills.com/)

Use only one accent color per view to maintain visual hierarchy and reduce noise

> SHOULD limit accent color usage to one per view

Verbatim from the baseline-ui skill — one line under "Design". Our reasoning: an accent works by being the exception, so its power is inversely proportional to how often it appears. Two accents on one screen do not give you two emphases; they give you an argument, and the user has to resolve it before they can act. Spend the accent on the single most important action in the view and let everything else be neutral — secondary actions can be text or outline, not another colour. This is about EMPHASIS, and it is compatible with the semantic palette: destructive red on a delete confirmation and success green on a completed state are meanings, not accents (see design-color-meaning), and they should not be recruited to add visual interest.

- [ibelick — baseline-ui skill](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/baseline-ui/SKILL.md)
- [Psychology of Color in UX](https://www.smashingmagazine.com/2025/08/psychology-color-ux-design-digital-products/)

### Custom Selection Styling

**ID:** `design-selection-styling`
**Agent rule (SHOULD):** Style `::selection` with brand colors instead of shipping the browser default blue.
**Source:** Rauno (https://interfaces.rauno.me/)

Style the document selection state with ::selection to match the brand

> Style the document selection state with ::selection.

The default browser selection color is a generic blue that rarely matches your design. Customizing ::selection with your brand colors creates a more cohesive and polished experience. It's a small detail that shows attention to craft.

```tsx
::selection { background: var(--accent); color: var(--accent-foreground); }
```

- [interfaces.rauno.me](https://interfaces.rauno.me/)
- [MDN ::selection](https://developer.mozilla.org/en-US/docs/Web/CSS/::selection)

### Feedback Near Trigger

**ID:** `design-feedback-near-trigger`
**Agent rule (MUST):** Render feedback at its trigger: swap the copy button to an inline checkmark, highlight the erroring input — do not fire a distant toast for a local action.
**Source:** Rauno (https://interfaces.rauno.me/)

Display feedback relative to its trigger — show inline confirmation, not distant notifications

> Display feedback relative to its trigger: Show a temporary inline checkmark on a successful copy, not a notification. Highlight the relevant input(s) on form error(s).

When feedback appears far from the action that triggered it, users may miss it entirely. Showing confirmation inline — like a checkmark replacing a copy button or highlighting the specific input with an error — keeps attention where it belongs.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Server-Side Auth Redirects

**ID:** `design-server-auth-redirect`
**Agent rule (MUST):** Redirect unauthenticated users on the server (302 before any HTML ships), not from a client-side effect — client redirects flash the protected page and jank the URL.
**Source:** Rauno (https://interfaces.rauno.me/)

Authentication redirects should happen on the server to avoid janky client-side URL changes

> Authentication redirects should happen on the server before the client loads to avoid janky URL changes.

Client-side auth checks load the protected page first, then redirect to login after JavaScript executes — causing a visible flash of the wrong page and a jarring URL change. Server-side redirects (302) send users directly to the login page before any content loads.

- [interfaces.rauno.me](https://interfaces.rauno.me/)

### Declare color-scheme for Dark Themes

**ID:** `design-color-scheme`
**Agent rule (MUST):** Set `color-scheme` on `<html>` (`dark`, or `light dark` to follow the OS) so browser-drawn UI — scrollbars, checkboxes, radios, range tracks, date pickers, number spinners — repaints for the theme. This is separate from reading `prefers-color-scheme`, which only tells you what the user wants.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set the CSS color-scheme property on <html> so native browser UI follows the theme

> `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)

Your CSS only paints what you render — scrollbars, checkboxes, radios, range tracks, date pickers, and number spinners are drawn by the browser itself, and it draws them light unless told otherwise. The `color-scheme` property is that signal: it switches the user agent's rendering intent, so those native widgets repaint dark for free. This is distinct from reading `prefers-color-scheme` (which tells *you* what the user wants, and prevents a theme flash) — `color-scheme` tells the *browser* what you chose. Set `color-scheme: dark` on the dark theme, or `light dark` on `<html>` to let the UA follow the OS.

```tsx
html { color-scheme: light dark; }
html[data-theme="dark"] { color-scheme: dark; }
```

- [MDN: color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme)
- [web.dev: Improved dark mode default styling](https://web.dev/articles/color-scheme)

### Match theme-color to the Page Background

**ID:** `design-theme-color-meta`
**Agent rule (SHOULD):** Match the mobile browser and PWA chrome to the page background by shipping one `<meta name="theme-color">` per scheme with the literal background value — a `<meta>` tag cannot read CSS custom properties, and leaving it unset puts a default light address bar above a dark page.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Declare a <meta name="theme-color"> per color scheme so browser chrome matches the page

> `<meta name="theme-color">` matches page background

On mobile, the surface directly above your page is not yours — Safari and Chrome tint the address bar, and an installed PWA tints its title bar and task-switcher card, from `<meta name="theme-color">`. Leave it unset and that chrome keeps a default light fill, producing a hard seam above a dark page. A `<meta>` tag cannot read CSS custom properties, so ship one tag per scheme with the literal background value and a `media` attribute: `media="(prefers-color-scheme: dark)"` and a matching light one.

```tsx
<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0a0a0a" media="(prefers-color-scheme: dark)">
```

- [MDN: meta name="theme-color"](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/name/theme-color)

### Give Native Selects Explicit Colors

**ID:** `design-select-colors`
**Agent rule (MUST):** Set BOTH `background-color` and `color` on every native `<select>` from your tokens (and pair them with `color-scheme` so the option popup follows) — form controls do not inherit them, so styling only the text leaves near-white on the platform's white Field background in Windows dark mode.
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Set both background-color and color on every native <select>, never just one

> Native `<select>`: explicit `background-color` and `color` (Windows dark mode)

Form controls do not inherit `color` and `background-color` the way ordinary elements do — the browser supplies its own. Style only the text for your dark theme and the platform keeps its light Field background underneath, giving you near-white text on white: the value and every option in the popup become unreadable. This bites hardest on Windows, where the UA background is least likely to follow your theme. Declare both properties from your tokens, and pair them with `color-scheme` so the native option list is drawn dark too.

- [MDN: <select>](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select)
- [MDN: color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme)

### No Side-Stripe Accent Borders

**ID:** `design-impeccable-side-tab-border`
**Agent rule (NEVER):** Hang a thick colored stripe off one side of a card (one border side >= 2px while the others are <= 1px, in a non-neutral color, on a rounded box) — it makes the border-box asymmetric so text lands off-centre, and encodes status in hue alone. Use one even border, a tinted surface, and a leading icon plus a worded status.
**Source:** impeccable (https://impeccable.style/)

Border a card evenly on all four sides instead of hanging a thick colored stripe off one edge

> Thick colored border on one side of a card — the most recognizable tell of AI-generated UIs.

impeccable's detector flags an element when one side's border-width is >= 2px while the others are <= 1px (or at least twice the widest other side), the border color is non-neutral, and either the width is >= 3px or the border-radius is greater than zero — a stripe on a rounded card. The pattern is not just overused: it makes the border-box asymmetric so text lands off-center, and it encodes status in hue alone. Use one even border, a tinted surface, and a leading icon plus a worded status instead.

- [impeccable.style](https://impeccable.style/)
- [MDN: border-left](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-left)

### No Glowing Accents on Dark Backgrounds

**ID:** `design-impeccable-dark-glow`
**Agent rule (NEVER):** Add a colored `box-shadow` glow (chroma >= 30, blur radius > 4px) to elements sitting on a near-black surface (relative luminance < 0.1). Build depth on dark from a surface lightness scale (roughly 15% / 20% / 25%), which stays legible in bright ambient light and costs no extra paint.
**Source:** impeccable (https://impeccable.style/)

Build depth on dark surfaces with a lightness scale, not with colored box-shadow glows

> Dark backgrounds with colored box-shadow glows are the default "cool" look of AI-generated UIs.

impeccable's detector fires when a background's relative luminance is below 0.1 and the element carries a box-shadow whose color chroma is >= 30 with a blur radius greater than 4px — light spilling out of a component onto a near-black page. This is distinct from "Avoid Glow as an Affordance" (design-ibelick-no-glow), which is about glow standing in for a real interaction signal; here the glow is applied to everything, so it signals nothing and merely dates the design. On dark, elevation should come from a surface lightness scale (roughly 15% / 20% / 25%), which stays legible in bright ambient light and costs no extra paint.

- [impeccable.style](https://impeccable.style/)
- [MDN: box-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/box-shadow)

### No Gradient Text

**ID:** `design-impeccable-gradient-text`
**Agent rule (NEVER):** Use `background-clip: text` (or `-webkit-background-clip: text`) with a gradient background and a transparent text color — the glyphs then have no color, so the selection highlight paints behind invisible letters and forced-colors mode can erase the heading entirely. Set one solid color and carry emphasis with weight or size.
**Source:** impeccable (https://impeccable.style/)

Set headings in a single solid color and carry emphasis with weight or size, not a clipped gradient

> Gradient text. `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.

The detector looks for `background-clip: text` (or its `-webkit-` alias) paired with a gradient background and a transparent text color. The gradient is painted as the element's background and clipped to the glyphs, which means the text itself has no color: the selection highlight paints behind transparent letters and the words disappear while selected, and forced-colors mode strips the background image so the heading can vanish entirely. The hue carries no information — it never encodes state, importance, or grouping — so a solid color plus a heavier weight or a larger size says the same thing without breaking selection and high-contrast users.

- [impeccable.style](https://impeccable.style/)
- [MDN: background-clip](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/background-clip)
- [MDN: forced-color-adjust](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/forced-color-adjust)

### Glassmorphism Is Not a Default

**ID:** `design-impeccable-no-glassmorphism`
**Agent rule (NEVER):** Apply `backdrop-filter: blur()` to ordinary content surfaces (cards, tiles, panels) — it re-blurs everything behind it on every scroll tick, and makes text contrast a property of whatever happens to be scrolling underneath (the same label can measure 8:1 over one band and 1.9:1 over the next), which no test can catch. Reserve blur for chrome that genuinely overlaps scrolling content — a sticky nav, a sheet — and use opaque surfaces everywhere else.
**Source:** impeccable (https://impeccable.style/)

Reserve backdrop blur for a surface that genuinely overlaps scrolling content, and use opaque surfaces everywhere else

> Glassmorphism as default. Blurs and glass cards used decoratively. Rare and purposeful, or nothing.

The detector flags `backdrop-filter: blur()` (any radius) applied to ordinary content surfaces — cards, tiles, panels — rather than to an overlay. Two costs follow. Paint: the browser must sample and blur everything behind the element on every frame it is composited, so a grid of glass cards re-blurs on each scroll tick. Contrast: the effective color behind translucent text is whatever happens to be scrolling underneath, so the same label can measure 8:1 over a dark band and 1.9:1 over a light one — the ratio is a property of the backdrop, not of your tokens, and cannot be tested. Blur earns its cost in exactly one place: chrome (a sticky nav, a sheet) that overlaps scrolling content, where the effect communicates layering. Even there, Emil Kowalski's apple-design skill draws one hard line inside the exception: "**Never stack a light translucent surface on another** — legibility collapses," because each layer samples the already-blurred layer beneath it and the text ends up floating on mush. And note what this principle does NOT cover: it polices glass on taste and cost grounds, but never asks whether the user has requested less of it — for that, see design-reduced-transparency-contrast.

- [impeccable.style](https://impeccable.style/)
- [MDN: backdrop-filter](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/backdrop-filter)
- [emilkowalski/skills — apple-design](https://github.com/emilkowalski/skills/tree/main/skills/apple-design)

### Never #000, Never #fff

**ID:** `design-impeccable-tinted-neutrals`
**Agent rule (NEVER):** Ship `#000`, `#fff`, or zero-chroma grays like `#808080` — tint every neutral toward the brand's hue at OKLCH chroma ~0.005–0.015, letting chroma fall toward 0 as lightness approaches 0 or 100. Use the actual brand hue, not a reflexive warm-orange or cool-blue.
**Source:** impeccable (https://impeccable.style/)

Tint every neutral toward the brand hue instead of shipping pure black, pure white, and dead grays

> Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).

The target is OKLCH chroma between roughly 0.005 and 0.015 at the brand's hue: small enough that nobody would call the surface "tinted", large enough to produce a subconscious sense that the neutrals and the brand color belong to one system. Pure #000, #fff, and #808080 have zero chroma, so they have no hue relationship to anything you ship and read as detached. Two lazy reflexes to avoid: tinting everything warm-orange, or everything cool-blue, regardless of what the brand actually is — the hue must be the brand's. Chroma must also fall toward zero as lightness approaches 0 or 100, otherwise the near-white and near-black ends start to look visibly colored rather than quietly cohesive.

```tsx
--surface: oklch(0.98 0.008 265);
--ink: oklch(0.18 0.01 265);
```

- [impeccable.style](https://impeccable.style/)
- [MDN: oklch()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklch)

### Alpha Is a Design Smell

**ID:** `design-impeccable-alpha-smell`
**Agent rule (SHOULD):** Define an explicit opaque token per surface instead of reaching for `rgba()`/`hsla()` to fake a missing palette step — a translucent color's contrast ratio belongs to the backdrop, not the token, so the same `text-white/60` can measure 6.2:1 on one surface and 2.7:1 on the next. Exception: focus rings and transient hover/pressed states, which never carry text.
**Source:** impeccable (https://impeccable.style/)

Define an explicit opaque token per surface instead of leaning on rgba() and hsla() to fake missing palette steps

> Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency.

A translucent color has no fixed value: the browser flattens it against whatever sits behind it, so the final color — and therefore the contrast ratio — is a property of the backdrop, not of the token. The same `text-white/60` label can measure 6.2:1 on one surface and 2.7:1 on the next, meaning a component that passes AA in the design file silently fails the moment it is reused, and no CI check can catch it because the value only exists at composite time. Stacked alpha compounds this and adds blending work per layer. When you reach for alpha to get "a slightly lighter gray", what you actually need is another step in the palette. The stated exception: focus rings and interactive states (hover, pressed), where the effect is transient and never carries text.

- [impeccable.style](https://impeccable.style/)
- [WCAG 2.1: Contrast (Minimum)](https://www.w3.org/TR/WCAG21/#contrast-minimum)

### Hairline Border or Soft Shadow, Not Both

**ID:** `design-impeccable-hairline-plus-shadow`
**Agent rule (NEVER):** Pair a visible hairline border with a wide, diffuse shadow — it is a generated-UI signature. The two make contradictory claims: the hairline says the surface has a crisp edge in the plane, the soft shadow says it is floating above the plane with light wrapping its edge, so the border kills the lift and the shadow kills the line. Commit to one — a defined EDGE (crisp hairline, no shadow) or a soft ELEVATION (shadow, no border). The detector fires on >=2 sides at <=1.5px with border alpha >=0.28 while a shadow layer of alpha >=0.12 has blur >=16px: `border shadow-lg` fires, `border shadow-xs` does not. A single layered shadow that INCLUDES its ring (`0 0 0 1px …`, 0 blur) is not this pattern — see `design-layered-shadows`.
**Source:** impeccable (https://impeccable.style/)

Commit a card to a defined edge or to a soft elevation — pairing a 1px border with a wide diffuse shadow is the "every card style I know" tell

> A hairline border paired with a wide, diffuse shadow is a recurring generated-UI signature. Commit to one — a defined edge or a soft elevation — rather than both at once.

The detector is precise about what counts: at least two sides carrying a VISIBLE hairline (width <= 1.5px with border-color alpha >= 0.28) while the element also has a box-shadow whose largest blur radius is >= 16px, measured only across shadow layers with alpha >= 0.12. So `border shadow-lg` on a card fires it; `border shadow-xs` does not, and neither does a shadow built entirely from near-invisible layers. The reason it reads as cheap is that the two devices make contradictory claims. A hairline says "this surface has a crisp, defined boundary and sits in the plane." A wide diffuse shadow says "this surface is floating above the plane, and its edge is soft because light wraps around it." Ship both and the edge fights the lift: the border stops the shadow from selling elevation, and the shadow stops the border from reading as a deliberate line. Pick one and mean it — a crisp hairline with no shadow (flat, precise, editorial), or a soft shadow with no border (lifted, tactile). Note the one legitimate exception, which is not this pattern: a shadow that INCLUDES its hairline as a 0-blur ring layer (`0 0 0 1px …`) is a single layered shadow, not a border plus a shadow — see design-layered-shadows.

- [impeccable](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [MDN: box-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/box-shadow)

### Desaturate Status Colors on Dark

**ID:** `design-interface-desaturate-on-dark`
**Agent rule (SHOULD):** Give each semantic color (success, error, warning) a SEPARATE dark-theme value: hold the hue angle, raise lightness a little, and pull chroma DOWN. A swatch picked to fight a white surface has nothing to fight on near-black — it vibrates and the glyph edges shimmer. It is not a contrast failure (the ratio may pass), it is a saturation failure. On dark, also lean on borders rather than shadows, which barely read. This moves the OPPOSITE way from `design-impeccable-tinted-neutrals` (which pushes a little brand chroma INTO the neutrals); a palette should do both.
**Source:** interface-design (https://github.com/Dammyjay93/interface-design)

Keep the hue and drop the chroma when a semantic color moves to a dark surface, because the swatch tuned for white vibrates on near-black

> Dark mode. Shadows are weak on dark — lean on borders. Desaturate semantic colors slightly. Same hierarchy system, inverted values. Keep one hue; shift only lightness across surfaces.

A success green and an error red are picked against white, where a high-chroma swatch has to fight a bright surface to be seen. Move the identical token to a near-black panel and the fight is over: the same chroma now sits against almost no lightness, the edges of the glyphs shimmer, and the badge buzzes rather than reads. It is not a contrast failure — the ratio may pass — it is a saturation failure, and the fix is the third sentence of the quote: same hue, less chroma. In OKLCH that is one number: hold the hue angle, raise lightness a little so the badge stays legible, and pull chroma down until the swatch sits still. This is NOT design-impeccable-tinted-neutrals, which pushes the NEUTRALS a tiny amount of chroma TOWARD the brand hue so surfaces feel like one system. This rule moves in the opposite direction on the opposite tokens: it takes chroma AWAY from an already-saturated SEMANTIC color so it survives a dark surface. A palette can and should do both. Express the pair as two theme values per semantic role rather than one, and let the dark token be a deliberate value, not the light one reused.

- [interface-design (Damola Akinleye)](https://github.com/Dammyjay93/interface-design)
- [OKLCH color picker](https://oklch.com/)
- [Material Design: Dark theme](https://m2.material.io/design/color/dark-theme.html)

### Controls Get Their Own Tokens

**ID:** `design-interface-control-tokens`
**Agent rule (SHOULD):** Declare `--control-bg`, `--control-border` and `--control-focus` as their own trio — do not bind inputs, selects and checkboxes to the surface/card tokens. A card is a surface that RECEIVES the eye and should recede; an input must announce itself as a place where something goes, and if it shares the card's background and the divider's border its boundary lands near 1.2:1 and the field becomes a rumour. Separable tokens are what let you meet `design-non-text-contrast` (WCAG 1.4.11, 3:1 for the boundary that identifies a control) without shouting every divider on the page. On dark, inputs read best slightly DARKER than their surroundings — an inset well says "type here" without chrome.
**Source:** interface-design (https://github.com/Dammyjay93/interface-design)

Give inputs, checkboxes and selects dedicated background, border and focus tokens instead of reusing the card and background tokens

> Control tokens. Inputs/selects/checkboxes get dedicated background, border, and focus tokens — don't reuse surface tokens, so you can tune controls independently.

This is why form fields disappear into the page. A card token and a control token are asked to do opposite jobs: a card is a surface that RECEIVES the eye and should recede, while an input is a surface that INVITES input and must announce itself as a place where something goes. Bind `--control-bg` to `--card` and the field is exactly as bright as the panel it sits in, so the only thing left marking it as a field is its border — and if that border is also the card's `--border`, tuned to be a quiet divider, the boundary lands near 1.2:1 and the input becomes a rumour. Upstream's own advice sharpens the point: on dark, inputs should be slightly DARKER than their surroundings, not lighter, because an inset well reads as "type here" without heavy chrome — a move you simply cannot make while the control shares the surface token. Declare `--control-bg`, `--control-border` and `--control-focus` as their own trio, and tune them against one hard floor: design-non-text-contrast (WCAG 1.4.11) requires 3:1 for the visual boundary that identifies a control, measured against the surface actually behind it. That floor is the reason the tokens must be separable — you cannot raise the input border to 3:1 without also shouting every divider on the page, unless the two are different tokens.

- [interface-design (Damola Akinleye)](https://github.com/Dammyjay93/interface-design)
- [Understanding SC 1.4.11: Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)

### Four Text Levels, Not Two

**ID:** `design-interface-text-hierarchy-levels`
**Agent rule (SHOULD):** Define four text levels as tokens and use all four — primary (body, highest contrast), secondary (supporting copy), tertiary (metadata: timestamps, field labels, counts), muted (disabled/placeholder, lowest contrast). Two levels ("text" and "gray text") collapse every secondary role onto one step, so nothing recedes. Weight and colour carry more hierarchy than size — a single 14px size can hold three tiers.
**Source:** interface-design (https://github.com/Dammyjay93/interface-design)

Build four text levels — primary, secondary, tertiary, muted — and use all four, instead of shipping "text" and "gray text"

> Don't just have "text" and "gray text." Build four levels... Use all four consistently. If you're only using two, your hierarchy is too flat.

The four levels have fixed jobs: primary is default body text at the highest contrast; secondary is supporting copy, slightly muted; tertiary is metadata — timestamps, field labels, counts; muted is disabled and placeholder text, the lowest contrast in the system. Ship only two and every secondary role collapses onto one step: the field label, the supporting sentence, the timestamp and the greyed-out placeholder all shout at the same volume, so nothing recedes and the eye has nowhere to go. The fix is not a new font size — the Apple/Linear move is that weight and colour carry more hierarchy than size, so a single 14px size can hold three tiers cleanly. Define the four as tokens once and bind every text role to one of them, rather than reaching for whichever grey is nearest.

- [interface-design (Damola Akinleye)](https://github.com/Dammyjay93/interface-design)
- [NN/g: Visual Hierarchy](https://www.nngroup.com/articles/visual-hierarchy-ux-definition/)

### On Dark, Borders Beat Shadows

**ID:** `design-interface-dark-borders-over-shadows`
**Agent rule (SHOULD):** On dark surfaces define elevation with a hairline low-opacity border plus one small step of surface lightness, not a drop shadow — a shadow works by darkening pixels behind the element and near-black has no luminance left to remove, so `shadow-lg` exists in the computed style and nowhere on screen.
**Source:** interface-design (https://github.com/Dammyjay93/interface-design)

Define elevation on dark surfaces with a hairline border and a surface lightness step, because a drop shadow has nothing left to darken

> Borders over shadows — Shadows are less visible on dark backgrounds. Lean more on borders for definition.

A drop shadow works by darkening the pixels behind an element. On a near-black background there is almost no luminance left to remove, so shadow-lg on a dark card produces an elevation that exists in the computed style and nowhere on the screen — and if the card fill matches the panel behind it, the edges disappear entirely. Definition on dark comes from two cheaper, more reliable levers: a hairline border (a low-opacity light stroke reads as a crisp edge at any ambient brightness) and one small step of surface lightness — each jump only a few percentage points, barely visible in isolation but unmistakable once stacked. This is distinct from two neighbours in this corpus. design-impeccable-dark-glow is about the opposite failure — a saturated chroma glow spilling off a dark card, which is loud but meaningless. content-impeccable-dark-mode-text-compensation is about the type on dark (weight and colour compensation), not the box around it. This principle is only about where the edge of the box comes from.

- [interface-design (Damola Akinleye)](https://github.com/Dammyjay93/interface-design)
- [Material Design: Dark theme](https://m2.material.io/design/color/dark-theme.html)
- [MDN: box-shadow](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/box-shadow)

### Text Anti-Aliasing and Transforms

**ID:** `design-text-antialiasing-transforms`
**Agent rule (SHOULD):** Animate a wrapper rather than the text node when scaling — re-rasterizing glyphs at fractional sizes makes strokes crawl and can flip sub-pixel anti-aliasing to grayscale mid-flight, and one wrapper transform keeps the lockup scaling as a single object. If artifacts persist, promote the wrapper with `translateZ(0)` or `will-change: transform` and release it when the transition ends (blanket promotion is still wrong — see `performance-gpu-translatez`).
**Source:** Vercel (https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)

Animate a wrapper rather than the text node itself, and promote it to its own layer when scaling artifacts persist

> Text anti-aliasing & transforms. Scaling text can change smoothing. Prefer animating a wrapper instead of the text node. If artifacts persist set `translateZ(0)` or `will-change: transform` to promote to its own layer.

Glyphs are hinted and anti-aliased for the size they are rendered at. Put a scale transform directly on a text node and the browser may re-rasterize it at every intermediate fractional size, so the strokes visibly crawl and thicken through the animation, and sub-pixel anti-aliasing can switch to grayscale mid-flight. Moving the transform up to a wrapper fixes the composition too: one transform and one origin means the lockup scales as a single object instead of each line scaling about its own centre and drifting apart. If artifacts survive that, promote the wrapper — translateZ(0) or will-change: transform gives it its own compositor layer, so the text is rasterized once and merely re-composited per frame. Distinct from performance-gpu-translatez, which is about when promotion is worth its memory cost at all (and warns against blanket promotion) — here promotion is a targeted, transient fix for a rendering artifact, applied to the animating wrapper and released when the transition ends. Also distinct from content-font-smoothing, which concerns static -webkit-font-smoothing choices, not the smoothing change a transform induces.

```tsx
.title-wrap { will-change: transform; transform: scale(0.96); }
.title-wrap.is-in { transform: scale(1); } /* drop will-change on transitionend */
```

- [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines)
- [MDN: will-change](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/will-change)
- [MDN: transform](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/transform)
- [MDN: font-smooth](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-smooth)

### Non-Text Contrast (3:1)

**ID:** `design-non-text-contrast`
**Agent rule (MUST):** Anything non-text that identifies a component or its state — input outlines, unchecked checkboxes, an off toggle, an icon-only glyph, focus indicators — and any part of a graphic needed to understand the content must hit **3:1** against adjacent colors (the text bar of 4.5:1 does not apply here). WCAG SC 1.4.11 Non-text Contrast, Level AA. A 1.2:1 hairline border on a white card is the common fail. Disabled components and unrestyled browser chrome are exempt; re-measure in dark mode, where alpha borders collapse.
**Source:** WCAG (https://www.w3.org/WAI/WCAG21/quickref/)

Give control boundaries, states, and meaningful graphics at least 3:1 contrast against adjacent colors

> The visual presentation of the following have a contrast ratio of at least 3:1 against adjacent color(s): User Interface Components — visual information required to identify user interface components and states, except for inactive components or where the appearance of the component is determined by the user agent and not modified by the author; Graphical Objects — parts of graphics required to understand the content, except when a particular presentation of graphics is essential to the information being conveyed.

Every other contrast rule here is about text: design-rams-color-contrast enforces the 4.5:1 WCAG text floor, design-minimum-contrast applies APCA Lc values to type, and content-impeccable-dark-mode-text-compensation is about text weight in dark themes. None of them sets any floor for the parts of a control that are not text — an input outline, an unchecked checkbox, a toggle in its off state, the glyph in an icon-only button, a focus indicator, or the line in a chart that carries the data. design-crisp-borders is an aesthetic rule about hairline edges and carries no ratio at all. SC 1.4.11 Non-text Contrast (Level AA) is that missing floor: 3:1 against adjacent colors, for anything required to identify a component or its state, and for any part of a graphic required to understand the content. The common failure is a 1.2:1 hairline border on a white card — the field is still readable, but nothing tells you it is a field. Note the exceptions: inactive (disabled) components are exempt, as is browser-default chrome you have not restyled. Measure boundaries against what is actually behind them, and re-measure in dark mode, where alpha-based borders collapse.

- [Understanding SC 1.4.11: Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)
- [Understanding SC 1.4.3: Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)

### Tokens Go in @theme, Not :root

**ID:** `design-theme-not-root`
**Agent rule (MUST):** Declare design tokens in `@theme`, not `:root` — a variable in `:root` is a working custom property but Tailwind never sees it, so it generates NO utilities and the codebase fills with `bg-[var(--brand)]` arbitrary values. `@theme { --color-brand: … }` generates `bg-brand`/`text-brand`/`border-brand`/`ring-brand` AND still emits the custom property for `var()`. The namespace prefix does the work: `--color-*` feeds color utilities, `--spacing-*` spacing, `--font-*` families, `--breakpoint-*` breakpoints. Nothing errors when you get it wrong.
**Source:** Tailwind (https://tailwindcss.com/docs)

Declare design tokens inside @theme so they generate utilities, instead of in :root where they only ever produce arbitrary values

> Theme variables are not just CSS variables — they instruct Tailwind to create new utility classes that you can use in your markup. Variables defined in `:root` do not generate any utilities.

This is the most common v4 onboarding mistake, and it is invisible: nothing errors, nothing warns. You write `:root { --brand: #06c; }` because that is how CSS custom properties have always worked, and it does define a working variable — but Tailwind never sees it, so no `bg-brand` exists. The codebase then fills with `bg-[var(--brand)] text-[var(--brand)] border-[var(--brand)]`, arbitrary values that carry no variant ergonomics and no autocomplete, and every reviewer reads them as noise. Move the same declaration into `@theme` under the right namespace — `@theme { --color-brand: oklch(0.62 0.19 259); }` — and Tailwind generates `bg-brand`, `text-brand`, `border-brand`, `ring-brand`, and the rest, while still emitting `--color-brand` as a real custom property that `var()` resolves anywhere. The namespace prefix is what does the work: `--color-*` feeds color utilities, `--spacing-*` spacing, `--font-*` families, `--breakpoint-*` breakpoints. A token in the wrong namespace, or in none at all, generates nothing.

```tsx
/* generates nothing */ :root { --brand: oklch(0.62 0.19 259); }
/* generates bg-brand, text-brand, … */ @theme { --color-brand: oklch(0.62 0.19 259); }
```

- [Tailwind v4: Theme variables](https://tailwindcss.com/docs/theme)
- [Tailwind CSS v4.0 announcement](https://tailwindcss.com/blog/tailwindcss-v4)

### Borders Default to currentColor

**ID:** `design-border-currentcolor`
**Agent rule (MUST):** Never write a border width without a border color in the same breath. In v4 `border-color` defaults to `currentColor`, NOT `gray-200` as in v3 — so a bare `border` inherits the text color, a near-black paragraph gets a near-black box, `text-destructive` turns the outline red, and it can never be a surface-relative hairline in dark mode. Pair the width with a semantic token: `border border-border`. A base-layer rule resetting `border-color` is a migration crutch, not the destination.
**Source:** Tailwind (https://tailwindcss.com/docs)

Always pair a border width with an explicit border color, because v4 no longer defaults borders to gray-200

> In v3, the `border` and `divide` utilities used your configured `gray-200` color by default. We've changed this to `currentColor` in v4 to make Tailwind less opinionated and match browser defaults.

This is the classic "we upgraded to v4 and every card grew an ugly black outline" bug. `<div class="border p-4">` used to give you a soft gray hairline; now `border-color` resolves to `currentColor`, so the border inherits the element's text color and a near-black paragraph produces a near-black box. It is not a crash, so it survives code review and ships. Two things make it worse than a one-time visual regression. First, the border now moves whenever the text color moves: put `text-destructive` on that card and the outline turns red with it. Second, it silently defeats dark mode, because a border that tracks the foreground can never be a surface-relative hairline. The fix is a habit, not a config change: never write a border width without a border color in the same breath — `border border-border` — and reach for a semantic token so the hairline flips with the theme. If you are migrating a large v3 codebase and cannot audit every call site at once, the documented stopgap is a base-layer rule setting `border-color` back to your gray token, but treat that as a migration crutch, not the destination.

```tsx
<div class="border p-4" />              <!-- v3: gray hairline. v4: currentColor -->
<div class="border border-border p-4" /> <!-- theme-aware in both -->
```

- [Tailwind v4: Upgrade guide](https://tailwindcss.com/docs/upgrade-guide)
- [Tailwind v4: border-color](https://tailwindcss.com/docs/border-color)
- [MDN: border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-color)

### Social Images Need Absolute URLs

**ID:** `design-og-image-absolute-url`
**Agent rule (MUST):** `og:image` and `twitter:image` must be ABSOLUTE URLs. A relative `/og.png` resolves fine in your browser (it has a current document) and ships a blank grey card on Slack, iMessage and LinkedIn, which fetch the HTML and have no origin to resolve against — and nothing in your build, typecheck, or local preview complains. Build the URL from one site-wide base constant. Ship a stable 1200x630 image and set `twitter:card` to `summary_large_image`, or the artwork renders at favicon size.
**Source:** @Ibelick (https://www.ui-skills.com/)

og:image and twitter:image must be absolute URLs, because a relative path renders a blank card everywhere the link is actually shared

> Open Graph and Twitter images must use absolute URLs; prefer correct image dimensions and stable aspect ratios; set twitter:card appropriately, summary_large_image by default

From the social cards rules in ibelick's fixing-metadata skill. This is the single most common social-preview bug, and its defining property is that it is invisible during development. `<meta property="og:image" content="/og.png">` resolves fine in your browser, because your browser has a current document to resolve it against. Slack, iMessage, LinkedIn, and every other unfurler do not: they fetch your HTML, read the tag, and get a path with no origin to attach it to. Some drop it, some guess, all of them are entitled to give up — so the link ships as a blank grey card, and nothing in your build, your typecheck, or your local preview ever complains. The rule is to emit the full origin, which in practice means building the URL from one site-wide base constant (`${SITE_URL}/og.png`) rather than trusting each page to remember. Two neighbours in the same rule group matter as much: the image wants a stable, correct aspect (1200 x 630 is the safe default that survives every crop), and `twitter:card` wants `summary_large_image`, without which the card renders as a thumbnail and the artwork you commissioned appears the size of a favicon.

```tsx
<meta property="og:image" content={`${SITE_URL}/og.png`} />
<meta name="twitter:card" content="summary_large_image" />
```

- [fixing-metadata (skill source)](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-metadata/SKILL.md)
- [The Open Graph protocol](https://ogp.me/)
- [X: Summary card with large image](https://developer.x.com/en/docs/x-for-websites/cards/overview/summary-card-with-large-image)

### canonical and og:url Must Agree

**ID:** `design-canonical-og-agreement`
**Agent rule (MUST):** `canonical` must point at the page's preferred URL and `og:url` must be that same string. When they disagree (`/blog/post` vs `/blog/post?utm_source=x`) the page identifies itself differently depending on who asks: every share links to the tracked variant, so the authority accrues to a URL the page itself disowns, and the crawler gets a duplicate to reconcile. Compute the canonical once and feed the same variable to both tags. Campaign params belong in the link you hand out, never in the tags a page declares about itself.
**Source:** @Ibelick (https://www.ui-skills.com/)

The URL a page declares as canonical and the URL it hands to social crawlers must be the same string, or one page becomes two

> canonical must point to the preferred URL for the page; og:url must match the canonical URL

From the canonical/indexing and social cards rules in ibelick's fixing-metadata skill. These are two tags in different sections of the head, usually written by different people at different times, and they quietly answer the same question: which URL IS this page? When they disagree — canonical says `/blog/post`, og:url says `/blog/post?ref=twitter&utm_source=x` — you have shipped a page that identifies itself differently depending on who is asking. Everyone who shares it links to the tracked variant, so the authority those shares earn accrues to a URL that the page itself disowns, and the crawler is handed a duplicate to reconcile that it did not need. The failure is not loud: both URLs work, both render, and the split only shows up later as a page that never quite ranks. The fix is mechanical — compute the canonical once and feed the same variable to both tags, so drift becomes impossible rather than merely unlikely. Campaign parameters belong in the link you hand out, never in the tags a page declares about itself.

- [fixing-metadata (skill source)](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-metadata/SKILL.md)
- [Google: Consolidate duplicate URLs](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)
- [The Open Graph protocol](https://ogp.me/)

### Consistent Title Format and a Written Description

**ID:** `design-meta-title-and-description`
**Agent rule (MUST):** Every page needs a `<title>` in one site-wide format (`${page} — ${SITE_NAME}`), with the distinctive word FIRST — results truncate around 60 characters, so a stuffed title loses the product name, the one word a human was scanning for. Shareable or searchable pages SHOULD also ship a hand-written `<meta name="description">` of ~150-160 plain-text characters; skip it and the engine writes one from whatever body copy came first, usually a cookie banner or a skip link. (Distinct from `content-page-titles`, which is the title tracking in-app context.)
**Source:** @Ibelick (https://www.ui-skills.com/)

Every page needs a title in one site-wide format, short enough to survive truncation, plus a description you wrote instead of one the crawler invents

> every page must have a title; use a consistent title format across the site; keep titles short and readable, avoid stuffing; shareable or searchable pages should have a meta description

From the title and description rules in ibelick's fixing-metadata skill. Distinct from content-page-titles, which is about the title tracking in-app context as the user navigates; this is the site-wide template and the description that ships with the document. Three things go wrong together. Titles get stuffed — `Home | Best Free AI Tools 2026 | Fast | Cheap | MyApp` — and the search result truncates at roughly 60 characters, so the keywords survive and the product name, the one word a human was scanning for, is the part that gets cut. Titles drift, because each page invents its own separator and word order, and a site whose results do not look like they came from the same site reads as untrustworthy. And the description is skipped, which does not mean no description: it means the engine writes one for you, scraped from whatever body copy came first, which is usually a cookie banner or a skip link. The rule reduces to one template (`${page} — ${SITE_NAME}`), the distinctive word first, and a plain-text description of about 150-160 characters written on purpose.

- [fixing-metadata (skill source)](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-metadata/SKILL.md)
- [Google: Influencing your title links](https://developers.google.com/search/docs/appearance/title-link)
- [Google: Control your snippets](https://developers.google.com/search/docs/appearance/snippet)

### robots Must Match Access Intent

**ID:** `design-robots-intent`
**Agent rule (MUST):** The `robots` meta must match actual access intent, so DERIVE it from the environment instead of hardcoding: default to `noindex` and let exactly one environment opt in (`process.env.VERCEL_ENV === "production"`). Preview and staging deploys are public URLs nobody thinks of as public, and an indexed staging copy competes with production for your own brand name. The symmetric failure is the overcorrection: a hardcoded `noindex` merges and production silently deindexes itself — deindexing is quiet, traffic just stops. Reserve `noindex` for private, duplicate, or non-public pages.
**Source:** @Ibelick (https://www.ui-skills.com/)

Derive the robots tag from the deploy environment: noindex by default on previews and staging, index only where the page is genuinely public

> previews or staging pages should be noindex by default when possible; robots meta must match actual access intent; use noindex only for private, duplicate, or non-public pages

From the canonical and indexing rules in ibelick's fixing-metadata skill. Preview deploys are public URLs that nobody thinks of as public. Leave them indexable and a crawler will eventually find one, at which point a half-finished staging copy of your site is competing with production for your own brand name — and because it is thinner, newer, and often a near-duplicate, the outcome is unpredictable in exactly the way you cannot afford. That is the expensive, common failure. The symmetric failure is what people ship when they overcorrect: someone hardcodes `<meta name="robots" content="noindex">` to fix staging, it merges, and production quietly deindexes itself. Nobody notices for weeks, because deindexing is silent — traffic just stops. Both failures come from treating robots as a static tag rather than a function of the environment. Derive it: default to noindex and let exactly one environment opt in (`process.env.VERCEL_ENV === 'production'`). Defaulting to noindex means every new preview surface is safe on the day it ships, and the single env that opts in is the one place you can actually check.

```tsx
const isProd = process.env.VERCEL_ENV === "production";
<meta name="robots" content={isProd ? "index,follow" : "noindex,nofollow"} />
```

- [fixing-metadata (skill source)](https://raw.githubusercontent.com/ibelick/ui-skills/main/skills/fixing-metadata/SKILL.md)
- [Google: Block search indexing with noindex](https://developers.google.com/search/docs/crawling-indexing/block-indexing)

### Underlines From the Font

**ID:** `design-underline-from-font`
**Agent rule (SHOULD):** Take underline geometry from the font: `text-underline-position: from-font`, `text-decoration-thickness: from-font`, `text-decoration-skip-ink: auto` — the browser's default position slices through the descenders of g, y, p and j. Colour is the only part of a real `text-decoration` that animates reliably, so transition `text-decoration-color` for a colour hover and build anything richer (a wipe, a grow, a slide) as a separate element animated on `transform: scaleX()`.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Take underline position and thickness from the font's own metrics, and build any animated underline as a separate element

> Default underlines sit wherever the browser decides. Pull position and thickness from the font's own metrics with `text-underline-position: from-font` and `text-decoration-thickness: from-font`, or tune manually with `text-decoration-thickness`, `text-underline-offset` and `text-decoration-skip-ink`. [...] Unless the only thing animating is a color change, build the underline as a separate element instead of using `text-decoration`: color is the only part of a real underline that animates reliably.

Two halves, and the second is the one people miss. The first is placement: a default underline is drawn at a position the browser picks, which at large sizes and in serif faces slices straight through the descenders of g, y, p and j. A well-made font ships its own underline position and thickness in its metrics, and `text-underline-position: from-font` plus `text-decoration-thickness: from-font` tells the browser to use them; `text-decoration-skip-ink: auto` then breaks the line around any descender that still crosses it. The second half is animation. `text-decoration-thickness`, `text-underline-offset` and `text-decoration-line` are not reliably animatable — a hover transition on them either does nothing or steps in visible jumps. Color is the exception, and the only exception. So the rule is conditional, not absolute: if the hover effect is a color change, use a real `text-decoration` and transition `text-decoration-color`; the moment the effect is a wipe, a grow, or a slide, the underline has to be a separate element (a `::after` box, or a `background-image` line) that you can animate on `transform: scaleX()` — which is compositor-friendly, unlike anything `text-decoration` could have given you. A dotted underline via `text-decoration-style` remains the conventional hint that a word carries extra information, which is why `abbr` gets `text-decoration: underline dotted` by default.

```tsx
a { text-underline-position: from-font; text-decoration-thickness: from-font; text-decoration-skip-ink: auto; transition: text-decoration-color 150ms; }
```

- [jakubkrehel/skills — better-typography: details & accessibility](https://github.com/jakubkrehel/skills/blob/main/skills/better-typography/details-and-accessibility.md)
- [MDN: text-underline-position](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-underline-position)

### Trim the Text Box

**ID:** `design-text-box-trim`
**Agent rule (SHOULD):** Use `text-box: trim-both cap alphabetic` to remove the font's reserved space and half-leading, so symmetric padding becomes optically symmetric instead of leaving text riding low in badges, chips and short buttons. This is progressive enhancement — ship pre-tuned padding as the base and gate the trim (plus the symmetric padding it enables) behind `@supports`; the layout must be correct without it.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Symmetric padding does not optically centre text, because the font reserves uneven space above and below the letters — trim it with text-box

> Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. [...] Browser support is still limited; treat it as progressive enhancement.

A line box is not the same height as the letters in it. The font declares an ascent and a descent that leave room for accents and descenders, and the line-height adds half-leading above and below on top of that. Neither is symmetric around the cap height, so when you give a badge `py-2` on both sides, the text does NOT land in the optical middle — it sits a pixel or two low, and every badge, chip and short button in the product carries the same small wrongness. The usual fix is to fudge it: `pt-1.5 pb-2`, tuned by eye, per component, per font, and silently invalidated the moment the typeface changes. `text-box: trim-both cap alphabetic` fixes the cause instead — it tells the browser to measure the box from the cap height to the baseline and throw away the reserved space outside it, so symmetric padding becomes optically symmetric. Support is still limited, so this is genuinely progressive enhancement: ship the pre-tuned padding as the base, and let an `@supports (text-box: trim-both cap alphabetic)` block reset the padding to symmetric and apply the trim. The layout must be correct without it.

```tsx
.badge { padding-top: 0.375rem; padding-bottom: 0.5rem; }
@supports (text-box: trim-both cap alphabetic) {
  .badge { text-box: trim-both cap alphabetic; padding-block: 0.5rem; }
}
```

- [jakubkrehel/skills — better-typography: spacing & sizing](https://github.com/jakubkrehel/skills/blob/main/skills/better-typography/spacing-and-sizing.md)
- [MDN: text-box](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/text-box)

### Image Hairline: Pure Alpha, Never Tinted

**ID:** `design-image-hairline-outline`
**Agent rule (NEVER):** Tint an image hairline. Separate an image from its surface with a 1px `outline` at low alpha in PURE black (`oklch(0 0 0 / 0.1)`) on light and PURE white (`oklch(1 0 0 / 0.1)`) on dark — never a near-black or near-white from the palette (`slate-900`, `#0a0a0a`, `#f5f5f7`). This is the ONE neutral you must not tint, and the scoped exception to `design-impeccable-tinted-neutrals`: that rule governs surfaces you control, while a hairline sits on arbitrary photographic content, where any hue picks up the surface behind it and reads as dirt on the image edge. Use `outline` with `outline-offset: -1px`, not `border` — an outline is painted outside the layout algorithm, so the image keeps its intended size and a grid stays aligned.
**Source:** jakubkrehel (https://github.com/jakubkrehel/skills)

Separate an image from its surface with an inset 1px outline of pure black or pure white at low alpha — the one neutral you must not tint

> Add a subtle `1px` outline with low opacity to images. [...] **Light mode**: pure black, `oklch(0 0 0 / 0.1)`. **Dark mode**: pure white, `oklch(1 0 0 / 0.1)`. Never use a near-black or near-white from the project palette (e.g. slate-900, zinc-900, `#0a0a0a`, `#111827`, `#f5f5f7`). Tinted outlines pick up the surrounding surface color and read as dirt on the image edge. [...] **Why outline instead of border?** `outline` doesn't affect layout (no added width/height), and `outline-offset: -1px` keeps it inset so images stay their intended size.

Read this against design-impeccable-tinted-neutrals, which says the opposite — never #000, never #fff, tint every neutral toward the brand hue. Both are right, and the conflict is kept rather than flattened, because they are scoped to different surfaces. A tinted neutral works when it sits on a surface you control: the hue is a quiet, deliberate relationship between two things you shipped. An image hairline sits on arbitrary photographic content, and on the boundary between that content and whatever surface the image happens to land on today. A hue that is invisible on your neutral-100 card goes muddy-green against a warm cream backdrop and grey-violet against a warm photograph — and because it is a 1px line at the exact edge of a photo, the brain does not read "a subtly tinted separator", it reads dirt on the image. Pure black and pure white at low alpha have no hue to shift, so they read as a shadow of the edge itself under any backdrop. This is the one neutral you must NOT tint. Second half of the rule, and cheap to get wrong: use `outline` with `outline-offset: -1px`, not `border`. A border adds 2px to the box, which knocks a grid of images out of alignment against anything unbordered next to it; an outline is painted outside the layout algorithm entirely, and the negative offset pulls it inside so the image keeps its intended size.

```tsx
img { outline: 1px solid oklch(0 0 0 / 0.1); outline-offset: -1px; }
@media (prefers-color-scheme: dark) { img { outline-color: oklch(1 0 0 / 0.1); } }
```

- [jakubkrehel/skills — better-ui: surfaces](https://github.com/jakubkrehel/skills/blob/main/skills/better-ui/surfaces.md)
- [MDN: outline-offset](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/outline-offset)

### Honour Reduced Transparency and Increased Contrast

**ID:** `design-reduced-transparency-contrast`
**Agent rule (MUST):** Honour the two OS preferences that govern translucency, not just `prefers-reduced-motion`: under `prefers-reduced-transparency: reduce` drop `backdrop-filter` to `none` and raise the background to a solid token; under `prefers-contrast: more` go near-solid and add a defined, contrasting border so the chrome still reads as a separate layer once the blur that did that job is gone. A `backdrop-filter` toolbar's effective text contrast is whatever happens to be scrolling under it — unmeasurable, and unreadable for a low-vision user.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Translucent chrome must go solid under prefers-reduced-transparency and gain a defined border under prefers-contrast: more

> **`prefers-reduced-transparency: reduce`** — make translucent surfaces frostier/solid: raise background opacity, drop the blur. **`prefers-contrast: more`** — near-solid backgrounds with a defined, contrasting border.

We honour `prefers-reduced-motion` everywhere and ignore the two OS preferences that govern translucency — the exact thing glass is made of. That gap is worth naming, because this codebase also ships design-impeccable-no-glassmorphism, which polices blur on taste and performance grounds and never once asks whether the user has asked for less of it. Taste is not consent. Both signals exist because translucent chrome is genuinely hostile to some people: a `backdrop-filter` toolbar's effective text contrast is whatever happens to be scrolling underneath it, which is unmeasurable and, for a low-vision user, unreadable — and for someone with a vestibular or cognitive sensitivity, a background that shifts continuously behind the text is noise. `prefers-reduced-transparency: reduce` is macOS "Reduce transparency", iOS the same, Windows "Transparency effects" off. `prefers-contrast: more` is macOS "Increase contrast" and the Windows contrast themes. The remedy is small and additive: keep the glass as the default, then in a `@media (prefers-reduced-transparency: reduce)` block drop `backdrop-filter` to `none` and raise the background to a solid token, and in a `@media (prefers-contrast: more)` block add a defined, contrasting border so the chrome still reads as a separate layer once the blur that used to do that job is gone. Neither query has a JS fallback you need — `window.matchMedia` reads both if you want to reflect the state in the UI.

```tsx
.chrome { background: oklch(1 0 0 / 0.6); backdrop-filter: blur(12px); }
@media (prefers-reduced-transparency: reduce) {
  .chrome { background: var(--surface); backdrop-filter: none; }
}
@media (prefers-contrast: more) {
  .chrome { background: var(--surface); border: 1px solid var(--border-strong); }
}
```

- [emilkowalski/skills — apple-design](https://github.com/emilkowalski/skills/tree/main/skills/apple-design)
- [MDN: prefers-reduced-transparency](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-transparency)
- [MDN: prefers-contrast](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast)

### Scroll Edge Effects, Not Hard Dividers

**ID:** `design-scroll-edge-effects`
**Agent rule (SHOULD):** Where floating chrome overlaps scrolling content, fade the seam with a short `mask-image` gradient instead of drawing a 1px divider under the sticky header — content should recede under the chrome, not be guillotined by a rule that claims it ends there. Apply the mask ONLY where floating UI actually overlaps content; a fade at an edge nothing floats over just eats readable text.
**Source:** Emil Kowalski (https://emilkowalski.com/)

Where floating chrome overlaps scrolling content, fade the content out with a mask instead of drawing a 1px rule under the header

> **Scroll edge effects, not hard dividers.** Instead of a 1px border under a sticky header, fade a small blur/gradient mask where content meets floating chrome — only where floating UI actually overlaps content.

A hard border under a sticky header is a claim that the header is a boundary — that content ends there. It does not; content continues underneath, and the border cuts it. What the eye wants at that seam is evidence of depth: the content should recede under the chrome rather than being sliced by it. A short `mask-image: linear-gradient(...)` on the scroll container (or an equivalent gradient overlay) fades the last few pixels of content to transparent exactly where the floating chrome sits over it, so a scrolling line of text dissolves under the header instead of being guillotined by a rule. Note the last clause of the rule, which is the part that stops this becoming decoration: only where floating UI actually overlaps content. A mask at an edge nothing floats over is a gratuitous fade that eats readable text. Also worth reading against design-impeccable-hairline-plus-shadow: that principle bans a hairline and a soft shadow together and tells you to commit to one of them — but both of its options are still a drawn edge, and neither proposes the mask. This is the third answer it never offers, and at the one seam where the other two are both wrong.

```tsx
.scroller { mask-image: linear-gradient(to bottom, transparent 0, #000 48px); }
```

- [emilkowalski/skills — apple-design](https://github.com/emilkowalski/skills/tree/main/skills/apple-design)
- [MDN: mask-image](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/mask-image)

---

## Aesthetics

Creative visual design principles for distinctive, production-grade interfaces. 19 rules.

### Type Is Not a Delivery Vehicle

**ID:** `aesthetics-distinctive-typography`
**Agent rule (SHOULD):** Use distinctive, characterful fonts instead of generic defaults (Inter, Roboto, Arial). Pair a display font with a refined body font for memorable visual identity.
**Source:** Skills (https://skills.sh/)

Choose typefaces with character instead of the current default families, and make the type treatment itself memorable

> Make the type treatment itself a memorable part of the design, not a neutral delivery vehicle for the content.

Generic fonts are everywhere — safe, and forgettable. The monoculture also moves: the tell is no longer just Arial/Inter/Roboto but the newer default wave — Geist, Plus Jakarta Sans, Space Grotesk, Instrument Sans/Serif, Mona Sans, Fraunces, Recoleta. Reaching for one of those because it is the current "tasteful" pick is the same reflex, one cycle later. Upstream frames the test as subject-derived: the typeface should come from the product's own world, not from whatever is trending in the training distribution.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [Google Fonts](https://fonts.google.com/)
- [Fontshare](https://www.fontshare.com/)

### Pair Display and Body Deliberately

**ID:** `aesthetics-font-pairing`
**Agent rule (SHOULD):** Pair a distinctive display font (serif or geometric sans) for headlines with a refined body font for content. Same font everywhere creates flat hierarchy. Limit to 2 font families; use font-display: swap.
**Source:** Skills (https://skills.sh/)

Pair a characterful display face with a complementary body face and set an intentional type scale

> Pair the display and body faces deliberately, not the same families you would reach for on any other project, and set a clear type scale with intentional weights, widths, and spacing.

Typography hierarchy is the foundation of visual communication. When headlines and body text share the same neutral face at three sizes, the page has no voice. A display face used with restraint commands attention; a complementary body face carries the reading. The scale between them — weights, widths, spacing — is the part most generated designs skip, and it is what makes a page feel set rather than assembled.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [Typewolf Font Pairing](https://www.typewolf.com/)

### Spend Your Boldness in One Place

**ID:** `aesthetics-color-dominance`
**Agent rule (SHOULD):** Use bold dominant colors with 1-2 sharp accent highlights. Avoid timid, evenly-distributed palettes. The 60-30-10 rule works, but pushing to 90% dominant with surgical accent placement is often better.
**Source:** Skills (https://skills.sh/)

Commit to one dominant color with a single sharp accent and keep everything around it quiet, instead of an evenly-distributed timid palette

> Spend your boldness in one place. Let the signature element be the one memorable thing, keep everything around it quiet and disciplined, and cut any decoration that does not serve the brief. Not taking a risk can be a risk itself!

A palette where every color competes is not bold, it is undecided — and a palette of washed-out neutrals is not restraint, it is a refusal to choose. Both fail the same way. Spend the boldness once: one dominant color that carries the surface, one sharp accent reserved for the thing you want the eye to land on, and disciplined quiet everywhere else.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [Refactoring UI](https://www.refactoringui.com/)

### One Orchestrated Moment, Not Scattered Effects

**ID:** `aesthetics-orchestrated-motion`
**Agent rule (SHOULD):** Orchestrate page load reveals with staggered animation-delay (100-150ms intervals). Reveal in reading order: hero first, then navigation, then content. Random micro-interactions feel chaotic.
**Source:** Skills (https://skills.sh/)

Concentrate motion into a single choreographed sequence rather than sprinkling unrelated micro-interactions across the page

> Leverage motion deliberately. Think about where and if animation can serve the subject: a page-load sequence, a scroll-triggered reveal, hover micro-interactions, ambient atmosphere. An orchestrated moment usually lands harder than scattered effects; choose what the direction calls for.

Motion is choreography. When ten elements each animate on their own schedule, the interface reads as broken rather than alive. Pick one moment — usually the page-load sequence — and stage it: elements entering in a deliberate order, on a consistent easing and a fixed stagger. Prefer CSS keyframes and `animation-delay` over a JS runtime for this: it is declarative, it runs on the compositor, and it costs no main-thread work on the most contended frame of the page's life. Reserve JS for motion that needs physics or gesture input. Restraint applies here too: see `aesthetics-scroll-interactions`.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [MDN: CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Animations)
- [Motion](https://motion.dev/)

### Extra Animation Is an AI Tell

**ID:** `aesthetics-scroll-interactions`
**Agent rule (SHOULD):** Use IntersectionObserver for scroll-triggered reveals. Stagger animations with animation-delay (100-150ms intervals). Keep animations subtle (translate 10-20px, fade 0 to 1). Use motion-safe: to respect reduced motion preferences. Transform passive browsing into active discovery.
**Source:** Skills (https://skills.sh/)

Reveal-on-scroll everything and the page reads as generated — animate only where motion carries meaning

> However, sometimes less is more, and extra animation contributes to the feeling that the design is AI-generated.

This principle used to say the opposite — that scroll-triggering should "surprise and delight." Upstream now names delight-maximalism as the tell: when every section fades up, every card lifts on hover, every number counts itself in, the motion stops meaning anything and starts reading as a generator's default. Reserve the reveal for content that genuinely benefits from being staged, and let the rest of the page simply be there when the reader arrives. A page that animates one thing is read as confident; a page that animates everything is read as machine-made.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [MDN: prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)

### Numbers Must Mean Sequence

**ID:** `aesthetics-decorative-numbering`
**Agent rule (NEVER):** Stamp numbered markers (01 / 02 / 03) on a set whose order carries no information. The test takes a second: reorder the items — if nothing breaks, if Security could just as well be 01 and Analytics 03, the numerals are decoration wearing the costume of structure, and they lie to a reader who reads "01" as a promise that something follows. A real process (Push → Build → Promote) or a typed timeline earns them, because there the order IS the information. Same bar for eyebrows, dividers and labels: encode something true, or drop them.
**Source:** Skills (https://skills.sh/)

Stamp 01 / 02 / 03 on a set only when the order actually carries information the reader needs

> Structural devices, numbering, eyebrows, dividers, labels, should encode something true about the content, not decorate it. Many generic designs use numbered markers (01 / 02 / 03), but that's only appropriate if the content actually is a sequence - like a real process or a typed timeline where order carries information the reader needs.

There is a one-second test: reorder the items. If nothing breaks — if Security could just as well be 01 and Analytics 03 — then the numerals are decoration wearing the costume of structure, and they are actively lying to the reader, who reads "01" as a promise that something comes next. A real process (Push → Build → Promote) or a typed timeline earns its numbers, because there the order IS the information. Same rule governs the eyebrow chip (`aesthetics-impeccable-hero-eyebrow`): structure or nothing. impeccable ships a mechanical threshold for the same tell (`numbered-section-markers`), and it is worth knowing where the line falls: it scans the page's text for zero-padded markers in the 01–12 range and fires only when 3 or more DISTINCT markers appear AND at least 2 of them are consecutive (01, 02, 03 → two sequential pairs). One stray "01" is not the pattern; a run of three is, because a run is what turns numerals into the page's section cadence. It classifies the result as the AI editorial scaffold one tier deeper than the tracked eyebrow chip — the same reflex, spent on a bigger typographic gesture.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [impeccable](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [MDN: The Ordered List element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/ol)

### Layout Must Be a Choice, Not the Default

**ID:** `aesthetics-spatial-composition`
**Agent rule (SHOULD):** Break predictable symmetric grids with asymmetry, overlap, negative margins, and varied scale. Feature one dominant element at unexpected scale. Use whitespace asymmetrically to create tension.
**Source:** Skills (https://skills.sh/)

Test the layout against the brief — if it is the grid you would produce for any similar page, revise it

> Then review that plan against the brief before building: if any part of it reads like the generic default you would produce for any similar page (work through a similar prompt to see if you arrive somewhere similar) rather than a choice made for this specific brief — revise that part, say what you changed and why.

The symmetric three-column grid is the layout every generator arrives at, for every brief, which is exactly the test upstream proposes: run a similar prompt and see whether you land in the same place. If you do, the layout was not chosen, it was defaulted into. Asymmetry, overlap, varied scale, and diagonal flow are the usual escapes — but they are means, not the point. The point is that the composition should be traceable to something true about this subject.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [Refactoring UI: Layout](https://www.refactoringui.com/)

### Commit to a Direction

**ID:** `aesthetics-bold-direction`
**Agent rule (SHOULD):** Commit to a design direction (brutalist, editorial, organic) and execute with precision. Avoid generic AI aesthetics: purple gradients, sparkles, excessive border-radius. Polarizing is better than forgettable.
**Source:** Skills (https://skills.sh/)

Pick one aesthetic direction and execute it fully instead of hedging toward the safe median

> This client has already rejected proposals that felt templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take one real aesthetic risk you can justify.

The failure this catches is not ugliness, it is hedging: a page that borrows a little brutalism, a little soft-pastel SaaS, and a little editorial serif, so that no choice can be blamed and none can be remembered. Choose a direction — brutalist, editorial, organic, technical — and let every element pay into it, including the ones it costs you. Specific anti-patterns (purple, gradients, glass, glow) are not this principle's inventory: they are owned with real detector thresholds by `design-ibelick-no-purple`, `design-ibelick-no-gradients`, `design-impeccable-no-glassmorphism` and `design-impeccable-dark-glow`.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [Awwwards](https://www.awwwards.com/)

### Defaults Are Not Choices

**ID:** `aesthetics-anti-generic`
**Agent rule (NEVER):** Use generic fonts (Inter, Roboto, Arial, system-ui), purple gradients, perfectly centered layouts, excessive border-radius, or sparkle emojis. These are hallmarks of AI-generated slop. Choose distinctive typography, intentional colors, and layouts with asymmetry.
**Source:** Skills (https://skills.sh/)

The reflexive AI looks are legitimate only when the brief asks for them — never spend a free axis on one

> All three are legitimate for some briefs, but they are defaults rather than choices, and they appear regardless of subject. Where the brief pins down a visual direction, follow it exactly — the brief's own words always win, including when it asks for one of these looks. Where it leaves an axis free, don't spend that freedom on one of these defaults.

The diagnostic is not "is this look bad" — cream, near-black-and-acid, and broadsheet are all fine designs for the right subject. The diagnostic is "did the subject produce this, or did the model?" If the same palette and layout would have arrived for a fintech dashboard, a wellness app, and a dev tool alike, it came from the training distribution. Our corpus pins the individual looks: `aesthetics-impeccable-cream-palette` (1), `aesthetics-dark-acid-default` (2).

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)

### Near-Black + Acid Accent Is a Default

**ID:** `aesthetics-dark-acid-default`
**Agent rule (SHOULD):** Treat near-black + one bright acid-green/vermilion accent as a reflex, not a choice — it is one of the looks AI-generated design clusters around, and its tell is interchangeability: the same surface and accent look equally plausible on a fintech dashboard, a wellness app and a dev tool, which means it was derived from none of them. Derive the dark surface instead: take the product's own hue, hold the hue angle and drop chroma, and pull the accent from the subject's material world rather than a neon swatch. (Distinct from `design-impeccable-dark-glow`, which is about glow SHADOWS, not the palette.)
**Source:** Skills (https://skills.sh/)

The dark canvas with one bright acid-green or vermilion accent arrives regardless of subject — derive the dark surface instead

> AI-generated design right now clusters around three looks: (1) a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta accent; (2) a near-black background with a single bright acid-green or vermilion accent; (3) a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns.

Look (2) is the "technical, serious, a bit dangerous" reflex, and its tell is interchangeability: paste the same near-black surface and the same acid-green accent onto a fintech dashboard, a wellness app, and a dev tool, and all three still look plausible — which is precisely the problem, because a palette that fits every subject was derived from none of them. Distinct from `design-impeccable-dark-glow`, which is about glow SHADOWS on dark surfaces, not the palette itself. The fix is derivation: take the product's own hue, hold the hue angle and drop chroma for the surface (see `design-impeccable-tinted-neutrals`), and pull the accent from the subject's material world rather than from a neon swatch.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)
- [OKLCH color picker](https://oklch.com/)

### Build to a Quality Floor

**ID:** `aesthetics-craftsmanship`
**Agent rule (SHOULD):** Demonstrate meticulous craftsmanship: consistent spacing scale (4/8/12/16/24px), pixel-perfect alignment, harmonious proportions. No arbitrary values, misaligned elements, or inconsistent padding. Every detail should feel intentional.
**Source:** Skills (https://skills.sh/)

Hold a non-negotiable baseline of responsiveness, focus, and reduced motion, and critique your own work as you build

> Build to a quality floor without announcing it: responsive down to mobile, visible keyboard focus, reduced motion respected. Critique your own work as you build, taking screenshots if your environment supports it – a picture is worth 1000 tokens.

The floor is invisible when present and unmistakable when missing: consistent spacing rhythm, honest alignment, a focus ring you can actually see, a layout that survives 375px, motion that stands down when asked. It is not a feature to advertise — it is the price of entry. The self-critique half matters as much: look at the rendered thing, not the code. Upstream adds Chanel's rule — before leaving the house, take one accessory off.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)

### One Signature Element

**ID:** `aesthetics-memorable-differentiation`
**Agent rule (SHOULD):** Include one memorable, unforgettable element per design (animated border, distinctive illustration, dramatic typography, unexpected shadow). Ask: "What will someone remember?" If you cannot answer, add a signature element. One bold detail beats a dozen safe flourishes.
**Source:** Skills (https://skills.sh/)

Give the page a single element it will be remembered by, and make it embody the brief

> Signature: the single unique element this page will be remembered by that embodies the brief in an appropriate way.

A signature is not an effect you sprinkle on at the end — it is the one thing the page is for, formally. It might be a piece of dramatic typography, an interactive instrument drawn from the subject's own world, a hand-drawn diagram, an unexpected structural move. What disqualifies a signature is genericity: if it could belong to any other product, it is decoration. And it must be alone — a page with three signatures has none, which is why this pairs with spending boldness once.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)

### Do Not Converge Across Generations

**ID:** `aesthetics-design-variety`
**Agent rule (SHOULD):** Never converge on common choices. Vary themes (light/dark), fonts (serif/sans/mono), and aesthetics across designs. Avoid using Space Grotesk, Inter, or blue accents on every project. Each design should have a distinct personality.
**Source:** Skills (https://skills.sh/)

Vary theme, type, and direction between projects instead of re-running the one look you happen to be good at

> Just like a human designer who's hired, there's often a careful balance between doing what you're good at and taking each project as a chance to experiment and learn.

A model with no memory reproduces its best-rehearsed look every time, which is how ten different briefs end up with the same dark canvas and the same grotesk. Upstream's counter-move is memory: "Human creators have memory and always try to do something new, so if you have a space to quickly jot down notes about what you've tried, it can help you in future passes." Keep that note file, read it before you start, and deliberately spend this project on the axis you did not spend last time.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)

### Match Complexity to the Vision

**ID:** `aesthetics-complexity-matching`
**Agent rule (SHOULD):** Match implementation complexity to aesthetic vision. Minimalist designs need restrained styling (single shadows, solid colors, clean borders). Maximalist designs can layer effects, gradients, and animations. Mismatch creates cognitive dissonance—a simple note card with layered shadows, blurs, and glowing buttons signals importance the content does not warrant.
**Source:** Skills (https://skills.sh/)

Maximalist directions need elaborate execution; minimal directions need precision — the failure is mismatch, not amount

> Match complexity to the vision. Maximalist directions need elaborate execution; minimal directions need precision in spacing, type, and detail. Elegance is executing the chosen vision well.

There is no universal "right amount" of visual complexity. The problem is mismatch: applying maximalist techniques to minimal content creates cognitive dissonance. A simple note card with layered shadows, a gradient background, blur, and a glowing button is claiming an importance the content does not have. Conversely, a maximalist direction executed with half-effort just looks broken. Elegance is not minimalism — it is executing whichever vision you chose, all the way.

- [Anthropic frontend-design skill](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)

### Kill the Icon-Tile Feature Card

**ID:** `aesthetics-impeccable-icon-tile-stack`
**Agent rule (NEVER):** Stack a rounded-square icon tile above a feature heading — the tell is geometric: a heading's previous sibling measuring 32–128px on both axes, roughly square, with a visible background or border and a border-radius under half its width. Move the icon inline into the heading line, drop the container, or give the feature a real image. (A circular avatar, radius = half the width, is exempt.)
**Source:** impeccable (https://impeccable.style/)

Stop stacking a rounded-square tinted icon tile above every feature heading — put the icon inline instead

> A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape.

The tell is geometric, so it can be detected mechanically: a previous sibling of a heading that measures 32–128px on BOTH axes, is roughly square, has a visible background or border, and has a border-radius under half its width. (A circular avatar is exempt — its radius is half the width.) That is the shape every generator reaches for, and it is why three-up feature grids from different products are indistinguishable. Break the geometry, not the icon: move the icon inline into the heading line, drop the container entirely, or let the feature carry an actual image. If the icon must sit in a box, the box has to earn it.

- [impeccable](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)
- [Refactoring UI](https://www.refactoringui.com/)

### Drop the Eyebrow Chip

**ID:** `aesthetics-impeccable-hero-eyebrow`
**Agent rule (NEVER):** Put a tracked-caps eyebrow or pill chip immediately above a hero headline — font-size <= 14px combined with either uppercase plus letter-spacing >= 1.6px, or font-weight >= 700 in an accent color; 3 or more such kickers on one page is the same failure at page scale. Fold its content ("Now in beta") into the subhead or a real nav-level badge, and separate sections with structure (a rule, spacing, a genuine `<h2>`).
**Source:** impeccable (https://impeccable.style/)

Remove the tracked-caps label above the hero headline and put its content where it belongs

> A tiny uppercase letter-spaced label sitting immediately above an oversized hero headline — or the same shape rendered as a pill chip — is now the default AI SaaS hero.

The detector fires on a sibling immediately before a heading with font-size <= 14px AND either (a) uppercase with letter-spacing >= 1.6px, or (b) font-weight >= 700 in an accent color. A companion rule, repeated-section-kickers, fires when 3 or more such kickers appear on one page — which is what happens the moment the pattern becomes the page's section separator. The eyebrow is usually smuggling real information ("Now in beta", "New") that deserves a real home: fold the status into the subhead as a sentence, or surface it as a genuine nav-level badge next to the product name. Sections should separate on structure — a rule, spacing, a real h2 — not on a decorative kicker.

- [impeccable](https://impeccable.style/)
- [Practical Typography](https://practicaltypography.com/)

### The Cream Background Is a Default, Not a Choice

**ID:** `aesthetics-impeccable-cream-palette`
**Agent rule (NEVER):** Reach for the reflexive warm cream/beige page surface — mechanically: `min(r,g,b) >= 209`, channels ordered `r >= g >= b`, and warmth `r - b` between 6 and 48, which catches `bg-amber-50/100`, `bg-orange-50/100`, `bg-yellow-50`, and `bg-stone-50/100/200`. If you can guess the palette from the product's domain alone, it is the training-data reflex. Derive the surface instead: hold the brand hue angle and drop chroma to roughly 0.01.
**Source:** impeccable (https://impeccable.style/)

Derive the page surface from the brand hue rather than reaching for the reflexive warm beige

> A warm cream or beige page background has become the default "tasteful" AI surface, reached for by reflex.

Cream is mechanically identifiable: min(r,g,b) >= 209, channels ordered r >= g >= b, and warmth (r - b) between 6 and 48. That window also catches Tailwind's bg-amber-50/100, bg-orange-50/100, bg-yellow-50 and bg-stone-50/100/200 — the exact classes a generator picks when it wants to look considered. Pair the check with the skill's category-reflex test: if you can guess the palette from the product's domain alone (fintech blue, wellness sage, AI-tool cream), it is the training-data reflex talking, not a decision. The fix is derivation, not avoidance — take the brand hue, hold the hue angle, and drop chroma to roughly 0.01 for a tinted neutral that belongs to this product and no other.

- [impeccable](https://impeccable.style/)
- [Tailwind color palette](https://tailwindcss.com/docs/colors)
- [OKLCH color picker](https://oklch.com/)

### Long Headlines Don't Get Display Size

**ID:** `aesthetics-impeccable-oversized-hero`
**Agent rule (SHOULD):** Reserve display size for short headlines — an `h1` is oversized only when ALL THREE hold: font-size >= 72px AND at least 40 characters AND >= 28% of viewport height (or >= 25% of viewport area). Keep the display size, cut the headline to its shortest true form, and let the full sentence live at 18–20px directly underneath.
**Source:** impeccable (https://impeccable.style/)

Keep display type for short headlines and demote full sentences to the subhead so the fold stays usable

> A full-sentence headline set at display size ends up dominating the viewport, leaving no room for anything else above the fold.

This is not an argument against big type. The detector requires ALL THREE conditions together: font-size >= 72px, at least 40 characters, and an h1 occupying >= 28% of viewport height (or >= 25% of viewport area). A punchy one- or two-word headline at 72px+ is completely fine — it is length PLUS viewport share that makes it a tell, because a 40+ character sentence at display size wraps to four or five lines and pushes the CTA, the product shot, and everything else below the fold. Keep the display size and cut the headline to its shortest true form, then let the full sentence live at 18–20px directly underneath, where sentences read.

- [impeccable](https://impeccable.style/)
- [Type Scale](https://type-scale.com/)

### Not Every Page Needs a Hero Metric

**ID:** `aesthetics-impeccable-hero-metric-template`
**Agent rule (NEVER):** Ship a decorative hero metric — a round, unsourced "10x faster" / "99.99%" / "500M+" with no denominator, no window, and no source, dressed in a gradient accent. A prominent number is allowed on exactly one condition: it shows actual user data (this account, this window, live, timestamped). Otherwise replace the stat row with one concrete product screenshot.
**Source:** impeccable (https://impeccable.style/)

Show a prominent number only when it comes from real data, not as decorative gradient furniture

> The hero-metric template. Big number, small label, supporting stats, gradient accent. SaaS cliché.

The skill permits a prominent metric under exactly one condition: it shows actual user data. The failure mode is the decorative, unsourced number — "10x faster", "99.99%", "500M+" — a round figure with no denominator, no window, and no source, used as visual furniture to make a hero feel substantiated. It belongs to the same family as identical repeated card grids: three cells that look like evidence and carry none. So either the number is real (this account, this week, live, timestamped, with the series behind it), or it should not be there at all — replace the stat row with one concrete product screenshot, which at least shows the thing you are selling.

- [impeccable](https://impeccable.style/)
- [pbakaus/impeccable](https://github.com/pbakaus/impeccable)