Accessibility annotation type for widget nodes.

When attached to a widget via the a11y prop, these attributes override the auto-inferred accessibility semantics on the renderer side. The renderer automatically derives roles and labels from widget types and props (e.g. a button's label becomes the accessible name), so most widgets need no explicit a11y annotation. Use this for cases where auto-inference is insufficient.

Construction

Builder chain (like Border, Shadow, Font):

A11y.new()
|> A11y.role(:heading)
|> A11y.level(1)
|> A11y.label("Page title")

Bare map via cast/1 (convenience for inline props):

Button.new("btn", "Go", a11y: %{label: "Go forward"})

DSL do-block via from_opts/1:

button "btn", "Go" do
  a11y do
    label "Go forward"
  end
end

Override semantics

Most fields are optional overrides. When nil (the default), the renderer uses its auto-inferred value. When set, the SDK value wins.

Some widgets auto-manage certain fields based on their interaction state. For example, sliders set busy: true during drag so that assistive technology suppresses rapid value announcements and announces only the final value on release. Setting busy explicitly from the SDK overrides this auto-detected state.

Busy and live regions

busy maps to WAI-ARIA aria-busy. When true on a node (or a parent of a live region), assistive technology suppresses announcements until busy clears, then announces the final state.

Widgets that own continuous interactions (sliders) set this automatically. For app-managed live regions that reflect another widget's state (e.g. a text display showing a color value during canvas drag), set busy explicitly based on the interaction state:

text("hex", hex_value,
  a11y: %{live: :polite, busy: model.drag != :none}
)

Fields

• role -- overrides the inferred accesskit role (e.g. :heading, :alert)
• label -- accessible name announced by screen readers
• description -- longer description (maps to accesskit description)
• live -- live region semantics: :polite or :assertive
• hidden -- if true, node is excluded from the accessibility tree
• expanded -- expanded/collapsed state for disclosure widgets
• required -- marks a form field as required
• level -- heading level (1-6)
• busy -- suppresses AT announcements until cleared (auto-managed by sliders during drag; set explicitly for custom continuous interactions)
• invalid -- form validation failure
• modal -- dialog is modal
• read_only -- can be read but not edited
• mnemonic -- Alt+letter keyboard shortcut (single character)
• toggled -- toggled/checked state (for custom toggle widgets)
• selected -- selected state (for custom selectable widgets)
• value -- current value as a string (for custom value-displaying widgets)
• orientation -- :horizontal or :vertical (for custom oriented widgets)
• labelled_by -- ID of the widget that labels this one
• described_by -- ID of the widget that describes this one
• error_message -- ID of the widget showing the error message for this one
• disabled -- override disabled state for AT
• position_in_set -- 1-based position within a set (lists, radio groups, tabs)
• size_of_set -- total items in the set
• has_popup -- popup type: "listbox", "menu", "dialog", "tree", "grid"