web-interface-guidelines
Skill24 starsChanged 32 days agoMITView on GitHub
Concise rules for building accessible, fast, delightful web UIs. Use when reviewing or implementing interfaces, forms, focus, animation, layout, performance, or dark mode — guided by MUST / SHOULD / NEVER decisions.
5 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- Kaidera-AI/skillstheir own version, first seen Oct 13, 2026
- beelabstudio/aitheir own version, first seen Sep 20, 2026
- garnertb/skillsedited, first seen Aug 20, 2026
- EastSun5566/skillstheir own version, first seen Jul 11, 2026
- utxo-AG/claude-skillstheir own version, first seen Feb 10, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 1
- garnertb/skills★ 128% same
Wrote their own version · 4
- Kaidera-AI/skills★ 2same name
- utxo-AG/claude-skills★ 2same name
- beelabstudio/ai★ 0same name
- EastSun5566/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository33 other files it gives its agents.
- skills/vercel-react-best-practices/AGENTS.mdAGENTS.md
- accessibility-complianceSkill
- agents-md-persianSkill
- backend-securitySkill
- component-registry-cliSkill
- design-system-patternsSkill
- find-skillsSkill
- frontend-designSkill
- frontend-securitySkill
- grill-meSkill
- improve-codebase-architectureSkill
- interaction-designSkill
- iran-validationSkill
- jalali-calendarSkill
- mcp-builderSkill
- neshan-mapsSkill
- nextjs-multi-design-systemSkill
- open-graph-social-previewSkill
- parspack-s3-uploadSkill
- persian-conversationalSkill
- persian-formalSkill
- persian-rtl-uiSkill
- persian-seoSkill
- persian-typographySkill
- persian-ui-copySkill
- responsive-designSkill
- rtl-data-visualizationSkill
- seoSkill
- ui-craft-rulesSkill
- ui-library-mcpSkill
- vercel-react-best-practicesSkill
- web-quality-auditSkill
- zarinpal-paymentSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
55 rules. 0 are common, 33 are distinctive, and 22 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
33
Distinctive
This author's own choices. Worth a look.
22
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
NEVER to guide decisions.
- Distinctive: line 18
MUST: Full keyboard support per WAI-ARIA APG
- Very specific: line 19
MUST: Visible, unobscured focus rings (:focus-visible.
- Distinctive: line 20
MUST: Manage focus (trap, move, return) per APG patterns
- Very specific: line 21
NEVER: outline: none without visible focus replacement
- Distinctive: line 25
MUST: Hit target ≥24px (mobile ≥44px).
- Distinctive: line 26
MUST: Mobile input font-size ≥16px to prevent iOS zoom
- Very specific: line 27
NEVER: Disable browser zoom (user-scalable=no, maximum-scale=1)
- Very specific: line 28
MUST: touch-action: manipulation to prevent double-tap zoom
- Distinctive: line 32
MUST: Hydration-safe inputs (no lost focus/value)
- Distinctive: line 33
NEVER: Block paste in inputs/textareas
- Distinctive: line 34
MUST: Loading buttons show spinner and keep original label
- Distinctive: line 35
MUST: Keep submit enabled until request starts.
- Distinctive: line 36
MUST: Accept free text, validate after — don't block typing
- Distinctive: line 37
MUST: Errors inline next to fields.
- Very specific: line 38
MUST: autocomplete + meaningful name.
- Distinctive: line 39
MUST: Warn on unsaved changes before navigation
- Very specific: line 43
MUST: URL reflects state (filters/tabs/pagination/expanded panels)
- Distinctive: line 44
MUST: Back/Forward restores scroll position
- Very specific: line 45
MUST: Links use real anchors / Next Link for navigation
- Distinctive: line 46
NEVER: Use buttons for navigation that should be links
- Distinctive: line 50
SHOULD: Optimistic UI; reconcile on response.
- Distinctive: line 51
MUST: Confirm destructive actions or provide Undo
- Very specific: line 52
MUST: Use polite aria-live for toasts/inline validation
- Distinctive: line 57
SHOULD: Prefer CSS over JS animation libraries when possible
- Very specific: line 58
MUST: Animate compositor-friendly props (transform, opacity) only
- Very specific: line 59
NEVER: Animate layout props (top, left, width, height)
- Very specific: line 60
NEVER: transition: all — list properties explicitly
- Distinctive: line 61
MUST: Animations interruptible and input-driven
- Very specific: line 65
MUST: Deliberate alignment to grid/baseline/edges
- Distinctive: line 66
MUST: Verify mobile, laptop, ultra-wide
- Very specific: line 67
MUST: Respect safe areas (env(safe-area-inset-*))
- Distinctive: line 68
MUST: Avoid unwanted scrollbars.
- Distinctive: line 69
SHOULD: Flex/grid over JS measurement for layout
- Distinctive: line 73
MUST: Skeletons mirror final content to avoid layout shift
- Distinctive: line 74
MUST: No dead ends; always offer next step/recovery
- Very specific: line 75
MUST: Design empty/sparse/dense/error states
- Distinctive: line 76
MUST: Redundant status cues (not color-only)
- Very specific: line 77
MUST: Icon-only buttons have descriptive aria-label
- Distinctive: line 78
MUST: Prefer native semantics before ARIA
- Very specific: line 79
MUST: Locale-aware dates/times/numbers (Intl.*)
- Very specific: line 83
MUST: Text containers handle long content (truncate, line-clamp, break-words)
- Very specific: line 84
MUST: Flex children need min-w-0 to allow truncation
- Distinctive: line 85
MUST: Handle empty states — no broken UI for empty strings/arrays
- Distinctive: line 89
MUST: Track and minimize unnecessary re-renders
- Distinctive: line 90
MUST: Virtualize large lists (>50 items)
- Distinctive: line 91
MUST: Preload above-fold images.
- Distinctive: line 92
MUST: Prevent CLS (explicit image dimensions)
- Very specific: line 96
MUST: color-scheme: dark on dark themes
- Very specific: line 97
MUST: Native controls get explicit background-color and color when needed
- Very specific: line 101
MUST: Controlled inputs with value need onChange (or use defaultValue)
- Distinctive: line 102
SHOULD: Guard date/time rendering against hydration mismatch
- Distinctive: line 106
SHOULD: Nested radii: child ≤ parent.
- Distinctive: line 107
MUST: Meet contrast — prefer APCA over WCAG 2 when possible
- Very specific: line 108
MUST: Increase contrast on :hover / :active / :focus
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Web Interface Guidelines
Concise rules for building accessible, fast, delightful UIs. Use MUST / SHOULD / NEVER to guide decisions.
Interactions
Keyboard
- MUST: Full keyboard support per WAI-ARIA APG
- MUST: Visible, unobscured focus rings (
:focus-visible; group with:focus-within) - MUST: Manage focus (trap, move, return) per APG patterns
- NEVER:
outline: nonewithout visible focus replacement
Targets & Input
- MUST: Hit target ≥24px (mobile ≥44px); if visual is smaller, expand hit area
- MUST: Mobile input font-size ≥16px to prevent iOS zoom
- NEVER: Disable browser zoom (
user-scalable=no,maximum-scale=1) - MUST:
touch-action: manipulationto prevent double-tap zoom
Forms
- MUST: Hydration-safe inputs (no lost focus/value)
- NEVER: Block paste in inputs/textareas
- MUST: Loading buttons show spinner and keep original label
- MUST: Keep submit enabled until request starts; then disable with spinner
- MUST: Accept free text, validate after — don't block typing
- MUST: Errors inline next to fields; on submit, focus first error
- MUST:
autocomplete+ meaningfulname; correcttypeandinputmode - MUST: Warn on unsaved changes before navigation
State & Navigation
- MUST: URL reflects state (filters/tabs/pagination/expanded panels)
- MUST: Back/Forward restores scroll position
- MUST: Links use real anchors / Next
Linkfor navigation - NEVER: Use buttons for navigation that should be links
Feedback
- SHOULD: Optimistic UI; reconcile on response; on failure rollback or Undo
- MUST: Confirm destructive actions or provide Undo
- MUST: Use polite
aria-livefor toasts/inline validation
Animation
- MUST: Honor
prefers-reduced-motion - SHOULD: Prefer CSS over JS animation libraries when possible
- MUST: Animate compositor-friendly props (
transform,opacity) only - NEVER: Animate layout props (
top,left,width,height) - NEVER:
transition: all— list properties explicitly - MUST: Animations interruptible and input-driven
Layout
- MUST: Deliberate alignment to grid/baseline/edges
- MUST: Verify mobile, laptop, ultra-wide
- MUST: Respect safe areas (
env(safe-area-inset-*)) - MUST: Avoid unwanted scrollbars; fix overflows
- SHOULD: Flex/grid over JS measurement for layout
Content & Accessibility
- MUST: Skeletons mirror final content to avoid layout shift
- MUST: No dead ends; always offer next step/recovery
- MUST: Design empty/sparse/dense/error states
- MUST: Redundant status cues (not color-only)
- MUST: Icon-only buttons have descriptive
aria-label - MUST: Prefer native semantics before ARIA
- MUST: Locale-aware dates/times/numbers (
Intl.*)
Content Handling
- MUST: Text containers handle long content (
truncate,line-clamp,break-words) - MUST: Flex children need
min-w-0to allow truncation - MUST: Handle empty states — no broken UI for empty strings/arrays
Performance
- MUST: Track and minimize unnecessary re-renders
- MUST: Virtualize large lists (>50 items)
- MUST: Preload above-fold images; lazy-load the rest
- MUST: Prevent CLS (explicit image dimensions)
Dark Mode & Theming
- MUST:
color-scheme: darkon dark themes - MUST: Native controls get explicit
background-colorandcolorwhen needed
Hydration
- MUST: Controlled inputs with
valueneedonChange(or usedefaultValue) - SHOULD: Guard date/time rendering against hydration mismatch
Design
- SHOULD: Nested radii: child ≤ parent; concentric
- MUST: Meet contrast — prefer APCA over WCAG 2 when possible
- MUST: Increase contrast on
:hover/:active/:focus
Source
Adapted from Vercel Labs — web-interface-guidelines (AGENTS.md).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

