Foundations: how agents use a website today|INEMA.CLUB-PRO

Lesson 3 · 20 min

Semantic HTML and a well-labeled form: the interface every agent already reads

Before any tool for agents, there is an interface they all already read: HTML. A label tied to its field, a real button, a main region, a heading, a language, and alt text. It is stable, it works for screen readers and for agents, and it does not depend on an experimental browser. In this lesson you fix the sample page until the check comes back at zero.

Start the lesson
A bike shop tool wall, each tool in its own outline with a blank label, and a monitor in the corner.

In this lesson you will

  1. 1Six fixes the agent feels right away
  2. 2Native element before ARIA
  3. 3Check with arvore.mjs until zero
  4. 4Bring the same fix to your own site

Goal: fix the labels, button, regions, and alt text until arvore.mjs finds no problems in your copy of the page.

01Six fixes, from the old page to the new one

Click each one. All of them show up in the arvore.mjs check.

Click each block in the diagram to see what it does.

Native element first: button, label, main. ARIA only where HTML doesn't have the right element.

02The fixed form

The snippet that changed from antes.html to depois.html. The form works on its own, for people and for any agent that operates the screen.

Snippet · kit/site/depois.html
<html lang="pt-BR">
…
<main>
  <h1>Agendar revisão</h1>
  <img src="bike.svg" width="60" height="40" alt="Bicicleta na bancada da oficina">
  <form id="agendar" aria-describedby="ajuda">
    <p id="ajuda">Escolha o serviço e o dia. A oficina confirma por e-mail.</p>
    <label for="nome">Seu nome</label>
    <input id="nome" name="nome" autocomplete="name" required>
    <label for="servico">Serviço</label>
    <select id="servico" name="servico" required>
      <option value="">Escolha</option>
      <option value="basica">Revisão básica</option>
      <option value="completa">Revisão completa</option>
    </select>
    <label for="data">Data</label>
    <input id="data" name="data" type="date" required>
    <button type="submit">Agendar</button>
    <output id="resultado" role="status" aria-live="polite"></output>
  </form>
</main>
Terminal · check depois.html
cd ~/projetos/formacao-webmcp-base-v72/kit
node arvore.mjs depois; echo "saída: $?"
Example from the repository
## árvore de acessibilidade · 15 linhas · 415 bytes
- main:
  - heading "Agendar revisão" [level=1]
  - img "Bicicleta na bancada da oficina"
  - paragraph: Escolha o serviço e o dia. A oficina confirma por e-mail.
  - text: Seu nome
  - textbox "Seu nome"
  - text: Serviço
  - combobox "Serviço":
    - option "Escolha" [selected]
    - option "Revisão básica"
    - option "Revisão completa"
  - text: Data
  - textbox "Data"
  - button "Agendar"
  - status
## conferência · http://127.0.0.1:PORTA/depois.html
problemas: 0
saída: 0

Now everything has a role and a name: heading, img with a description, the three fields, the button "Agendar", and the status for the response. The tree grew from 182 to 415 bytes, and the check comes back at zero.

03Your copy to fix

Copy antes.html to a folder of your own and run the check: 10 problems. Then edit the copy until it hits zero. arvore.mjs accepts the path to any .html.

Terminal · copy and check
O=${TMPDIR:-/tmp}/oficina
mkdir -p $O && cp ~/projetos/formacao-webmcp-base-v72/kit/site/antes.html $O/
cd ~/projetos/formacao-webmcp-base-v72/kit
node arvore.mjs $O/antes.html | tail -3; echo "saída: ${PIPESTATUS[0]}"
Example from the repository
  - campo #servico sem <label>
  - campo #data sem <label>
problemas: 10
saída: 1

The last three lines of the copy check, before the fix. The full list is in lesson 2.

04Practice

Reset the copy and bring the fix to your own site.

E1 · Reset the copy

20 min

Edit /tmp/oficina/antes.html with the six fixes, without looking at depois.html. Run arvore.mjs after each change and watch the list shrink.

Done when: node arvore.mjs /tmp/oficina/antes.html → problemas: 0 and saída: 0.

E2 · The form still works

5 min

Run tres-jeitos.mjs on your fixed copy: the agent has to find the three fields and the button by name and read the result.

Done when: node tres-jeitos.mjs /tmp/oficina/antes.html → line 2 · operar with controles na árvore · 0 sem nome and saída: 0.

E3 · One fix on your own site

30 min

On the page of your site from lesson 2, apply the fixes (start with the labels and the button) on a local copy or in a test environment. Publish when the check drops.

Done when: node arvore.mjs on the page (copy or published) shows problemas: lower than the number you noted in lesson 2.

05Lesson quiz

Question 1 of 4

What is the right way to give a form text field a name?skill

06In three sentences

Six fixeslabel, button, main and h1, lang, alt, and status.
Native firstThe right element before ARIA; ARIA doesn't submit a form.
Check until zeroarvore.mjs tells you what's missing, on your copy and on your site.

Going further

MDN: the label elementMDN: the status ARIA roleCourse kit: antes.html and depois.htmlinemaSEO Program: the shallow page and what the bot reads
Previous lessonNext lesson