Accessibility

Accessibility starts with the component structure and continues through your content, composition, styling, and testing. Honest UI provides a foundation; it does not make an assembled application conformant by itself.

What Honest UI provides

Honest UI prefers native HTML for familiar controls. Complex interactions such as dialogs, menus, popovers, comboboxes, and tabs use primitives that provide roles, state, focus management, and documented keyboard behavior.

Depending on the component, that foundation can include:

• Native roles and states.
• Keyboard operation and focus management.
• Visible focus styles.
• Connections among form controls, labels, descriptions, and errors.
• Disabled and invalid states.
• Reduced-motion handling for documented animated components.

Read the component's Accessibility section because responsibilities differ. An Input needs a useful label, an icon-only Button needs an accessible name, and a chart needs an equivalent way to understand important values.

Give controls useful names

Every form control needs an accessible name. Use a persistent visible label for fields that people must identify, understand, or revisit. Field connects a label, description, validation message, and control with consistent spacing.

Write labels for the information or decision:

• Email address, not Email when the expected value could be unclear.
• Project visibility, not Visibility when several settings use that word.
• Receive product updates, not Updates for a preference switch.

Descriptions should explain a constraint or consequence rather than repeat the label. Place essential requirements before submission instead of teaching them only through an error.

Preserve documented keyboard behavior

Test each interaction without a mouse. Do not apply one keyboard pattern to every control: native buttons, checkboxes, tabs, menus, sliders, and comboboxes have different expected keys.

Check that:

• Tab and Shift+Tab move through interactive elements in a logical order.
• Buttons and links respond to their native activation keys.
• Composite controls support the arrow-key behavior documented by their primitive.
• Escape closes dismissible dialogs and popups when supported.
• Focus moves into modal content when it opens and returns to a logical place when it closes.
• Every pointer-only action has an equivalent keyboard path.

Keep focus visible

Do not remove focus styles. Focus must remain visible against the component and adjacent colors, including in dark themes and forced-colors modes.

Check that sticky headers, dialogs, and other overlays do not hide the focused element. Avoid moving focus unless the interaction requires it and the destination is predictable.

Explain unavailable and loading actions

Use a disabled state only when the control cannot be used. If the reason is not obvious, explain it nearby. A disabled control cannot normally reveal its own tooltip or receive keyboard focus, so required instructions must remain available elsewhere.

For an action in progress, preserve the layout, communicate the busy state, and prevent accidental duplicate work when necessary. Do not announce success until the requested work has completed.

Write errors that support recovery

Connect validation messages to their controls and identify the specific correction:

• Enter an email address in the format name@example.com.
• Choose at least one role.
• Enter 12 or more characters.

Avoid Invalid, Required, and Something went wrong when the cause or recovery step is known. Preserve entered values after an error whenever it is safe to do so.

Do not rely on one sensory cue

Do not communicate meaning through color, position, shape, sound, motion, hover, or drag alone. Pair important states with visible text and expose the same meaning to assistive technology.

Pointer targets should be at least 24 by 24 CSS pixels unless a WCAG 2.2 spacing or other defined exception applies. Prefer larger targets, including 44 by 44 CSS pixels, for important controls and touch-heavy interfaces.

Test the complete task

Automated checks catch only some problems. For each changed task, verify:

1. Semantic structure and accessible names.
2. Complete keyboard operation and visible focus.
3. The task with a supported screen-reader and browser combination.
4. Text enlargement and reflow at 200% and 400% zoom where applicable.
5. Light, dark, and forced-colors presentations.
6. Reduced-motion behavior.
7. Labels, errors, loading, empty, disabled, and success states.
8. Touch target size and operation without precise pointer movement.

Document which environments you tested. Do not claim WCAG conformance from a component primitive or automated scan alone.