# Web accessibility

Web accessibility is the practice of building pages that work for people who do not interact with them the way the designer imagined — with a screen reader, a keyboard alone, magnification, voice control, or a browser set to reduce motion. Nearly all of it is achieved by using the correct HTML element and not overriding what it already does.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/technology/accessibility/

## Name, role, state — the three questions

Assistive technology asks three things of every interactive element. If all three have answers, the element works. If any is missing, it is either unusable or ambiguous, and ambiguity is worse than absence because the user cannot tell which.

**Name** — What is this called? A button's text, a field's `<label>`, an image's `alt`. A `<div>` with an icon inside has no name at all.
**Role** — What kind of control is it? Button, link, checkbox, heading, table. A native element carries its role for free; a styled `<div>` carries none.
**State** — What is it doing now? Pressed, expanded, checked, disabled, invalid, current. State that exists only as a CSS class is invisible to everything except sighted users.

The shortest route to all three is to use the element that already has them. `<button>` is focusable, activates on Enter and Space, announces as a button and can be disabled. A click handler bolted to a `<div>` reproduces none of that, and reproducing it by hand takes more code than using the button did.

## The failures that account for most of the damage

| Defect | Who it stops | Fix |
|---|---|---|
| Images with no `alt` | Screen-reader users; anyone on a failed image load | Describe the content, or an empty `alt` if genuinely decorative |
| Fields with no label | Screen-reader and voice-control users | `<label for>` — grey hint text inside the field is not a label, and it vanishes on typing |
| Focus outline removed | Every keyboard user, including sighted ones | Style the focus ring; never remove it without a visible replacement |
| Colour as the only signal | Colour-blind readers, anyone in bright light | Add a shape, an icon or text alongside the colour |
| Low contrast | Low-vision readers and most people on a phone outdoors | Meet the contrast ratio; verify computed colours, not source |
| Headings used for size | Screen-reader users navigating by heading | Use the level that reflects structure; style separately |
| Keyboard traps | Every keyboard user | Ensure focus can always leave; test with Tab and Shift+Tab only |

> **Careful** A focus style can be defeated at a distance. A token defined in one stylesheet layer and re-defined in a later one silently wins, and the source looks correct. Verify with the browser's computed style on a focused element, not by reading CSS.

## Does Connect use accessibility practices, and how are they checked?

**Used, as a build property rather than an audit finding, and stated without a certification claim.** Connect holds no accessibility certification and no page here should imply one. What exists is structural: every visible element in the application carries a `data-ui` name, the front end is plain ES modules with a large ordered stylesheet set, and both facts make automated checking against real rendered screens possible rather than aspirational.

The `data-ui` naming matters more than it sounds. A checker that can name the element it is complaining about produces a report an engineer can act on, and a regression in one control can be attributed rather than described as "the settings page".

This documentation inherits the same discipline for a different reason. The pages carry no JavaScript, so the accessibility tree is whatever the served HTML says it is — no widget is constructed after load, no focus is moved by a script, and there is no state that exists only in memory. A page that is correct in the source is correct in the browser.

## The overlap with machine readers

A page built this way is also the easiest kind of page for a program to use, and the reason is not a coincidence. A screen reader and a browser-driving agent both consume the accessibility tree rather than the pixels: they need an element's name, its role and its state, and they need the reading order to match the visual order.

- A named button can be found and pressed by an agent; an unnamed icon cannot be described, let alone chosen between.
- A real `<table>` with headers is parsed; a grid of positioned `<div>` elements is a picture of a table.
- A landmark structure — header, nav, main, footer — lets both a reader and a program skip to the content.
- State expressed in the markup survives being read by something that never sees the CSS.

The practical consequence is that accessibility work does not compete with machine readability for budget. It is the same work, and a team that has done one has mostly done the other.

## Questions

### Is an automated checker enough?

No. Automated tools reliably catch contrast, missing names, invalid ARIA and structural errors, which is a large share of defects but a small share of the experience. Whether a control is *usable* by keyboard, whether an error message is announced when it appears, whether focus lands somewhere sensible after an action — those need a person operating the page.

### Does Connect hold an accessibility certification?

No, and no page in this corpus claims one. Certification is a formal assessment against a standard by a body qualified to make it; describing engineering practice as a certification would be a fabrication. What can be said is what the code does, which is what this page says.

### Should I add ARIA to make an element accessible?

Usually not as a first move. Native elements carry name, role and state already, and ARIA added on top of a correct element is at best redundant. ARIA earns its place for patterns HTML has no element for — see the [WAI-ARIA page](/docs/technology/aria/) for where the line falls.

## Related

- [WAI-ARIA](https://connectbyjbrh.com/docs/technology/aria/)
- [Page experience and Core Web Vitals](https://connectbyjbrh.com/docs/technology/core-web-vitals/)
- [Content Security Policy](https://connectbyjbrh.com/docs/technology/csp/)
- [A focus ring that was defined, valid-looking and computed to nothing](https://connectbyjbrh.com/research/focus-rings-that-computed-to-none/)
- [Defects that are invisible in the source and obvious in a browser](https://connectbyjbrh.com/research/invisible-ui-defects/)

## What this page is based on

- W3C Web Content Accessibility Guidelines 2.2, https://www.w3.org/TR/WCAG22/
- W3C ARIA Authoring Practices Guide, https://www.w3.org/WAI/ARIA/apg/
- Connect architecture source pack — docs-source/sources/GENERAL.md §4, every visible element carries a `data-ui` name; 56 ordered stylesheet layers
- Connect capability registry (docs-source/facts.py FORBIDDEN_CLAIMS) — no certification may be claimed