Розмітка кнопок і полів: data-sa-*

Для розробників, у коді: атрибути data-sa-*, що називають, групують, підказують, захищають і ховають елементи — і що сканування робить без них.

Сканування читає те, що читає програма озвучування. Розмітка — для того, чого DOM не може сказати: стабільний ідентифікатор між перемальовуваннями, назва краща за плейсхолдер, інструкція, яку знає лише автор, до якого набору належить елемент, чого помічник ніколи не має торкатися.

Правило предка

Більшість атрибутів читається через closest(): поставте атрибут на свій компонент — і елемент, який бібліотека малює всередині, його успадкує. <p-button data-sa-risk="safe"> позначає внутрішній <button>. Власний атрибут елемента завжди перемагає атрибут предка. Винятки зазначено нижче.

Атрибути

Атрибут	Читається з	Що робить
`data-sa-id="email"`	елемента	Стабільна адреса, що переживає перемальовування. Має бути унікальною: другий елемент із тим самим id отримує згенерований. На `<a>` також робить посилання кандидатом в елементи, а на секції — називає місце для прокрутки.
`data-sa-label="Email"`	елемента	Назва, якою користується помічник. Без неї назва виводиться: `<label>`, `aria-label`/`aria-labelledby`, плейсхолдер, текст елемента.
`data-sa-hint="…"`	елемента, інакше найближчого предка	Інструкція для помічника, що друкується біля назви елемента в момент, коли він вирішує, куди писати. Єдине, що знаєте лише ви («це поле містить усі мови; перемикач вище обирає, яку ви редагуєте»). Пишеться раз, будь-якою мовою; відвідувачі її не бачать.
`data-sa-group="Привітання"`	предків, до двох назв	Набір, до якого належить елемент, від зовнішнього до внутрішнього (`Привітання › Мова`). Без нього: `<legend>` у `<fieldset>`, власний текст обгортального `<label>`, `aria-label`.
`data-sa-private`	елемента чи будь-якого предка	Приховано від читання і від дій, усе піддерево. Для секретів, токенів і чужих персональних даних на вашому екрані.
`data-sa-actions="off"`	елемента чи будь-якого предка	Лише читання: помічник може описати піддерево, але ніколи в ньому не діє. Деструктивна панель, довідковий блок.
`data-sa-read`	елемента чи будь-якого предка	Дозволяє описовий текст області (підказку, помилку форми; до 400 символів), а в режимі читання `marked` — значення полів усередині. Читання екрана.
`data-sa-scroll`	першого збігу на сторінці	Контейнер, який має рухати «гортай далі», коли ваш body не гортається.

Атрибути згоди — data-sa-risk, data-sa-commit — на сторінці Згода і збереження; атрибути списків — data-sa-list, -row, -field, -add, -fields, -variants, -variant, -variant-of, -variant-options — на Списках і варіантах.

Що сканування бачить без розмітки

Кожен видимий елемент форми: поля, textarea, select і ARIA-комбобокси, галочки й радіокнопки, кнопки, повзунки. Поля паролів, приховані поля і поля файлів не скануються ніколи.
Кожне посилання, позначене чи ні, з href чи без — якір лише зі слухачем кліку є звичайною кнопкою. Посилання без назви відкидається; перелічується щонайбільше 25, і коли ліміт тисне, першими йдуть посилання всередині nav, footer і aside (на ті сторінки помічник і так переходить навігацією). Два посилання з однаковою назвою несуть кожне свій шлях призначення, щоб можна було обрати потрібне; посилання з target="_blank" позначається, бо блокувальник спливних вікон ковтає такий клік мовчки.
Місця призначення для «покажи, де це»: секція з data-sa-id чи data-sa-label, id, на який вказує href="#…" на тій самій сторінці (назву дає текст посилання — зміст робить цю роботу за вас), h1–h6, названий landmark. Ліміт 25, h4–h6 відкидаються першими.
Стан ARIA: aria-expanded (згорнутий розкривач показується як «натисніть, щоб відкрити»), aria-selected / aria-checked / aria-pressed (обраний варіант набору), disabled і readonly.

Назви: чого уникати

<label>, що обгортає цілу групу, називає свої елементи текстом, який пише перед ними, а не всім, що всередині. Якщо ваш label каже «Привітання», а далі містить перемикач, поле і підказку — поле називається «Привітання» (добре), а кнопки перемикача — власним текстом.
Елемент без назви перелічується як (unnamed) і адресується за id; дайте йому aria-label — за назвою помічник відрізняє галочку рядка від його текстового поля і каже відвідувачу, який елемент змінив.
Приватний нащадок не вилучає свого тексту з назви батька. Кнопка, у тексті якої є пошта відвідувача, зберігає цю пошту в назві, навіть якщо span позначено приватним; дайте кнопці aria-label.
В Angular ставте шлях елемента (do.0, persona.role) як data-sa-id, а не formControlName, який усередині FormArray — просто індекс.

Підказки: куди їх ставити

Підказка читається з елемента, на якому стоїть. Підказку на полі рядка не прочитати, доки рядка немає, тож те саме речення має бути на кнопці, що створює рядок. Усередині оголошеного рядка списку (data-sa-row) підказка відкидається — список доходить до помічника одним рядком, і його поля не мають власного запису; ставте підказку на елементи самого списку поза рядками.

Підказки, що працюють, — це факти про цей елемент одним реченням: «натисніть це, потім натисніть період; готовий період застосовується одразу, дати з календаря — лише після “Застосувати”».