AddThisFeature

Screen Reader Only Utility

One tested way to add text for assistive technology without it appearing on screen.

simple Components & Primitives

What it adds

A single visually hidden utility used for labels, instructions, and context that assistive technology needs and sighted users do not.

What your agent is told to do

5
  1. 1

    Find every place the app currently hides text from sight — off-screen positioning, zero dimensions, transparent colour, tiny font sizes, aria-label strings duplicating nearby copy — and consolidate them onto one utility.

  2. 2

    Build it by clipping the element to nothing while keeping it rendered and in the accessibility tree: it must occupy no visual space and contribute nothing to layout, yet still be read in document order.

  3. 3

    Provide a second variant that becomes visible when it receives focus, and use it for skip links and any other hidden content that is itself focusable.

  4. 4

    Audit each existing usage as you migrate it and delete the ones where visible text would serve everyone better — a column header, a button label, or an error message usually belongs on screen.

  5. 5

    Do not implement it with display none, visibility hidden, or the hidden attribute. Those remove the element from the accessibility tree as well as the screen, so the text is announced to nobody and the effort is wasted.

Edge cases it handles

7
  • Hidden content that can take focus must become visible when focused, or a keyboard user tabs to something they cannot see and loses their place entirely.
  • display none, visibility hidden, and zero width with zero height all remove the node from the accessibility tree; the utility must clip rather than remove, and a review should catch any regression back to them.
  • Clipping breaks in familiar ways — an ancestor with overflow hidden, a transform creating a new containing block, or a flex or grid parent that still allocates a gap for the element — so the utility needs a fixed positioning context and no residual margin.
  • Some cases do not want hidden text at all. Record in the utility's own documentation that visible labels, visible error text, and visible column headers are preferable, and that this utility is for supplementary context only.
  • Line breaks and whitespace inside the hidden text are read aloud; keep the string a single clean sentence rather than formatted markup.
  • Hidden text inside a control that also carries an accessible name will be concatenated with it, producing a doubled announcement — decide which source wins.
  • Browser translation and text selection still reach the hidden text, so it must read sensibly if a user copies the surrounding block.

Definition of done

8
  • One utility covers every visually hidden string in the app, with no bespoke off-screen positioning left behind.
  • Hidden text is present in the accessibility tree and read in document order.
  • The focusable variant becomes fully visible on focus and returns to hidden on blur.
  • No usage relies on display none, visibility hidden, or the hidden attribute.
  • The utility survives overflow hidden, transformed, and flex or grid ancestors without leaking a scrollbar or a gap.
  • Cases better served by visible text have been converted rather than hidden.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.