About
About
Accessibility
Pages that work with a keyboard, a screen reader or voice control: what the built-ins do, what the compiler checks, and what no tool can check for you.
This essay is about the accessibility a WebFluent page has before you do anything, the part the compiler checks on every build, and the part that stays yours: building pages people can use with a keyboard, a screen reader, voice control, zoom or reduced motion.
Most inaccessible pages were not made that way on purpose. A <div> with a click handler looks like a button and is not one; a field whose label is a placeholder looks labelled until the reader types. Each is a small mistake that a checklist would catch, and checklists are read once.
WebFluent moves as much of the checklist as it can out of your hands. The built-ins render the markup assistive technology expects, the router and forms manage focus, and the compiler reports what it can see as a finding with a code, on every build. That leaves the work no tool can do (meaning, wording, order) and frees your attention for it.
What the built-ins do
You get these behaviours without asking, as long as you use the built-in elements rather than rebuilding them:
- Semantic elements. A
Buttonis a<button>, aLinkan<a>,Heading(…).h2an<h2>.HeaderandFooterare landmarks, and so is aSectiongiven anaria-label. ATableis a<table>whose head cells are<th scope="col">, aListis a<ul>or<ol>, and the page's content is a<main>. - A skip link. It is first in the tab order, visible when focused, and jumps past the navigation to the content.
- Route changes that behave like page loads. Focus moves to the new page's heading, the scroll returns to the top, and the new title is announced.
- Labelled fields.
label:is a real<label for>.hint:and the error are tied to the control witharia-describedby. An error setsaria-invalidand is announced when it appears (Forms). - Forms that point at the problem. A submit that fails moves focus to the first field with an error and announces it.
- Dialogs that hold focus.
ModalandDialogare real<dialog>elements: the rest of the page is inert, Escape closes them, and focus returns to what opened them. - Focus held where you ask. Any other element holds focus with
trapFocus: open— a find bar, a panel. Focus moves in, Tab and Shift+Tab go round inside it, a click outside brings focus back, and whenopenturns false, focus returns to where it was. - Menus with the keys people expect. The arrow keys move and skip a disabled item, Home and End jump to the ends, Enter and Space choose, ArrowRight opens a submenu and ArrowLeft leaves it, and Escape closes the innermost menu and returns focus. A check item is a
menuitemcheckboxwitharia-checked; an item's shortcut is itsaria-keyshortcuts. - Splitters you can move without a mouse. A
Splitteris aseparatorwith its size asaria-valuenow. It takes focus, the arrow keys move it, Home and End go to its ends, and Enter resets it. - Announcements. A
Toast, and atoast(…)from a handler, is spoken politely. To announce anything else, callannounce("{n} results")from a handler, orannounce(text, .assertive)for what cannot wait. - The active link. The link to the current page carries
aria-current="page". - Reduced motion. A reader who asked for it gets no animation at all, and a carousel does not play on its own (Motion).
- Visible focus. Every interactive built-in shows a focus ring for the keyboard (
:focus-visible), but not on every click.
What the compiler checks
The compiler checks every page for the mistakes it can see in the markup, and reports each as a warning on every build and in the editor. Each code has a full entry, with a fix, in Diagnostics, and wf explain CODE prints it in your terminal.
| Code | What it checks |
|---|---|
|
|
Every |
|
|
Every |
|
|
Every |
|
|
Buttons, links and headings have text |
|
|
Every |
|
|
A video has captions and controls; audio has a transcript |
|
|
A table has a header row |
|
|
No heading level is skipped, and each page has exactly one |
|
|
The theme's colour pairs meet WCAG AA contrast: text on the background and surfaces, and a tone's label ( |
|
|
A |
|
|
A control's |
|
|
No literal |
|
|
Every |
|
|
Every |
For example, this button's aria-label does not contain the word it shows, so a voice-control user who says "click Save" may not reach it:
page Editor(path: "/", title: "Editor", description: "Write a note.") {
Heading("Editor").h1
Button("Save", aria-label: "Submit the form")
}
The fix is to start the aria-label with the visible words: aria-label: "Save the note".
What the compiler cannot check
The compiler can see markup; it cannot see meaning. These are still yours:
- Alt text that says what the picture shows, in its context. "Photo" passes
A01and helps nobody. - Link text that says where it goes. Twelve "Read more" links pass
A06. - An order that makes sense. The reading order is the source order. Do not rearrange it visually with
order:or absolute positioning. - Colour that is not the only signal. An error in red also says so in words; a chart has labels.
- The contrast of your own styles.
A13checks the theme's tokens, not a colour written directly in astyle { }block. - Custom controls. A
Cardmade clickable withon clickis not a button to a keyboard until it has a role, a place in the tab order and key handlers. - Time limits. A
Toastdisappears. Anything the reader must act on belongs in anAlertthat stays.
Each of these is a judgement about what a page means to the person using it, which is why no build can make it. What a tool can do is make the judgement cheaper: Make a page work with a keyboard and a screen reader names every control so it matches what a sighted reader sees, turns a card into a control a keyboard can reach, and then checks the page the way its readers use it — with only a keyboard, a screen reader, 200% zoom and reduced motion — ending with a checklist. Because wf test finds a control by the name a reader sees, as assistive technology does, a test that clicks through a page is also a test that someone can operate it.