> 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/budowanie-aplikacji/interfejs-uzytkownika/wcag/dobre-praktyki-wcag-ogolne-low-code.md).

# Dobre praktyki WCAG - ogólne (low-code)

{% hint style="info" %}
WCAG - zakładka Audyt

[WCAG - Audyt](/budowanie-aplikacji/interfejs-uzytkownika/formularze/tworzenie-formularza/zakladka-audyt-naruszenia-wcag/wcag-audyt.md)
{% endhint %}

{% hint style="info" %}
WCAG - Strona zawiera formularz

[WCAG - strona jako formularz](/budowanie-aplikacji/interfejs-uzytkownika/formularze/tworzenie-formularza/zakladka-audyt-naruszenia-wcag/wcag-strona-jako-formularz.md)
{% endhint %}

## **Zakładka Audyt**

W przypadku modyfikacji istniejących aplikacji należy zwrócić uwagę na zakładkę **Audyt**. (Niestety, na ten moment sprawdzany jest tylko xml - głównie etykiety. Nie są tam wychwytywane błędy w TextContent, dlatego sprawdzając lub modyfikując wniosek pod kątem WCAG, **nie należy** opierać się wyłącznie na zakładce **Audyt**).

<figure><img src="/files/J1EWW7ROmI211Bjc3uCt" alt=""><figcaption><p><em><strong>Ilustracja 1.</strong> Przykładowa lista naruszeń WCAG</em></p></figcaption></figure>

<figure><img src="/files/leqifpZ21ZQh7jfbwFxg" alt=""><figcaption><p><em><strong>Ilustracja 2.</strong> Przykład wniosek bez uwag w zakładce <strong>Audyt</strong></em></p></figcaption></figure>

### **HTML - Treści (TextContents) i komponenty niestandardowe (CustomComponents)**

Przy tworzeniu i modyfikowaniu TextContent'ów warto **sprawdzić HTML przy użyciu walidatora:** [Markup Validation Service (HTML) – https://validator.w3.org/](https://validator.w3.org/) ([dodatkowe informacje](http://wcag.stowarzyszenie.edu.pl/mod/page/view.php?id=149) ![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg))

<figure><img src="/files/pJTrVQ7cib0ScdCMQvLS" alt="" width="563"><figcaption><p><em><strong>Ilustracja 3.</strong> Przykład użycia walidatora markup</em></p></figcaption></figure>

Należy zwrócić uwagę na linki (target), obrazki (alt), listy i nagłówki (z zachowaniem właściwej hierarchi).

### **AriaLabel i ariaDescription**

* **ariaLabel** – Wartość właściwości etykiety komponentu.
* **ariaDescription** – Wartość właściwości opisu komponentu. Jest to tekst słownie opisujący komponent, odczytywany przez czytniki ekranowe. Najczęściej stanowi rozszerzony opis pola (np. zawiera maskę pola, treść tooltipa nieczytanego przez czytnik ekranowy, walidatora).
* **Domyślnie ariaLabel są puste, należy je dodać zgodnie z przykładem.** (patrz **Pole tekstowe (TextField)** i **Pole wielokrotnego wyboru (Checkbox)** w tabeli poniżej)<br>
* **ariaLabel należy dodać , jeżeli komponent nie ma powiązania z etykietą.**
* Atrybut **ariaLabel** powinien być stosowany w interaktywnych elementach strony.

<figure><img src="/files/mY5vhnxf7fw7aUsHOSve" alt=""><figcaption><p><em><strong>Ilustracja 4.</strong> Dodatkowe zasady dotyczące użycia ARIA</em></p></figcaption></figure>

Dodatkowe informacje: [Using ARIA](https://www.w3.org/TR/using-aria/#notes2)![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg)

### **Weryfikacja ariaLabel i ariaDescription**

Sposoby weryfikacji **ariaLabel** i **ariaDescription**:

* przy użyciu **czytnika ekranu** – można sprawdzić, jak atrybuty są odczytywane użytkownikowi. (Linki do przykładowych czytników znajdują się na końcu dokumentacji)
* przy użyciu narzędzi developerskich – **DevTools** – atrybuty **ariaLabel** i **ariaDescription** można sprawdzić bezpośrednio w strukturze DOM, w zakładce **Elements**.
* przy użyciu wtyczki do przeglądarki np. [WAVE Evaluation Tool](https://chromewebstore.google.com/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh?hl=en-US\&utm_source=ext_sidebar)

<figure><img src="/files/YgT1KacTIBdkhvGK5LLM" alt="" width="563"><figcaption><p><em><strong>Ilustracja 5.</strong> Podgląd atrybutów <strong><code>ariaLabel</code></strong></em> <em>i <strong><code>ariaDescription</code></strong> w <strong>DevTools</strong></em></p></figcaption></figure>

### **Nagłówki**

* **\<h1>**\
  Eximee Designer domyślnie będzie miało ustawione **\<h1>** jako tytuł wniosku. Mimo że, używanie kilku nagłówków **\<h1>** jest dozwolone przez standardy HTML (o ile nie są zagnieżdżone), nie jest to uważane za dobrą praktykę. Zasadniczo na stronie powinien znajdować się jeden nagłówek **\<h1>**, który opisuje główną treść strony. W przypadku dodawania nagłówków na wniosku najlepiej zacząć od poziomu **\<h2>**.
* **Nagłówki sekcji -** każda dodana sekcja na wniosku może posiadać własny nagłówek. **Sekcja w sekcji** będzie miała kolejny poziom nagłówka (aria-level) – dotyczy to również sekcji powtarzalnej.

<figure><img src="/files/VuOxUGXXlrMB95NOtGEu" alt=""><figcaption><p><em><strong>Ilustracja 6.</strong> Definiowanie nagłówków w Eximee Designer</em></p></figcaption></figure>

* Dodatkowe informacje: [\<h1>–\<h6>: The HTML Section Heading elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements) ![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg)

### **Reużywalność komponentów złożonych (dynamiczne nazwy)**

Jeśli dany **komponent złożony** jest używany **wielokrotnie** – np. w szablonie wniosku lub jako element innego komponentu złożonego - można dla jego pól ustalić **różne wartości ariaLabel i ariaDescription**, zależne od kontekstu użycia.

Przykładowo: pole "**Imię**" może mieć inny opis w przypadku wnioskodawcy, a inny dla współwnioskodawcy.

Aby to osiągnąć, należy w **artefakcie zawierającym re-użyty komponent złożony** :

* Przejść do zakładki **Tłumaczenia**.
* Dla każdego pola osobno dodać odpowiednie klucze tłumaczeń **ariaLabel** i/lub **ariaDescription**.\
  **Uwaga: Klucz musi być pełną ścieżką do pola.**

Przykład:\
Pole **Ulica** (GesTextField1), znajdujące się w komponencie złożonym, zostało użyte dwa razy w wniosku – z nadanymi id **GesComplexComponent2** i **GesComplexComponent3**.\
Dla każdego wystąpienia można przypisać inne **ariaLabel**, np.:

* **GesComplexComponent2.GesTextField1.ariaLabel** : "**Ulica** **zamieszkania**"
* **GesComplexComponent3.GesTextField1.ariaLabel** : "**Ulica korespondencji**"

<figure><img src="/files/RLOT5eIS4J4aGsatRmaa" alt=""><figcaption><p><em><strong>Ilustracja 7.</strong> Definiowanie <strong>ariaLabel</strong> dla komponentów złożonych</em></p></figcaption></figure>

#### Sposób weryfikacji

Po wejściu na pole czytnik powinien przeczytać właściwe ariaLabel, czyli "ulica zamieszkania" i "ulica korespondencji"

### **Strona jako formularz**

Jeśli parametr jest zaznaczony, strona wniosku ma nadaną rolę **`form`**. Domyślnie ten parametr jest włączony.

<figure><img src="/files/V3CRTRxvBhxTHFemx1dg" alt=""><figcaption><p><em><strong>Ilustracja 8.</strong> Funkcjonalność "Strona jako formularz"</em></p></figcaption></figure>

### **Wymagalność/ opcjonalność pól**

**Pola wymagane do wypełnienia powinny być oznaczone** – należy dodać informację o ich wymagalności w warstwie wizualnej np. poprzez dopisek "\*pole wymagane" lub symbol "\*". Powinny także **odróżniać się wizualnie** od pól niewymaganych, aby użytkownik mógł łatwo je zidentyfikować.

### **Tytuł strony**

**Tytuł strony powinien jasno** **identyfikować bieżącą lokalizację,** bez konieczności czytania zawartości strony.

### **Tekst jako obrazek**

**Nie należy zamieszczać tekstu w formie obrazu** (wyjątek stanowi logo). ([dodatkowe informacje](https://wcag20.widzialni.org/grafiki-tekstowe,new,mg,165,172.html,73) ![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg))

### **Zmiana rozmiaru tekstu (niestandardowy styl)**

* Po zwiększeniu rozmiaru tekstu o **200%** nie może dojść do utraty czytelności ani funkcjonalności interfejsu. ([dodatkowe informacje](https://wcag20.widzialni.org/zmiana-rozmiaru-tekstu,new,mg,165,172.html,72) ![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg))
* Tekst powinien spełniać minimalne wymagania dotyczące odstępów, aby zapewnić jego czytelność:
  * wysokość linii: co najmniej 1,5-krotność rozmiaru czcionki
  * odstęp między akapitami: co najmniej 2-krotność rozmiaru czcionki
  * odstęp między literami: co najmniej 0,12-krotność rozmiaru czcionki
  * odstęp między wyrazami: co najmniej 0,16-krotność rozmiaru czcionki
* Wszystkie elementy **musza pozostać czytelne i widoczne** po zastosowaniu powyższych parametrów.

### **Znaki specjalne w treści**

Jeśli w treści używane są znaki specjalne, np. strzałki pełniące funkcję dekoracyjną, należy je ukryć przed czytnikami ekranu za pomocą atrybutu **aria-hidden**.\
Przykład: *\<span aria-hidden="true">→\</span> Przejdź dalej*

### **Responsywność**

**Treść musi być prezentowana bez utraty informacji ani funkcjonalności na ekranach o minimalnej szerokości 320 px i wysokości 256 px.**\
Dodatkowo **nie może występować przewijanie w poziomie**, z wyjątkiem dwuwymiarowych treści, takich jak: tabele, złożone obrazy, mapy oraz wykresy.

### **Wysoki kontrast**

Wszystkie elementy powinny być **widoczne i czytelne po włączeniu trybu wysokiego kontrastu.**\
Rozszerzenie do Chrome: <https://chromewebstore.google.com/detail/wysoki-kontrast/djcfdncoelnlbldjfhinnjlhdjlikmph?hl=pl>

### **Nawigacja**

Elementy nawigacji na podstronach powinny znajdować się w tym samym miejscu, zachowując spójny układ na wszystkich stronach.

### **CSS - Ukrycie tekstu z wizualnego przekazu + ignorowanie tekstu przez czytniki**

<figure><img src="/files/9MTALP8asCRVhLDepG2U" alt="" width="563"><figcaption><p><em><strong>Ilustracja 9.</strong> Przykład ukrycia elementów układu przy użyciu CSS</em></p></figcaption></figure>

Dodatkowe informacje: [CSS - Invisible Content Just for Screen Reader Users](https://webaim.org/techniques/css/invisiblecontent/)![(informacje)](https://wiki.consdata.pl/s/-rvpvnr/8703/51k4y0/_/images/icons/emoticons/information.svg)

**display:none or visibility: hidden → ukrycie tekstu przed wszystkimi**

### **Podsumowanie**

Formularz powinien zawierać stronę z podsumowaniem danych – tzw. stronę potwierdzenia – umożliwiającą użytkownikowi ich weryfikację, cofnięcie się do wcześniejszych kroków w celu dokonania poprawek oraz ostateczne potwierdzenie poprawności danych.


---

# 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/budowanie-aplikacji/interfejs-uzytkownika/wcag/dobre-praktyki-wcag-ogolne-low-code.md?ask=<question>&goal=<endgoal>
```

`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.