# Web Design Guidelines > Audit interface code against a concise MUST/SHOULD/NEVER rule set covering interaction, animation, layout, accessibility, performance, and theming. Use this skill as a pre-merge gate on user-facing UI. - Skill: `10xequity/web-design-guidelines` (Agent Skill) - Install (CLI): `npx skillmds@latest add 10xequity/web-design-guidelines` - Raw SKILL.md: https://api.skillmd.com/api/skills/10xequity/web-design-guidelines/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: 10xequity (https://skillmd.com/u/10xequity) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/10xequity/web-design-guidelines --- # Web Design Guidelines Skill ## Purpose Audit interface code against a concise MUST/SHOULD/NEVER rule set covering interaction, animation, layout, accessibility, performance, and theming. ## When to use Use this skill as a pre-merge gate on user-facing UI. Use `impeccable-ui.md` for design direction and craft; use this for conformance. ## Inputs - the pages or components under review - target breakpoints and browsers - framework and whether the app hydrates - any product-specific interaction requirements ## Output Return: - findings grouped as interactions, animation, layout, content and accessibility, performance, theming, hydration - each finding labelled MUST / SHOULD / NEVER, with the element and the corrected code - an explicit statement of what was not checked ## Constraints - **Keyboard** — full support per WAI-ARIA APG; visible `:focus-visible` rings; managed focus (trap, move, return); never `outline: none` without a replacement - **Targets** — hit target ≥24px, ≥44px on mobile; mobile `` font-size ≥16px to prevent iOS zoom; never disable browser zoom; `touch-action: manipulation` - **Forms** — never block paste; keep submit enabled until the request starts, then spinner with the original label; accept free text and validate after; allow incomplete submission to surface validation; errors inline with focus moved to the first one; `autocomplete` plus correct `type` and `inputmode`; warn on unsaved changes; label and control share one hit target - **State** — URL reflects filters, tabs, pagination, expanded panels; Back/Forward restores scroll; navigation uses ``/``, never `
` - **Feedback** — confirm destructive actions or offer Undo; polite `aria-live` for toasts; optimistic UI reconciled on response - **Animation** — honor `prefers-reduced-motion`; animate only `transform` and `opacity`; never animate layout props; never `transition: all`; animations interruptible, no autoplay; correct `transform-origin` - **Layout** — deliberate alignment, optical ±1px where perception beats geometry; verify mobile, laptop, and ultra-wide; respect `env(safe-area-inset-*)`; no unwanted scrollbars - **Content and a11y** — no dead ends; design empty, sparse, dense, and error states; skeletons mirror final content; `tabular-nums` for compared numbers; status cues never colour-only; icon-only buttons carry `aria-label`; native semantics before ARIA; resilient to short and very long user content; locale-aware dates and numbers via `Intl` - **Content handling** — text containers truncate or clamp; flex children need `min-w-0`; empty strings and arrays must not break layout - **Performance** — virtualize lists over 50 items; preload above-fold images and lazy-load the rest; explicit image dimensions to prevent CLS; mutations target under 500ms; batch layout reads and writes; profile with throttling - **Theming** — `color-scheme: dark` on ``; `` matches background; native `