# WCAG best practices - components (low-code) ## **Label (Text)** ### Best practices * **Headings and labels should be clear and non-duplicated** – the user should be able to easily recognize what a given description refers to. * **Labels not associated with a field** should be set as a paragraph, using the option **“Display as paragraph (`

`)”.**

Figure 1. The option "Display as paragraph <p>

**Association of the label with the field:** * **If the label refers to one component** – select that component from the list in the field `labelRef`.\ Example: if the label `Text7` is to be the description for the field `TextField2`, then in the WCAG label configuration `Text7` the component should be indicated `TextField2` as related.

Figure 2. Association of the GesTextField1 text field with the label

* **If the label refers to multiple components** – select the component **first or most important** in the context of the group.\ Example: if a postal code consists of two fields of type **`TextField`**, the label should be associated with the first one. **Label consistency:** * The same elements on different pages should have identical labels to maintain consistency of navigation and content from the user's perspective, including for screen reader users. ### Verification method check ariaLabel and ariaDescription (if filled in) ## **Text field (TextField)** ### Best practices **Completing the label and accessibility attributes (ariaLabel, ariaDescription):** * **Each field should have an assigned label or `ariaLabel`** (if there is no visual label). * **By default**, after adding the component `TextField`, the properties **`ariaLabel`** and **`ariaDescription`** are empty – they must be filled in manually.\ Example: instead of `GesTextField1.ariaLabelKey` use `GesTextField1.label`, which will automatically assign the label value to `ariaLabel`.

Figure 3. Example of filling in ariaLabelKey

**Best practices for describing fields:** **Field requiredness** * Message **"required field"** may be too general.\ It is recommended to use specific messages, e.g. **"The first name field is required"**. **Format validation** * If the field has format validation (e.g. PESEL, NIP), add to `ariaDescription` a description of the requirements, e.g.:\ \&#xNAN;*"11 digits required, without spaces or special characters."* **Mask** * If the field has **a mask** → describe in `ariaDescription`what characters are allowed/disallowed. * If the field has **`visibleMask`** → describe e.g.:\ \&#xNAN;*"For the postal code, enter digits only, without a hyphen."* **Maximum length** * If the field has the `maxLength` value set `ariaDescription` → add information about the limit to*"Up to 30 characters."* **Suggester** * If the field contains a **suggester** (dynamic hints) → describe its behavior, e.g.:\ \&#xNAN;*"The value may be changed automatically if an invalid number is entered."* **Validator** * When the validator error message is ambiguous, include its meaningful description in `ariaDescription` e.g.:\ \&#xNAN;*"The field cannot contain special characters."* **Formatter** * If the field contains a **formatter** → describe how it works, e.g.:\ \&#xNAN;*"The text will be automatically converted to uppercase."* **Paste restrictions** * If the field **does not allow pasting text** → this should be described in `ariaDescription`e.g.:\ \&#xNAN;*"The field does not support pasting data."* **Prefix / suffix** * If the field contains a **prefix** or **suffix** (e.g. "+48", "PLN") → add to `ariaDescription`e.g.:\ \&#xNAN;*"The field is preceded by country code +48."* ### Verification method check ariaLabel and ariaDescription (if filled in) ## **Context help (Tooltip)** ### Best practices If a tooltip has visibility conditions, make sure they match the conditions of the component to which the tooltip is assigned. ## **Multiple-choice field (Checkbox) and Checkbox section (CheckboxSection)** ### Best practices **Filling in `ariaLabel` and `ariaDescription` for the Checkbox and CheckboxSection component:** * **By default**, after adding the component **Checkbox**, the fields **`ariaLabel`** and **`ariaDescription`** are empty.\ The value **`ariaLabel`** should be filled in manually – usually it is enough to assign it the value from the field `text`. **Example:**\ Replace:\ `GesCheckbox11.ariaLabel` → `GesCheckbox11.text`\ \&#xNAN;*(resulting in: `ariaLabel = text`)*

Figure 4. Example of filling in ariaLabel

* **Attribute `ariaDescription` is not always required**, but it is worth adding in a more complex context, e.g. when the checkbox requires additional explanation. \ **Checkbox with formatted content (`TextContent`):**
* **If the checkbox is powered by formatted content from the `TextContent`component, remember that screen readers do not read `TextContent`.**\ **Therefore, the text content should also be assigned to `ariaLabel`to ensure accessibility.**

Figure 5. Example of filling in ariaLabel for a checkbox powered by content

### Verification method check ariaLabel and ariaDescription (if filled in) ## **Date field (DatePicker)** ### Best practices **Filling in `ariaLabel` and `ariaDescription` for the DatePicker component:** * **Each field should have an assigned label or `ariaLabel`** (if there is no visual label). * **By default**, after adding the component **DatePicker**, the properties **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually or assigned `ariaLabel` to the component's label key. **Example:**\ Instead of `GesDatePicker1.ariaLabelKey` → use `GesDatePicker1.label`\ \&#xNAN;*(resulting in: `ariaLabel = label`)* **Best practices for filling in `ariaDescription` for date fields:** * **If the field has date selection restrictions (`dateRange`)** → add a description to `ariaDescription`e.g.:\ \&#xNAN;*"Select a date in the range from 01.01.2020 to 31.12.2030."* * **If the field has a custom format set (`dateFormat`)** → describe it in `ariaDescription`e.g.:\ \&#xNAN;*"Date in the format: month–year (MM-YYYY)."* * **If masking is enabled (`autoMask`)** → it is worth adding information on how automatic completion works, e.g.:\ \&#xNAN;*"Enter digits only – the separator will be added automatically."* ### Verification method check ariaLabel and ariaDescription (clear information about the data format)check ariaLabel and ariaDescription (if filled in) ## **Image (Image)** ### Best practices **Alternative text (`imageAlt`) for images** * Each image should have alternative text filled in (`imageAlt` or `imageAltKey` in the form file).

Figure 6. Example imageAltKey in the form source

* **Recommendations:** * Maximum text length: **80 characters** * Maintain **consistency of style and language** of the description with the rest of the interface * **Empty `alt`** (`alt=""`) should be used **only when the image is decorative**, e.g.: * background * content divider line * decorative icon without informational function * **Informational/Decorative presentation** - In the WCAG section, you can set informational presentation (the image can be focused) or decorative presentation (it cannot be focused and has an empty imageAlt attribute). * **Image as a link**\ If the image is contained in a link, `alt` it should contain **both a graphic description and information about the function**, e.g.:\ \\ \XYZ Bank logo – Go to XYZ Bank homepage\ \ * **SVG elements**\ For SVG graphics, you can add the attribute **`ariaLabel`** and **`ariaDescription`** \ ![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg) More: [Additional information](https://cwozn.ujk.edu.pl/wp-content/uploads/2020/11/Teksty-alternatywne-do-grafik-i-fotografii-na-stronach-WWW.pdf) ### Verification method check alt value in the application ## **Select value from list field (Combobox)** ### Best practices **Filling in `ariaLabel` and `ariaDescription` for the Combobox component:** * **Every ComboBox component should have an assigned label or `ariaLabel`** (if there is no visual label). * **By default**, after adding a ComboBox, the fields **`ariaLabel`** and **`ariaDescription`** are **empty** – they should be filled in manually or assigned `ariaLabel` to the label key. **Example:**\ `GesCombobox1.ariaLabelKey` → `GesCombobox1.label`\ \&#xNAN;*(resulting in: `ariaLabel = label`)* **Alternative text for the default value "Choose":** * In the **"Other"** tab (in the ComboBox configuration) you can define **alternative text for the default value "Choose"**, which improves accessibility and clarity for screen reader users.

Figure 7. Alternative text for "Choose"

### Verification method check ariaLabel and ariaDescription ## **Radio group (RadioGroup)/ Tile group (TileGroup)** ### Best practices **Label and accessibility attributes:** * **Each component should have a label (`label`) or `ariaLabel`** (if no visual label is available). * **By default**, after adding the component (`ComboBox`, `RadioGroup`, `TileGroup`), the fields **`ariaLabel`** and **`ariaDescription`** are empty — they should be filled in manually or **assigned `ariaLabel` to the label key.** **RadioGroup:** * **Each option (`Radio`) should have a unique value (`value`)**, to avoid conflicts in form behavior and screen reader errors. * `RadioGroup` may have: * **one common tooltip** (for the whole group), * or **separate tooltips for each option**, if each requires additional description. **TileGroup:** * If an image has been`Tile`added to the tile content ( **image**), you should: * add **alternative description (`alt`)**, which clearly informs about the image content, * **set `alt=""`** in the case of decorative graphics, so they are not read by screen readers. ### Verification method check ariaLabel and ariaDescription, check alt values if they have been added to images ## **Repeatable section (RepeatableSection)** ### Best practices * **The section should have a title (`label`) or `ariaLabel`** – this ensures that the screen reader correctly identifies its content and context. * In the attribute **`ariaDescription`** you should include information about **the minimum and maximum number of possible occurrences** of the section. ### Verification method check ariaDescription ## **Slider/Step slider** ### Best practices * **By default**, after adding the component **Slider**, the properties **`ariaLabel`** and **`ariaDescription`** are **empty**.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * In the attribute **`ariaDescription`** it is worth including information about the range of values available for selection ### Verification method check ariaDescription ## **Plus Minus** ### Best practices * **By default**, after adding a Plus-Minus component **Plus-Minus**, the attributes **`ariaLabel`** and **`ariaDescription`** are **empty**.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * In the attribute **`ariaDescription`** it is worth adding information about **the minimum and maximum possible value**, so that screen reader users have clarity about the available range. ### Verification method check ariaDescription ## **Collapsible formatted content (RollableTextContent)** ### Best practices * **Make sure the component has a title (label) and `ariaLabel`.** * **`ariaLabel`** should clearly describe the component's content so that screen readers can properly convey the information about the content to the user. ### Verification method check title value ## **Product selection (ProductSelector)** ### Best practices * **By default**, after adding the component **ProductSelector**, the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * **Images** used in the component **ProductSelector** should have values filled in `alt` — in accordance with accessibility guidelines, so that screen readers can correctly describe the graphics. * **HTML content** used in the component (`ContentHTML`) should be verified using an HTML validation tool (e.g. [Markup Validation Service](https://validator.w3.org/)) in order to eliminate errors and improve accessibility. ### Verification method check alt value and HTML code ## **Internal link (PageNavigationLink) and external link (Link)** ### Best practices * **By default**, after adding a link the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * **Do not use only uppercase letters (caps lock) in link texts**, so as not to make them harder to read and recognize for users and screen readers. * **The user should be informed whether clicking the link will open a new tab or launch another application.**\ This can be achieved by: * setting the link opening property, e.g. `target="_blank"`, * adding informational text e.g. in the title (`title`) or in **`ariaDescription`.** * a clear graphic or textual indication. * In the link properties, you can set among others: * opening method (`target`, e.g. `_blank`), * text displayed on hover (attribute `title`), * the anchor name (page fragment).

Figure 8. Link component properties

### Verification method check ariaLabel and ariaDescription ## **Statements (Statements)** ### Best practices In the **Properties** the following properties overriding the texts displayed in the interface can be changed: * **Overriding property:**\ `"Collapse statements content"` * **Overriding property:**\ `"Expand statements content"` * **Content overriding property:**\ `"You have not consented to the required statements"` * **Content overriding property:**\ `"You have not made a selection for all statements, fill in the required information in the statements section"` * **Content overriding property:**\ `"I accept the selected statements"` * **Content overriding property:**\ `"I accept all statements"`

Figure 9. Statement component properties

## **Attachments (UploadFile)** ### Best practices * **By default**, after adding **UploadFile** the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * In the attributes * **By default**, after adding a link the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. or **`ariaDescription`** information about the following should be included: * **whether attachments are required**, * **how many files can be added**. ### Verification method check ariaLabel ## **Map (MapView)** ### Best practices * **By default**, after adding **MapView** the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * In the attribute **`ariaLabel`** or **`ariaDescription`** it is worth including information important to the user, e.g.: * description of the purpose of the map, * usage tips (e.g. whether a location can be selected), * other important accessibility information. ### Verification method check ariaLabel ## **Data confirmation (ConfirmationSection)** ### Best practices * **By default**, after adding **confirmation section** the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. * In the attribute **`ariaLabel`** or **`ariaDescription`** it is worth including additional information helpful in the context of data confirmation, e.g.: * instructions for confirmation, * information about the need to check the data before submitting. ## **QR code generator (QRCodeGenerator)** ### Best practices **By default**, after adding **QRCodeGenerator** the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. ### Verification method check ariaLabel ## **QR code scanner (QRCodeScanner)** ### Best practices **By default**, after adding **QRCodeScanner** the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. ### Verification method check ariaLabel ## **AZTEC code scanner (AztecCodeScanner)** ### Best practices **By default**, after adding **AztecCodeScanner** the fields **`ariaLabel`** and **`ariaDescription`** the fields are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. ### Verification method check ariaLabel ## Useful pages * requirements guide: [**https://wcag20.widzialni.org/index.php**](https://wcag20.widzialni.org/index.php) * [**Web Content Accessibility Guidelines (WCAG) 2.1**](https://www.w3.org/Translations/WCAG21-pl/) * [WAVE Evaluation Tool](https://chromewebstore.google.com/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh) * high contrast mode - extension: ## Screen readers * NVDA screen reader download (for Windows): \ or * * On Linux we have a built-in reader (toggle on/off Win+Alt+S) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/wcag/dobre-praktyki-wcag-komponenty-low-code.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.