Prepared Docs

Image requires exactly one of alt or decorative in every mode — passing both, or neither, is a type error. How that choice is exposed depends on whether the image conveys meaning.

Alt text

Meaningful images: Provide a concise alt that describes purpose or content (for example, "Prepared logo" or "Officer profile photo").
Decorative images: Pass decorative when the image adds no information beyond surrounding text or UI chrome. It renders an empty alt and is skipped by screen readers.

Do not omit alt or use placeholder strings like "image" when the image carries meaning.

URL mode (`src`)

Renders a native <img> with the alt attribute forwarded directly (empty when decorative is set). Screen readers announce the alt text as the image label.

Inline SVG mode (`svg`)

Accessibility attributes are applied to the <svg> node. @prepared911/ui/image and ui-core agree on this:

Meaningful (alt set): role="img" and aria-label from alt (LocalizedMessage on @prepared911/ui).
Decorative (decorative, or alt=""): aria-hidden="true" and focusable="false".
No title or desc. Image does not add them. A <title> or <desc> inside the SVG component duplicates the accessible name, so leave them out.

@prepared911/ui/image sizes that SVG with size={{ inline, block }} from the space scale instead of numeric width and height.

Themed modes (`lightSrc`/`darkSrc`, `lightSvg`/`darkSvg`)

Both theme variants mount in the DOM, but the inactive variant uses display: none and is removed from the accessibility tree. Assistive tech announces a single image — the visible variant — with the shared alt value. Pass id once; it is applied to a display: contents themed root so the document keeps a single stable id without JavaScript theme branching (and without duplicating id on both variants).

Best practices

Do not convey critical information by image alone — pair logos, status marks, or charts with visible text.
Test decorative treatment: if removing the image would confuse sighted users, it is not decorative and needs descriptive alt text.
For URL SVGs loaded via src, the browser treats them like raster images; alt text behavior matches standard <img> semantics.

Image / API and Development

Input / Usage

Alt text

URL mode (src)

Inline SVG mode (svg)

Themed modes (lightSrc/darkSrc, lightSvg/darkSvg)

Best practices

Image requires exactly one of alt or decorative in every mode — passing both, or neither, is a type error. How that choice is exposed depends on whether the image conveys meaning.

Alt text

Meaningful images: Provide a concise alt that describes purpose or content (for example, "Prepared logo" or "Officer profile photo").
Decorative images: Pass decorative when the image adds no information beyond surrounding text or UI chrome. It renders an empty alt and is skipped by screen readers.

Do not omit alt or use placeholder strings like "image" when the image carries meaning.

URL mode (`src`)

Renders a native <img> with the alt attribute forwarded directly (empty when decorative is set). Screen readers announce the alt text as the image label.

Inline SVG mode (`svg`)

Accessibility attributes are applied to the <svg> node. @prepared911/ui/image and ui-core agree on this:

Meaningful (alt set): role="img" and aria-label from alt (LocalizedMessage on @prepared911/ui).
Decorative (decorative, or alt=""): aria-hidden="true" and focusable="false".
No title or desc. Image does not add them. A <title> or <desc> inside the SVG component duplicates the accessible name, so leave them out.

@prepared911/ui/image sizes that SVG with size={{ inline, block }} from the space scale instead of numeric width and height.

Themed modes (`lightSrc`/`darkSrc`, `lightSvg`/`darkSvg`)

Best practices

Do not convey critical information by image alone — pair logos, status marks, or charts with visible text.
Test decorative treatment: if removing the image would confuse sighted users, it is not decorative and needs descriptive alt text.
For URL SVGs loaded via src, the browser treats them like raster images; alt text behavior matches standard <img> semantics.

Image / API and Development

Input / Usage

Alt text

URL mode (src)

Inline SVG mode (svg)

Themed modes (lightSrc/darkSrc, lightSvg/darkSvg)

Best practices