Accessibility

Accessible visual asset usage starts by deciding what the asset contributes. An icon can label an action or communicate status, a logo can identify an organization or product, and a vector can be decorative or illustrate information.

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

Hide any icon, logo, or vector that only adds visual detail or repeats nearby text.

import { Sparkles } from "honestui/icons";
import { Scribble1Sketch } from "honestui/vectors";

<div>
  <Sparkles aria-hidden="true" />
  <span>New this week</span>
  <Scribble1Sketch aria-hidden="true" />
</div>

Decorative assets should not receive focus. Hiding repeated artwork prevents a screen reader from announcing the same information twice.

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>

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. Icon-only buttons and links also need a visible focus indicator. Make the target at least 24 × 24 CSS pixels or satisfy a defined WCAG 2.2 exception; aim for 44 × 44 CSS pixels for important or touch-heavy controls.

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 shape alone to communicate an error, warning, or success state.

When a logo is the only visible identification, give it the organization or product name:

import { VercelWordmark } from "honestui/logos";

<VercelWordmark role="img" aria-label="Vercel" />

If visible text already says “Vercel,” use aria-hidden="true" on the logo. Avoid labels such as “Vercel logo”; the meaningful information is the identity, not the fact that it is a logo.

Most vectors are decorative and should be hidden. If an illustration communicates information that is not available in nearby text, give it a concise label or provide an equivalent text description.

import { PeepStanding1Character } from "honestui/vectors";

<PeepStanding1Character role="img" aria-label="A person waving" />

Complex illustrations may need a longer description in surrounding content rather than an oversized aria-label.

Icons that carry meaning should meet a contrast ratio of at least 3:1 against adjacent colors when WCAG non-text contrast applies. Check default, hover, focus, and active states in both light and dark themes. Disabled controls are exempt from that criterion, but their unavailable state and nearby explanation should still be understandable.

Logos and vectors can contain fixed colors. Test them against every intended background, and do not alter a brand mark in a way that makes it unrecognizable. Decorative artwork can use quieter colors, but it should not reduce the readability of nearby content.

When adding or changing an asset:

1. Confirm that decorative icons, logos, and vectors are hidden from the accessibility tree.
2. Check that icon-only controls have specific accessible names.
3. Confirm that meaningful logos expose the correct identity without repeating nearby text.
4. Provide equivalent text for informative illustrations.
5. Navigate interactive controls with a keyboard and confirm that focus is visible.
6. Test meaningful assets with a screen reader.
7. Check contrast and visibility in light mode, dark mode, and disabled states.
8. Verify that zooming to 200% does not clip the asset or its label.