[dashorst]

Restyles the reference guide in the design of wicket.apache.org and restores syntax highlighting, which the guide has not had: the pom passed <sourceHighlighter>, a parameter asciidoctor-maven-plugin 2.x does not know and ignores, so all of the guide's 500+ listings rendered as plain text. Closes #1844.

The copied 2017 default stylesheet is gone. The plugin's own default stylesheet loads first, and css/wicket.css overrides it through docinfo with the site's tokens, its self-hosted Alegreya and JetBrains Mono fonts and its Rouge colours. The page makes no external requests any more (no Google Fonts, no Font Awesome from cdnjs).

• Code: Rouge through the source-highlighter attribute. Every listing has a language label and a copy button. In HTML samples, wicket:id and the wicket: tags are marked.
• Navigation: a masthead with links to the site, the line's Javadoc and the other versions. The table of contents is drawn as the site's ribbon rail, highlights the section in view and opens only that chapter.
• Blocks: notes and warnings become asides on the tint with an orange rule. Tables get an ink rule above and hairlines between rows.
• Dark mode follows the system setting.

Before and after

Before	After
(no dark mode)

For review

• Core: css/wicket.css, js/guide.js, the three docinfo*.html files, and the pom.xml and single.adoc attribute changes.
• Mechanical: the font files and their licence texts (copied from the site repo), img/wicket-mark.svg, LICENSE and .rat-excludes.
• Licensing: the fonts are SIL OFL 1.1 and are listed in LICENSE next to the example fonts. The Asciidoctor (MIT) entry and licenses/LICENSE-asciidoctor.txt are removed because the copied stylesheet they covered is gone.
• Serif body: the body text is serif again, as on the site, which reverses WICKET-6372.
• Copied tokens: the design tokens are copied from the site's _sass/ribbon/_base.scss and have to be kept in step by hand.
• PDF: keeps its font icons and is otherwise unchanged.

Tested with mvn clean verify -Pjs-test (green) and mvn -pl wicket-user-guide -Pguide generate-resources. The rendered guide was checked at 1440px and 390px, in light and dark mode, in Chromium.

🤖 Generated with Claude Code

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.72%. Comparing base (2c719d9) to head (7c743a4).
⚠️ Report is 18 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1845      +/-   ##
============================================
+ Coverage     62.70%   62.72%   +0.01%     
- Complexity    11507    11514       +7     
============================================
  Files          1254     1254              
  Lines         48660    48665       +5     
  Branches       6844     6845       +1     
============================================
+ Hits          30512    30523      +11     
+ Misses        15468    15467       -1     
+ Partials       2680     2675       -5     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[papegaaij]

A few smaller accessibility points, optional but worth it now that the guide gets an accessibility chapter:

• There's no skip link past the masthead and the 40-plus links of the TOC, and the generated HTML has no <main> or labelled <nav>. A "Skip to content" link in docinfo-header.html that shows on focus, plus role="main" on #content and role="navigation" with aria-label="Table of contents" on #toc from guide.js, would cover it.
• All 539 copy buttons are named "Copy". An aria-label built from the language the bar already shows ("Copy Java code") makes a screen reader's button list usable.
• aria-live on the button itself is announced inconsistently (NVDA often reads it, VoiceOver often doesn't). One visually hidden role="status" element on the page that receives "Copied" is the reliable pattern.

[papegaaij]

Below 640px wicket.css hides the "Apache Wicket" span with display: none, which hides it from screen readers too. The image has alt="", so on a phone this link has no accessible name and is announced as just "link" (WCAG 2.4.4, 4.1.2). An aria-label names it at every width and matches the visible text on wide screens (2.5.3):

Suggested change

	<a class="mast-brand" href="https://wicket.apache.org/"><img src="./img/wicket-mark.svg" alt="" width="30" height="30"><span>Apache Wicket</span></a>
	<a class="mast-brand" href="https://wicket.apache.org/" aria-label="Apache Wicket"><img src="./img/wicket-mark.svg" alt="" width="30" height="30"><span>Apache Wicket</span></a>

[dashorst]

Done in 7c743a4: the brand link has aria-label="Apache Wicket".

[papegaaij]

A chapter's sections open only by scrolling to it. display: none takes them out of the tab order and away from screen readers, so a keyboard user can't reach "Accessibility → Testing" from the TOC: activating the chapter link moves focus into the content, and Shift+Tab from there doesn't lead back to the TOC. Opening a chapter while focus is inside it fixes that for keyboard users. Tabbing onto a chapter link shows its sections, and the next Tab goes into them:

Suggested change

	.js-toc #toc li > ul { display: none; }
	.js-toc #toc li.is-open > ul { display: block; }
	.js-toc #toc li > ul { display: none; }
	.js-toc #toc li.is-open > ul, .js-toc #toc li:focus-within > ul { display: block; }

Two related points:

• guide.js could set aria-current="location" next to the is-current class (and remove it with the class), so the current entry isn't conveyed by colour alone.
• Screen readers in browse mode don't always move focus, so :focus-within doesn't fully help them. A disclosure button with aria-expanded per chapter would, at the cost of more script.

[dashorst]

Done in 7c743a4: :focus-within opens the chapter, and guide.js sets aria-current="location" together with is-current. I left out the disclosure buttons for now. With the skip link, the landmarks and :focus-within, keyboard users can reach every section, so I'd rather see whether browse-mode users actually miss them before adding the extra script.

[papegaaij]

.nl isn't overridden, so CSS property names in the HTML examples (about 23 of them) keep rouge-github's #990000. On the dark code background that is a contrast of about 1.6:1. The token plays the same role as .na:

Suggested change

	pre.rouge .na { color: var(--ribbon-deep); }
	pre.rouge .na, pre.rouge .nl { color: var(--ribbon-deep); }

[dashorst]

Done in 7c743a4: .nl now gets the same colour as .na.

[papegaaij]

Some images have a transparent background with dark lines and text, img/component-lifecycle.png for one; on the dark page its arrows are nearly invisible. A light background for images in dark mode keeps them readable:

Suggested change

	.imageblock img { border-radius: 2px; }
	.imageblock img { border-radius: 2px; }
	@media (prefers-color-scheme: dark) { .imageblock img { background: #fff; } }

[dashorst]

Done in 7c743a4: images get a white background in dark mode.

[papegaaij]

wicket_line has to be bumped by hand at every major release, and adjusted on every cherry-pick to a maintenance line; that's easy to forget, and the masthead and the Javadoc link would then point at the wrong line. It can come from the project version instead. build-helper-maven-plugin is already managed in the root pom; its parse-version goal, added next to the asciidoctor plugin in the guide profile:

<plugin>
	<groupId>org.codehaus.mojo</groupId>
	<artifactId>build-helper-maven-plugin</artifactId>
	<executions>
		<execution>
			<id>parse-version</id>
			<goals>
				<goal>parse-version</goal>
			</goals>
		</execution>
	</executions>
</plugin>

then provides the major version for the attributes here:

Suggested change

	<webfonts>false</webfonts>
	<webfonts>false</webfonts>
	<wicket_line>${parsedVersion.majorVersion}.x</wicket_line>
	<wicket_line_major>${parsedVersion.majorVersion}</wicket_line_major>

I tried it on this branch with mvn -pl wicket-user-guide -Pguide generate-resources: the masthead shows "12.x" and the Javadoc link points at apidocs/12.x. The two attributes in single.adoc can then go.

[dashorst]

Done in 7c743a4: parse-version runs in the guide profile and sets both attributes. The masthead shows 12.x and the Javadoc link points at apidocs/12.x.

[papegaaij]

With wicket_line and wicket_line_major set from the project version in the pom (see the comment there), these two lines can go:

Suggested change

	:wicket_line: 12.x
	:wicket_line_major: 12

[dashorst]

Removed in 7c743a4.

[dashorst]

Thanks @papegaaij. 7c743a4 takes all the inline suggestions and the three general points:

• A skip link is now the first tab stop. #content gets role="main", and #toc gets role="navigation" with aria-label="Table of contents".
• Copy buttons are named after their language ("Copy Java code", or "Copy code" for listings without one).
• "Copied" goes to a single visually hidden role="status" element instead of aria-live on each button.

I checked the result in Chromium: 539 buttons and six distinct labels, one status region, and aria-current on the current TOC entry. A focused chapter link shows its sections.