Markup examples

Enable element selection and use the attribute reference with these examples. Replace example keys with stable keys from your website and documentation.

Scenarios to Start With

Online store: the user asks "how do I pay for the order?", the payment article is found and the button with data-ai-context-id="checkout.payment.submit" is shown.
SaaS form: the user does not understand where to paste a token, and the field's data-ai-context-id from documentation helps highlight the required input.
Account area: the user asks about notification settings, first a menu item on the current page is shown, then the next step after navigation is explained.

In all scenarios, article text stays human: "click the payment button", "enter the token", "open notifications". The context key lives in the span attribute and does not get in the way of reading the instruction.

Example: product card

<main data-ai-area="content" data-ai-section="catalog">
  <article
    data-ai-label="Product: Alpha Sneakers"
    data-ai-kind="product-card"
    data-ai-context-id="catalog.product-card"
    data-ai-kb-query="how to choose product and size"
    data-ai-entity-type="product"
    data-ai-entity-id="sku-alpha-42"
  >
    <h2>Alpha Sneakers</h2>
    <p>Sizes 39-44</p>
    <button
      data-ai-label="Add Alpha Sneakers to cart"
      data-ai-kind="primary-action"
      data-ai-action="cart.add"
      data-ai-context-id="cart.add"
      data-ai-kb-query="how to add a product to cart"
      data-ai-entity-type="product"
      data-ai-entity-id="sku-alpha-42"
    >
      Add to cart
    </button>
  </article>
</main>

Example: tariffs and payment

<section data-ai-area="content" data-ai-section="pricing">
  <div
    data-ai-label="Pro plan"
    data-ai-kind="plan-card"
    data-ai-context-id="pricing.plan.pro"
    data-ai-kb-query="what is included in Pro plan"
    data-ai-entity-type="plan"
    data-ai-entity-id="pro"
  >
    <h3>Pro</h3>
    <button
      data-ai-label="Choose Pro plan"
      data-ai-kind="primary-action"
      data-ai-action="plan.choose"
      data-ai-context-id="pricing.plan.choose"
      data-ai-kb-query="how to choose and pay for a plan"
      data-ai-entity-type="plan"
      data-ai-entity-id="pro"
    >
      Choose
    </button>
  </div>
</section>

Example: form

<form data-ai-area="form" data-ai-section="checkout-delivery">
  <label for="delivery-city">Delivery city</label>
  <input
    id="delivery-city"
    name="city"
    data-ai-label="Delivery city"
    data-ai-kind="form-field"
    data-ai-context-id="checkout.delivery.city"
    data-ai-kb-query="how to enter delivery city"
  />
  <button
    data-ai-label="Continue checkout"
    data-ai-kind="primary-action"
    data-ai-action="checkout.continue"
    data-ai-context-id="checkout.continue"
    data-ai-kb-query="how to continue checkout"
  >
    Continue
  </button>
</form>

Custom select controls

A native HTML select works without extra option markup. For a button with a popover list, place data-ai-context-id on the button and provide role="combobox", aria-expanded, aria-controls referencing the panel ID, and data-ai-value containing the current value. ArrowDown must open a panel with role="listbox". Options need role="option", data-ai-value, and aria-selected; use aria-disabled="true" for unavailable options.

After selection, update the button value or the option's aria-selected. The widget checks this change before reporting success. It first matches value/data-ai-value, then the label; selection is rejected when several options have the same label. If a long explanation accompanies the option name, provide the short name separately in its data-ai-label.

Prepare a Stable Target

An important element usually needs:

data-ai-context-id — a stable key for documentation links and actions;
data-ai-label — a human-readable name;
data-ai-kb-query — a search phrase for cases where the knowledge base has no exact key.

Example:

<button
  data-ai-context-id="checkout.payment.submit"
  data-ai-label="Pay for order"
  data-ai-kind="primary-action"
  data-ai-action="checkout.payment.submit"
  data-ai-kb-query="how to pay for an order"
>
  Pay
</button>

data-ai-section only describes a section and does not make a container selectable by itself. The full attribute list, length limits, and rules for repeated elements are in Website element markup.

data-ai-action describes the meaning of a button; it does not authorize execution. For clicking, filling, and other changes, the site must keep the same authentication, restrictions, and confirmations used for normal visitor actions.

Describe the Path to a Hidden Target

In documentation, name the final target, for example: “Open notification settings.” If the target is hidden in a menu or panel, the agent needs a way to find the element that reveals it.

Standard aria-controls, popovertarget, commandfor, and <details>/<summary> relationships are detected automatically. For a custom component, declare the revealed context root explicitly:

<button
  data-ai-context-id="account.menu.toggle"
  data-ai-label="Open account menu"
  data-ai-reveals-context-id="account.notifications"
  data-ai-reveal-action="click"
>
  Menu
</button>

<a
  data-ai-context-id="account.notifications.open"
  data-ai-label="Notification settings"
  href="/account/notifications"
>
  Notifications
</a>

data-ai-reveal-action accepts click, hover, or focus; click is used when the attribute is omitted. One trigger can reveal several roots separated by spaces. A nested interface may use up to 8 reveal operations.

For click, focus, fill, clear, select, and toggle, the widget can perform the discovered reveal steps and then address the final target. For highlight and scroll_to, hidden panels are not opened automatically: the visitor is shown the available trigger and the path continues after it is opened.