This is an automated email from the ASF dual-hosted git repository.

dashorst pushed a commit to branch user-guide-accessibility-1839
in repository https://gitbox.apache.org/repos/asf/wicket.git

commit ab1d424c47eac164970693e18702c5b065ce8ca5
Author: Martijn Dashorst <[email protected]>
AuthorDate: Sun Nov 8 00:17:41 2026 +0100

    Add an accessibility chapter to the user guide
    
    The user guide did not tell developers how to build an accessible Wicket
    application, and its own examples fell short: no <html> in the guide
    carried a lang attribute, so a page built from "Wicket says Hello world!"
    or "Wicket as page layout manager" failed WCAG 3.1.1 from the first line.
    
    The new chapter 25, Accessibility, sits after the testing chapters and
    before the best practices, where forms, repeaters, i18n, AJAX and
    WicketTester have all been introduced. It covers:
    
    - what Wicket takes care of and what stays with the application;
    - a table of all 55 WCAG 2.2 success criteria of level A and AA, with the
      Wicket mechanism, the application's part and a link to the code;
    - an accessible base page: a title per page, lang from the session
      locale, a skip link, landmarks and replacement error pages;
    - form errors: wicket:for and wicket:label, a message next to the field,
      and a behavior that adds aria-invalid and aria-describedby;
    - focus and announcements after AJAX updates: focusComponent, live
      regions that stay in the page, busy indicators and ModalDialog roles;
    - keyboard-operable AJAX controls on <button> and <a>, not on <div>;
    - data tables: caption, row headers, aria-sort and a stable markup id
      for sort links so that focus survives an AJAX sort;
    - validating an application: WicketTester/TagTester assertions, axe-core
      with Playwright, HTML validation and the manual checks.
    
    Where Wicket has no support today the chapter shows the workaround with
    the current API; the gaps are input for the component audit in GitHub
    issue #1838.
    
    The full-page examples elsewhere in the guide get lang="en", and the
    layout chapter's base page gets a title label, lang, a skip link and
    landmark elements, so the new chapter can refer to it. The reference to
    the internals chapter moves from 26 to 27.
    
    GitHub issue #1839
    
    Generated-by: Claude Code (Claude Opus 5.5)
---
 .../src/main/asciidoc/accessibility.adoc           |   6 +
 .../asciidoc/accessibility/accessibility_1.adoc    |  29 ++
 .../asciidoc/accessibility/accessibility_2.adoc    | 341 +++++++++++++++++++++
 .../asciidoc/accessibility/accessibility_3.adoc    | 119 +++++++
 .../asciidoc/accessibility/accessibility_4.adoc    | 154 ++++++++++
 .../asciidoc/accessibility/accessibility_5.adoc    | 150 +++++++++
 .../asciidoc/accessibility/accessibility_6.adoc    |  53 ++++
 .../asciidoc/accessibility/accessibility_7.adoc    | 112 +++++++
 .../asciidoc/accessibility/accessibility_8.adoc    | 162 ++++++++++
 .../asciidoc/accessibility/accessibility_9.adoc    |   2 +
 .../asciidoc/bestpractices/bestpractices_1.adoc    |   4 +-
 .../src/main/asciidoc/forms2/forms2_10.adoc        |   2 +-
 .../src/main/asciidoc/forms2/forms2_5.adoc         |   2 +-
 .../src/main/asciidoc/forms2/forms2_8.adoc         |   2 +-
 .../src/main/asciidoc/helloWorld/helloWorld_3.adoc |   2 +-
 .../main/asciidoc/keepControl/keepControl_5.adoc   |   6 +-
 .../main/asciidoc/keepControl/keepControl_7.adoc   |   2 +-
 .../main/asciidoc/keepControl/keepControl_8.adoc   |   4 +-
 .../src/main/asciidoc/layout/layout_3.adoc         |  37 ++-
 .../src/main/asciidoc/layout/layout_4.adoc         |  23 +-
 .../main/asciidoc/modelsforms/modelsforms_4.adoc   |   2 +-
 wicket-user-guide/src/main/asciidoc/repeaters.adoc |   2 +-
 .../src/main/asciidoc/resources/resources_8.adoc   |   4 +-
 wicket-user-guide/src/main/asciidoc/single.adoc    |  40 +++
 .../src/main/asciidoc/testing/testing_3.adoc       |   2 +-
 .../src/main/asciidoc/urls/urls_3.adoc             |   4 +-
 .../versioningCaching/versioningCaching_2.adoc     |   2 +-
 27 files changed, 1231 insertions(+), 37 deletions(-)

diff --git a/wicket-user-guide/src/main/asciidoc/accessibility.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility.adoc
new file mode 100644
index 0000000000..19925df7b7
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility.adoc
@@ -0,0 +1,6 @@
+
+An accessible web application can be used by people who do not see the screen, 
who do not use a mouse, who zoom the page to four times its size or who need 
more time to read and type. The reference for what that takes is the Web 
Content Accessibility Guidelines (WCAG), published by the W3C. In many 
countries WCAG level AA is also a legal requirement, for public sector websites 
and increasingly for commercial ones.
+
+Wicket does not make an application accessible by itself, and it does not 
stand in the way either: the HTML of our pages is ours to write, and most of 
what Wicket adds to it can be adjusted. In this chapter we will see what Wicket 
contributes to an accessible application, which WCAG 2.2 success criteria of 
level A and AA depend on what we write, and how to implement the criteria that 
need code: an accessible base page, form errors, focus and announcements after 
AJAX updates, keyboard-ope [...]
+
+The examples build on the base page of 
<<_wicket_as_page_layout_manager,chapter 5>>, on the forms of chapters 
<<_wicket_models_and_forms,11>> and <<_wicket_forms_in_detail,12>>, on the AJAX 
support of <<_working_with_ajax,chapter 19>> and on _WicketTester_ from 
<<_test_driven_development_with_wicket,chapter 23>>.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_1.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_1.adoc
new file mode 100644
index 0000000000..016c0e8777
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_1.adoc
@@ -0,0 +1,29 @@
+
+WCAG states its requirements as success criteria, and a success criterion is 
met or failed by a page, not by a library. No framework can therefore make an 
application conform to WCAG. What a framework can do is render markup that does 
not fail a criterion by itself, and give the application the means to meet the 
criteria that depend on its content.
+
+=== What Wicket takes care of
+
+Wicket renders the markup we write in our HTML files and changes only the tags 
that are bound to a component. For accessibility this is good news: the 
elements that convey structure, such as headings, lists, landmarks, tables and 
the labels of form fields, are written by us and reach the browser as we wrote 
them. In addition, several components and resolvers render markup that helps 
assistive technology:
+
+* a _<label>_ tag with attribute _wicket:for_ gets a _for_ attribute that 
points to the right form component, whatever markup id Wicket generates for it 
(see <<_accessible_form_errors,paragraph 25.4>>);
+* the label of a form component (_setLabel_ or _<wicket:label>_) is used in 
its validation messages, so an error names the field it is about;
+* text fields render the HTML5 attributes _required_ and _pattern_ when the 
component is required or has a _PatternValidator_;
+* _RadioChoice_ and _CheckBoxMultipleChoice_ render a _<label>_ for each 
option;
+* the headers of a _DataTable_ are _<th>_ cells with a _scope_ attribute, and 
the table renders a _<caption>_ when we give it one (see 
<<_accessible_data_tables,paragraph 25.7>>);
+* after an AJAX update Wicket gives focus back to the element that had it, 
when the update replaced that element with one with the same markup id (see 
<<_focus_and_announcements_after_ajax_updates,paragraph 25.5>>);
+* _ModalDialog_ can trap the focus inside the dialog and return it to where it 
was when the dialog closes;
+* _AutoCompleteTextField_ renders the ARIA role and states of a combobox.
+
+=== What stays with the application
+
+Most success criteria are about content and design, and those are ours: the 
contrast between text and background, the alternative text of images, the order 
and wording of headings, the text of labels, links and messages, captions for 
video, and a layout that still works when the text is enlarged. Wicket has no 
say in any of these. The same goes for ARIA attributes on our own markup: 
Wicket leaves them alone, and it adds very few of its own.
+
+=== Server-side components and AJAX
+
+Because Wicket renders HTML on the server, a Wicket page without AJAX behaves 
like any other server-rendered page: each request loads a complete page, 
browsers and screen readers announce its title, and focus starts at the top. 
Most accessibility problems of single-page applications do not arise.
+
+AJAX brings them back. When an AJAX response replaces a part of the page, the 
browser does not announce anything, and if the element that had the focus 
disappears, the focus is lost. Wicket replaces a component by replacing its 
whole element in the DOM, which has two consequences we will meet again in this 
chapter: an ARIA live region must not be the element of the component we 
update, and focus can only be restored to an element whose markup id survives 
the update.
+
+=== Where Wicket falls short today
+
+A few things an accessible page needs are not supported by Wicket at the 
moment: Wicket does not render a _lang_ attribute, form components do not get 
_aria-invalid_ when they fail validation, and the default error pages use an 
HTML 4.01 doctype without a _lang_ attribute. For each of them this chapter 
shows a workaround with the current API. An audit of all components against 
WCAG 2.2 AA is under way in https://github.com/apache/wicket/issues/1838[GitHub 
issue #1838], and its results ma [...]
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_2.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_2.adoc
new file mode 100644
index 0000000000..4873182d28
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_2.adoc
@@ -0,0 +1,341 @@
+
+The following table lists every success criterion of WCAG 2.2 at level A and 
AA, in the order of the specification. For each criterion it shows what Wicket 
offers, what is left to the application, and where this chapter has code for 
it. Criteria Wicket has no bearing on are marked as such: they depend on 
content, design or media only, and are met or failed the same way in any web 
application. The criterion 4.1.1 Parsing is not in the table, because WCAG 2.2 
has removed it.
+
+The descriptions of the criteria are shortened; the full text and the 
techniques that meet each criterion are in https://www.w3.org/TR/WCAG22/[the 
WCAG 2.2 specification] and 
https://www.w3.org/WAI/WCAG22/Understanding/[Understanding WCAG 2.2].
+
+[cols="3,1,5,5,1",options="header"]
+|===
+|Success criterion |Level |Wicket |Application |Code
+
+|1.1.1 Non-text Content
+|A
+|_Image_ and _ContextImage_ render the _alt_ attribute we write in the markup. 
_AjaxIndicatorAppender_ renders its busy indicator with an empty _alt_.
+|An _alt_ text for every meaningful image, _alt=""_ for decorative ones, text 
alternatives for icons, a CAPTCHA alternative if _CaptchaImageResource_ is used.
+|
+
+|1.2.1 Audio-only and Video-only (Prerecorded)
+|A
+|No bearing.
+|A transcript or an audio track for prerecorded media.
+|
+
+|1.2.2 Captions (Prerecorded)
+|A
+|No bearing. _Video_ and _Track_ render the _<video>_ and _<track>_ tags.
+|Captions for prerecorded video.
+|
+
+|1.2.3 Audio Description or Media Alternative (Prerecorded)
+|A
+|No bearing.
+|Audio description or a text alternative for prerecorded video.
+|
+
+|1.2.4 Captions (Live)
+|AA
+|No bearing.
+|Captions for live video.
+|
+
+|1.2.5 Audio Description (Prerecorded)
+|AA
+|No bearing.
+|Audio description for prerecorded video.
+|
+
+|1.3.1 Info and Relationships
+|A
+|Our markup reaches the browser unchanged. _wicket:for_ connects labels and 
fields; _RadioChoice_ and _CheckBoxMultipleChoice_ label their options; 
_DataTable_ renders _<th scope="col">_ and a _<caption>_. Fields do not get 
_aria-invalid_, and row headers in a _DataTable_ need a workaround.
+|Headings, lists, landmarks, _<fieldset>_ and _<legend>_ for groups of fields, 
a label for every field, table headers.
+|<<_an_accessible_base_page,25.3>>, <<_accessible_form_errors,25.4>>, 
<<_accessible_data_tables,25.7>>
+
+|1.3.2 Meaningful Sequence
+|A
+|Components render where their tag is in the markup.
+|A source order that matches the reading order; no reordering with CSS that 
changes the meaning.
+|
+
+|1.3.3 Sensory Characteristics
+|A
+|No bearing.
+|Instructions that do not rely on shape, colour, size or position only ("the 
button on the right").
+|
+
+|1.3.4 Orientation
+|AA
+|No bearing.
+|A layout that works in portrait and landscape.
+|
+
+|1.3.5 Identify Input Purpose
+|AA
+|Wicket keeps the _autocomplete_ attribute we write on a field.
+|An _autocomplete_ attribute with the right token on fields that ask for data 
about the user (_email_, _name_, _street-address_, ...).
+|<<_accessible_form_errors,25.4>>
+
+|1.4.1 Use of Color
+|A
+|The CSS classes Wicket adds (_error_ and _required_ on labels, 
_feedbackPanelERROR_ on messages) carry no colour of their own.
+|Errors, required fields, links and states that are not shown by colour alone.
+|<<_accessible_form_errors,25.4>>
+
+|1.4.2 Audio Control
+|A
+|No bearing.
+|A way to stop audio that plays automatically.
+|
+
+|1.4.3 Contrast (Minimum)
+|AA
+|No bearing.
+|A contrast ratio of 4.5:1 for text, 3:1 for large text.
+|
+
+|1.4.4 Resize Text
+|AA
+|No bearing.
+|A page that still works when the text is enlarged to 200%.
+|
+
+|1.4.5 Images of Text
+|AA
+|No bearing.
+|Real text instead of images of text.
+|
+
+|1.4.10 Reflow
+|AA
+|No bearing. The markup of _DataTable_ and other components is styled by us.
+|A layout that works at a width of 320 CSS pixels without scrolling in two 
directions; data tables may scroll horizontally.
+|
+
+|1.4.11 Non-text Contrast
+|AA
+|No bearing.
+|A contrast ratio of 3:1 for the borders of fields and buttons, focus 
indicators and icons that convey information.
+|
+
+|1.4.12 Text Spacing
+|AA
+|No bearing.
+|A layout that does not break when users increase line, word and letter 
spacing.
+|
+
+|1.4.13 Content on Hover or Focus
+|AA
+|No bearing.
+|Tooltips and pop-ups that can be dismissed, hovered and stay until dismissed.
+|
+
+|2.1.1 Keyboard
+|A
+|Links and buttons are keyboard-operable when their component is attached to 
_<a>_ or _<button>_. An AJAX behavior attached to any other element is not.
+|Every function operable from the keyboard; AJAX behaviors on elements that 
can receive focus.
+|<<_keyboard_operable_ajax_controls,25.6>>
+
+|2.1.2 No Keyboard Trap
+|A
+|_ModalDialog.trapFocus()_ keeps the focus inside an open dialog on purpose; 
_closeOnEscape()_ lets the user leave it.
+|A way out of every widget with the keyboard; a close button in every dialog.
+|<<_keyboard_operable_ajax_controls,25.6>>
+
+|2.1.4 Character Key Shortcuts
+|A
+|Wicket defines no keyboard shortcuts.
+|Single-key shortcuts that can be turned off or remapped, if the application 
defines any.
+|
+
+|2.2.1 Timing Adjustable
+|A
+|A stateful page lives in the HTTP session; when the session times out, the 
user sees the page expired page and loses the input. Stateless pages and forms 
(_StatelessForm_) do not expire.
+|A session timeout that is long enough, a warning before it expires with a way 
to extend it, or stateless pages for long forms.
+|
+
+|2.2.2 Pause, Stop, Hide
+|A
+|_AbstractAjaxTimerBehavior_ and _AjaxSelfUpdatingTimerBehavior_ can be 
stopped with _stop(target)_.
+|A way to pause content that moves or updates by itself for more than five 
seconds.
+|
+
+|2.3.1 Three Flashes or Below Threshold
+|A
+|No bearing.
+|No content that flashes more than three times per second.
+|
+
+|2.4.1 Bypass Blocks
+|A
+|No bearing.
+|A skip link and landmarks.
+|<<_an_accessible_base_page,25.3>>
+
+|2.4.2 Page Titled
+|A
+|A _Label_ on the _<title>_ tag gives every page its own title. The default 
error pages have a fixed English title.
+|A title for every page that describes its topic or purpose.
+|<<_an_accessible_base_page,25.3>>
+
+|2.4.3 Focus Order
+|A
+|After an AJAX update Wicket restores the focus only if the focused element 
keeps its markup id. Sort links of an AJAX _DataTable_ get new markup ids, so 
the focus is lost after sorting.
+|Focus moved deliberately after AJAX updates and when dialogs open and close.
+|<<_focus_and_announcements_after_ajax_updates,25.5>>, 
<<_accessible_data_tables,25.7>>
+
+|2.4.4 Link Purpose (In Context)
+|A
+|_PagingNavigator_ renders "<<", "<", ">" and ">>" as the text of its links 
and puts the description in a _title_ attribute only.
+|Link texts that describe the target, such as a "Delete" button that names 
what it deletes.
+|<<_focus_and_announcements_after_ajax_updates,25.5>>, 
<<_accessible_data_tables,25.7>>
+
+|2.4.5 Multiple Ways
+|AA
+|No bearing.
+|More than one way to find a page: navigation, search, a site map.
+|
+
+|2.4.6 Headings and Labels
+|AA
+|No bearing.
+|Headings and labels that describe the topic or purpose.
+|
+
+|2.4.7 Focus Visible
+|AA
+|Wicket's own stylesheets do not remove the focus outline.
+|A visible focus indicator on every element that can receive focus.
+|
+
+|2.4.11 Focus Not Obscured (Minimum)
+|AA
+|No bearing.
+|Sticky headers, footers and banners that do not hide the element with the 
focus.
+|
+
+|2.5.1 Pointer Gestures
+|A
+|No bearing.
+|A single-pointer alternative for gestures with multiple fingers or a path.
+|
+
+|2.5.2 Pointer Cancellation
+|A
+|_AjaxLink_, _AjaxButton_ and _AjaxEventBehavior_ on _click_ fire on the 
up-event. Behaviors on _mousedown_ or _pointerdown_ do not.
+|Actions on _click_ rather than on the down-event.
+|<<_keyboard_operable_ajax_controls,25.6>>
+
+|2.5.3 Label in Name
+|A
+|No bearing.
+|An accessible name (_aria-label_, hidden text) that starts with or contains 
the visible label.
+|<<_focus_and_announcements_after_ajax_updates,25.5>>
+
+|2.5.4 Motion Actuation
+|A
+|No bearing.
+|An alternative for functions triggered by shaking or tilting the device.
+|
+
+|2.5.7 Dragging Movements
+|AA
+|No bearing. _Palette_ moves items with buttons, not by dragging.
+|A single-pointer alternative for drag and drop, such as in sortable lists or 
file drop zones.
+|
+
+|2.5.8 Target Size (Minimum)
+|AA
+|No bearing.
+|Targets of at least 24 by 24 CSS pixels, or enough space around them.
+|
+
+|3.1.1 Language of Page
+|A
+|Wicket does not render a _lang_ attribute. A _TransparentWebMarkupContainer_ 
on the _<html>_ tag can add it from the session locale. The default error pages 
have no _lang_.
+|A _lang_ attribute on _<html>_ that matches the language of the page.
+|<<_an_accessible_base_page,25.3>>
+
+|3.1.2 Language of Parts
+|AA
+|Wicket keeps a _lang_ attribute we write in the markup, and 
_AttributeModifier_ can set it from code.
+|A _lang_ attribute on passages in another language.
+|<<_an_accessible_base_page,25.3>>
+
+|3.2.1 On Focus
+|A
+|AJAX behaviors on _focus_ run only when we attach them.
+|No change of context, such as navigation or a submit, when an element 
receives focus.
+|<<_keyboard_operable_ajax_controls,25.6>>
+
+|3.2.2 On Input
+|A
+|_FormComponentUpdatingBehavior_, _AjaxFormComponentUpdatingBehavior_ and 
_OnChangeAjaxBehavior_ run code whenever a value changes.
+|No navigation or other change of context on changing a value, unless the user 
has been told in advance; a submit button instead.
+|<<_keyboard_operable_ajax_controls,25.6>>
+
+|3.2.3 Consistent Navigation
+|AA
+|Markup inheritance gives all pages the same navigation.
+|Navigation that appears in the same order on every page.
+|<<_an_accessible_base_page,25.3>>
+
+|3.2.4 Consistent Identification
+|AA
+|Reusable panels and _wicket:message_ keep names and labels the same across 
pages.
+|Components with the same function labelled the same way.
+|
+
+|3.2.6 Consistent Help
+|A
+|Markup inheritance puts help links in the same place on every page.
+|Help mechanisms in the same relative order on every page.
+|<<_an_accessible_base_page,25.3>>
+
+|3.3.1 Error Identification
+|A
+|Validation messages name the field through its label. The error state reaches 
the _<label>_ as the CSS class _error_, but not the field: there is no 
_aria-invalid_ and no _aria-describedby_.
+|A message next to the field, _aria-invalid_ on the field and a reference from 
the field to its message.
+|<<_accessible_form_errors,25.4>>
+
+|3.3.2 Labels or Instructions
+|A
+|_wicket:for_ and _<wicket:label>_ connect a visible label to every field. 
Text fields copy their label into the _placeholder_ attribute.
+|A visible label for every field, required fields marked in the label, formats 
explained before the user types.
+|<<_accessible_form_errors,25.4>>
+
+|3.3.3 Error Suggestion
+|AA
+|Validation messages come from resource bundles and can be reworded per field 
and per validator.
+|Messages that say how to correct the input.
+|<<_accessible_form_errors,25.4>>
+
+|3.3.4 Error Prevention (Legal, Financial, Data)
+|AA
+|A multi-step _Wizard_ or a confirmation page can be built from regular pages 
and panels.
+|Review, confirmation or undo for submissions with legal or financial 
consequences.
+|
+
+|3.3.7 Redundant Entry
+|A
+|A form keeps its model between requests, so values entered earlier can be 
shown again.
+|No asking for the same information twice in one process, unless needed.
+|
+
+|3.3.8 Accessible Authentication (Minimum)
+|AA
+|_PasswordTextField_ allows pasting and password managers. 
_CaptchaImageResource_ is a cognitive function test.
+|Login without a cognitive test, or with an alternative; _autocomplete_ on 
username and password fields.
+|
+
+|4.1.2 Name, Role, Value
+|A
+|Native elements carry name, role and value. Wicket adds no roles to elements 
that need them: an AJAX behavior on a _<div>_, _TabbedPanel_ and _ModalDialog_ 
have no ARIA roles.
+|Native elements first; ARIA roles, states and names on custom widgets.
+|<<_keyboard_operable_ajax_controls,25.6>>, <<_accessible_data_tables,25.7>>
+
+|4.1.3 Status Messages
+|AA
+|_FeedbackPanel_ is not a live region, and messages that arrive by AJAX are 
not announced.
+|A live region that stays in the page, updated by AJAX.
+|<<_focus_and_announcements_after_ajax_updates,25.5>>
+|===
+
+Most rows say "No bearing" or put the work on the application. The rows with a 
link are the ones where Wicket offers a mechanism, or where its default markup 
needs help; the next paragraphs deal with them.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_3.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_3.adoc
new file mode 100644
index 0000000000..49bf4bf195
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_3.adoc
@@ -0,0 +1,119 @@
+
+Several success criteria are met once for the whole application, in the page 
all other pages extend. In <<_wicket_as_page_layout_manager,chapter 5>> we have 
built such a base page with markup inheritance; here we complete it with a 
title for every page, a _lang_ attribute that follows the session locale, a 
skip link and landmarks.
+
+*BasePage.html:*
+
+[source,html]
+----
+<!DOCTYPE html>
+<html wicket:id="html" xmlns:wicket="http://wicket.apache.org";>
+<head>
+       <meta charset="utf-8">
+       <title wicket:id="pageTitle">Page title</title>
+</head>
+<body>
+       <a class="skip-link" href="#content"><wicket:message 
key="skipToContent">Skip to main content</wicket:message></a>
+       <header>
+               <p class="site-name">Example</p>
+       </header>
+       <nav wicket:message="aria-label:mainNavigation">
+               <ul>
+                       <li><a href="#">Home</a></li>
+               </ul>
+       </nav>
+       <main id="content" tabindex="-1">
+               <wicket:child/>
+       </main>
+       <footer>
+               <p>Footer</p>
+       </footer>
+</body>
+</html>
+----
+
+*BasePage.java:*
+
+[source,java]
+----
+public abstract class BasePage extends WebPage {
+
+       public BasePage() {
+               TransparentWebMarkupContainer html = new 
TransparentWebMarkupContainer("html");
+               html.add(AttributeModifier.replace("lang", () -> 
getLocale().toLanguageTag()));
+               add(html);
+
+               add(new Label("pageTitle", this::getPageTitle));
+       }
+
+       protected abstract String getPageTitle();
+}
+----
+
+*BasePage.properties:*
+
+[source,properties]
+----
+skipToContent=Skip to main content
+mainNavigation=Main
+----
+
+=== The language of the page
+
+Screen readers choose their pronunciation from the _lang_ attribute of the 
_<html>_ element (success criterion 3.1.1). Wicket does not render this 
attribute, so we bind the _<html>_ tag to a _TransparentWebMarkupContainer_ and 
add the attribute with an _AttributeModifier_. Since the container is 
transparent, the components of the page and of its subclasses can stay where 
they are and need not be added to the container. Method _getLocale()_ returns 
the locale of the session (see <<_intern [...]
+
+If an application supports only one language, a _lang_ attribute written in 
the markup is enough. Passages in another language than the page, such as a 
quote or the name of a language in a language switcher, get their own _lang_ 
attribute (success criterion 3.1.2), either in the markup or with an 
_AttributeModifier_ on the component that renders them.
+
+=== A title for every page
+
+Browsers show the title of a page in their tab, and screen readers read it 
first when a page loads (success criterion 2.4.2). The _<title>_ tag of the 
base page is bound to a _Label_, and every page provides its own text by 
implementing _getPageTitle_:
+
+[source,java]
+----
+public class RegistrationPage extends BasePage {
+
+       @Override
+       protected String getPageTitle() {
+               return "Register - Example";
+       }
+}
+----
+
+A localized application returns _getString("title")_ and keeps the titles in 
the resource bundle of each page. A title starts with what is specific to the 
page, so that users who have several tabs open can tell them apart.
+
+=== Skip link and landmarks
+
+The skip link is the first link of the page and points to the _<main>_ 
element, so keyboard users can jump past the header and the navigation (success 
criterion 2.4.1). The attribute _tabindex="-1"_ on _<main>_ makes sure that 
browsers move the keyboard focus to it, and not only the scroll position. The 
skip link may be hidden until it receives focus, but it must become visible 
then:
+
+[source,css]
+----
+.skip-link {
+       position: absolute;
+       left: -10000px;
+}
+
+.skip-link:focus {
+       left: 1em;
+       top: 1em;
+}
+----
+
+The elements _<header>_, _<nav>_, _<main>_ and _<footer>_ are exposed as 
landmarks, which screen reader users can list and jump to. When a page has more 
than one _<nav>_, each one needs a name; here the main navigation gets an 
_aria-label_ from the resource bundle with the attribute form of 
_wicket:message_.
+
+Because every page extends the base page, the navigation and any help link 
appear in the same place and the same order on every page, as success criteria 
3.2.3 and 3.2.6 ask.
+
+=== Error pages
+
+Wicket shows its own pages when a page has expired, when access is denied and 
when an internal error occurs. These pages use an HTML 4.01 doctype, have no 
_lang_ attribute and an English title, and they do not share the layout and 
navigation of the application. We can replace them with pages that extend our 
base page:
+
+[source,java]
+----
+@Override
+protected void init() {
+       super.init();
+       
getApplicationSettings().setPageExpiredErrorPage(MyPageExpiredPage.class);
+       getApplicationSettings().setAccessDeniedPage(MyAccessDeniedPage.class);
+       
getApplicationSettings().setInternalErrorPage(MyInternalErrorPage.class);
+}
+----
+
+The page expired page is also what users see when their session has timed out 
(success criterion 2.2.1), so it deserves a text that explains what happened 
and what to do next.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_4.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_4.adoc
new file mode 100644
index 0000000000..5997da31ef
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_4.adoc
@@ -0,0 +1,154 @@
+
+A form is accessible when every field has a label that is connected to it, 
when an error tells the user which field is wrong and how to correct it, and 
when the error can be found without seeing it. Wicket does the first part; for 
the last part we need a small behavior of our own.
+
+=== Labels with wicket:for
+
+A _<label>_ is connected to its field by the _for_ attribute, which must 
contain the _id_ of the field. Since Wicket generates the markup ids of 
components, we cannot write that _id_ in the markup ourselves. The attribute 
_wicket:for_ solves this: it contains the component id of the field, and Wicket 
renders the _for_ attribute with the markup id of that component, which it 
makes the field output:
+
+[source,html]
+----
+<label wicket:for="email"><wicket:label>Email address</wicket:label></label>
+<input type="email" wicket:id="email" autocomplete="email">
+----
+
+The tag _<wicket:label>_ inside the label does one more thing: if the field 
has no label model yet, its text becomes the label of the field. Validation 
messages use this label, so the message for a required field reads _'Email 
address' is required._ instead of naming the component id. The same can be done 
from code with _setLabel(IModel)_, in which case _<wicket:label>_ renders the 
text of the model. Either way the visible label and the name in the messages 
are the same text, which is wh [...]
+
+The attribute _autocomplete_ tells browsers and assistive technology what the 
field asks for (success criterion 1.3.5). Wicket leaves it alone, so we write 
it in the markup with the right token, such as _email_, _name_, _tel_ or 
_street-address_.
+
+Besides the _for_ attribute, _wicket:for_ adds the CSS class _required_ to the 
label of a required field, _error_ to the label of a field that failed 
validation and _disabled_ to the label of a disabled field. The names of these 
classes can be changed with the resource keys _AutoLabel.CSS.required_, 
_AutoLabel.CSS.error_ and _AutoLabel.CSS.disabled_. These classes are useful 
for styling, but they are not enough on their own: a class is not exposed to 
assistive technology, and a colour mu [...]
+
+NOTE: Text fields render the label of the component in their _placeholder_ 
attribute, and replace any placeholder we wrote in the markup. Some screen 
readers then read the label twice. Text fields also render the HTML5 attribute 
_required_ when the component is required. When the form is submitted without 
AJAX, the browser then checks the field first and shows its own message instead 
of Wicket's; AJAX submits skip this check. The attribute _novalidate_ on the 
_<form>_ tag turns the brows [...]
+
+=== Errors next to the field
+
+A message in a _FeedbackPanel_ at the top of the page tells the user that 
something went wrong, but a user who works through the form field by field does 
not see it there. Success criterion 3.3.1 asks that the field in error is 
identified, and the most robust way is a message next to the field, which the 
field refers to. A _ComponentFeedbackPanel_ shows the messages of one component 
only, so we put one after each field:
+
+[source,html]
+----
+<form wicket:id="form" novalidate>
+       <label wicket:for="email"><wicket:label>Email 
address</wicket:label></label>
+       <input type="email" wicket:id="email" autocomplete="email">
+       <div wicket:id="emailError" class="field-error"></div>
+
+       <button wicket:id="register">Register</button>
+</form>
+----
+
+Visually the message is now next to the field. For a screen reader it is not 
yet connected to it: the field must say that it is invalid, with 
_aria-invalid="true"_, and refer to its message with _aria-describedby_. Wicket 
does not render either attribute, so we add them with a behavior:
+
+[source,java]
+----
+public class AriaInvalidBehavior extends Behavior {
+
+       private final Component errorMessage;
+
+       public AriaInvalidBehavior() {
+               this(null);
+       }
+
+       public AriaInvalidBehavior(Component errorMessage) {
+               this.errorMessage = errorMessage;
+       }
+
+       @Override
+       public void bind(Component component) {
+               if (!(component instanceof FormComponent)) {
+                       throw new IllegalArgumentException("AriaInvalidBehavior 
needs a FormComponent");
+               }
+               if (errorMessage != null) {
+                       errorMessage.setOutputMarkupId(true);
+               }
+       }
+
+       @Override
+       public void onComponentTag(Component component, ComponentTag tag) {
+               if (((FormComponent<?>) component).isValid() == false) {
+                       tag.put("aria-invalid", "true");
+                       if (errorMessage != null) {
+                               tag.append("aria-describedby", 
errorMessage.getMarkupId(), " ");
+                       }
+               }
+       }
+}
+----
+
+The behavior writes both attributes only while the field has an error message, 
which is the case in the render that follows a failed submit. 
_ComponentTag.append_ keeps an _aria-describedby_ that is already in the 
markup, for instance one that points to a hint about the expected format. The 
page puts it together:
+
+[source,java]
+----
+public class RegistrationPage extends BasePage {
+
+       public RegistrationPage() {
+               Form<Void> form = new Form<>("form");
+               form.setOutputMarkupId(true);
+               add(form);
+
+               EmailTextField email = new EmailTextField("email", 
Model.of(""));
+               email.setRequired(true);
+               form.add(email);
+
+               ComponentFeedbackPanel emailError = new 
ComponentFeedbackPanel("emailError", email);
+               form.add(emailError);
+               email.add(new AriaInvalidBehavior(emailError));
+
+               form.add(new AjaxButton("register") {
+                       @Override
+                       protected void onSubmit(AjaxRequestTarget target) {
+                               // store the registration
+                       }
+
+                       @Override
+                       protected void onError(AjaxRequestTarget target) {
+                               target.add(form);
+                               form.visitFormComponents((field, visit) -> {
+                                       if (field.isValid() == false) {
+                                               target.focusComponent(field);
+                                               visit.stop();
+                                       }
+                               });
+                       }
+               });
+       }
+
+       @Override
+       protected String getPageTitle() {
+               return "Register - Example";
+       }
+}
+----
+
+After a failed submit the field is rendered like this (the markup ids are 
generated by Wicket):
+
+[source,html]
+----
+<input type="email" autocomplete="email" value="" required="required" 
placeholder="Email address"
+       pattern="..." name="email" id="email3" aria-invalid="true" 
aria-describedby="emailError4">
+<div class="field-error" id="emailError4">
+       <ul class="feedbackPanel">
+               <li class="feedbackPanelERROR"><span>'Email address' is 
required.</span></li>
+       </ul>
+</div>
+----
+
+When the form is submitted with AJAX, as here, _onError_ moves the focus to 
the first field in error. A screen reader then reads the label of the field, 
that it is invalid, and the error message. Without the focus change the user 
would not notice that anything happened. When the form is submitted without 
AJAX, the whole page is rendered again and the focus starts at the top; a 
summary of the errors at the top of the form, with links to the fields, is then 
the way to lead the user to them.
+
+The text of the message is ours to write. Success criterion 3.3.3 asks that it 
suggests how to correct the input, which the generic messages of Wicket's 
validators do not always do. They can be reworded for a single field in the 
resource bundle of the page, with a key that combines the component id and the 
validator, for example _email.Required_ or _email.EmailAddressValidator_ (see 
<<_wicket_forms_in_detail,chapter 12>>).
+
+=== aria-invalid for every field
+
+Instead of adding _AriaInvalidBehavior_ to each field, we can add it to every 
form component the application creates, with a component instantiation listener 
in the _init_ method of the application:
+
+[source,java]
+----
+@Override
+protected void init() {
+       super.init();
+       getComponentInstantiationListeners().add(component -> {
+               if (component instanceof FormComponent) {
+                       component.add(new AriaInvalidBehavior());
+               }
+       });
+}
+----
+
+This gives every invalid field _aria-invalid_, but not the reference to its 
message, because the listener does not know where the message is. Fields with a 
message next to them still get an _AriaInvalidBehavior_ with that message, as 
in the example above.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_5.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_5.adoc
new file mode 100644
index 0000000000..ba76c4f688
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_5.adoc
@@ -0,0 +1,150 @@
+
+When an AJAX response updates a part of the page, nothing tells the user so: 
the browser does not reload the page, the screen reader does not announce 
anything, and the keyboard focus stays where it was, if the element that had it 
still exists. In this paragraph we will see how to move the focus where the 
user needs it and how to announce what has changed.
+
+=== How Wicket replaces components
+
+Wicket updates a component by replacing its whole element in the DOM with the 
newly rendered markup. If the replaced element had the focus, Wicket gives the 
focus back to the new element with the same markup id. This works as long as 
the component keeps its markup id, which is the case for a component that stays 
in the component tree and has _setOutputMarkupId(true)_.
+
+The focus is lost when the focused element does not come back: a button that 
deletes its own row, a link that hides itself, or the items of a repeater that 
creates new components at every render, because new components get new markup 
ids. The focus then falls back to the start of the document, and keyboard and 
screen reader users have to find their way back from there (success criterion 
2.4.3).
+
+=== Moving the focus with focusComponent
+
+In those cases we move the focus ourselves with _focusComponent_ of 
_AjaxRequestTarget_. Its argument must have _setOutputMarkupId(true)_, 
otherwise the method throws an _IllegalArgumentException_. Wicket sets the 
focus after the components of the response have been replaced, so the component 
may be one that is part of the same update.
+
+The next example is a page with a list of addresses, each with a button to 
delete it. After a deletion the button is gone, so we move the focus to the 
heading of the list:
+
+*AddressesPage.html:*
+
+[source,html]
+----
+<wicket:extend>
+       <h1 wicket:id="heading" tabindex="-1">Your addresses</h1>
+
+       <div role="status">
+               <span wicket:id="status"></span>
+       </div>
+
+       <ul wicket:id="list">
+               <li wicket:id="addresses">
+                       <span wicket:id="address"></span>
+                       <button wicket:id="delete">Delete<span 
class="visually-hidden"> <span wicket:id="deleteWhat"></span></span></button>
+               </li>
+       </ul>
+</wicket:extend>
+----
+
+*AddressesPage.java:*
+
+[source,java]
+----
+public class AddressesPage extends BasePage {
+
+       private final List<String> addresses = new ArrayList<>(List.of("Main 
Street 1", "Station Road 2"));
+
+       public AddressesPage() {
+               IModel<String> statusMessage = Model.of("");
+               Label status = new Label("status", statusMessage);
+               status.setOutputMarkupId(true);
+               add(status);
+
+               WebMarkupContainer heading = new WebMarkupContainer("heading");
+               heading.setOutputMarkupId(true);
+               add(heading);
+
+               WebMarkupContainer list = new WebMarkupContainer("list");
+               list.setOutputMarkupId(true);
+               add(list);
+
+               list.add(new ListView<>("addresses", () -> addresses) {
+                       @Override
+                       protected void populateItem(ListItem<String> item) {
+                               item.add(new Label("address", item.getModel()));
+                               AjaxLink<String> delete = new 
AjaxLink<>("delete", item.getModel()) {
+                                       @Override
+                                       public void onClick(AjaxRequestTarget 
target) {
+                                               
addresses.remove(getModelObject());
+                                               
statusMessage.setObject("Address " + getModelObject() + " removed.");
+
+                                               target.add(list, status);
+                                               target.focusComponent(heading);
+                                       }
+                               };
+                               delete.add(new Label("deleteWhat", 
item.getModel()));
+                               item.add(delete);
+                       }
+               });
+       }
+
+       @Override
+       protected String getPageTitle() {
+               return "Your addresses - Example";
+       }
+}
+----
+
+A heading cannot receive focus by itself, so it gets _tabindex="-1"_: this 
lets a script focus it without adding it to the tab order. Which element should 
get the focus depends on the task. After deleting an item, the next item or the 
heading of the list are good choices; after opening a panel, its first field or 
its heading; after closing it, the control that opened it.
+
+Every _Delete_ button has the same visible text, so each button gets the 
address as hidden text, and a screen reader announces "Delete Main Street 1" 
(success criterion 2.4.4). The accessible name still starts with the visible 
text, as success criterion 2.5.3 asks. The hidden text uses a CSS class that 
hides content visually but not from screen readers:
+
+[source,css]
+----
+.visually-hidden {
+       position: absolute;
+       width: 1px;
+       height: 1px;
+       overflow: hidden;
+       clip-path: inset(50%);
+       white-space: nowrap;
+}
+----
+
+=== Announcing changes with a live region
+
+A message such as "Address removed" or "Your changes have been saved" is a 
status message: it should be announced without moving the focus (success 
criterion 4.1.3). This is what ARIA live regions are for. A screen reader 
announces changes to the content of an element with _role="status"_ (or 
_aria-live="polite"_), and urgent ones in an element with _role="alert"_.
+
+A live region only works if it is in the page before its content changes. 
Since Wicket replaces the whole element of a component it updates, the live 
region must not be that element: an element that is new in the page is not 
announced reliably. In the example above, the _<div role="status">_ is plain 
markup that stays in the page, and the AJAX response replaces only the _Label_ 
inside it. The label is rendered with an empty text when the page loads, so the 
region exists, empty, from the start.
+
+The same applies to a _FeedbackPanel_. It is not a live region, and messages 
that it shows after an AJAX update are not announced. Wrapping it in a region 
that stays in the page solves this:
+
+[source,html]
+----
+<div role="status">
+       <div wicket:id="feedback"></div>
+</div>
+----
+
+[source,java]
+----
+FeedbackPanel feedback = new FeedbackPanel("feedback");
+feedback.setOutputMarkupId(true);
+add(feedback);
+----
+
+and, in the AJAX callback, _success("Your changes have been saved.")_ followed 
by _target.add(feedback)_. A live region is for short messages; for validation 
errors the field and its message, as shown in 
<<_accessible_form_errors,paragraph 25.4>>, work better than an announcement of 
all errors at once.
+
+=== Busy indicators
+
+The indicator of _AjaxIndicatorAppender_ and the indicating AJAX links and 
buttons is an image with an empty _alt_ attribute, so it is invisible to screen 
readers. For requests that take long, a "Loading..." text in a live region, set 
in the request's _before_ handler and cleared in the _complete_ handler (see 
<<_ajax_request_attributes_and_call_listeners,paragraph 19.6>>), tells all 
users that the application is working.
+
+=== Dialogs
+
+_ModalDialog_ from wicket-extensions can trap the focus inside the dialog with 
_trapFocus()_, and gives the focus back to the element that had it when the 
dialog is closed. With _closeOnEscape()_ the dialog can be closed with the 
Escape key. These are opt-in, and the dialog element has no ARIA role, so we 
add the role, _aria-modal_ and a reference to the title of the dialog by 
overriding _newDialog_:
+
+[source,java]
+----
+ModalDialog dialog = new ModalDialog("dialog") {
+       @Override
+       protected WebMarkupContainer newDialog(String dialogId) {
+               WebMarkupContainer dialog = super.newDialog(dialogId);
+               dialog.add(AttributeModifier.replace("role", "dialog"));
+               dialog.add(AttributeModifier.replace("aria-modal", "true"));
+               dialog.add(AttributeModifier.replace("aria-labelledby", 
"dialog-title"));
+               return dialog;
+       }
+};
+dialog.trapFocus();
+dialog.closeOnEscape();
+add(dialog);
+----
+
+The content panel of the dialog then has a heading with _id="dialog-title"_, 
and a button that closes the dialog.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_6.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_6.adoc
new file mode 100644
index 0000000000..0ca983bf72
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_6.adoc
@@ -0,0 +1,53 @@
+
+Every function of the application must be operable from the keyboard (success 
criterion 2.1.1). With Wicket this mostly comes down to the element an AJAX 
component or behavior is attached to.
+
+=== Links and buttons, not div and span
+
+Browsers make two kinds of elements operable from the keyboard: links with an 
_href_ attribute and form controls such as _<button>_. They can receive focus 
with the Tab key, the Enter key activates a link, Enter and Space activate a 
button, and screen readers announce them as link or button. A _<div>_ or 
_<span>_ has none of this. An _AjaxEventBehavior_ on _click_ attached to a 
_<div>_ works with the mouse, but a keyboard user cannot reach it, and a screen 
reader user does not know it is there:
+
+[source,html]
+----
+<!-- only for mouse users -->
+<div wicket:id="details">Show details</div>
+----
+
+[source,java]
+----
+add(new WebMarkupContainer("details")
+       .add(AjaxEventBehavior.onEvent("click", target -> 
showDetails(target))));
+----
+
+The same goes for an _AjaxLink_ attached to a _<div>_ or _<span>_: _AjaxLink_ 
adapts the tag only when it is an _<a>_ or a _<button>_. The solution is to 
attach the component to the element that matches what it does. An action on the 
current page, such as showing details, deleting an item or opening a dialog, is 
a button:
+
+[source,html]
+----
+<button wicket:id="details">Show details</button>
+----
+
+[source,java]
+----
+add(new AjaxLink<Void>("details") {
+       @Override
+       public void onClick(AjaxRequestTarget target) {
+               showDetails(target);
+       }
+});
+----
+
+On a _<button>_, _AjaxLink_ renders _type="button"_, so the button does not 
submit a form it is in. Navigation to another page or to another state that the 
user may want to bookmark is a link, and a plain _Link_ or 
_BookmarkablePageLink_ on an _<a>_ tag does it without AJAX at all. On an _<a>_ 
tag, _AjaxLink_ renders _href="#"_: the link can receive focus and is operable 
from the keyboard, but screen readers announce it as a link, which is not what 
users expect of an action.
+
+Forms are submitted with _Button_, _AjaxButton_ or _AjaxSubmitLink_ on a 
_<button>_ or _<input type="submit">_. A form with such a button can also be 
submitted with the Enter key in a text field.
+
+If a custom widget cannot be a native element, it needs everything the native 
element would have given it: a role (_role="button"_), a place in the tab order 
(_tabindex="0"_), a key handler for Enter and Space, and an accessible name. 
This is a lot of work to get right, and a _<button>_ styled with CSS is nearly 
always the better choice.
+
+=== Events that change the context
+
+Some AJAX behaviors react to events that the user does not intend as a 
command. A behavior on _focus_ runs when keyboard users merely tab through the 
page; it must not navigate, submit or open a dialog (success criterion 3.2.1). 
A behavior on _change_, such as _AjaxFormComponentUpdatingBehavior_ or 
_OnChangeAjaxBehavior_, runs every time the value changes: in a _<select>_ that 
is navigated with the arrow keys, that is for every option the user passes. 
Updating a part of the page, such as [...]
+
+Behaviors that react to _mousedown_ or _pointerdown_ run before the user can 
cancel the action by moving the pointer away (success criterion 2.5.2). The 
_click_ event, which _AjaxLink_ and _AjaxButton_ use, does not have this 
problem.
+
+=== Dialogs and other widgets
+
+A modal dialog takes the keyboard focus when it opens, keeps it inside while 
it is open and gives it back when it closes. _ModalDialog_ does this with 
_trapFocus()_, and _closeOnEscape()_ gives keyboard users a way out without 
searching for the close button (success criterion 2.1.2). The setup is shown in 
<<_focus_and_announcements_after_ajax_updates,paragraph 25.5>>.
+
+For widgets such as tabs, trees and menus, the WAI-ARIA Authoring Practices 
(https://www.w3.org/WAI/ARIA/apg/[]) describe the roles and the keyboard 
interaction users expect. _TabbedPanel_ renders its tabs as a list of links, 
which is operable from the keyboard but does not implement the tabs pattern.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_7.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_7.adoc
new file mode 100644
index 0000000000..4360a3a173
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_7.adoc
@@ -0,0 +1,112 @@
+
+A data table is accessible when its headers are marked as headers, so that a 
screen reader can announce the column (and the row) of each cell, when it has a 
caption that says what the table contains, and when the sort state of its 
columns is exposed. _DataTable_ from wicket-extensions renders most of this; 
this paragraph shows how to add the rest.
+
+=== What DataTable renders
+
+The headers of a _DataTable_ come from _HeadersToolbar_ or its AJAX variant 
_AjaxFallbackHeadersToolbar_. Each header is a _<th>_ with _scope="col"_, or 
_scope="colgroup"_ for a header that spans several columns. The header toolbar 
is placed in _<thead>_, the rows in _<tbody>_, as success criterion 1.3.1 asks. 
A _DataTable_ must be attached to a _<table>_ tag.
+
+=== A caption
+
+The _<caption>_ of a table is its title: screen readers announce it when the 
user enters the table, and it appears in their list of tables. _DataTable_ 
renders a caption when method _getCaptionModel_ returns a model with a text. By 
default it returns _null_, and the caption is not rendered:
+
+[source,java]
+----
+public class ContactsTable extends DataTable<Contact, String> {
+
+       public ContactsTable(String id, List<IColumn<Contact, String>> columns,
+               ISortableDataProvider<Contact, String> provider) {
+               super(id, columns, provider, 20);
+               setOutputMarkupId(true);
+               addTopToolbar(new AccessibleHeadersToolbar<>(this, provider));
+       }
+
+       @Override
+       protected IModel<String> getCaptionModel() {
+               return () -> "Contacts";
+       }
+}
+----
+
+_DataTable_ calls _getCaptionModel_ in its constructor, so the method must not 
use fields of the subclass, which are not initialized yet at that moment. A 
localized caption is a _ResourceModel_.
+
+=== Row headers
+
+In many tables one column identifies the row, like the name of a contact. 
Marking its cells as row headers lets screen readers announce the name together 
with the other cells of the row. _DataTable_ renders all cells of the body as 
_<td>_, and _IColumn_ has no way to render a _<th>_. We can rename the tag of 
the cells in the first column by overriding _newCellItem_ in the table:
+
+[source,java]
+----
+@Override
+protected Item<IColumn<Contact, String>> newCellItem(String id, int index,
+       IModel<IColumn<Contact, String>> model) {
+       if (index != 0) {
+               return super.newCellItem(id, index, model);
+       }
+       return new Item<>(id, index, model) {
+               @Override
+               protected void onComponentTag(ComponentTag tag) {
+                       super.onComponentTag(tag);
+                       tag.setName("th");
+                       tag.put("scope", "row");
+               }
+       };
+}
+----
+
+The argument _index_ is the index of the column, and Wicket also renders the 
closing tag with the new name.
+
+=== Sortable headers
+
+A sortable header contains a link that changes the sort order, and the _<th>_ 
gets the CSS class _wicket_orderUp_, _wicket_orderDown_ or _wicket_orderNone_. 
As with the label classes of <<_accessible_form_errors,paragraph 25.4>>, the 
class is not exposed to assistive technology. The ARIA attribute _aria-sort_ on 
the header of the sorted column is: screen readers announce it as "sorted 
ascending" or "sorted descending". We add it in a subclass of the header 
toolbar:
+
+[source,java]
+----
+public class AccessibleHeadersToolbar<S> extends AjaxFallbackHeadersToolbar<S> 
{
+
+       public AccessibleHeadersToolbar(DataTable<?, S> table, 
ISortStateLocator<S> stateLocator) {
+               super(table, stateLocator);
+       }
+
+       @Override
+       protected WebMarkupContainer newSortableHeader(String headerId, S 
property,
+               ISortStateLocator<S> locator) {
+               WebMarkupContainer header = super.newSortableHeader(headerId, 
property, locator);
+               header.get("orderByLink").setMarkupId(getTable().getMarkupId() 
+ "-sort-" + property);
+               header.add(AttributeModifier.replace("aria-sort", () -> {
+                       SortOrder order = 
locator.getSortState().getPropertySortOrder(property);
+                       return switch (order) {
+                               case ASCENDING -> "ascending";
+                               case DESCENDING -> "descending";
+                               case NONE -> null;
+                       };
+               }));
+               return header;
+       }
+}
+----
+
+The header returned by _newSortableHeader_ is rendered as the _<th>_ itself, 
so the attribute ends up in the right place. When the model returns _null_, 
_AttributeModifier_ leaves the attribute out, so only the sorted column gets 
_aria-sort_.
+
+The second line of the method fixes a focus problem of AJAX sorting. 
_AjaxFallbackHeadersToolbar_ re-creates its headers at every render, so after a 
click on a sort link the table comes back with new sort links, with new markup 
ids. As we have seen in <<_focus_and_announcements_after_ajax_updates,paragraph 
25.5>>, Wicket can only restore the focus to an element with the same markup 
id, so a keyboard user loses the focus after every sort. Giving the sort link 
(which the header contains wi [...]
+
+The resulting header looks like this:
+
+[source,html]
+----
+<th class="wicket_orderUp" aria-sort="ascending" scope="col">
+       <a href="..." id="contacts1-sort-name"><span>Name</span></a>
+</th>
+----
+
+=== Paging
+
+The _NavigationToolbar_ of a _DataTable_ uses a _PagingNavigator_, whose links 
have the texts "<<", "<", ">" and ">>". A screen reader reads these characters 
as the name of the links; the descriptions "Go to first page" and so on are 
only in the _title_ attribute, which is not reliably announced (success 
criterion 2.4.4). The link of the current page, and the links to the first and 
previous page on the first page, are rendered without _href_ and with a 
_disabled_ attribute, which an _<a> [...]
+
+[source,html]
+----
+<wicket:panel>
+       <a wicket:id="first"><span aria-hidden="true">&lt;&lt;</span><span 
class="visually-hidden"><wicket:message key="PagingNavigator.first"/></span></a>
+       ...
+</wicket:panel>
+----
+
+The markup of the subclass must contain the same component ids as the 
original, _first_, _prev_, _navigation_ (with _pageLink_ and _pageNumber_), 
_next_ and _last_.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_8.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_8.adoc
new file mode 100644
index 0000000000..854ca14950
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_8.adoc
@@ -0,0 +1,162 @@
+
+An application is checked against WCAG at three levels: assertions on the 
rendered markup in unit tests, automated checks with a rule engine in a 
browser, and checks by hand. The first two can run in every build. They are 
worth having, but they are not enough: automated tools find only a part of the 
failures. A tool can verify that an image has an _alt_ attribute, not that the 
text describes the image; that a field has a label, not that the label makes 
sense; that focus moves, not that i [...]
+
+=== Markup assertions with WicketTester
+
+With _WicketTester_ and _TagTester_ (see 
<<_test_driven_development_with_wicket,chapter 23>>) we can assert the 
accessibility properties our own code is responsible for, without a browser and 
at the speed of a unit test. The following test checks the base page and the 
registration form of this chapter: the _lang_ attribute, the page title, a 
label for every field and _aria-invalid_ with a description after a failed 
submit.
+
+[source,java]
+----
+class AccessibilityTest {
+
+       private WicketTester tester;
+
+       @BeforeEach
+       void setUp() {
+               tester = new WicketTester(new MyApplication());
+       }
+
+       @AfterEach
+       void tearDown() {
+               tester.destroy();
+       }
+
+       @Test
+       void pageLanguageFollowsSessionLocale() {
+               tester.getSession().setLocale(Locale.forLanguageTag("nl-NL"));
+               tester.startPage(RegistrationPage.class);
+
+               TagTester html = 
TagTester.createTagByName(tester.getLastResponseAsString(), "html");
+               assertEquals("nl-NL", html.getAttribute("lang"));
+       }
+
+       @Test
+       void pageHasTitle() {
+               tester.startPage(RegistrationPage.class);
+
+               TagTester title = 
TagTester.createTagByName(tester.getLastResponseAsString(), "title");
+               assertEquals("Register - Example", title.getValue());
+       }
+
+       @Test
+       void everyFieldHasLabel() {
+               tester.startPage(RegistrationPage.class);
+               String markup = tester.getLastResponseAsString();
+
+               Set<String> fields = Set.of("input", "select", "textarea");
+               Set<String> unlabelledTypes = Set.of("hidden", "submit", 
"button", "reset", "image");
+               List<TagTester> tags = TagTester.createTags(markup,
+                       tag -> fields.contains(tag.getName()), false);
+
+               assertFalse(tags.isEmpty());
+               for (TagTester field : tags) {
+                       if 
(unlabelledTypes.contains(field.getAttribute("type"))) {
+                               continue;
+                       }
+                       String id = field.getAttribute("id");
+                       assertNotNull(id, "field without id: " + 
field.getMarkup());
+                       assertNotNull(TagTester.createTagByAttribute(markup, 
"for", id),
+                               "no <label for=\"" + id + "\">");
+               }
+       }
+
+       @Test
+       void invalidFieldIsMarkedAndDescribed() {
+               tester.startPage(RegistrationPage.class);
+
+               FormTester form = tester.newFormTester("form");
+               form.setValue("email", "");
+               tester.executeAjaxEvent("form:register", "click");
+
+               TagTester email = tester.getTagByWicketId("email");
+               assertEquals("true", email.getAttribute("aria-invalid"));
+
+               String errorId = email.getAttribute("aria-describedby");
+               TagTester error = tester.getTagById(errorId);
+               assertTrue(error.getValue().contains("is required."));
+       }
+}
+----
+
+The method _createTags_ of _TagTester_ takes a function that selects tags by 
their name and attributes, which makes it easy to write checks that hold for 
all pages, such as the label check above, and to run them over every page of 
the application. After an AJAX request, _getTagByWicketId_ and _getTagById_ 
search the markup of the components in the AJAX response.
+
+=== Automated checks in the browser
+
+Many failures only show in the browser: contrast, which depends on the CSS; 
the names of elements as the browser computes them; duplicate ids; ARIA 
attributes that do not fit the role of their element. A rule engine such as 
https://github.com/dequelabs/axe-core[axe-core] checks these in the rendered 
page. It runs in a browser that a test drives, against the running application, 
so the test needs the application started in the same way as for other 
integration tests, and a browser automat [...]
+
+The following test uses Playwright for Java and Deque's Playwright integration 
for axe-core:
+
+[source,xml]
+----
+<dependency>
+       <groupId>com.deque.html.axe-core</groupId>
+       <artifactId>playwright</artifactId>
+       <version>4.10.1</version>
+       <scope>test</scope>
+</dependency>
+----
+
+[source,java]
+----
+class AccessibilityBrowserIT {
+
+       private static final String BASE_URL = System.getProperty("app.url", 
"http://localhost:8080";);
+
+       private static final List<String> WCAG_22_AA = List.of("wcag2a", 
"wcag2aa", "wcag21a", "wcag21aa",
+               "wcag22aa");
+
+       private static Playwright playwright;
+
+       private static Browser browser;
+
+       @BeforeAll
+       static void launchBrowser() {
+               playwright = Playwright.create();
+               browser = playwright.chromium().launch();
+       }
+
+       @AfterAll
+       static void closeBrowser() {
+               playwright.close();
+       }
+
+       @Test
+       void registrationPage() {
+               Page page = browser.newPage();
+               page.navigate(BASE_URL + "/register");
+               assertNoViolations(page);
+
+               page.getByRole(AriaRole.BUTTON, new 
Page.GetByRoleOptions().setName("Register")).click();
+               page.locator("[aria-invalid=true]").first().waitFor();
+               assertNoViolations(page);
+       }
+
+       private static void assertNoViolations(Page page) {
+               AxeResults results = new 
AxeBuilder(page).withTags(WCAG_22_AA).analyze();
+               List<Rule> violations = results.getViolations();
+               assertTrue(violations.isEmpty(), () -> page.url() + "\n" + 
violations.stream()
+                       .map(rule -> rule.getId() + ": " + rule.getHelp() + " 
(" + rule.getNodes().size() + "x)")
+                       .collect(Collectors.joining("\n")));
+       }
+}
+----
+
+The tags restrict axe-core to the rules for WCAG 2.0, 2.1 and 2.2 at level A 
and AA. The test checks the page twice: as it loads, and after a failed submit. 
Many pages have states that only exist after an interaction, such as validation 
errors, an open dialog, a panel loaded by AJAX or a table sorted by another 
column, and each of these states needs its own check. Finding the button by its 
role and accessible name, as Playwright's _getByRole_ does, is a small 
accessibility check of its o [...]
+
+=== HTML validation
+
+WCAG 2.2 no longer has a success criterion for valid markup, but invalid 
markup still breaks accessibility: a duplicate _id_ makes a _<label for>_ or an 
_aria-describedby_ point to the wrong element, and a misnested element can 
change the structure that screen readers present. The 
https://validator.github.io/validator/[Nu Html Checker] validates HTML5. It can 
be run from the command line as _vnu.jar_ with the URLs of the running 
application, or with files written by tests from _getLastRe [...]
+
+In development mode Wicket leaves its own tags and _wicket:id_ attributes in 
the markup, which the checker reports as errors. Validate the markup of the 
application in deployment mode, or call 
_getMarkupSettings().setStripWicketTags(true)_ in the test configuration.
+
+=== Checks by hand
+
+No tool replaces the following checks. They take a few minutes per page, and 
they are the ones that find the problems users actually run into.
+
+* *Keyboard.* Put the mouse away and use the page with Tab, Shift+Tab, Enter, 
Space, the arrow keys and Escape. Every function must be reachable and 
operable, the focus must always be visible, it must move in a logical order, it 
must never get stuck, and after every AJAX update it must be somewhere sensible 
(success criteria 2.1.1, 2.1.2, 2.4.3, 2.4.7 and 2.4.11).
+* *Screen reader.* Use the page with NVDA or JAWS on Windows, VoiceOver on 
macOS and iOS, or TalkBack on Android. Check that the title is read when the 
page loads, that headings and landmarks give an overview of the page, that 
every field announces its label and errors, that buttons and links announce 
what they do, and that status messages are announced (success criteria 1.3.1, 
2.4.2, 2.4.6, 3.3.1, 4.1.2 and 4.1.3).
+* *Zoom and reflow.* Zoom the browser to 200%: all text must grow and nothing 
may be cut off or overlap (success criterion 1.4.4). Then make the viewport 320 
CSS pixels wide, which is the same as 1280 pixels at 400% zoom: the content 
must be readable without scrolling in two directions, except for content such 
as data tables that needs two dimensions (success criterion 1.4.10). Increase 
the line, paragraph, letter and word spacing as described in success criterion 
1.4.12 and check that n [...]
+* *Contrast.* Measure the contrast of text, of the borders of fields and 
buttons, of the focus indicator and of icons with a contrast checker, in every 
state: hover, focus, disabled and error (success criteria 1.4.3 and 1.4.11).
+* *Content.* Read the alternative texts, headings, labels, link texts and 
error messages, and check that they make sense on their own (success criteria 
1.1.1, 2.4.4, 2.4.6 and 3.3.3).
+
+The table in <<_wcag_2_2_success_criteria_in_wicket,paragraph 25.2>> lists, 
for each success criterion, what the application has to take care of, and is a 
checklist for the remaining criteria.
diff --git 
a/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_9.adoc 
b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_9.adoc
new file mode 100644
index 0000000000..cee4b18bb7
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/accessibility/accessibility_9.adoc
@@ -0,0 +1,2 @@
+
+WCAG conformance is a property of pages, and most of what makes a Wicket page 
accessible is in the markup and content we write ourselves. Wicket helps with 
labels connected through _wicket:for_, validation messages that name their 
field, table headers and captions, and focus restoration after AJAX updates. 
Where it does not help yet, as with the _lang_ attribute, _aria-invalid_, live 
regions, the sort state of table headers and the default error pages, a few 
lines of code with the curren [...]
diff --git 
a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc 
b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc
index 72c82c58ad..a129969380 100644
--- a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc
+++ b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_1.adoc
@@ -40,7 +40,7 @@ public class RegistrationPage extends Page {
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <body>
     <form wicket:id="form">
         <!-- These are internal structure information from RegistrationForm -->
@@ -114,7 +114,7 @@ public class RegistrationPage extends Page {
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <body>
     <form wicket:id="form">
         <div wicket:id="registration">
diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc 
b/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc
index 7c0509cdce..14b748e370 100644
--- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc
+++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc
@@ -16,7 +16,7 @@ To avoid these kinds of problems we should build a stateless 
login page which do
 
 [source,html]
 ----
-<html>
+<html lang="en">
    <head>
       <meta charset="utf-8" />
    </head>
diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc 
b/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc
index 15e0dddc28..5c9bd778d0 100644
--- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc
+++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_5.adoc
@@ -88,7 +88,7 @@ A notable difference between this component and Button is 
that SubmitLink can be
 
 [source,html]
 ----
-<html xmlns:wicket="http://wicket.apache.org";>
+<html lang="en" xmlns:wicket="http://wicket.apache.org";>
        <head>
        </head>
        <body>
diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc 
b/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc
index df4b6658ff..dda7f2314b 100644
--- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc
+++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_8.adoc
@@ -9,7 +9,7 @@ In the next example (project UploadSingleFile) we will see a 
form which allows u
 
 [source,html]
 ----
-<html>
+<html lang="en">
        <head>
        </head>
        <body>
diff --git a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc 
b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
index 7c70e9f460..a7f8961f03 100644
--- a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
@@ -39,7 +39,7 @@ Here is the HTML markup for _HomePage_ (file HomePage.html):
 [source,html]
 ----
 <!DOCTYPE html>
-<html>
+<html lang="en">
        <head>
                <meta charset="utf-8" />
                <title>Apache Wicket HelloWorld</title>
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc 
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc
index c4231fca86..e664b0a37e 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc
@@ -9,7 +9,7 @@ In the following  example we have defined a fragment in a page 
and we used it as
 
 [source,html]
 ----
-<html>
+<html lang="en">
   ...
 <body>
 ...
@@ -33,7 +33,7 @@ When the page is rendered, markup inside the fragment will be 
inserted *inside d
 
 [source,html]
 ----
-<html>
+<html lang="en">
   ...
 <body>
 ...
@@ -52,7 +52,7 @@ Instead of displaying this message with a new component or in 
a new page, we can
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <body>
        <div wicket:id="contentArea"></div>
        <wicket:fragment wicket:id="formFrag">
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc 
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc
index 77ff7941a8..6d6f329bcc 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_7.adoc
@@ -3,7 +3,7 @@ Wicket's _<wicket:remove>_ tag can be very useful when our web 
designer needs to
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <head>
 
 </head>
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc 
b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc
index 059fab5078..897d27b126 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_8.adoc
@@ -7,7 +7,7 @@ For example given the following markup and code:
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <head>
   <title>Hello world page</title>
 </head>
@@ -30,7 +30,7 @@ the output will be:
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <head>
   <title>Hello world page</title>
 </head>
diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc 
b/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc
index a2f81fa6fd..0813f6fc22 100644
--- a/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc
@@ -65,25 +65,34 @@ Now we can build a generic template page using our brand 
new panels. Its markup
 
 [source,html]
 ----
-<html>
+<!DOCTYPE html>
+<html lang="en" xmlns:wicket="http://wicket.apache.org";>
 <head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-...
+<meta charset="utf-8">
+<title wicket:id="pageTitle">Jug4Tenda</title>
 <!--Include CSS-->
 ...
 </head>
 <body>
-<div id="header" wicket:id="headerPanel">header</div>
+<a class="skip-link" href="#content">Skip to main content</a>
+<header id="header" wicket:id="headerPanel">header</header>
 <div id="body">
-       <div id="menu" wicket:id="menuPanel">menu</div>
-       <div id="content" wicket:id="contentComponent">content</div>
+       <nav id="menu" wicket:id="menuPanel">menu</nav>
+       <main id="content" tabindex="-1" 
wicket:id="contentComponent">content</main>
 </div>
-<div id="footer" wicket:id="footerPanel">footer</div>
+<footer id="footer" wicket:id="footerPanel">footer</footer>
 </body>
 </html>
 ----
 
-The HTML code for this page implements the generic left-menu layout of our 
site. You can note the 4 _<div>_ tags used as containers for the corresponding 
areas.
+The HTML code for this page implements the generic left-menu layout of our 
site. Each layout area gets the HTML element that names its role: _<header>_, 
_<nav>_ for the menu, _<main>_ for the content and _<footer>_. Browsers and 
screen readers expose these elements as landmarks, so users can jump between 
the areas. Three more details make the template usable by everyone:
+
+* the _lang_ attribute on _<html>_ tells browsers and screen readers which 
language the page is written in;
+* the _<title>_ is bound to a _Label_, so that every page can give itself its 
own title;
+* the first link of the page, _Skip to main content_, lets keyboard users jump 
past the header and the menu straight to the content area.
+
+All three are discussed in <<_accessibility,chapter 25>>, which also shows how 
to derive the _lang_ attribute from the session locale instead of writing it in 
the markup.
+
 The page class contains the code to physically assemble the page and panels:
 
 [source,java]
@@ -102,17 +111,24 @@ public class JugTemplate extends WebPage {
        private Component footerPanel;
 
     public JugTemplate(){
+               add(new Label("pageTitle", this::getPageTitle));
                add(headerPanel = new HeaderPanel("headerPanel"));
                add(menuPanel = new MenuPanel("menuPanel"));
                add(footerPanel = new FooterPanel("footerPanel"));
                add(new Label(CONTENT_ID, "Put your content here"));
        }
 
+       protected String getPageTitle() {
+               return "Jug4Tenda";
+       }
+
     //getters for layout areas
     //...
 }
 ----
 
+The title label reads its text from method _getPageTitle_ each time the page 
is rendered, so subclasses override this method to give themselves a title of 
their own.
+
 Done! Our template page is ready to be used. Now all the pages of our site 
will be subclasses of this parent page and they will inherit the layout and the 
HTML markup. They will only substitute the _Label_ inserted as content area 
with their custom content.
 
 === Final example
@@ -159,6 +175,11 @@ public class SimpleLoginPage extends JugTemplate {
                replace(new LoginPanel(CONTENT_ID));
                getMenuPanel().setVisible(false);
        }
+
+       @Override
+       protected String getPageTitle() {
+               return "Login - Jug4Tenda";
+       }
 }
 ----
 
diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc 
b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
index b3c9402cb5..5c09f050b7 100644
--- a/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
@@ -4,7 +4,7 @@ An example of a parent page using the tag _<wicket:child>_ is 
the following:
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
 </head>
@@ -35,7 +35,7 @@ Considering the two pages seen above, the final markup 
generated for child page
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 </head>
@@ -56,22 +56,27 @@ Applying _<wicket:child>_ tag to our layout example, we 
obtain the following mar
 
 [source,html]
 ----
-<html>
+<!DOCTYPE html>
+<html lang="en" xmlns:wicket="http://wicket.apache.org";>
 <head>
-       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+       <meta charset="utf-8">
+       <title wicket:id="pageTitle">Jug4Tenda</title>
 </head>
 <body>
-<div id="header" wicket:id="headerPanel">header</div>
+<a class="skip-link" href="#content">Skip to main content</a>
+<header id="header" wicket:id="headerPanel">header</header>
 <div id="body">
-       <div id="menu" wicket:id="menuPanel">menu</div>
-       <wicket:child/>
+       <nav id="menu" wicket:id="menuPanel">menu</nav>
+       <main id="content" tabindex="-1">
+               <wicket:child/>
+       </main>
 </div>
-<div id="footer" wicket:id="footerPanel">footer</div>
+<footer id="footer" wicket:id="footerPanel">footer</footer>
 </body>
 </html>
 ----
 
-We have replaced the _<div>_ tag of the content area with the tag 
_<wicket:child>_. Going forward with our example we can build a login page 
creating class _SimpleLoginPage_ which extends the _JugTemplate_ page, but with 
a related markup file like this:
+We have replaced the content component inside the _<main>_ element with the 
tag _<wicket:child>_. The _<main>_ element itself stays in the template: it is 
plain markup now, and it is still the target of the skip link. Going forward 
with our example we can build a login page creating class _SimpleLoginPage_ 
which extends the _JugTemplate_ page, but with a related markup file like this:
 
 [source,html]
 ----
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc 
b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc
index 10b7482797..2ad3676d8a 100644
--- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc
@@ -103,7 +103,7 @@ Html:
 
 [source,html]
 ----
-<html>
+<html lang="en">
        <head>
                <title>Login page</title>
        </head>
diff --git a/wicket-user-guide/src/main/asciidoc/repeaters.adoc 
b/wicket-user-guide/src/main/asciidoc/repeaters.adoc
index c77a5f52c5..6d88a824da 100644
--- a/wicket-user-guide/src/main/asciidoc/repeaters.adoc
+++ b/wicket-user-guide/src/main/asciidoc/repeaters.adoc
@@ -3,7 +3,7 @@ A common task for web applications is to display a set of 
items. The most typica
 
 [source,html]
 ----
-<html>
+<html lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>Insert title here</title>
diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc 
b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc
index 7e4032d9a6..fd59fb0c01 100644
--- a/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc
+++ b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc
@@ -4,7 +4,7 @@ Some web developers prefer to put their <script> tags at the 
end of page body an
 [source,html]
 ----
 
-<html>
+<html lang="en">
 
 <head>
 //no <script> tag here...
@@ -51,7 +51,7 @@ Please note that _HeaderResponseContainer_'s needs also a 
name for the correspon
 [source,html]
 ----
 
-<html>
+<html lang="en">
 
 <head>
 <!-- no <script> tag here... -->
diff --git a/wicket-user-guide/src/main/asciidoc/single.adoc 
b/wicket-user-guide/src/main/asciidoc/single.adoc
index 11c5056aa6..bc37beef57 100644
--- a/wicket-user-guide/src/main/asciidoc/single.adoc
+++ b/wicket-user-guide/src/main/asciidoc/single.adoc
@@ -727,6 +727,46 @@ include::testingspring/testingspring_2.adoc[leveloffset=+1]
 
 include::testingspring/testingspring_3.adoc[leveloffset=+1]
 
+== Accessibility
+
+include::accessibility.adoc[]
+
+=== What Wicket does and what the application does
+
+include::accessibility/accessibility_1.adoc[leveloffset=+1]
+
+=== WCAG 2.2 success criteria in Wicket
+
+include::accessibility/accessibility_2.adoc[leveloffset=+1]
+
+=== An accessible base page
+
+include::accessibility/accessibility_3.adoc[leveloffset=+1]
+
+=== Accessible form errors
+
+include::accessibility/accessibility_4.adoc[leveloffset=+1]
+
+=== Focus and announcements after AJAX updates
+
+include::accessibility/accessibility_5.adoc[leveloffset=+1]
+
+=== Keyboard-operable AJAX controls
+
+include::accessibility/accessibility_6.adoc[leveloffset=+1]
+
+=== Accessible data tables
+
+include::accessibility/accessibility_7.adoc[leveloffset=+1]
+
+=== Validating an application
+
+include::accessibility/accessibility_8.adoc[leveloffset=+1]
+
+=== Summary
+
+include::accessibility/accessibility_9.adoc[leveloffset=+1]
+
 == Wicket best practices
 
 include::bestpractices.adoc[]
diff --git a/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc 
b/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc
index d888c9519c..a5d1470385 100644
--- a/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc
@@ -9,7 +9,7 @@ This test class allows to check if the generated markup 
contains one or more tag
 
 [source,html]
 ----
-<html xmlns:wicket="http://wicket.apache.org";>
+<html lang="en" xmlns:wicket="http://wicket.apache.org";>
        <head>
                <meta charset="utf-8" />
                <title></title>
diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc 
b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc
index e1d91ff7a8..2ae53745aa 100644
--- a/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc
@@ -6,7 +6,7 @@ Bookmarkable pages can be linked directly inside markup files 
without writing an
 [source,html]
 ----
 <!DOCTYPE html>
-<html xmlns:wicket="http://wicket.apache.org";>
+<html lang="en" xmlns:wicket="http://wicket.apache.org";>
        <head>
                <meta charset="utf-8" />
                <title>Apache Wicket Quickstart</title>
@@ -34,7 +34,7 @@ If we take a look also at the markup of SubPackagePage we can 
see that it contai
 [source,html]
 ----
 <!DOCTYPE html>
-<html xmlns:wicket="http://wicket.apache.org";>
+<html lang="en" xmlns:wicket="http://wicket.apache.org";>
        <head>
                <meta charset="utf-8" />
                <title>Apache Wicket Quickstart</title>
diff --git 
a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
 
b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
index eb11460212..8beff1303e 100644
--- 
a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
+++ 
b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc
@@ -113,7 +113,7 @@ public void init()
 
 Class _org.apache.wicket.util.lang.Bytes_ is an utility class provided by 
Wicket to express size in bytes (for further details refer to the JavaDoc).
 
-NOTE: More insights on internal page storing will be covered in 
<<internals.adoc#_wicket_internals,chapter 26>>
+NOTE: More insights on internal page storing will be covered in 
<<internals.adoc#_wicket_internals,chapter 27>>
 
 === Page expiration
 

Reply via email to