> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/wcag/dobre-praktyki-wcag-komponenty-low-code.md). # 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 the description refers to. * **Labels not associated with a field** should be set as a paragraph, using the option **“Display as paragraph (`

`)”.**

Figure 1. Option "Display as paragraph <p>

**Label association with field:** * **If the label applies to one component** – select that component from the list in the field `labelRef`.\ Example: if the label `Text7` is to be a description for the field `TextField2`, then in the WCAG label configuration `Text7` the component should be indicated `TextField2` as associated.

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

* **If the label applies to multiple components** – select the component **first or most important** in the context of the group.\ Example: if the 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 users of screen readers. ### Verification method check ariaLabel and ariaDescription (if filled in) ## **Text field (TextField)** ### Best practices **Filling in 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 field descriptions:** **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` the description of requirements, e.g.:\ \&#xNAN;*"11 digits required, no spaces or special characters."* **Mask** * If the field has **mask** → describe in `ariaDescription`, e.g. which characters are allowed/not allowed. * If the field has **`visibleMask`** → describe e.g.:\ \&#xNAN;*"For the postal code, enter only digits, without a hyphen."* **Maximum length** * If the field has set value `maxLength` → add to `ariaDescription` information about the limit, e.g.:\ \&#xNAN;*"Up to 30 characters."* **Suggester** * If the field contains **suggester** (dynamic suggestions) → describe its behavior, e.g.:\ \&#xNAN;*"The value may change automatically when an invalid number is entered."* **Validator** * When the validator error message is ambiguous, include in `ariaDescription` a meaningful description, e.g.:\ \&#xNAN;*"The field cannot contain special characters."* **Formatter** * If the field contains **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 **prefix** or **suffix** (e.g. "+48", "PLN") → add to `ariaDescription`, e.g.:\ \&#xNAN;*"Field preceded by country code +48."* ### Verification method check ariaLabel and ariaDescription (if filled in) ## **Context help (Tooltip)** ### Best practices If the 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**, 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 it in a more complex context, e.g. when the checkbox requires additional explanation. \ **Checkbox with formatted content (`TextContent`):**
* **If the checkbox is fed with formatted content from the `TextContent`, remember that screen readers do not read `TextContent`.**\ **Therefore, the text content should also be assigned to `ariaLabel`, to ensure its accessibility.**

Figure 5. Example of filling in ariaLabel for a checkbox fed with 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`** 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 12/31/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 the mask is enabled (`autoMask`)** → it is worth adding information on how automatic filling works, e.g.:\ \&#xNAN;*“Enter digits only – the separator will be added automatically.”* ### Verification method check ariaLabel and ariaDescription (clear information about data format)check ariaLabel and ariaDescription (if filled in) ## **Image (Image)** ### Best practices **Alternative text (`imageAlt`) for images** * Every image should have alternative text filled in (`imageAlt` or `imageAltKey` in the form file).

Figure 6. Sample 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 attribute `alt`** (`alt=""`) should be used **only when the image serves a decorative function**, e.g.: * background * content divider line * decorative icon without an 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 the 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 on the application ## **Value selection from list (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 the ComboBox, the fields **`ariaLabel`** and **`ariaDescription`** are **empty** – they must 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 "Select":** * In the **"Other"** (in the ComboBox configuration) you can define **alternative text for the default value "Select"**, which improves accessibility and comprehensibility for users of screen readers.

Figure 7. Alternative text for "Select"

### 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 a visual label is not available). * **By default**, after adding the component (`ComboBox`, `RadioGroup`, `TileGroup`), the fields **`ariaLabel`** and **`ariaDescription`** are empty — they must 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 shared tooltip** (for the whole group), * or **separate tooltips for each option**, if each requires additional description. **TileGroup:** * If in the tile content (`Tile`) **an image has been added**, you should: * add **alternative description (`alt`)**, which clearly informs about the image content, * **set `alt=""`** for decorative graphics so that they are not read by screen readers. ### Verification method check ariaLabel and ariaDescription, check alt values if they were 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`** 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 that can be selected ### Verification method check ariaDescription ## **Plus Minus** ### Best practices * **By default**, after adding a component of type **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 content of the component so that screen readers can correctly convey the content information to the user. ### Verification method check title value ## **Product selection (ProductSelector)** ### Best practices * **By default**, after adding the component **ProductSelector**, fields **`ariaLabel`** and **`ariaDescription`** 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 filled-in values `alt` — in line with accessibility principles, so that screen readers can correctly describe the graphic. * **HTML content** used in the component (`ContentHTML`) should be verified using an HTML validation tool (e.g. [Markup Validation Service](https://validator.w3.org/)) to eliminate errors and improve accessibility. ### Verification method check alt values and HTML code ## **Internal link (PageNavigationLink) and external link (Link)** ### Best practices * **By default**, after adding the link the fields **`ariaLabel`** and **`ariaDescription`** 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 informative text e.g. in the title (`title`) or in the **`ariaDescription`.** * a clear graphic or textual designation. * In the link properties you can set, among others: * opening mode (`target`, e.g. `_blank`), * text displayed when hovering the cursor over it (attribute `title`), * anchor name (page fragment).

Figure 8. Link component properties

### Verification method check ariaLabel and ariaDescription ## **Statements** ### Best practices In the **Properties** the following overriding properties for texts displayed in the interface can be changed: * **Overriding property:**\ `"Collapse statement content"` * **Overriding property:**\ `"Expand statement 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 declarations"` * **Content overriding property:**\ `"I accept all declarations"`

Illustration 9. Properties of the declarations component

## **Attachments (UploadFile)** ### Best practices * **By default**, after adding **UploadFile** fields **`ariaLabel`** and **`ariaDescription`** 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 the link the fields **`ariaLabel`** and **`ariaDescription`** are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. or **`ariaDescription`** should include information regarding: * **requirement for attachments**, * **number of files that can be added**. ### Verification method ariaLabel check ## **Map (MapView)** ### Best practices * **By default**, after adding **MapView** fields **`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 **`ariaLabel`** or **`ariaDescription`** it is worth including information important to the user, e.g.: * description of the map's purpose, * usage instructions (e.g. whether a location can be selected), * other relevant accessibility information. ### Verification method ariaLabel check ## **Data confirmation (ConfirmationSection)** ### Best practices * **By default**, after adding **confirmation section** fields **`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 **`ariaLabel`** or **`ariaDescription`** it is worth including additional information helpful in the context of confirming data, e.g.: * instructions for confirmation, * information about the need to check the data before approving it. ## **QR code generator (QRCodeGenerator)** ### Best practices **By default**, after adding **QRCodeGenerator** fields **`ariaLabel`** and **`ariaDescription`** are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. ### Verification method ariaLabel check ## **QR code scanner (QRCodeScanner)** ### Best practices **By default**, after adding **QRCodeScanner** fields **`ariaLabel`** and **`ariaDescription`** are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. ### Verification method ariaLabel check ## **AZTEC code scanner (AztecCodeScanner)** ### Best practices **By default**, after adding **AztecCodeScanner** fields **`ariaLabel`** and **`ariaDescription`** are empty.\ They should be filled in manually — especially **`ariaLabel`**, if the component does not have a visible label. ### Verification method ariaLabel check ## 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 available for download (for Windows): \ or * [http://trakt.org.pl/free-screen-readers/](http://trakt.org.pl/bezplatne-czytniki-ekranu/) * On Linux, we have a built-in screen reader (toggle on/off Win+Alt+S) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/interfejs-uzytkownika/wcag/dobre-praktyki-wcag-komponenty-low-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.