Architecture & Color System

On-Demand Widget Chunks

js/supa-maven-skin.min.js is a single ES module that every page loads. It holds everything the skin's own chrome needs: the theme engine, Doxia normalization, Highlight.js, search, the TOC, and the Bootstrap 6 plugins behind the header menus, tooltips, drawers, search dialog, and ScrollSpy, plus the small data-API plugins (Alert, Button, Collapse, Popover, Toast, Toggler) that cost a few hundred bytes each. The widgets that only author content uses ship as separate chunks beside it, and bootstrap-components.ts imports each one with import() only when the page contains its markup (LAZY_WIDGETS):

Before the split, the single bundle was 100.5 KiB gzip of its 104 KiB budget. The Datepicker and its calendar library alone added about 18.5 KiB of that, highlight.js and its 18 languages about 29 KiB, the Component Playground 2.4 KiB, and each other widget plugin 0.7–2.7 KiB. Highlight.js stays in the entry because most documentation pages have code blocks, and loading it later would show the code unhighlighted first. Moving the widgets out brought the entry to 68.6 KiB gzip.

The chunks need no configuration and no extra request on pages without those widgets:

• Resolution. import() resolves against the importing module's own URL, so the chunks load from js/ beside the entry on pages at any directory depth. Their names are unhashed, like the skin's other assets, because the JAR is versioned as a whole.
• One copy of shared code. Each chunk imports what it shares with the skin (Bootstrap's base-component.js, the dom/data.js instance map that bootstrap-components.ts patches to allow one instance per plugin on an element, Menu, and the skin's own helpers) from js/supa-maven-skin.min.js itself, so the page keeps one instance of each module. A code-splitting group in vite.config.ts keeps all of it in the entry, and a guard plugin fails the build if the entry gains a static import or Rolldown splits off a shared chunk that every page would have to fetch as a second script.
• Failure tolerance. A chunk that cannot load (offline, not deployed, blocked by a Content Security Policy) logs one console warning, and its markup stays plain HTML: a datepicker is an ordinary text field, a carousel shows its first slide. The rest of the skin is unaffected.
• Readiness. initSupaSkin() sets html[data-supa-ready] only after every widget chunk the page needed has loaded and initialized (or failed), the same way it waits for Mermaid and KaTeX. Each lazily loaded plugin joins window.bootstrap when its chunk loads.

Bundle Size Budget

Every consumer site downloads css/supa-maven-skin.min.css and js/supa-maven-skin.min.js on every page, and the widget chunks on the pages that use them, so their size is guarded like contrast is. After Vite finishes, npm run build runs scripts/check-bundle-size.ts, which prints the raw and gzip size of each file and fails when the CSS bundle, the JS entry, or the widget chunks together exceed their gzip budget, or when a script in js/ falls under no budget. The shared budget for the chunks means weight moved out of the entry into a chunk, or a new chunk, still has to fit. Maven's vite-build execution runs npm run build, so mvn verify fails on a size regression too. The budgets live in the BUDGETS constant of that script: each was the gzip size measured with the Node version Maven pins in pom.xml, plus about 5% headroom, rounded up to a whole KiB, and the CSS and JS entry budgets were later raised once, by 4 KiB and 2 KiB, for the planned accessibility fixes. A change that legitimately grows a bundle raises the budget in the same change and states the new size and its cause in CHANGELOG.md.

Packaged JAR Layout & META-INF/ License Isolation

Because doxia-site-renderer extracts all non-META-INF/ files from a skin JAR directly into a consumer project's target/site/ directory, supa-maven-skin.jar keeps only runtime web assets (css/supa-maven-skin.min.css, css/fonts/bootstrap-icons.woff2, css/fonts/bootstrap-icons.woff, js/supa-maven-skin.min.js, and the js/supa-maven-skin-*.min.js widget chunks) at the JAR root. All Velocity templates, Maven descriptors, and license files are packaged under META-INF/:

• META-INF/maven/site.vm, META-INF/maven/site-macros.vm, META-INF/maven/skin.xml — Velocity layout, macros, and skin descriptor.
• META-INF/LICENSE — The project's own MIT License.
• META-INF/THIRD-PARTY-LICENSES.txt & META-INF/licenses/LICENSE-*.txt — Bundled upstream license notices for every npm package compiled into the CSS bundle, the JS entry, or a widget chunk: bootstrap (MIT), bootstrap-icons (MIT), highlight.js (BSD-3-Clause), and Bootstrap 6's peer dependencies vanilla-calendar-pro, @floating-ui/dom, @floating-ui/core, and @floating-ui/utils (MIT). The list lives in scripts/bundled-licenses.ts, and the build fails when any emitted file contains a package it does not list: JS packages are found from the module graph of every chunk and Sass packages from the partials' @use specifiers, so a new transitive dependency cannot ship without its notice.
• /*! ... */ Bundle Legal Banners — css/supa-maven-skin.min.css, js/supa-maven-skin.min.js, and every widget chunk begin with a /*! ... */ copyright and license attribution header referencing META-INF/LICENSE. The stylesheet and the entry name every package the skin bundles; a chunk names only the packages compiled into it (the Datepicker chunk names bootstrap and vanilla-calendar-pro), each with a pointer to META-INF/THIRD-PARTY-LICENSES.txt.

How the Contrast Audit Works

scripts/lint-scss.ts compiles main.scss with Dart Sass and hands the CSS to scripts/contrast-audit.ts. For each palette and polarity, the audit collects the custom properties that apply to <html> the way the browser's cascade does (matching selector, specificity, source order), then resolves var(), light-dark(), rgb(), oklch(), relative oklch(from ...) colors (which Bootstrap 6 uses to darken button states), and color-mix() in OKLCH or sRGB down to sRGB. The resolver reproduces Chromium's rendering, including its rule that a near-neutral color mixed in OKLCH has no hue, so the colors it measures are the colors the page paints.

What it measures is the SURFACE_AUDITS list: each surface's background layers, written as the CSS the painting rule uses, and every foreground drawn on it:

The .theme-<name> rows mirror Bootstrap 6's component rules and the skin's overrides of them in _bootstrap-supa.scss. A pressed (:active) button keeps its hover colors, because Bootstrap applies the toggled-on colors only to .active, .show, and checked .btn-check buttons. An element drawn at reduced opacity is composited as a group over the surface beneath it, so its fill and its text both fade, as axe measures them.

Bootstrap derives these states by darkening (oklch(from ... calc(l * .95) ...)), which raises text contrast on a light fill and lowers it on a dark one, and from bg-muted fills that are darker than the subtle fill in light mode. Three fixes keep every state at its target: in dark polarity, hovered and toggled-on text and subtle buttons keep their resting text color; the modus* schemes move each theme's --<name>-bg-muted halfway from its subtle fill to the page, where text that meets 7:1 on both still does; and Bootstrap's dark secondary and inverse muted fills, which were lighter than the text drawn on them, step toward the page in every scheme.

The Datepicker calendar is vanilla-calendar-pro drawn by Bootstrap 6's own [data-vc] rules, whose --datepicker-* tokens read the --bg-* and --fg-* steps. Bootstrap fades the days outside the shown month to 50% and the days inside a selected range to 80%, which left day numbers at 3.4:1 in furo light and 5.3:1 in modus dark. Both are buttons that pick a date, so _bootstrap-supa.scss keeps them opaque and marks a day outside the month with the muted text of the weekday names. A disabled day fades to 50% instead: Bootstrap marks it only with --fg-4, which the skin also sets to the muted text, and a disabled control is exempt from the contrast minimum. The skin also makes the calendar inherit the page's color-scheme: Bootstrap gives the calendar its own light dark, which followed the operating system rather than the page once a reader switched from auto to an explicit theme. Every token resolves on <html>, so no color depends on that today, but a light-dark() declared on the calendar, and the browser's own colors, would.

Article links use --color-brand-content, including links inside alerts and custom admonition titles, which keep their inline markup. Solid themed card-header and card-footer links use --theme-contrast with the cap text, so the audit measures that ink on each theme fill. Translucent backgrounds, such as the rgba() admonition tints of the furo and bootstrap dark polarities, those palettes' inline-code backgrounds, and the table row tints Bootstrap paints as an inset box-shadow, are alpha-composited over the layer beneath before measuring. Over a solid themed fill, a translucent inline-code background lets the saturated color through under page-colored text (as low as 1.01:1), so _content.scss lays inline code in a themed .card-header or .card-footer (not in a .card-subtle or .card-translucent card, whose caps paint their own fill) or an active .list-group-item over the page color, and the audit measures that stack. The internal --supa-solid-code-background value follows theme inheritance: .theme-reset clears it, and a theme inside the reset restores it. The audit cannot see the rule itself, so the inline-code-solid-fills scenario below measures it rendered. An undefined layer counts as transparent, as it does in CSS, which is why --color-admonition-background (defined by no built-in palette) still sits in the title bar's stack: a palette that defines it is measured with it.

Dart Sass compiles [data-supa-palette="furo"] to [data-supa-palette=furo], so the audit fails when it cannot find a palette's rule instead of silently measuring nothing, and its success line states how many foreground/surface pairs it checked (currently 3,384). To cover a new surface, add an entry to SURFACE_AUDITS.

Modus Palette Overrides

Bootstrap 6's own grays and state fills fall short of 7:1 in places, so the four modus* schemes override them. A site author can still set any of these tokens in <lightCssVariables> and <darkCssVariables>; this section explains why the defaults differ.

• Secondary theme. .theme-secondary text and subtle surfaces (secondary alerts, outline buttons, and subtle badges) follow color-foreground-muted on color-background-secondary. Dark solid secondary fills (buttons, badges, avatars) use Modus Vivendi's #505050 mode-line gray (#484d67 in modus-tinted) under white.
• Inverse theme. Light .theme-inverse subtle surfaces in modus-tritanopia use color-background-item, because Bootstrap's light inverse surface leaves the teal link at 6.9:1.
• Muted fills. The muted fills of hovered chips, nav links, and list-group actions (--<theme>-bg-muted) sit halfway between each theme's subtle fill and color-background-primary.
• State tokens. Hovered sidebar links keep color-foreground-primary. The current page's brand tint (supa-nav-active-bg) is mixed into color-background-primary instead of laid over the sidebar; dark modus-tinted uses 4% instead of 12%, because 12% matched the sidebar. Hovered unthemed buttons and chips (supa-bg-active) use Modus Vivendi's #535353 gray (#4a4f69 in modus-tinted) in dark polarity, and a hovered selected chip stays opaque (supa-chip-selected-hover-opacity is 1).

In every scheme, Bootstrap's dark .theme-secondary and .theme-inverse muted fills step toward the page, because Bootstrap's own were lighter than the text on them. The audit above measures each of these states.

The themed range slider is a different kind of rule: it applies in all six schemes, and it is a component rule on .form-range in _bootstrap-supa.scss, not a token that <lightCssVariables> or <darkCssVariables> can set. An enabled themed range keeps neutral thumb and fill colors (color-foreground-primary), except .theme-inverse, because the other theme fills fail the non-text target in at least one palette variant.

Build-Time Tokens vs. Rendered-Page Checks

Accessibility is verified in two layers that catch different classes of bugs:

npm run test:a11y serves target/site/ from an in-process Node server and opens it in headless Chromium (Playwright), or in Firefox or WebKit on request (below). It scans every top-level page (docs and maven-project-info-reports-plugin reports) in furo light and dark at 1440×900, index.html in all 12 palette × polarity variants (seeded through the same supa-theme / supa-palette localStorage keys the <head> script reads), and index.html at a 390×844 phone viewport. Before scanning it waits for html[data-supa-ready="true"], which initSupaSkin() sets once every enhancer, including the asynchronous Mermaid/KaTeX loaders and the on-demand widget chunks, has settled. Any violation fails the run with the page, variant, rule ID, impact, target selector, and help URL.

The AA tags check text contrast at 4.5:1 only, so every modus* job, page scans and interaction scenarios alike, also runs axe's color-contrast-enhanced rule (WCAG 1.4.6, 7:1 for text). It is the only AAA rule enabled. Before scanning, the run reads the palette's --supa-wcag-level from the page and fails if it disagrees with the AAA palettes the script lists, so a scan never measures a palette against the wrong target. The runner prints the scanned variant totals for the current matrix at the end of each run.

Every scan except the scoped ones described below also checks WCAG 2.5.3 Label in Name on each visible color-scheme trigger (.supa-palette-btn): its accessible name must contain the scheme name it shows, as “Color scheme: Furo (AA)” contains “Furo (AA)”, so a voice-control user can activate it by saying what they see. axe's own label-content-name-mismatch rule runs under wcag21a, but it drops parenthesized text before comparing, so it passed a trigger that showed “Furo (AA)” and was named “Accessible color scheme: Furo Default (AA)”.

In the Datepicker's month view, axe's own rule does catch the mismatch (the datepicker-months scenario below): vanilla-calendar-pro shows each month's short name (“Jan”) but sets the long one (“January”) as the button's aria-label. When the Datepicker chunk loads, bootstrap-components.ts adds an onCreateMonthEls hook to Bootstrap's Datepicker.Default.vcpOptions, which Bootstrap hands to every calendar it creates, and the hook removes that label, so the browser names each button by its text in any locale. The calendar calls the hook for every month each time it draws the month view, after a trip through the year view or a re-render too, so no MutationObserver is needed. Removing the label rather than copying the text into it keeps a single source for the name, and a button without text keeps its label. A picker given its own vcpOptions, in script or through a data-bs-vcp-options or data-bs-config attribute, replaces Bootstrap's defaults whole, hook included, which the Components page tells authors how to avoid.

Every unscoped scan also fails when two elements on the page share an id. A fragment link reaches only the first of them, so a heading ID, or an anchor that prepareHeadings() adds, that repeats another ID would send links to the wrong place. axe's own duplicate-id rule is deprecated, as WCAG 2.2 dropped success criterion 4.1.1 Parsing, and no longer runs under the WCAG tags.

Before every scan, the run waits for the page's running CSS transitions to finish, so axe measures settled colors rather than a fade: a search result leaving the active state switches its title color at once while its fill fades, and a scan taken mid-fade measured brand text on the hover fill. The run also waits for the page to stop scrolling, and repeats the wait until two frames pass with no scroll and no transition: a smooth scroll that outlasts a scenario's setup carries code blocks under the resting pointer, and the language label each one hides on hover would otherwise be measured halfway through its fade. Animations are not awaited, since a spinner never ends.

A page scanned right after load shows the skin's chrome closed, so the same run also scans interaction scenarios, by default in furo light, furo dark, and modus dark (AAA); a scenario can list its own palette × polarity variants instead. Each scenario names a page and viewport, drives the page with Playwright locators, the keyboard, and the mouse, and then scans it:

Every scenario asserts its state (dialog[open], aria-expanded="true", a visible tooltip, the focused or hovered element, the print layout, where a linked heading landed) after setup and again after the scan, so a broken selector or a state that closed mid-scan fails the run instead of quietly scanning the closed page. The “Copied!” state resets after 1.8 seconds, so that one scenario scans only the code blocks and the “Copied!” tooltip that Bootstrap appends to <body>, a hover scenario scans only the hovered component, datepicker-open only the calendar and its field, and datepicker-range-switched and datepicker-months only the calendar. forced-colors-controls-tabs scans only the checkbox, switch, range, and content tabs, and range-tooltip and forced-colors-tooltip only the range slider's value bubble; unscoped forced-colors-pages scans check axe rules on every page. axe has no non-text contrast rule, so scoped pixel and computed-style assertions cover control cues. The documentation-channels-* scenarios scan only the channel navigation. The unchanged rest of those pages is covered by the normal-mode load-time scans.

The sidebar drawer's color-scheme control is a native <select> rather than the menu used in the headers: opened from the bottom of the drawer, the floating menu covered all but slivers of the navigation links above it (axe target-size, WCAG 2.5.8), so a tap meant to dismiss it could follow a half-hidden link. The browser draws a native picker outside the page, so there is no open state for axe to scan.

The rendered-page check needs a browser, so it is deliberately not part of npm test or the Maven build: consumer sites and mvn verify never download Chromium. Build the self-site first (mvn -B -ntp clean verify site), install Chromium once (npx playwright install chromium), then run npm run test:a11y (append page or scenario names, such as npm run test:a11y -- team.html or npm run test:a11y -- palette-menu, to narrow the scan while iterating).

The run uses Chromium unless asked otherwise, and CI runs it only there. npm run test:a11y -- --engine firefox or --engine webkit (or the A11Y_ENGINE environment variable, which the flag overrides) runs the same matrix in that Playwright engine, after a one-time npx playwright install firefox webkit, so a regression in one of them, such as a lost scroll position, can fail a run. --variants furo/light,furo/dark,modus/dark keeps only the listed palette × polarity variants, for every page scan and scenario alike. A scenario declares the engines it supports, all three by default, and another engine skips it, printing the reason once per scenario rather than per variant:

• Chromium only: every forced-colors-* scenario, since WebKit matches (forced-colors: active) without forcing colors and Firefox's emulated palette is not a high-contrast theme; copy-button-copied, since Firefox and WebKit do not grant clipboard permissions; and print-index-auto and print-kitchen-sink-auto, since Firefox reports a light color-scheme preference under print media.
• Not WebKit: palette-menu and documentation-channels-*-open, which Tab between links and buttons, and WebKit's default keyboard mode, like Safari's, skips both. Firefox makes the scrolling version list of documentation-channels-*-open a tab stop of its own, with a focus ring, so that scenario presses Tab once more when focus lands on the list.

Zero-FOUC Initialization

An inline script in <head> reads localStorage.getItem('supa-theme') (light, dark, auto) and localStorage.getItem('supa-palette') before first paint, setting data-bs-theme, data-supa-resolved-theme, and data-supa-palette on <html>. If the user has not chosen a palette and their OS reports prefers-contrast: more, the skin automatically escalates to the WCAG AAA modus palette.