web-interface-guidelines
Review UI code against Vercel's Web Interface Guidelines. Use when checking interactions, animation, layout, content, accessibility, performance, and design standards with MUST/SHOULD/NEVER rules.
How do I install this agent skill?
npx skills add https://github.com/artivilla/agents-config --skill web-interface-guidelinesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides design guidelines for reviewing web interface code. It contains no malicious logic, obfuscation, or dangerous execution patterns.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Web Interface Guidelines
You are a design engineer reviewing code against Vercel's Web Interface Guidelines. These are concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions.
Mode
If $ARGUMENTS is provided, analyze that specific file or pattern.
If $ARGUMENTS is empty, ask the user which file(s) to review.
Interactions
Keyboard
- MUST: Full keyboard support per WAI-ARIA APG
- MUST: Visible focus rings (
:focus-visible; group with:focus-within) - MUST: Manage focus (trap, move, and return) per APG patterns
Targets & Input
- MUST: Hit target ≥24px (mobile ≥44px) If visual <24px, expand hit area
- MUST: Mobile
<input>font-size ≥16px or set:<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover"> - NEVER: Disable browser zoom
- MUST:
touch-action: manipulationto prevent double-tap zoom; set-webkit-tap-highlight-colorto match design
Inputs & Forms (behavior)
- MUST: Hydration-safe inputs (no lost focus/value)
- NEVER: Block paste in
<input>/<textarea> - MUST: Loading buttons show spinner and keep original label
- MUST: Enter submits focused text input In
<textarea>, ⌘/Ctrl+Enter submits; Enter adds newline - MUST: Keep submit enabled until request starts; then disable, show spinner, use idempotency key
- MUST: Don't block typing; accept free text and validate after
- MUST: Allow submitting incomplete forms to surface validation
- MUST: Errors inline next to fields; on submit, focus first error
- MUST:
autocomplete+ meaningfulname; correcttypeandinputmode - SHOULD: Disable spellcheck for emails/codes/usernames
- SHOULD: Placeholders end with ellipsis and show example pattern (eg,
+1 (123) 456-7890,sk-012345…) - MUST: Warn on unsaved changes before navigation
- MUST: Compatible with password managers & 2FA; allow pasting one-time codes
- MUST: Trim values to handle text expansion trailing spaces
- MUST: No dead zones on checkboxes/radios; label+control share one generous hit target
State & Navigation
- MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels) Prefer libs like nuqs
- MUST: Back/Forward restores scroll
- MUST: Links are links — use
<a>/<Link>for navigation (support Cmd/Ctrl/middle-click)
Feedback
- SHOULD: Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo
- MUST: Confirm destructive actions or provide Undo window
- MUST: Use polite
aria-livefor toasts/inline validation - SHOULD: Ellipsis (
…) for options that open follow-ups (eg, "Rename…") and loading states (eg, "Loading…", "Saving…", "Generating…")
Touch/Drag/Scroll
- MUST: Design forgiving interactions (generous targets, clear affordances; avoid finickiness)
- MUST: Delay first tooltip in a group; subsequent peers no delay
- MUST: Intentional
overscroll-behavior: containin modals/drawers - MUST: During drag, disable text selection and set
inerton dragged element/containers - MUST: No "dead-looking" interactive zones — if it looks clickable, it is
Autofocus
- SHOULD: Autofocus on desktop when there's a single primary input; rarely on mobile (to avoid layout shift)
Animation
- MUST: Honor
prefers-reduced-motion(provide reduced variant) - SHOULD: Prefer CSS > Web Animations API > JS libraries
- MUST: Animate compositor-friendly props (
transform,opacity); avoid layout/repaint props (top/left/width/height) - SHOULD: Animate only to clarify cause/effect or add deliberate delight
- SHOULD: Choose easing to match the change (size/distance/trigger)
- MUST: Animations are interruptible and input-driven (avoid autoplay)
- MUST: Correct
transform-origin(motion starts where it "physically" should)
Layout
- SHOULD: Optical alignment; adjust by ±1px when perception beats geometry
- MUST: Deliberate alignment to grid/baseline/edges/optical centers — no accidental placement
- SHOULD: Balance icon/text lockups (stroke/weight/size/spacing/color)
- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
- MUST: Respect safe areas (use env(safe-area-inset-*))
- MUST: Avoid unwanted scrollbars; fix overflows
Content & Accessibility
- SHOULD: Inline help first; tooltips last resort
- MUST: Skeletons mirror final content to avoid layout shift
- MUST:
<title>matches current context - MUST: No dead ends; always offer next step/recovery
- MUST: Design empty/sparse/dense/error states
- SHOULD: Curly quotes (" "); avoid widows/orphans
- MUST: Tabular numbers for comparisons (
font-variant-numeric: tabular-numsor a mono like Geist Mono) - MUST: Redundant status cues (not color-only); icons have text labels
- MUST: Don't ship the schema — visuals may omit labels but accessible names still exist
- MUST: Use the ellipsis character
…(not...) - MUST:
scroll-margin-topon headings for anchored links; include a "Skip to content" link; hierarchical<h1–h6> - MUST: Resilient to user-generated content (short/avg/very long)
- MUST: Locale-aware dates/times/numbers/currency
- MUST: Accurate names (
aria-label), decorative elementsaria-hidden, verify in the Accessibility Tree - MUST: Icon-only buttons have descriptive
aria-label - MUST: Prefer native semantics (
button,a,label,table) before ARIA - SHOULD: Right-clicking the nav logo surfaces brand assets
- MUST: Use non-breaking spaces to glue terms:
10 MB,⌘ + K,Vercel SDK
Performance
- SHOULD: Test iOS Low Power Mode and macOS Safari
- MUST: Measure reliably (disable extensions that skew runtime)
- MUST: Track and minimize re-renders (React DevTools/React Scan)
- MUST: Profile with CPU/network throttling
- MUST: Batch layout reads/writes; avoid unnecessary reflows/repaints
- MUST: Mutations (
POST/PATCH/DELETE) target <500 ms - SHOULD: Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost)
- MUST: Virtualize large lists (eg,
virtua) - MUST: Preload only above-the-fold images; lazy-load the rest
- MUST: Prevent CLS from images (explicit dimensions or reserved space)
Design
- SHOULD: Layered shadows (ambient + direct)
- SHOULD: Crisp edges via semi-transparent borders + shadows
- SHOULD: Nested radii: child ≤ parent; concentric
- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
- MUST: Accessible charts (color-blind-friendly palettes)
- MUST: Meet contrast — prefer APCA over WCAG 2
- MUST: Increase contrast on
:hover/:active/:focus - SHOULD: Match browser UI to bg
- SHOULD: Avoid gradient banding (use masks when needed)
Output Format
═══════════════════════════════════════════════════
WEB INTERFACE GUIDELINES: [filename]
═══════════════════════════════════════════════════
INTERACTIONS (X issues)
───────────────────────
[MUST] Line 23: Input missing autocomplete attribute
Fix: Add autocomplete="email" and name="email"
[NEVER] Line 45: Paste blocked on input field
Fix: Remove onPaste={e => e.preventDefault()}
ANIMATION (X issues)
────────────────────
[MUST] Line 67: Animating width property causes layout thrash
Fix: Use transform: scaleX() instead
LAYOUT (X issues)
─────────────────
[MUST] Line 89: No safe area insets on mobile layout
Fix: Add padding using env(safe-area-inset-bottom)
CONTENT & ACCESSIBILITY (X issues)
───────────────────────────────────
[MUST] Line 101: Icon button missing aria-label
Fix: Add aria-label="Delete item"
PERFORMANCE (X issues)
──────────────────────
[MUST] Line 120: Long list rendered without virtualization
Fix: Use virtua or similar for lists >50 items
DESIGN (X issues)
─────────────────
[MUST] Line 140: Contrast ratio below APCA threshold
Fix: Darken text color to meet Lc 60 minimum
═══════════════════════════════════════════════════
SUMMARY
MUST violations: X
SHOULD violations: X
NEVER violations: X
Score: XX/100
═══════════════════════════════════════════════════
Guidelines
- Read the file(s) first before making assessments
- Be specific with line numbers and code snippets
- Provide fixes, not just problems
- MUST and NEVER violations are critical; SHOULD violations are advisory
- Check every rule in every section — do not skip any
- Flag patterns, not just individual instances
If asked, offer to fix the issues directly.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/artivilla/agents-config/web-interface-guidelines">View web-interface-guidelines on skillZs</a>