> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Accessibility

> WCAG 2.1 Level AA accessibility support in FlowX.AI, including screen reader compatibility, keyboard navigation, and configurable accessibility properties across web and mobile platforms.

## Overview

FlowX.AI provides **WCAG 2.1 Level AA** accessibility compliance for applications built with the platform. Accessibility features are configured in the **UI Designer** and automatically applied by the renderers at runtime across web (Angular, React), iOS, and Android platforms.

<CardGroup cols={3}>
  <Card title="Screen readers" icon="ear-listen">
    ARIA labels, hints, roles, and live regions automatically mapped to UI components
  </Card>

  <Card title="Keyboard navigation" icon="keyboard">
    Full keyboard support with visible focus indicators and logical tab order
  </Card>

  <Card title="Cross-platform" icon="mobile">
    Web, iOS (VoiceOver), and Android (TalkBack) support from a single configuration
  </Card>
</CardGroup>

***

## Configuring accessibility in UI Designer

Accessibility properties are configured in the **Settings** tab of the component configuration panel. Properties are saved in `platformDisplayOptions.flowxProps.accessibility` for the generic platform and apply across all renderers.

```json theme={"system"}
{
  "platformsDisplayOptions": [
    {
      "flowxProps": {
        "accessibility": {
          "label": "",
          "decorative": false,
          "altText": "",
          "role": ""
        }
      },
      "platform": "generic"
    }
  ]
}
```

### Available properties

| Property       | Description                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **label**      | Accessibility label announced by screen readers. Use when the component has no visible label or needs a different label for assistive technologies.                 |
| **decorative** | Marks the element as decorative so it is ignored by assistive technologies.                                                                                         |
| **altText**    | Short descriptive text alternative for images, announced by screen readers.                                                                                         |
| **role**       | Landmark role for navigation areas. Options: `main`, `navigation`, `search`, `form`, `header`, `footer`, `aside`, `region`, `dialogue`, `alertdialogue`, `section`. |

***

## Accessibility properties by component

Not all components expose the same accessibility properties. The SDK automatically reads certain existing properties (like label and placeholder text) and exposes them to assistive technologies. Additional properties can be configured where needed.

### Form elements

| Component            | Auto-read by SDK                        | Configurable in Designer |
| -------------------- | --------------------------------------- | ------------------------ |
| **Input**            | label, text, placeholder, helper, error | accessibility label      |
| **Single select**    | label, text, placeholder, helper, error | accessibility label      |
| **Multi select**     | label, text, placeholder, helper, error | accessibility label      |
| **Date picker**      | label, text, placeholder, helper, error | accessibility label      |
| **Text area**        | label, text, placeholder, helper, error | accessibility label      |
| **Slider**           | label, value, helper, error             | accessibility label      |
| **Checkbox**         | label, text, helper, error              | accessibility label      |
| **Radio button**     | label, text, helper, error              | accessibility label      |
| **Switch**           | label, text, helper, error              | accessibility label      |
| **Segmented button** | label, text, helper, error              | accessibility label      |

<Tip>
  Use the accessibility label when the component has no visible label or text, or when you need a different label for assistive technologies.
</Tip>

### Interactive elements

| Component       | Auto-read by SDK | Configurable in Designer        |
| --------------- | ---------------- | ------------------------------- |
| **Button**      | label            | accessibility label (icon-only) |
| **File upload** | label            | accessibility label (icon-only) |

<Tip>
  For icon-only buttons, always set an accessibility label so screen readers can announce the button's purpose.
</Tip>

### Display elements

| Component        | Auto-read by SDK | Configurable in Designer |
| ---------------- | ---------------- | ------------------------ |
| **Text**         | text             | decorative               |
| **Link**         | text             | decorative               |
| **Image**        | —                | alt text, decorative     |
| **Message**      | text             | decorative               |
| **Card**         | title, subtitle  | —                        |
| **Form**         | title            | —                        |
| **File preview** | title, subtitle  | —                        |

### Navigation areas

| Component | Auto-read by SDK | Configurable in Designer |
| --------- | ---------------- | ------------------------ |
| **Step**  | title            | accessibility label      |
| **Tab**   | title            | accessibility label      |
| **Modal** | title            | accessibility label      |

<Tip>
  Use the accessibility label for navigation areas when the area has no visible label or text, or when a different label is needed for assistive technologies.
</Tip>

***

## Landmark roles

Navigation areas are assigned landmark roles that help screen reader users understand the page structure and navigate between regions.

### Default roles

| Navigation area | Default role | Configurable |
| --------------- | ------------ | ------------ |
| **Page**        | `main`       | No           |
| **Stepper**     | `navigation` | No           |
| **Step**        | `navigation` | No           |
| **Tabbar**      | `navigation` | No           |
| **Tab**         | `navigation` | No           |
| **Modal**       | `dialogue`   | No           |
| **Zone**        | `section`    | Yes          |

### Zone roles

Zones can be configured with a landmark role to convey their purpose to assistive technologies:

* `main` — primary content area
* `section` — generic section (default)
* `nav` — navigation region
* `header` — page or section header
* `footer` — page or section footer
* `aside` — complementary content

***

## Keyboard navigation

FlowX.AI applications support full keyboard navigation with visible focus indicators. Focus is indicated by an outline around the active element.

### General patterns

| Key               | Action                                                                 |
| ----------------- | ---------------------------------------------------------------------- |
| `Tab`             | Move focus to the next interactive element                             |
| `Shift + Tab`     | Move focus to the previous interactive element                         |
| `Enter` / `Space` | Activate the focused element (button, link, toggle)                    |
| `Escape`          | Close modal or dismiss popup                                           |
| Arrow keys        | Navigate within a component (radio options, slider, select list, tabs) |

### Component-specific behavior

<AccordionGroup>
  <Accordion title="Button / File upload" icon="hand-pointer">
    * `Tab` focuses the element (skipped if disabled)
    * `Space` / `Enter` executes the action
  </Accordion>

  <Accordion title="Input / Text area" icon="input-text">
    * `Tab` focuses the element and enables typing (skipped if disabled)
    * Arrow keys move within the text
    * If the element has a clear button, `Tab` navigates to it; `Space` / `Enter` clears the value
  </Accordion>

  <Accordion title="Checkbox" icon="square-check">
    * `Tab` focuses the first option, then subsequent options
    * `Space` / `Enter` selects or deselects the focused option
    * After the last option, `Tab` moves to the next element
  </Accordion>

  <Accordion title="Radio / Segmented button" icon="circle-dot">
    * `Tab` focuses the selected option (or the first option if none selected)
    * `Down` / `Right` arrow moves focus forward and selects
    * `Up` / `Left` arrow moves focus backward and selects
    * Navigation wraps cyclically through options
  </Accordion>

  <Accordion title="Switch" icon="toggle-on">
    * `Tab` focuses the element (skipped if disabled)
    * `Space` / `Enter` toggles the value
  </Accordion>

  <Accordion title="Slider" icon="sliders">
    * `Tab` focuses the slider knob
    * `Up` / `Right` arrow increases by one step
    * `Down` / `Left` arrow decreases by one step
  </Accordion>

  <Accordion title="Select" icon="list-dropdown">
    * `Tab` focuses the element and enables typing (skipped if disabled)
    * `Up` / `Down` arrow opens the listbox
    * In the listbox: arrows navigate options, `Enter` selects and closes, `Escape` closes
    * Focus remains on the input while the listbox is open
    * If the element has a clear button, `Tab` navigates to it
  </Accordion>

  <Accordion title="Multi select" icon="list-check">
    * `Tab` focuses the element and enables typing (skipped if disabled)
    * In the listbox: arrows navigate options, `Enter` selects (without closing), `Escape` closes
    * Focus remains on the input while the listbox is open
  </Accordion>

  <Accordion title="Tabs" icon="folder">
    * `Tab` moves focus to the active tab header
    * `Left` / `Right` arrow navigates between tab headers cyclically
    * `Space` / `Enter` activates the focused tab
    * `Tab` from the active tab header moves focus to the first focusable element in the tab content
  </Accordion>

  <Accordion title="Modal" icon="window-maximize">
    * When opened, focus moves to the first focusable element inside the modal
    * Focus is trapped within the modal — `Tab` cycles through modal content
    * `Escape` closes the modal
  </Accordion>

  <Accordion title="Accordion" icon="bars-staggered">
    * `Tab` focuses the accordion trigger
    * `Enter` / `Space` expands or collapses the section
    * When expanded, `Tab` moves to the first focusable element in the content
    * When collapsed, `Tab` moves to the next accordion header cyclically
  </Accordion>
</AccordionGroup>

***

## Screen reader support

FlowX.AI renderers automatically apply ARIA attributes to components based on their type and configuration. Many attributes are auto-bound — no manual configuration needed.

### Auto-bound ARIA attributes

<AccordionGroup>
  <Accordion title="Form elements" icon="input-text">
    | Attribute                                         | Applied to                        |
    | ------------------------------------------------- | --------------------------------- |
    | `aria-describedby`                                | Helper text, error messages       |
    | `aria-required`                                   | Required fields                   |
    | `aria-invalid`                                    | Fields with validation errors     |
    | `aria-checked`                                    | Checkbox, radio, switch state     |
    | `aria-selected`                                   | Select option state               |
    | `aria-expanded`                                   | Select/multiselect dropdown state |
    | `aria-autocomplete`                               | Select search input               |
    | `aria-valuemin`, `aria-valuemax`, `aria-valuenow` | Slider                            |
  </Accordion>

  <Accordion title="Navigation and containers" icon="compass">
    | Attribute                                      | Applied to                       |
    | ---------------------------------------------- | -------------------------------- |
    | `role="tablist"`                               | Tab container, stepper           |
    | `role="tab"`, `aria-controls`, `aria-selected` | Individual tabs                  |
    | `role="tabpanel"`, `aria-describedby`          | Tab content panels               |
    | `role="dialog"`, `aria-modal`                  | Modals                           |
    | `aria-labelledby`                              | Modal (references title)         |
    | `aria-current`                                 | Active step in stepper           |
    | `aria-expanded`                                | Accordion headers                |
    | `role="radiogroup"`                            | Radio/segmented button container |
  </Accordion>

  <Accordion title="Interactive elements" icon="hand-pointer">
    | Attribute                       | Applied to                       |
    | ------------------------------- | -------------------------------- |
    | `aria-label`                    | Buttons, links (from label/text) |
    | `aria-disabled`                 | Disabled buttons and inputs      |
    | `aria-pressed`                  | Toggle buttons                   |
    | `role="button"` / `role="link"` | Buttons and links                |
    | `aria-live="polite"`            | Message components               |
  </Accordion>

  <Accordion title="Display elements" icon="image">
    | Attribute            | Applied to                               |
    | -------------------- | ---------------------------------------- |
    | `alt`                | Images (from alt text property)          |
    | `aria-hidden="true"` | Decorative images, text, links, messages |
  </Accordion>
</AccordionGroup>

***

## Platform support

### Implementation status

| Feature                       | Web (Angular/React) | iOS (VoiceOver) | Android (TalkBack) |
| ----------------------------- | :-----------------: | :-------------: | :----------------: |
| Accessibility labels          |          ✅          |        ✅        |          ✅         |
| Decorative elements           |          ✅          |        ✅        |          ✅         |
| Image alt text                |          ✅          |        ✅        |          ✅         |
| Landmark roles                |          ✅          |        —        |          —         |
| Keyboard navigation           |          ✅          |       N/A       |         N/A        |
| ARIA auto-binding             |          ✅          |       N/A       |         N/A        |
| Form elements (screen reader) |          ✅          |        ✅        |          ✅         |
| Date picker (screen reader)   |          🚧         |        🚧       |         🚧         |
| Single select (screen reader) |          🚧         |        🚧       |         🚧         |
| Multi select (screen reader)  |          🚧         |        🚧       |         🚧         |

<Info>
  🚧 indicates components with partial screen reader support that is actively being improved.
</Info>

### Version availability

| Platform                | Accessibility feature                     | Available since |
| ----------------------- | ----------------------------------------- | --------------- |
| **Web** (Angular/React) | WCAG 2.1 Level AA compliance              | FlowX.AI 5.1.1  |
| **Android**             | Accessibility properties from UI Designer | FlowX.AI 5.1.2  |
| **iOS**                 | VoiceOver support                         | FlowX.AI 5.1.3  |

***

## Client responsibilities

FlowX.AI handles accessibility for platform-rendered components automatically. However, some accessibility aspects depend on the container application and content authored by the client.

### What FlowX.AI handles

* ARIA attributes on all rendered components
* Keyboard navigation and focus management
* Screen reader announcements for form states (errors, required fields)
* Focus trapping in modals
* Landmark roles for navigation areas

### What clients are responsible for

<AccordionGroup>
  <Accordion title="HTML and page structure" icon="code">
    * Set the `lang` attribute on the `html` element for correct screen reader pronunciation
    * Provide a unique `title` for each page
    * Ensure viewport zoom is not disabled (`user-scalable=yes`)
    * Use logical heading hierarchy (`h1` → `h2` → `h3`, no skipping levels)
  </Accordion>

  <Accordion title="Content authoring" icon="pen">
    * Write descriptive button and link labels (avoid "click here", "read more")
    * Provide meaningful alt text for images
    * Mark decorative elements appropriately
    * Use plain language ([8th grade reading level](https://datayze.com/readability-analyzer.php))
    * Use left-aligned text for LTR languages, right-aligned for RTL
  </Accordion>

  <Accordion title="Color and contrast" icon="palette">
    * Normal text: minimum **4.5:1** contrast ratio
    * Large text: minimum **3:1** contrast ratio
    * Icons and UI elements: minimum **3:1** contrast ratio
    * Do not use color as the only way to convey information
    * Ensure error, warning, and success states are distinguishable without color
  </Accordion>

  <Accordion title="Media and animation" icon="film">
    * Avoid autoplaying media
    * Provide captions for video content
    * Avoid strobing or flashing animations (seizure triggers)
    * Respect `prefers-reduced-motion` for custom animations
  </Accordion>

  <Accordion title="Mobile considerations" icon="mobile">
    * Support both portrait and landscape orientation
    * Ensure touch targets are large enough for easy activation
    * Provide sufficient space between interactive elements for scrolling
    * Avoid horizontal scrolling
  </Accordion>
</AccordionGroup>

***

## Testing recommendations

<CardGroup cols={2}>
  <Card title="Keyboard testing" icon="keyboard">
    Navigate your application using only the keyboard. Verify that all interactive elements are reachable via `Tab`, that focus is visible, and that focus order matches the visual layout.
  </Card>

  <Card title="Screen reader testing" icon="ear-listen">
    Test with VoiceOver (macOS/iOS), TalkBack (Android), or NVDA/JAWS (Windows). Verify labels are announced correctly and form states are communicated.
  </Card>

  <Card title="Automated testing" icon="robot">
    Use axe-core or similar tools in your CI pipeline to catch common accessibility issues. Storybook's `addon-a11y` plugin provides real-time feedback during development.
  </Card>

  <Card title="High contrast modes" icon="circle-half-stroke">
    Activate Windows High Contrast mode or inverted colors. Verify content is still legible and interactive elements are distinguishable.
  </Card>
</CardGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Platform considerations" icon="desktop" href="../building-blocks/ui-designer/platform-considerations">
    Platform-specific configuration for web, iOS, and Android renderers
  </Card>

  <Card title="UI Designer" icon="pen-ruler" href="../building-blocks/ui-designer/ui-designer">
    Overview of the UI Designer and component configuration
  </Card>

  <Card title="Localization and i18n" icon="language" href="../building-blocks/ui-designer/localization-and-i18n">
    Language, region, and formatting configuration
  </Card>

  <Card title="WCAG 2.1 Guidelines" icon="scale-balanced" href="https://www.w3.org/WAI/WCAG21/quickref/">
    Official W3C quick reference for WCAG 2.1 success criteria
  </Card>
</CardGroup>