CustomCursorA11y [anti-pattern] v1.0.0

Custom cursor implementations that apply cursor: none globally or add trailing/lerp animation create five distinct accessibility failures: semantic cursor loss, click hot-zone misalignment, vestibular motion harm (prefers-reduced-motion), silent breakage on touch devices, and invisibility under Windows High Contrast Mode.

Label

Custom Cursor Without Accessibility Safeguards

Trap

A custom cursor passes visual QA and device testing but fails silently for three user groups simultaneously: users with vestibular disorders (cursor-follow is continuous full-viewport motion triggered by every pointer move), low-vision users who depend on the OS high-contrast system cursor, and touch device users who may see a ghost cursor element stuck at coordinates 0,0.

Risks

• cursor: none on :root — erases system cursor on browser scrollbars, native dialogs, and elements that CSS cannot reach
  Lerp-smoothed cursor trail — continuous spatial displacement; no escape; vestibular harm for every mouse movement
  Custom cursor DOM element missing pointer-events: none — eats clicks, breaking interactive elements underneath
  Missing aria-hidden='true' on cursor element — screen readers announce a decorative div
  No hover: hover + pointer: fine guard — touch users see a stuck element on screen
  Low-contrast custom cursor — invisible under macOS Increase Contrast / Windows High Contrast Mode

  Remediation

  • Gate cursor activation on (hover: hover) AND (pointer: fine) AND (prefers-reduced-motion: no-preference) — all three must pass.
  • Never apply cursor: none globally; restrict to a specific .branded-zone class and restore cursor: auto on all interactive descendants.
  • Always set pointer-events: none and aria-hidden='true' on the cursor DOM element.
  • Restore system cursor semantics on , ,
  , , <select> even inside the branded zone.</li> <li>Use translate3d for positioning (compositor thread); never lerp unless prefers-reduced-motion is explicitly no-preference.</li> <li>For SaaS, dashboards, utilities, or any WCAG AA project: skip custom cursors entirely.</li> </ul> <h2>Safe Variant</h2> <pre><code>const canUseCursor = window.matchMedia('(hover: hover) and (pointer: fine)').matches && window.matchMedia('(prefers-reduced-motion: no-preference)').matches; if (canUseCursor) { const cursor = document.createElement('div'); cursor.setAttribute('aria-hidden', 'true'); cursor.style.pointerEvents = 'none'; document.body.appendChild(cursor); document.addEventListener('pointermove', (e) => { cursor.style.transform = `translate3d(${e.clientX}px,${e.clientY}px,0)`; }, { passive: true }); } </code></pre> <h2>Severity</h2> <p>critical</p> <h2>Detection Heuristics</h2> <ul> <li>cursor: none appears on body, :root, or html in any stylesheet</li> <li>A JS file initializes a cursor-tracking element without matchMedia guards</li> <li>A DOM element with class <em>cursor</em> exists without aria-hidden='true'</li> <li>pointer-events is not set to none on the custom cursor element</li> </ul> </div> </div> <div class="proj-panel" data-panel="full" hidden data-astro-cid-ztpy2nk5> <p class="proj-when" data-astro-cid-ztpy2nk5>Loaded when retrieval picks the atom as a focal / direct hit.</p> <div class="atom-prose" data-astro-cid-ztpy2nk5><h1>CustomCursorA11y [anti-pattern] v1.0.0</h1> <p>Custom cursor implementations that apply cursor: none globally or add trailing/lerp animation create five distinct accessibility failures: semantic cursor loss, click hot-zone misalignment, vestibular motion harm (prefers-reduced-motion), silent breakage on touch devices, and invisibility under Windows High Contrast Mode.</p> <h2>Label</h2> <p>Custom Cursor Without Accessibility Safeguards</p> <h2>Trap</h2> <p>A custom cursor passes visual QA and device testing but fails silently for three user groups simultaneously: users with vestibular disorders (cursor-follow is continuous full-viewport motion triggered by every pointer move), low-vision users who depend on the OS high-contrast system cursor, and touch device users who may see a ghost cursor element stuck at coordinates 0,0.</p> <h2>Risks</h2> <ul> <li>cursor: none on :root — erases system cursor on browser scrollbars, native dialogs, and <select> elements that CSS cannot reach</li> <li>Lerp-smoothed cursor trail — continuous spatial displacement; no escape; vestibular harm for every mouse movement</li> <li>Custom cursor DOM element missing pointer-events: none — eats clicks, breaking interactive elements underneath</li> <li>Missing aria-hidden='true' on cursor element — screen readers announce a decorative div</li> <li>No hover: hover + pointer: fine guard — touch users see a stuck element on screen</li> <li>Low-contrast custom cursor — invisible under macOS Increase Contrast / Windows High Contrast Mode</li> </ul> <h2>Remediation</h2> <ul> <li>Gate cursor activation on (hover: hover) AND (pointer: fine) AND (prefers-reduced-motion: no-preference) — all three must pass.</li> <li>Never apply cursor: none globally; restrict to a specific .branded-zone class and restore cursor: auto on all interactive descendants.</li> <li>Always set pointer-events: none and aria-hidden='true' on the cursor DOM element.</li> <li>Restore system cursor semantics on <a>, <button>, <input>, <textarea>, <select> even inside the branded zone.</li> <li>Use translate3d for positioning (compositor thread); never lerp unless prefers-reduced-motion is explicitly no-preference.</li> <li>For SaaS, dashboards, utilities, or any WCAG AA project: skip custom cursors entirely.</li> </ul> <h2>Safe Variant</h2> <pre><code>const canUseCursor = window.matchMedia('(hover: hover) and (pointer: fine)').matches && window.matchMedia('(prefers-reduced-motion: no-preference)').matches; if (canUseCursor) { const cursor = document.createElement('div'); cursor.setAttribute('aria-hidden', 'true'); cursor.style.pointerEvents = 'none'; document.body.appendChild(cursor); document.addEventListener('pointermove', (e) => { cursor.style.transform = `translate3d(${e.clientX}px,${e.clientY}px,0)`; }, { passive: true }); } </code></pre> <h2>Severity</h2> <p>critical</p> <h2>Detection Heuristics</h2> <ul> <li>cursor: none appears on body, :root, or html in any stylesheet</li> <li>A JS file initializes a cursor-tracking element without matchMedia guards</li> <li>A DOM element with class <em>cursor</em> exists without aria-hidden='true'</li> <li>pointer-events is not set to none on the custom cursor element</li> </ul> <h2>Label</h2> <p>Custom Cursor Without Accessibility Safeguards</p> <h2>Trap</h2> <p>A custom cursor passes visual QA and device testing but fails silently for three user groups simultaneously: users with vestibular disorders (cursor-follow is continuous full-viewport motion triggered by every pointer move), low-vision users who depend on the OS high-contrast system cursor, and touch device users who may see a ghost cursor element stuck at coordinates 0,0.</p> <h2>Risks</h2> <ul> <li>cursor: none on :root — erases system cursor on browser scrollbars, native dialogs, and <select> elements that CSS cannot reach</li> <li>Lerp-smoothed cursor trail — continuous spatial displacement; no escape; vestibular harm for every mouse movement</li> <li>Custom cursor DOM element missing pointer-events: none — eats clicks, breaking interactive elements underneath</li> <li>Missing aria-hidden='true' on cursor element — screen readers announce a decorative div</li> <li>No hover: hover + pointer: fine guard — touch users see a stuck element on screen</li> <li>Low-contrast custom cursor — invisible under macOS Increase Contrast / Windows High Contrast Mode</li> </ul> <h2>Remediation</h2> <ul> <li>Gate cursor activation on (hover: hover) AND (pointer: fine) AND (prefers-reduced-motion: no-preference) — all three must pass.</li> <li>Never apply cursor: none globally; restrict to a specific .branded-zone class and restore cursor: auto on all interactive descendants.</li> <li>Always set pointer-events: none and aria-hidden='true' on the cursor DOM element.</li> <li>Restore system cursor semantics on <a>, <button>, <input>, <textarea>, <select> even inside the branded zone.</li> <li>Use translate3d for positioning (compositor thread); never lerp unless prefers-reduced-motion is explicitly no-preference.</li> <li>For SaaS, dashboards, utilities, or any WCAG AA project: skip custom cursors entirely.</li> </ul> <h2>Safe Variant</h2> <pre><code>const canUseCursor = window.matchMedia('(hover: hover) and (pointer: fine)').matches && window.matchMedia('(prefers-reduced-motion: no-preference)').matches; if (canUseCursor) { const cursor = document.createElement('div'); cursor.setAttribute('aria-hidden', 'true'); cursor.style.pointerEvents = 'none'; document.body.appendChild(cursor); document.addEventListener('pointermove', (e) => { cursor.style.transform = `translate3d(${e.clientX}px,${e.clientY}px,0)`; }, { passive: true }); } </code></pre> <h2>Severity</h2> <p>critical</p> <h2>Detection Heuristics</h2> <ul> <li>cursor: none appears on body, :root, or html in any stylesheet</li> <li>A JS file initializes a cursor-tracking element without matchMedia guards</li> <li>A DOM element with class <em>cursor</em> exists without aria-hidden='true'</li> <li>pointer-events is not set to none on the custom cursor element</li> </ul> </div> </div> </section> <section class="atom-section" data-astro-cid-ztpy2nk5> <header class="atom-section-h" data-astro-cid-ztpy2nk5> <h2 data-astro-cid-ztpy2nk5>Source</h2> <span class="atom-section-meta" data-astro-cid-ztpy2nk5>where the compiled artifact came from</span> </header> <pre class="atom-source" data-astro-cid-ztpy2nk5><code data-astro-cid-ztpy2nk5>prime-system/examples/frontend-design/primes/compiled/@community/anti-pattern-custom-cursor-a11y/atom.yaml</code></pre> <p class="atom-source-meta" data-astro-cid-ztpy2nk5>Compiled at <strong data-astro-cid-ztpy2nk5>2026-05-07</strong></p> </section> </main> <aside class="atom-side" aria-label="Edges and graph" data-astro-cid-ztpy2nk5> <div class="atom-side-card" data-astro-cid-ztpy2nk5> <div class="atom-side-graph" data-astro-cid-ztpy2nk5> <figure class="mini-graph" aria-label="Related atoms graph" data-astro-cid-fdlvampy><svg viewBox="0 0 480 300" role="img" aria-labelledby="graph-title" data-astro-cid-fdlvampy><title id="graph-title">Edges from @community/anti-pattern-custom-cursor-a11y</title><line class="mg-edge mg-edge-out" x1="240" y1="150" x2="240" y2="45" data-astro-cid-fdlvampy></line><line class="mg-edge mg-edge-out" x1="240" y1="150" x2="330.93266739736606" y2="202.5" data-astro-cid-fdlvampy></line><line class="mg-edge mg-edge-out" x1="240" y1="150" x2="149.06733260263394" y2="202.50000000000003" data-astro-cid-fdlvampy></line><g data-astro-cid-fdlvampy><circle class="mg-node" cx="240" cy="45" r="5" data-astro-cid-fdlvampy></circle><text class="mg-label" x="240" y="35" data-astro-cid-fdlvampy>anti-pattern-hover…</text></g><g data-astro-cid-fdlvampy><circle class="mg-node" cx="330.93266739736606" cy="202.5" r="5" data-astro-cid-fdlvampy></circle><text class="mg-label" x="330.93266739736606" y="220.5" data-astro-cid-fdlvampy>check-reduced-moti…</text></g><g data-astro-cid-fdlvampy><circle class="mg-node" cx="149.06733260263394" cy="202.50000000000003" r="5" data-astro-cid-fdlvampy></circle><text class="mg-label" x="149.06733260263394" y="220.50000000000003" data-astro-cid-fdlvampy>constraint-reduced…</text></g><circle class="mg-center" cx="240" cy="150" r="11" data-astro-cid-fdlvampy></circle><text class="mg-center-label" x="240" y="178" data-astro-cid-fdlvampy>anti-pattern-custom-cu…</text></svg><figcaption data-astro-cid-fdlvampy>3 outgoing · 0 incoming </figcaption></figure> </div> <div class="atom-side-section" data-astro-cid-ztpy2nk5> <header class="atom-side-h" data-astro-cid-ztpy2nk5> <span class="dir-arrow" aria-hidden="true" data-astro-cid-ztpy2nk5>↗</span> <span data-astro-cid-ztpy2nk5>Outgoing</span> <span class="atom-side-count" data-astro-cid-ztpy2nk5>3</span> </header> <div class="edge-group" data-astro-cid-ztpy2nk5> <div class="edge-verb-row" data-astro-cid-ztpy2nk5> <span class="edge-verb" data-astro-cid-ztpy2nk5>related</span> <span class="edge-verb-count" data-astro-cid-ztpy2nk5>3</span> </div> <ul class="edge-list" data-astro-cid-ztpy2nk5> <li data-astro-cid-ztpy2nk5> <a href="/atom/frontend-design/anti-pattern-hover-only-interaction" title="@community/anti-pattern-hover-only-interaction" data-astro-cid-ztpy2nk5> <code data-astro-cid-ztpy2nk5>@community/anti-pattern-hover-only-interaction</code> </a> </li><li data-astro-cid-ztpy2nk5> <a href="/atom/frontend-design/check-reduced-motion-required" title="@community/check-reduced-motion-required" data-astro-cid-ztpy2nk5> <code data-astro-cid-ztpy2nk5>@community/check-reduced-motion-required</code> </a> </li><li data-astro-cid-ztpy2nk5> <a href="/atom/frontend-design/constraint-reduced-motion" title="@community/constraint-reduced-motion" data-astro-cid-ztpy2nk5> <code data-astro-cid-ztpy2nk5>@community/constraint-reduced-motion</code> </a> </li> </ul> </div> </div> </div> </aside> </div> <nav class="atom-foot" data-astro-cid-ztpy2nk5> <a href="/browse?corpus=frontend-design" data-astro-cid-ztpy2nk5>← Back to @community</a> <a href="/marketplace" data-astro-cid-ztpy2nk5>All Skills →</a> </nav> </div> </main> <footer class="gh-footer"> <div class="gh-footer-inner"> <div class="gh-footer-meta"> <strong>Skill Wiki</strong> v0.1.0<br> Typed atoms, a declared edge graph, retrieved on demand. Powered by the open Prime protocol. <br><br> Apache-2.0 licensed. </div> <div> <h4>Product</h4> <ul> <li><a href="/marketplace">Marketplace</a></li> <li><a href="/docs/usage/install">Install</a></li> <li><a href="/docs/spec/overview">Specification</a></li> </ul> </div> <div> <h4>Developers</h4> <ul> <li><a href="/docs/architecture/pipeline">Architecture</a></li> <li><a href="/docs/extending/custom-kinds">Extending</a></li> <li><a href="/docs/reference/cli">CLI</a></li> <li><a href="/docs/reference/mcp">MCP API</a></li> </ul> </div> <div> <h4>Resources</h4> <ul> <li><a href="/blog">Blog</a></li> <li><a href="/about">About</a></li> <li><a href="https://github.com/skill-wiki/prime-system" rel="noopener">GitHub</a></li> <li><a href="https://github.com/skill-wiki/prime-system/blob/main/LICENSE" rel="noopener">License</a></li> </ul> </div> </div> <div class="gh-footer-bottom"> <span>© 2026 Skill Wiki contributors. Apache-2.0.</span> <span>v0.1.0 · 1,002 atoms compiled</span> </div> </footer> </body> </html>