Примеры разметки

Подключите выбор элементов и используйте справочник атрибутов вместе с этими примерами. Ключи примеров замените устойчивыми ключами своего сайта и документации.

С каких сценариев начать

• Интернет-магазин: пользователь спрашивает "как оплатить заказ?", находится статья про оплату и показывается кнопка с data-ai-context-id="checkout.payment.submit".
• SaaS-форма: пользователь не понимает, куда вставить токен, а data-ai-context-id поля из документации помогает подсветить нужное поле ввода.
• Личный кабинет: пользователь спрашивает про настройку уведомлений, сначала показывается пункт меню на текущей странице, а затем объясняется, что делать после перехода.

Во всех сценариях текст статьи остается человеческим: "нажмите кнопку оплаты", "введите токен", "откройте уведомления". Контекстный ключ находится в атрибуте span и не мешает читать инструкцию.

Пример: карточка товара

<main data-ai-area="content" data-ai-section="catalog">
  <article
    data-ai-label="Товар: Кроссовки Alpha"
    data-ai-kind="product-card"
    data-ai-context-id="catalog.product-card"
    data-ai-kb-query="как выбрать товар и размер"
    data-ai-entity-type="product"
    data-ai-entity-id="sku-alpha-42"
  >
    <h2>Кроссовки Alpha</h2>
    <p>Размеры 39-44</p>
    <button
      data-ai-label="Добавить Кроссовки Alpha в корзину"
      data-ai-kind="primary-action"
      data-ai-action="cart.add"
      data-ai-context-id="cart.add"
      data-ai-kb-query="как добавить товар в корзину"
      data-ai-entity-type="product"
      data-ai-entity-id="sku-alpha-42"
    >
      В корзину
    </button>
  </article>
</main>

Пример: тарифы и оплата

<section data-ai-area="content" data-ai-section="pricing">
  <div
    data-ai-label="Тариф Pro"
    data-ai-kind="plan-card"
    data-ai-context-id="pricing.plan.pro"
    data-ai-kb-query="чем отличается тариф Pro"
    data-ai-entity-type="plan"
    data-ai-entity-id="pro"
  >
    <h3>Pro</h3>
    <button
      data-ai-label="Выбрать тариф Pro"
      data-ai-kind="primary-action"
      data-ai-action="plan.choose"
      data-ai-context-id="pricing.plan.choose"
      data-ai-kb-query="как выбрать и оплатить тариф"
      data-ai-entity-type="plan"
      data-ai-entity-id="pro"
    >
      Выбрать
    </button>
  </div>
</section>

Пример: форма

<form data-ai-area="form" data-ai-section="checkout-delivery">
  <label for="delivery-city">Город доставки</label>
  <input
    id="delivery-city"
    name="city"
    data-ai-label="Город доставки"
    data-ai-kind="form-field"
    data-ai-context-id="checkout.delivery.city"
    data-ai-kb-query="как указать город доставки"
  />
  <button
    data-ai-label="Продолжить оформление заказа"
    data-ai-kind="primary-action"
    data-ai-action="checkout.continue"
    data-ai-context-id="checkout.continue"
    data-ai-kb-query="как продолжить оформление заказа"
  >
    Продолжить
  </button>
</form>

Нестандартные списки выбора

Обычный HTML select работает без дополнительной разметки вариантов. Для списка из кнопки и всплывающей панели поставьте data-ai-context-id на кнопку, задайте ей role="combobox", aria-expanded, aria-controls с ID панели и data-ai-value с текущим значением. Клавиша ArrowDown должна открывать панель с role="listbox". Вариантам нужны role="option", data-ai-value и aria-selected; для недоступного варианта используйте aria-disabled="true".

После выбора обновите значение кнопки или aria-selected варианта. Виджет проверяет это изменение, прежде чем сообщить об успехе. Значение ищется сначала по value/data-ai-value, затем по подписи; при одинаковых подписях нескольких вариантов выбор не выполняется. Если рядом с названием есть длинное пояснение, укажите короткое название отдельно в data-ai-label варианта.

Подготовьте стабильную цель

Для важного элемента обычно достаточно:

• data-ai-context-id — стабильный ключ для связи с документацией и действиями;
• data-ai-label — понятное человеку название;
• data-ai-kb-query — поисковая фраза на случай, если точного ключа нет в базе знаний.

Пример:

<button
  data-ai-context-id="checkout.payment.submit"
  data-ai-label="Оплатить заказ"
  data-ai-kind="primary-action"
  data-ai-action="checkout.payment.submit"
  data-ai-kb-query="как оплатить заказ"
>
  Оплатить
</button>

data-ai-section сам по себе только описывает раздел и не делает контейнер выбираемым. Полный список атрибутов, ограничения длины и правила для повторяющихся элементов приведены в статье «Разметка элементов сайта».

data-ai-action описывает смысл кнопки, но не разрешает выполнение. Для клика, заполнения и других изменений сайт всё равно должен сохранять авторизацию, ограничения и подтверждения, которые действуют при обычной работе пользователя.

Опишите путь к скрытой цели

В документации указывайте конечную цель, например: «Откройте настройки уведомлений». Если цель скрыта в меню или панели, агенту нужен способ найти элемент, который её раскрывает.

Стандартные связи aria-controls, popovertarget, commandfor и <details>/<summary> определяются автоматически. Для собственного компонента явно укажите корень раскрываемого контекста:

<button
  data-ai-context-id="account.menu.toggle"
  data-ai-label="Открыть меню аккаунта"
  data-ai-reveals-context-id="account.notifications"
  data-ai-reveal-action="click"
>
  Меню
</button>

<a
  data-ai-context-id="account.notifications.open"
  data-ai-label="Настройки уведомлений"
  href="/account/notifications"
>
  Уведомления
</a>

data-ai-reveal-action принимает click, hover или focus; без атрибута используется click. Один переключатель может раскрывать несколько корней — перечислите их через пробел. Во вложенном интерфейсе может быть до 8 операций раскрытия.

Для click, focus, fill, clear, select и toggle виджет может последовательно выполнить найденное раскрытие и затем действие с конечной целью. Для highlight и scroll_to скрытые панели автоматически не открываются: посетителю показывается доступный переключатель, после его открытия путь продолжается.