Index of every page on this site: llms.txt
All skills
vercel-labs avatar

/web-design-guidelines

@5a37a63 official
by Vercel Labsvercel-labs/agent-skills35k stars
3,011
Run it yourself

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

Use this Skill: https://skilld.dev/gh/vercel-labs/agent-skills/web-design-guidelines

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencescommand.md

≈2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Web Interface Guidelines

Review these files for compliance: $ARGUMENTS

Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.

Rules

Accessibility

  • Icon-only buttons need aria-label
  • Form controls need <label> or aria-label
  • Interactive elements need keyboard handlers (onKeyDown/onKeyUp)
  • <button> for actions, <a>/<Link> for navigation (not <div onClick>)
  • Images need alt (or alt="" if decorative)
  • Decorative icons need aria-hidden="true"
  • Async updates (toasts, validation) need aria-live="polite"
  • Use semantic HTML (<button>, <a>, <label>, <table>) before ARIA
  • Headings hierarchical <h1>–<h6>; include skip link for main content
  • scroll-margin-top on heading anchors
  • Meaningful media needs captions, transcripts, or descriptions as applicable
  • Media controls need keyboard support; decorative media needs assistive-tech hiding

Focus States

  • Interactive elements need visible focus: focus-visible:ring-* or equivalent
  • Never outline-none / outline: none without focus replacement
  • Use :focus-visible over :focus (avoid focus ring on click)
  • Group focus with :focus-within for compound controls
  • Sticky headers/footers/overlays must not cover the focused element

Forms

  • Inputs need autocomplete and meaningful name
  • Use correct type (email, tel, url, number) and inputmode
  • Never block paste (onPaste + preventDefault)
  • Labels clickable (htmlFor or wrapping control)
  • Disable spellcheck on emails, codes, usernames (spellCheck={false})
  • Checkboxes/radios: label + control share single hit target (no dead zones)
  • Submit button stays enabled until request starts; spinner during request
  • Errors inline next to fields; focus first error on submit
  • Placeholders end with … and show example pattern
  • autocomplete="off" on non-auth fields to avoid password manager triggers
  • Warn before navigation with unsaved changes (beforeunload or router guard)

Animation

  • Honor prefers-reduced-motion (provide reduced variant or disable)
  • Animate transform/opacity only (compositor-friendly)
  • Never transition: all—list properties explicitly
  • Set correct transform-origin
  • SVG: transforms on <g> wrapper with transform-box: fill-box; transform-origin: center
  • Animations interruptible—respond to user input mid-animation
  • Autoplay motion >5 seconds alongside other content needs pause, stop, or hide controls
  • Muted decorative loops must stop under prefers-reduced-motion

Typography

  • … not ...
  • Curly quotes “ ” not straight "
  • Non-breaking spaces: 10&nbsp;MB, ⌘&nbsp;K, brand names
  • Loading states end with …: "Loading…", "Saving…"
  • font-variant-numeric: tabular-nums for number columns/comparisons
  • Use text-wrap: balance or text-pretty on headings (prevents widows)

Content Handling

  • Text containers handle long content: truncate, line-clamp-*, or break-words
  • Flex children need min-w-0 to allow text truncation
  • Handle empty states—don't render broken UI for empty strings/arrays
  • User-generated content: anticipate short, average, and very long inputs

Images

  • <img> needs explicit width and height (prevents CLS)
  • Below-fold images: loading="lazy"
  • Above-fold critical images: priority or fetchpriority="high"

Performance

  • Large lists (>50 items): virtualize (virtua, content-visibility: auto)
  • No layout reads in render (getBoundingClientRect, offsetHeight, offsetWidth, scrollTop)
  • Batch DOM reads/writes; avoid interleaving
  • Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
  • Add <link rel="preconnect"> for CDN/asset domains
  • Critical fonts: <link rel="preload" as="font"> with font-display: swap
  • Prefer <video autoplay muted loop playsinline> over animated GIF; provide a still alternative
  • Short non-essential loops: Safari H.264 MP4 <picture> source, prefers-reduced-motion media condition, and still fallback

Navigation & State

  • URL reflects state—filters, tabs, pagination, expanded panels in query params
  • Links use <a>/<Link> (Cmd/Ctrl+click, middle-click support)
  • Deep-link all stateful UI (if uses useState, consider URL sync via nuqs or similar)
  • Destructive actions need confirmation modal or undo window—never immediate

Touch & Interaction

  • touch-action: manipulation (prevents double-tap zoom delay)
  • -webkit-tap-highlight-color set intentionally
  • overscroll-behavior: contain in modals/drawers/sheets
  • Page rubber-band suppression: overscroll-behavior: none on <html> inside @media (pointer: fine); keep coarse-pointer page defaults for pull-to-refresh. Test hybrid touch devices: pointer describes the primary input, and none also disables scroll chaining and native swipe navigation
  • During drag: disable text selection, inert on dragged elements
  • Drag/swipe/pinch/path gestures need tap/click and keyboard alternatives unless essential
  • autoFocus sparingly—desktop only, single primary input; avoid on mobile

Safe Areas & Layout

  • Full-bleed layouts need env(safe-area-inset-*) for notches
  • Avoid unwanted scrollbars: overflow-x-hidden on containers, fix content overflow
  • Flex/grid over JS measurement for layout

Dark Mode & Theming

  • color-scheme: dark on <html> for dark themes (fixes scrollbar, inputs)
  • <meta name="theme-color"> matches page background
  • Native <select>: explicit background-color and color (Windows dark mode)

Locale & i18n

  • Dates/times: use Intl.DateTimeFormat not hardcoded formats
  • Numbers/currency: use Intl.NumberFormat not hardcoded formats
  • Detect language via Accept-Language / navigator.languages, not IP
  • Brand names, code tokens, identifiers: wrap with translate="no" to prevent garbled auto-translation

Hydration Safety

  • Inputs with value need onChange (or use defaultValue for uncontrolled)
  • Date/time rendering: guard against hydration mismatch (server vs client)
  • suppressHydrationWarning only where truly needed

Hover & Interactive States

  • Buttons/links need hover: state (visual feedback)
  • Interactive states increase contrast: hover/active/focus more prominent than rest

Content & Copy

  • Active voice: "Install the CLI" not "The CLI will be installed"
  • Title Case for headings/buttons (Chicago style)
  • Numerals for counts: "8 deployments" not "eight"
  • Specific button labels: "Save API Key" not "Continue"
  • Error messages include fix/next step, not just problem
  • Second person; avoid first person
  • & over "and" where space-constrained

Anti-patterns (flag these)

  • user-scalable=no or maximum-scale=1 disabling zoom
  • onPaste with preventDefault
  • transition: all
  • outline-none without focus-visible replacement
  • Inline onClick navigation without <a>
  • <div> or <span> with click handlers (should be <button>)
  • Images without dimensions
  • Large arrays .map() without virtualization
  • Form inputs without labels
  • Icon buttons without aria-label
  • Hardcoded date/number formats (use Intl.*)
  • autoFocus without clear justification
  • Animated GIF when compressed video is suitable
  • Gesture-only action without tap/click and keyboard alternative

Output Format

Group by file. Use file:line format (VS Code clickable). Terse findings.

## src/Button.tsx

src/Button.tsx:42 - icon button missing aria-label
src/Button.tsx:18 - input lacks label
src/Button.tsx:55 - animation missing prefers-reduced-motion
src/Button.tsx:67 - transition: all → list properties

## src/Modal.tsx

src/Modal.tsx:12 - missing overscroll-behavior: contain
src/Modal.tsx:34 - "..." → "…"

## src/Card.tsx

✓ pass

State issue + location. Skip explanation unless fix non-obvious. No preamble.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alertstoday5 checks · Risk SAFE
  • Gen Agent Trust Hubtoday

    This skill provides a utility for auditing UI code against accessibility and best-practice guidelines. It includes security considerations related to processing user-provided files, which is an expected part of its functionality. The skill follows safe patterns by using bundled references and providing clear maintenance instructions.

  • Sockettoday

    No alerts

  • Snyktoday

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 5a37a63. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 10 hours ago.

Activeupdated 3 weeks ago
Other metadata
metadata
{
  "author": "vercel",
  "version": "1.1.0",
  "argument-hint": "<file-or-pattern>"
}
  • web-design
  • accessibility
  • ui-review
  • guidelines
  • compliance
  • ux-audit
  • code-review

README badge

README badge for vercel-labs/agent-skills/web-design-guidelines

Audits UI code against Vercel's Web Interface Guidelines by fetching the latest ruleset and reporting compliance issues in a terse format. Use this to review HTML, CSS, or component files for accessibility, design system adherence, and UX best practices.

Generated from the current SKILL.md.

What design guidelines does this skill check against?
It fetches the latest Web Interface Guidelines from the Vercel Labs repository and checks code compliance against all rules in that document.
Can I use this to audit my entire site or just specific files?
You can specify individual files or patterns to review. If you don't provide a file argument, the skill will prompt you to specify which files to audit.
What output format does this skill use?
It reports findings in terse `file:line` format as specified in the fetched guidelines document.
Does this skill check accessibility?
Yes. Accessibility checks are included as part of the Web Interface Guidelines compliance review.

Generated from the current SKILL.md. These answers refresh after source changes.