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

.gitattributes

@@ -5,3 +5,5 @@
 *.svg binary
 *.webp binary
 *.pdf binary
+*.zip binary
+*.woff2 binary

.github/workflows/ui-check.yml

@@ -0,0 +1,30 @@
+name: UI check
+
+on:
+  pull_request:
+    paths:
+      - 'content/supplemental/**'
+      - 'tools/check-css.mjs'
+      - 'tools/check-css.test.mjs'
+      - '.github/workflows/ui-check.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Test the stylesheet check
+        run: node --test tools/check-css.test.mjs
+
+      - name: Check the stylesheets
+        run: node tools/check-css.mjs

AGENTS.md

@@ -94,6 +94,22 @@ See `CONTRIBUTING.md` for the full table. Bypass (rarely) with `git commit --no-
 
 Screenshots are captured at **2x** and declared at half their pixel width (`image::foo.png[width="413"]` for an 826px-wide file), so they stay sharp on high-DPI displays. `tools/screenshot-2x.mjs` does this: it drives Playwright directly with `deviceScaleFactor: 2` and captures a single element, which the Playwright MCP tool cannot do — its resize action takes a width and a height only, so every capture it makes is 1x. Run it with `--url`, `--selector` and `--out`; it prints the resulting pixel size and the width to declare. See the comment at the top of the file for the rest of its options.
 
+A diagram drawn with dark lines on a transparent background disappears in the dark theme. Give its image macro `role=light-background`, as in `image::transactions/transactions-1.png[,500,role=light-background]`, which puts a white plate behind it. Screenshots have their own background and need no role.
+
+## UI: styles, tokens and the pinned bundle
+
+The site uses the Antora default UI bundle pinned in `ui/ui-bundle.zip`. `ui/README.md` says which revision it is and how to update it. The styles are ours and live in `content/supplemental/css/`:
+
+- `tokens.css` holds the design tokens in three tiers: palette, semantic roles, components. The dark theme is the `:root[data-theme="dark"]` block at the end of the file, inside `@media screen` so print stays light. It sets the tier 2 colors and shadow, and the tier 3 colors that must differ in the dark theme (header logo, code, admonitions). No other stylesheet has a rule under `data-theme="dark"`. The only custom properties declared elsewhere are the `--adm-*` aliases in the Admonitions section of `site.css`.
+- `site.css` replaces the bundle stylesheet. Part 1 is the upstream `src/css` of the bundle's revision; change it only to port upstream changes, and override it in part 2 otherwise. Part 2 holds the Jmix styles, one section per component. A section that needs forced colors rules keeps them in its own `@media (forced-colors: active)` block.
+- `search.css`, `dropdown-menu.css` and `feedback-form.css` style the search, the two header menus (version and color theme) and the feedback form.
+- `content/supplemental/js/` holds the scripts that add to the bundle's `site.js`: `a11y.js` (ARIA state, copy button names, the skip link and keyboard access to search results), `code-toolbox.js` (starts a code block below the copy toolbox when the toolbox would cover its first line), `dropdown-menu.js` (the version menu), `theme-menu.js` (the color theme menu) and `feedback-form.js`.
+- The color theme is the `data-theme` attribute (`light` or `dark`) on `<html>`, and `data-theme-preference` holds the reader's choice (`system`, `light` or `dark`). Only `light` and `dark` are saved, in `localStorage` under `jmix-docs-theme`; choosing System removes the key. An inline script at the start of `content/supplemental/partials/head-styles.hbs` sets both attributes and adds a `color-scheme` meta element before the stylesheets load, so the page never shows the wrong theme; keep it before the stylesheet links. `theme-menu.js` changes them later. The DocsBot chat widget that Google Tag Manager adds draws itself for a light page, so `site.css` keeps its host, `#docsbotai-root`, at `color-scheme: light`.
+
+Outside `tokens.css`, write colors as `var(--…)`. Keywords such as `transparent`, `currentColor` and `inherit`, `color-mix()` over keywords and tokens, and the CSS system colors in forced colors blocks are the only exceptions. `node tools/check-css.mjs` rejects other color literals and reports custom properties that are used but never declared. It also makes sure the dark block sets every `--color-*` and `--shadow-*` token of the light block, and only tokens that the light block declares. CI runs it, with its tests (`node --test tools/check-css.test.mjs`), on pull requests that change `content/supplemental/` or the check.
+
+After a UI change, build the site and run `node tools/ui-audit.mjs`. It checks keyboard focus, contrast and the expected styles in both themes, the skip link, accessible names, keyboard access to search results, fonts, forced colors mode, and the color theme: that it is set before the first stylesheet, and how the theme menu behaves. It needs Playwright with Chromium, which is not a dependency of this repository. Run `npx playwright@latest install chromium` once. The built pages load the production analytics container, so check them only through the audit or a Playwright script that blocks external hosts. Do not open them in a browser pane or capture them with `tools/screenshot-2x.mjs`, because neither blocks the container.
+
 ## Conventions
 
 - In multi-locale examples use German (`de`) as the secondary locale.

CONTRIBUTING.md

@@ -180,6 +180,14 @@ pngquant --quality=65-85 --strip --force --ext .png path/to/screenshot.png
 
 Typical reduction for UI screenshots: 70-80% size, no visible quality loss.
 
+### Images in the dark theme
+
+Screenshots keep their own light background in the dark theme, but a diagram drawn with dark lines on a transparent background disappears. Add `role=light-background` to the image macro of such a diagram, for example `image::transactions/transactions-1.png[,500,role=light-background]`, or export it with a white background. Check new pages in both themes by choosing Light and Dark in the theme menu in the header.
+
+## Changing the UI
+
+UI styles live in `content/supplemental/css/`. Use the custom properties from `tokens.css` for colors; `node tools/check-css.mjs` rejects color literals in the other files. A new `--color-*` or `--shadow-*` token needs a value in the dark block of `tokens.css` too; the check reports it when it is missing. Build the site and run `node tools/ui-audit.mjs` before you open a pull request; it needs Playwright with Chromium (`npx playwright@latest install chromium`). The default UI bundle is pinned; see `ui/README.md` before you replace it.
+
 ## Repository history
 
 This repository was created in May 2026 with a fresh history; previous history (including pre-cleanup image revisions) is preserved in the archived repo at [TBD: link to old repo]. Refer there for `git blame` and commit history older than the initial commit.

antora-playbook.ci.yml

@@ -78,8 +78,7 @@ content:
     start_path: doc
 ui:
   bundle:
-    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
-    snapshot: true
+    url: ./ui/ui-bundle.zip
   supplemental_files: ./content/supplemental
 asciidoc:
   extensions:

antora-playbook.yml

@@ -60,8 +60,7 @@ content:
     start_path: doc
 ui:
   bundle:
-    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
-    snapshot: true
+    url: ./ui/ui-bundle.zip
   supplemental_files: ./content/supplemental
 asciidoc:
   extensions:

content/modules/bpm/pages/bpmn/bpmn-events.adoc

@@ -350,7 +350,7 @@ image::bpmn-events/end-event-not-mandatory.png[,250]
 
 Don’t try to bring all flows to the single end event – it only makes your diagram messy.
 
-image::bpmn-events/end-events-examples.png[,500]
+image::bpmn-events/end-events-examples.png[,500,role=light-background]
 
 Multiple end events allow to analyze how processes ended.
 

content/modules/bpm/pages/bpmn/bpmn-service-task.adoc

@@ -221,7 +221,7 @@ If more than one service tasks within a process refer to the same Java Delegate
 for each will be created a separate instance.
 All process instances share the corresponding class instance for the task.
 
-image::bpmn-service-task/java-delegate-instantiating.png[,600]
+image::bpmn-service-task/java-delegate-instantiating.png[,600,role=light-background]
 
 This means that the class must not use any member variables and must be thread-safe, as it can be executed simultaneously from different threads.
 This also may affect xref:field-injections[Fields injection].

content/modules/bpm/pages/bpmn/transactions.adoc

@@ -12,7 +12,7 @@ the engine performs a depth-first search through the process graph
 and will return once it has reached <<waiting-states,waiting states>> on every branch of execution.
 This is illustrated in the following picture:
 
-image::transactions/transactions-1.png[,500]
+image::transactions/transactions-1.png[,500,role=light-background]
 
 We see a segment of a BPMN process with a user task, a service task and a timer event.
 Completing the user task and validating the address is part of the same unit of work,
@@ -52,7 +52,7 @@ in order to be able to scope logical units of work.
 This is where *asynchronous continuations* come into play.
 Consider the following process (fragment):
 
-image::bpm:/transactions/transactions-2.png[,800]
+image::bpm:/transactions/transactions-2.png[,800,role=light-background]
 
 In the next case, we are completing the user task, generating an invoice and then sending that invoice to the customer.
 This time the generation of the invoice is not part of the same unit of work,

content/modules/bpm/pages/dmn-1-3.adoc

@@ -95,7 +95,7 @@ image::dmn/add-input.png[,900]
 
 A business rule is one or more logical conditions based on input parameters, connected by the logical operator 'AND'.
 
-image::dmn/business-rule-full.png[,900]
+image::dmn/business-rule-full.png[,900,role=light-background]
 
 For example, color == "red" AND size > 10.
 

content/modules/bpm/pages/process-artifacts.adoc

@@ -23,7 +23,7 @@ At runtime, for specific branches (or paths) of the process, <<executions,execut
 Finally,
 the process instance can either be transformed into a xref:bpm:history.adoc#historic-process-instances[historic process instance] or deleted.
 
-image::modeling-and-execution/process-artifacts.png[,900]
+image::modeling-and-execution/process-artifacts.png[,900,role=light-background]
 
 Below is a detailed description of the mentioned artifacts:
 

content/modules/flow-ui/pages/views/view-events.adoc

@@ -202,7 +202,7 @@ image::views/close-standard-view.svg[align="center"]
 
 The following diagram shows the process of opening a xref:views/view-classes.adoc#standard-detail-view[detail view]:
 
-image::views/open-detail-view.svg[align="center"]
+image::views/open-detail-view.svg[align="center",role=light-background]
 
 [[closing-entity-detail-view]]
 === Closing Entity Detail View