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 (<p>)”.

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 ariaDescriptionwhat 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 ariaDescriptione.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 ariaDescriptione.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 TextContentcomponent, remember that screen readers do not read TextContent. Therefore, the text content should also be assigned to ariaLabelto 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 ariaDescriptione.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 ariaDescriptione.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.: <a href="https://www.bank.com"> <img src="logo-bank.png" alt="XYZ Bank logo – Go to XYZ Bank homepage"> </a>

• SVG elements For SVG graphics, you can add the attribute ariaLabel and ariaDescription

More: Additional information

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 beenTileadded 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) 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

• Web Content Accessibility Guidelines (WCAG) 2.1

• WAVE Evaluation Tool

• high contrast mode - extension: https://chromewebstore.google.com/detail/wysoki-kontrast/djcfdncoelnlbldjfhinnjlhdjlikmph?hl=pl

Screen readers

• NVDA screen reader download (for Windows): https://www.nvda.pl/pobierz or

• http://trakt.org.pl/bezplatne-czytniki-ekranu/

• On Linux we have a built-in reader (toggle on/off Win+Alt+S)