{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "cursor-rule-web-interface-guidelines",
  "title": "Cursor Rule: Web Interface Guidelines",
  "description": "Cursor rule file for web interface guidelines.",
  "dependencies": [],
  "registryDependencies": [],
  "files": [
    {
      "path": "registry/optics/cursor/rules/web-interface-guidelines.mdc",
      "content": "---\ndescription: Web Interface Guidelines\nglobs: *\nalwaysApply: false\n---\nConcise rules for building accessible, fast, delightful UIs Use MUST/SHOULD/NEVER to guide decisions\n\n## Interactions\n\n- Keyboard\n  - MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/)\n  - MUST: Visible focus rings (`:focus-visible`; group with `:focus-within`)\n  - MUST: Manage focus (trap, move, and return) per APG patterns\n- Targets & input\n  - MUST: Hit target ≥24px (mobile ≥44px) If visual <24px, expand hit area\n  - MUST: Mobile `<input>` font-size ≥16px or set:\n    ```html\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover\">\n    ```\n  - NEVER: Disable browser zoom\n  - MUST: `touch-action: manipulation` to prevent double-tap zoom; set `-webkit-tap-highlight-color` to match design\n- Inputs & forms (behavior)\n  - MUST: Hydration-safe inputs (no lost focus/value)\n  - NEVER: Block paste in `<input>/<textarea>`\n  - MUST: Loading buttons show spinner and keep original label\n  - MUST: Enter submits focused text input In `<textarea>`, ⌘/Ctrl+Enter submits; Enter adds newline\n  - MUST: Keep submit enabled until request starts; then disable, show spinner, use idempotency key\n  - MUST: Don’t block typing; accept free text and validate after\n  - MUST: Allow submitting incomplete forms to surface validation\n  - MUST: Errors inline next to fields; on submit, focus first error\n  - MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode`\n  - SHOULD: Disable spellcheck for emails/codes/usernames\n  - SHOULD: Placeholders end with ellipsis and show example pattern (eg, `+1 (123) 456-7890`, `sk-012345…`)\n  - MUST: Warn on unsaved changes before navigation\n  - MUST: Compatible with password managers & 2FA; allow pasting one-time codes\n  - MUST: Trim values to handle text expansion trailing spaces\n  - MUST: No dead zones on checkboxes/radios; label+control share one generous hit target\n- State & navigation\n  - MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels) Prefer libs like [nuqs](https://nuqs.dev)\n  - MUST: Back/Forward restores scroll\n  - MUST: Links are links—use `<a>/<Link>` for navigation (support Cmd/Ctrl/middle-click)\n- Feedback\n  - SHOULD: Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo\n  - MUST: Confirm destructive actions or provide Undo window\n  - MUST: Use polite `aria-live` for toasts/inline validation\n  - SHOULD: Ellipsis (`…`) for options that open follow-ups (eg, \"Rename…\") and loading states (eg, \"Loading…\", \"Saving…\", \"Generating…\")\n- Touch/drag/scroll\n  - MUST: Design forgiving interactions (generous targets, clear affordances; avoid finickiness)\n  - MUST: Delay first tooltip in a group; subsequent peers no delay\n  - MUST: Intentional `overscroll-behavior: contain` in modals/drawers\n  - MUST: During drag, disable text selection and set `inert` on dragged element/containers\n  - MUST: No “dead-looking” interactive zones—if it looks clickable, it is\n- Autofocus\n  - SHOULD: Autofocus on desktop when there’s a single primary input; rarely on mobile (to avoid layout shift)\n\n## Animation\n\n- MUST: Honor `prefers-reduced-motion` (provide reduced variant)\n- SHOULD: Prefer CSS > Web Animations API > JS libraries\n- MUST: Animate compositor-friendly props (`transform`, `opacity`); avoid layout/repaint props (`top/left/width/height`)\n- SHOULD: Animate only to clarify cause/effect or add deliberate delight\n- SHOULD: Choose easing to match the change (size/distance/trigger)\n- MUST: Animations are interruptible and input-driven (avoid autoplay)\n- MUST: Correct `transform-origin` (motion starts where it “physically” should)\n\n## Layout\n\n- SHOULD: Optical alignment; adjust by ±1px when perception beats geometry\n- MUST: Deliberate alignment to grid/baseline/edges/optical centers—no accidental placement\n- SHOULD: Balance icon/text lockups (stroke/weight/size/spacing/color)\n- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)\n- MUST: Respect safe areas (use env(safe-area-inset-*))\n- MUST: Avoid unwanted scrollbars; fix overflows\n\n## Content & Accessibility\n\n- SHOULD: Inline help first; tooltips last resort\n- MUST: Skeletons mirror final content to avoid layout shift\n- MUST: `<title>` matches current context\n- MUST: No dead ends; always offer next step/recovery\n- MUST: Design empty/sparse/dense/error states\n- SHOULD: Curly quotes (“ ”); avoid widows/orphans\n- MUST: Tabular numbers for comparisons (`font-variant-numeric: tabular-nums` or a mono like Geist Mono)\n- MUST: Redundant status cues (not color-only); icons have text labels\n- MUST: Don’t ship the schema—visuals may omit labels but accessible names still exist\n- MUST: Use the ellipsis character `…` (not ``)\n- MUST: `scroll-margin-top` on headings for anchored links; include a “Skip to content” link; hierarchical `<h1–h6>`\n- MUST: Resilient to user-generated content (short/avg/very long)\n- MUST: Locale-aware dates/times/numbers/currency\n- MUST: Accurate names (`aria-label`), decorative elements `aria-hidden`, verify in the Accessibility Tree\n- MUST: Icon-only buttons have descriptive `aria-label`\n- MUST: Prefer native semantics (`button`, `a`, `label`, `table`) before ARIA\n- SHOULD: Right-clicking the nav logo surfaces brand assets\n- MUST: Use non-breaking spaces to glue terms: `10&nbsp;MB`, `⌘&nbsp;+&nbsp;K`, `Vercel&nbsp;SDK`\n\n## Performance\n\n- SHOULD: Test iOS Low Power Mode and macOS Safari\n- MUST: Measure reliably (disable extensions that skew runtime)\n- MUST: Track and minimize re-renders (React DevTools/React Scan)\n- MUST: Profile with CPU/network throttling\n- MUST: Batch layout reads/writes; avoid unnecessary reflows/repaints\n- MUST: Mutations (`POST/PATCH/DELETE`) target <500 ms\n- SHOULD: Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost)\n- MUST: Virtualize large lists (eg, `virtua`)\n- MUST: Preload only above-the-fold images; lazy-load the rest\n- MUST: Prevent CLS from images (explicit dimensions or reserved space)\n\n## Design\n\n- SHOULD: Layered shadows (ambient + direct)\n- SHOULD: Crisp edges via semi-transparent borders + shadows\n- SHOULD: Nested radii: child ≤ parent; concentric\n- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue\n- MUST: Accessible charts (color-blind-friendly palettes)\n- MUST: Meet contrast—prefer [APCA](https://apcacontrast.com/) over WCAG 2\n- MUST: Increase contrast on `:hover/:active/:focus`\n- SHOULD: Match browser UI to bg\n- SHOULD: Avoid gradient banding (use masks when needed)",
      "type": "registry:file",
      "target": "~/.cursor/rules/web-interface-guidelines.mdc"
    }
  ],
  "type": "registry:file"
}