agentleFS
MiladJoodiMiladJoodi/skills/skills/web-interface-guidelines/SKILL.md

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

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
  1. Distinctive:

    NEVER to guide decisions.

    line 12
  2. Distinctive:

    MUST: Full keyboard support per WAI-ARIA APG

    line 18
  3. Very specific:

    MUST: Visible, unobscured focus rings (:focus-visible.

    line 19
  4. Distinctive:

    MUST: Manage focus (trap, move, return) per APG patterns

    line 20
  5. Very specific:

    NEVER: outline: none without visible focus replacement

    line 21
  6. Distinctive:

    MUST: Hit target ≥24px (mobile ≥44px).

    line 25
  7. Distinctive:

    MUST: Mobile input font-size ≥16px to prevent iOS zoom

    line 26
  8. Very specific:

    NEVER: Disable browser zoom (user-scalable=no, maximum-scale=1)

    line 27
  9. Very specific:

    MUST: touch-action: manipulation to prevent double-tap zoom

    line 28
  10. Distinctive:

    MUST: Hydration-safe inputs (no lost focus/value)

    line 32
  11. Distinctive:

    NEVER: Block paste in inputs/textareas

    line 33
  12. Distinctive:

    MUST: Loading buttons show spinner and keep original label

    line 34
  13. Distinctive:

    MUST: Keep submit enabled until request starts.

    line 35
  14. Distinctive:

    MUST: Accept free text, validate after — don't block typing

    line 36
  15. Distinctive:

    MUST: Errors inline next to fields.

    line 37
  16. Very specific:

    MUST: autocomplete + meaningful name.

    line 38
  17. Distinctive:

    MUST: Warn on unsaved changes before navigation

    line 39
  18. Very specific:

    MUST: URL reflects state (filters/tabs/pagination/expanded panels)

    line 43
  19. Distinctive:

    MUST: Back/Forward restores scroll position

    line 44
  20. Very specific:

    MUST: Links use real anchors / Next Link for navigation

    line 45
  21. Distinctive:

    NEVER: Use buttons for navigation that should be links

    line 46
  22. Distinctive:

    SHOULD: Optimistic UI; reconcile on response.

    line 50
  23. Distinctive:

    MUST: Confirm destructive actions or provide Undo

    line 51
  24. Very specific:

    MUST: Use polite aria-live for toasts/inline validation

    line 52
  25. Distinctive:

    SHOULD: Prefer CSS over JS animation libraries when possible

    line 57
  26. Very specific:

    MUST: Animate compositor-friendly props (transform, opacity) only

    line 58
  27. Very specific:

    NEVER: Animate layout props (top, left, width, height)

    line 59
  28. Very specific:

    NEVER: transition: all — list properties explicitly

    line 60
  29. Distinctive:

    MUST: Animations interruptible and input-driven

    line 61
  30. Very specific:

    MUST: Deliberate alignment to grid/baseline/edges

    line 65
  31. Distinctive:

    MUST: Verify mobile, laptop, ultra-wide

    line 66
  32. Very specific:

    MUST: Respect safe areas (env(safe-area-inset-*))

    line 67
  33. Distinctive:

    MUST: Avoid unwanted scrollbars.

    line 68
  34. Distinctive:

    SHOULD: Flex/grid over JS measurement for layout

    line 69
  35. Distinctive:

    MUST: Skeletons mirror final content to avoid layout shift

    line 73
  36. Distinctive:

    MUST: No dead ends; always offer next step/recovery

    line 74
  37. Very specific:

    MUST: Design empty/sparse/dense/error states

    line 75
  38. Distinctive:

    MUST: Redundant status cues (not color-only)

    line 76
  39. Very specific:

    MUST: Icon-only buttons have descriptive aria-label

    line 77
  40. Distinctive:

    MUST: Prefer native semantics before ARIA

    line 78
  41. Very specific:

    MUST: Locale-aware dates/times/numbers (Intl.*)

    line 79
  42. Very specific:

    MUST: Text containers handle long content (truncate, line-clamp, break-words)

    line 83
  43. Very specific:

    MUST: Flex children need min-w-0 to allow truncation

    line 84
  44. Distinctive:

    MUST: Handle empty states — no broken UI for empty strings/arrays

    line 85
  45. Distinctive:

    MUST: Track and minimize unnecessary re-renders

    line 89
  46. Distinctive:

    MUST: Virtualize large lists (>50 items)

    line 90
  47. Distinctive:

    MUST: Preload above-fold images.

    line 91
  48. Distinctive:

    MUST: Prevent CLS (explicit image dimensions)

    line 92
  49. Very specific:

    MUST: color-scheme: dark on dark themes

    line 96
  50. Very specific:

    MUST: Native controls get explicit background-color and color when needed

    line 97
  51. Very specific:

    MUST: Controlled inputs with value need onChange (or use defaultValue)

    line 101
  52. Distinctive:

    SHOULD: Guard date/time rendering against hydration mismatch

    line 102
  53. Distinctive:

    SHOULD: Nested radii: child ≤ parent.

    line 106
  54. Distinctive:

    MUST: Meet contrast — prefer APCA over WCAG 2 when possible

    line 107
  55. Very specific:

    MUST: Increase contrast on :hover / :active / :focus

    line 108

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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: none without 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: manipulation to 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 + meaningful name; correct type and inputmode
  • 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 Link for 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-live for 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-0 to 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: dark on dark themes
  • MUST: Native controls get explicit background-color and color when needed

Hydration

  • MUST: Controlled inputs with value need onChange (or use defaultValue)
  • 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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.