HTML: build a meaningful, accessible page

Learn in your browser · Chapter 01 of 06

HTML says what each part of a page is. Write the smallest valid page, then meet the checker.

HTML is text with tags. A tag such as <h1> says what its content is: a main heading, a list, a link. It does not say how the content looks: that is CSS. Browsers turn HTML into the page you see and into an accessibility tree, which holds each item's name, role and state for screen readers.

You need a computer, a plain text editor and a browser. Make a folder called event-page, save each file there as plain text (UTF-8) with the ending shown, and double-click a page to open it in your browser. Only what you paste into the checker goes online. Save the smallest valid page as minimal.html.

<!doctype html>
<html lang="en-GB">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Marigold Lane Seed Swap</title>
</head>
<body>
  <h1>Marigold Lane Seed Swap</h1>
</body>
</html>

Scroll sideways to see every column.

Check it. Open validator.w3.org/nu, choose text input beside "Check by", paste in the page and press Check. The W3C Nu Html Checker reads HTML as a browser does and lists mistakes. For minimal.html it says Document checking completed. No errors or warnings to show. Here is a broken page, broken.html, and the reply (positions, extracts and guidance links left out).

<html>
<head>
<meta charset="utf-8">
</head>
<body>
<div class="top">Marigold Lane Seed Swap</div>
<h4>Programme</h4>
<img src="packets.svg">
<label for="nm">Name</label>
<input id="name" type="text">
<p>To join in, <a href="#name">click here</a>.</p>
</body>
</html>

Warning: Consider adding a lang attribute to the html start tag to declare the language of this document.
Error: Start tag seen without seeing a doctype first. Expected <!DOCTYPE html>.
Error: Element head is missing a required instance of child element title.
Error: An img element must have an alt attribute, except under certain conditions. For details, consult guidance on providing text alternatives for images.
Error: The value of the for attribute of the label element must be the ID of a non-hidden form control.
Warning: This document has heading elements but none of them has a computed heading level of 1.

Error means a rule is broken and Warning is advice. Work from the top, because one early mistake can cause later messages. The checker said nothing about the div standing in for a heading or the words "click here": both are valid, neither is meaningful. Its own page says it is a checker, not a pass or fail certificate, and that its checks change over time.

Learn in your browser · Chapter 02 of 06

Type in a small, real page for an invented community event, then see why each part is there.

The event, place and words are invented. Save this as event-page/index.html, typing it rather than pasting so you meet every line.

<!doctype html>
<html lang="en-GB">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Marigold Lane Seed Swap: Saturday 17 April 2027</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header>
    <p>Marigold Lane Seed Swap</p>
    <nav aria-label="On this page">
      <ul>
        <li><a href="#about">About the day</a></li>
        <li><a href="#programme">Programme</a></li>
        <li><a href="#signup">Sign up</a></li>
      </ul>
    </nav>
  </header>

  <main>
    <h1>Marigold Lane Seed Swap</h1>
    <p>Bring spare seeds and cuttings. Take home something new.</p>
    <svg viewBox="0 0 320 160" role="img" aria-labelledby="art-title">
      <title id="art-title">A seed packet and a small sprouting plant on a table</title>
      <rect width="320" height="160" fill="#efe6cf"/>
      <rect x="60" y="112" width="200" height="10" fill="#1b1a17"/>
      <rect x="100" y="60" width="44" height="52" fill="#fbf7ec" stroke="#1b1a17" stroke-width="3"/>
      <path d="M212 112V84M212 96Q196 94 192 80Q208 80 212 96M212 90Q228 88 232 74Q216 74 212 90" fill="none" stroke="#1b1a17" stroke-width="3"/>
    </svg>

    <section id="about">
      <h2>About the day</h2>
      <p><time datetime="2027-04-17">Saturday 17 April 2027</time>, 10:00 to 15:00, at Marigold Lane Village Hall (an invented place). Free.</p>
      <h3>What to bring</h3>
      <ul>
        <li>Seeds in labelled envelopes</li>
        <li>Cuttings wrapped in damp paper</li>
        <li>A bag for what you take home</li>
      </ul>
    </section>

    <section id="programme">
      <h2>Programme</h2>
      <table>
        <caption>Programme for Saturday 17 April 2027</caption>
        <thead>
          <tr><th scope="col">Time</th><th scope="col">Activity</th></tr>
        </thead>
        <tbody>
          <tr><th scope="row">10:00</th><td>Doors open and swap tables set up</td></tr>
          <tr><th scope="row">11:30</th><td>Swap tables open</td></tr>
          <tr><th scope="row">13:30</th><td>Children's seed-planting workshop</td></tr>
        </tbody>
      </table>
    </section>

    <section id="signup">
      <h2>Sign up</h2>
      <p>This form is a demonstration. Nothing is behind it, so it sends nothing anywhere. Type invented details only.</p>
      <form>
        <p>
          <label for="name">Your name</label>
          <input id="name" name="name" type="text">
        </p>
        <p>
          <label for="email">Email address</label>
          <input id="email" name="email" type="email" aria-describedby="email-hint">
        </p>
        <p id="email-hint">An invented address is fine. Nothing is stored.</p>
        <fieldset>
          <legend>Will you bring seeds to swap?</legend>
          <p><label><input type="radio" name="bring" value="yes"> Yes</label></p>
          <p><label><input type="radio" name="bring" value="no"> No, I am coming to browse</label></p>
        </fieldset>
        <p><button type="button">Join the list (demonstration only)</button></p>
      </form>
    </section>
  </main>

  <footer>
    <p>An invented event and place, made for learning.</p>
  </footer>
</body>
</html>

Save this beside it as style.css. It only makes the page readable.

body {
  margin: 0;
  font-family: system-ui, sans-serif;
  font-size: 1.125rem;
  line-height: 1.6;
  color: #1b1a17;
  background: #fbf7ec;
}
header, main, footer {
  max-width: 42rem;
  margin: 0 auto;
  padding: 0.5rem 1rem;
}
a { color: #6b4f00; }
:focus-visible {
  outline: 3px solid #1b1a17;
  outline-offset: 3px;
}
nav ul { display: flex; flex-wrap: wrap; gap: 0.5rem; padding: 0; list-style: none; }
nav a { display: inline-block; padding: 0.5rem 0.75rem; }
table { width: 100%; border-collapse: collapse; }
th, td { padding: 0.5rem; border: 1px solid #1b1a17; text-align: left; }
label { display: block; font-weight: 600; }
input[type="text"], input[type="email"], button { min-height: 2.75rem; font: inherit; }
input[type="radio"] { width: 1.5rem; height: 1.5rem; margin-right: 0.5rem; vertical-align: middle; }

To use your own picture later, replace the svg element with <img src="my-picture.jpg" alt="Describe the picture here">.

Scroll sideways to see every column.

This is part of the page's accessibility tree, as a test tool read it from Edge, with lines left out (dots). To see your own, right-click an element in Edge, choose Inspect, then open the Accessibility tab beside Styles.

- banner:
  - navigation "On this page":
    ...
        - link "About the day":
    ...
- main:
  - heading "Marigold Lane Seed Swap" [level=1]
  - img "A seed packet and a small sprouting plant on a table"
  - heading "About the day" [level=2]
    ...
  - heading "Programme" [level=2]
  - table "Programme for Saturday 17 April 2027":
    ...
  - heading "Sign up" [level=2]
    ...
    - textbox "Your name"
    ...
  - group "Will you bring seeds to swap?":
    ...
    - button "Join the list (demonstration only)"
- contentinfo:

Every item has a name and a role. People using screen readers can jump between headings and landmarks instead of hearing the whole page, and the W3C notes that keyboard users and reader modes benefit too. MDN says search engines weigh headings and links above text in plain divs, which promises nothing about your ranking. So choose elements by meaning: MDN says to use the generic div only when nothing more meaningful fits. MDN also says not to pick a heading level for its size: nest levels without skipping any, then size them in CSS.

Learn in your browser · Chapter 03 of 06

Vague links, useless alt text and fake tables are three easy faults to make.

Links. A link's text should say where it goes, even read alone, because people using screen readers can pull up a list of a page's links. "See the programme" works. "Click here" does not.

Images. alt is text that stands in for the image. The HTML standard's test: replacing every image with its alt text should not change the page's meaning. Choose by purpose, as the W3C's decision tree does.

• Informative: a short replacement for what it says, such as alt="Queue at the swap table".
• Decorative: an empty alt="", so software skips it.
• Functional (inside a link or button): what it does, such as alt="Print the programme", not "printer icon".
• Text in an image: the same words. For a chart, keep the alt short and put the full data in the page.

Never write "image of" or a file name (MDN). The checker reports a missing alt, but not a useless one. An svg has no alt: the event page names its drawing with role="img" and a <title>, and Edge listed it as an image with that name.

Tables hold data in rows and columns, never layout. Mark header cells th, say which way they point with scope="col" or scope="row", and add a caption as the title. Screen readers can then read each cell with its headers. A grid of divs offers none of that.

Learn in your browser · Chapter 04 of 06

A form is where people give you something, so every control must say what it is for.

Labels. Give every field a visible label joined to it: the for attribute must match the field's id. Screen readers then announce the name, and clicking the label, a bigger target, puts the cursor in the field (W3C, MDN). Wrapping the field in its label, as the radio buttons do, also works, but the W3C says for and id is generally better supported. Put related options in a fieldset with a legend. Tie help text, like the note under the email field, to its field with aria-describedby. Do not use placeholder as a label: MDN advises avoiding it, because it disappears when someone types.

Links go places, buttons do things. Use a href to move to another page or place, and button to act on the current page. A plain div made to look like a button cannot be reached with Tab and lacks a real button's keyboard behaviour (MDN). Give a button type="button" unless it should submit a form.

This form passes the checker and still fails people. Save minimal.html as form.html and replace its <h1> line with it.

<form>
<div>Your name</div>
<input type="text" name="name">
<label>Email address</label>
<input type="email" name="email">
<input type="text" name="group" placeholder="People in your group">
<div>Bringing seeds?</div>
<input type="radio" name="bring"> Yes
<input type="radio" name="bring"> No
</form>

Learn in your browser · Chapter 05 of 06

Tools find some problems. Your own hands and eyes find others.

Keyboard test. Put the mouse aside. Tab moves to the next link or control, Shift and Tab moves back, Enter follows a link or presses a button, Space presses a button or ticks a box, and the arrow keys move within a group of radio buttons. Look for every control reachable, an order that follows the reading order, and a focus outline you can always see. In the test run the event page's Tab order was:

Tab 1  link "About the day"
Tab 2  link "Programme"
Tab 3  link "Sign up"
Tab 4  textbox "Your name"
Tab 5  textbox "Email address"
Tab 6  radio "Yes"
Tab 7  button "Join the list (demonstration only)"
Tab 8  focus leaves the page content

Every stop had a solid 3-pixel outline. The two radio buttons are one stop, and the down arrow moved the choice from Yes to No. Pressing Enter in a text field, or pressing the button, did nothing: the HTML standard says a form with no submit button and more than one text field does not submit on Enter.

Colour contrast. WCAG asks for a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text (18 point, or 14 point bold). The ratio is (L1 + 0.05) / (L2 + 0.05), where L1 and L2 are the relative luminance, from 0 for black to 1 for white, of the lighter and darker colour. Tools do the sums, and the W3C suggests looking for one in its evaluation tools list. On the event page the text colour on cream is 16.26:1 and the link colour on cream 7.15:1. Grey #999999 on white is 2.85:1 and fails, #777777 on white is 4.48:1 and just fails, and #767676 on white is 4.54:1 and just passes.

Text size. Sizes set in rem, as in this CSS, follow the reader's browser settings (MDN). WCAG asks that text can be resized to 200% without losing content or function, so zoom your browser (Ctrl or Cmd and +) to 200% and look for lost text and sideways scrolling. Its reflow criterion asks for no sideways scrolling at 320 CSS pixels wide, which the page met in the test run. Doubling the root text size at that width as well, a stricter test than WCAG sets, made the two text fields grow until the page was 456 pixels wide.

Target size and the limits of tools. WCAG 2.2 asks for pointer targets of at least 24 by 24 CSS pixels, with exceptions such as links inside a sentence. Measured here: menu links 45 pixels tall, text fields 50, the button 44, radio buttons 24 by 24. The W3C says evaluation tools cannot determine accessibility, they can only assist, and GOV.UK asks for automated and manual testing together because automated testing alone misses some issues.

Learn in your browser · Chapter 06 of 06

Put a name to what you have been checking, then use it on HTML you did not write.

WCAG (Web Content Accessibility Guidelines) is the W3C's standard for accessible web content. WCAG 2.2 is a W3C Recommendation, published on 5 October 2023 and updated on 12 December 2024. Its testable success criteria sit under four principles (perceivable, operable, understandable, robust) at levels A, AA and AAA, and it adds nine criteria to WCAG 2.1. It also removed 4.1.1 Parsing, so valid HTML is good practice rather than a criterion of its own. This course exercises these criteria.

Scroll sideways to see every column.

Reviewing an assistant's HTML. An assistant can write a page in seconds. What it writes can be plausible and valid, and still div soup, unlabelled or vague. Treat it as a draft from a stranger: run the checker, read the tree, press Tab, and ask. Is there a main and one h1, with headings in order? Does every image have a meaningful alt, every field a label? Are buttons real buttons? Can everything be done from the keyboard? Never paste passwords, keys or other people's data into a prompt.

This example was written for this workbook to show the kind of output an assistant can give. It is not the output of any particular product. Save minimal.html as review.html and add this line just before </head>.

<style>a:focus, .btn:focus { outline: none; }</style>

Then replace the <h1> line with these lines.

<div class="page">
<div class="header"><h3>Community Garden Open Day</h3></div>
<img src="garden.jpg" alt="image">
<h1 class="small">What's on</h1>
<div class="row"><b>10:00</b> Planting <b>12:00</b> Tea and cake</div>
<span style="color:#999999">Free entry, all welcome</span>
<a href="/map">Click here</a> for the map.
<input type="text" placeholder="Your email">
<div class="btn" onclick="signUp()">Sign up</div>
</div>