||

Accessibility

Documentation Index

Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.

Use Honest UI icons without hiding meaning from assistive technology.

Accessible icon usage starts by deciding what the icon does. An icon can be decorative, reinforce visible text, label an icon-only control, or communicate status on its own.

Use native HTML for the surrounding control and add ARIA only when it improves the accessible name or meaning.

Decorative icons

Hide icons that only add visual detail with aria-hidden="true".

import { Sparkles } from "honestui/icons";

<p>
  <Sparkles aria-hidden="true" />
  New this week
</p>

Decorative icons should not receive focus and should not repeat nearby text.

Icons beside text

Visible text already names the action, so hide the icon from assistive technology.

import { Download } from "honestui/icons";

<button type="button">
  <Download aria-hidden="true" />
  Download report
</button>

This prevents a screen reader from announcing both the icon name and the visible label.

Icon-only controls

Put the accessible name on the interactive element, not on the SVG.

import { Trash2 } from "honestui/icons";

<button type="button" aria-label="Delete invoice">
  <Trash2 aria-hidden="true" />
</button>

Labels should describe the action and, when useful, its target. “Delete invoice” is clearer than “Trash.”

Icon-only buttons and links also need a visible focus indicator and a touch target of at least 44 × 44 pixels.

Meaningful status icons

When a non-interactive icon communicates information without nearby text, give the SVG an image role and an accessible label.

import { CircleAlert } from "honestui/icons";

<CircleAlert role="img" aria-label="Warning" />

Whenever possible, pair status icons with visible text. Do not rely on color or icon shape alone to communicate an error, warning, or success state.

Color and contrast

Icons that carry meaning should meet a contrast ratio of at least 3:1 against adjacent colors. Check default, hover, focus, active, and disabled states in both light and dark themes.

Decorative icons can use quieter colors, but they should not make nearby text harder to read.

Testing icons

When adding or changing an icon:

  1. Confirm that decorative icons are hidden from the accessibility tree.
  2. Check that icon-only controls have specific accessible names.
  3. Navigate to the control with a keyboard and confirm that focus is visible.
  4. Test the control with a screen reader.
  5. Check contrast in light mode, dark mode, and disabled states.
  6. Verify that zooming to 200% does not clip the icon or its label.