Restyle the docs UI on design tokens and add a dark theme

[glebfox]

This PR replaces the look of the Antora default UI with our own stylesheet built on design tokens. It also pins the UI bundle and fixes keyboard and forced colors access across the page. It adds a dark theme too, with a menu in the header to choose the color theme.

What changes

• Both playbooks use the pinned bundle ui/ui-bundle.zip (antora-ui-default 0e38223a) instead of the master snapshot, so upstream changes reach the site only when someone takes them. ui/README.md describes how to update it.
• content/supplemental/css/site.css replaces the bundle stylesheet. Part 1 is the upstream src/css of the pinned revision with three kinds of edits: the typeface sections, the removed focus outline resets, and colors replaced with tokens. Part 2 holds the Jmix styles. tokens.css keeps the tokens in three tiers: palette, semantic roles, components.
• The look:
  • a white header;
  • self-hosted Roboto and JetBrains Mono;
  • a navigation with a visible edge and a clear current page;
  • code blocks that look like the IDE: IntelliJ Light colors, titled blocks as editor tabs, the language and the copy button always visible;
  • admonitions in the colors of the logo;
  • restyled tables, pagination cards, feedback form and footer.
• Accessibility:
  • one focus ring on every control;
  • a skip link;
  • names and aria-expanded on the toggles;
  • keyboard access to the search results, "expand all" and the copy button;
  • forced colors support and reduced motion.
• tools/check-css.mjs rejects color literals outside tokens.css, and the new .github/workflows/ui-check.yml runs it on pull requests. tools/ui-audit.mjs checks the built site in Chromium:
  • a focus ring on every Tab stop;
  • the skip link and accessible names;
  • the search keyboard flow;
  • contrast and the expected styles;
  • fonts and forced colors.
• AGENTS.md and CONTRIBUTING.md describe how the UI is organized.

Before	After

Dark Theme

Fixes: #201

The light theme stays as it is; its only visible changes are the menu and a slightly different green for the thumbs-up of the feedback form.

• For readers:
  • a menu button after the search field with three choices: System, Light and Dark;
  • System is the default and follows the operating system, also while the page is open;
  • the choice is saved in the browser and applies to every page and to other open tabs;
  • an inline script sets the theme before the stylesheets load, so the page does not flash the wrong theme;
  • without JavaScript the page stays light and the menu is hidden; print is always light.
• The decisions:
  • the menu button opens a list of the three modes with the current one marked; a button that cycles through them would hide the next mode;
  • the "Ink" palette: dark grays with a slight violet tint, and violet stays the accent;
  • code in the colors of IntelliJ IDEA Dark on its editor background, with the comment color lightened to keep the contrast above 4.5:1;
  • images stay as they are, because a white plate behind every image would put about 270 window screenshots on white rectangles;
  • seven line diagrams that draw dark lines straight on transparency get role=light-background, which puts a white plate behind them;
  • the DocsBot chat widget stays light, because it draws itself for a light page;
  • the theme is a data-theme attribute on <html> and a dark block at the end of tokens.css, so the theme itself needs no component rule changes;
  • component rules change only for XML tags, the image role, the chat widget host, the feedback form and the menu;
  • the thumbs-up of the feedback form is now a mask icon from tokens, so it follows the theme, and its SVG file is removed.
• The checks:
  • tools/check-css.mjs also checks that the dark block sets every --color-* and --shadow-* token of the light block, and only tokens that the light block declares;
  • tools/ui-audit.mjs runs the focus, contrast and style checks in both themes, and its forced colors check now also covers the theme button's icon and the image plate;
  • its new theme check makes sure that the theme is set before the first stylesheet, that it follows the system when storage is blocked, and that it stays light in print;
  • the same check drives the menu with the keyboard and the pointer, and makes sure the page follows other tabs and a system setting that changes;
  • --mask <selector> hides elements in --snapshot and --compare; with the header masked, the light screenshots match the ones taken before this work.

node tools/ui-audit.mjs writes more screenshots to build/ui-audit/: theme-*.png for both themes (the -phone ones at 375px, the others at 1440px) and forced-*.png for forced colors.

Review notes

• The design specs and the implementation plans are not part of the change. If you want the reasoning behind a value, the restyle's are in docs/superpowers/ at 71c3870 and the dark theme's at aa887fb.
• Checked in Chromium only. The build passes, node --test tools/check-css.test.mjs and node tools/check-css.mjs pass, and node tools/ui-audit.mjs passes all 9 checks in both themes. Firefox and Safari still need a look.
• The built pages load the production analytics container. Look at them through tools/ui-audit.mjs or a Playwright script that blocks external hosts.
• No Java changes, so the example projects are not affected. The only content change is role=light-background on seven image macros in six pages.
• The DocsBot chat widget keeps its own light look. Its theme option is set in Google Tag Manager, outside this repository.

[knstvk]

Looks great.
Can we change this?