@meddleware/vitepress-theme 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.2] - 2026-11-01
+
+### Changed
+
+- The fixture's accessibility gate is the shared sweep (`defineA11ySuite`): besides axe at AA and AAA in every colour mode × season it now
+  checks reflow at 320 px, 200% text, forced colours, reduced motion and the keyboard (focus visible and not hidden behind the fixed navigation bar).
+- `SECURITY.md` is part of the published files.
+- **The footer no longer lies under the sidebar.** VitePress's own footer hides on a page with a sidebar; ours stays (it holds the legal links), and the fixed full-height sidebar covered its left edge from 60rem, so the © link could not be seen when focused (WCAG 2.4.11). On such a page the footer now starts where the content does, with VitePress's own offsets. Three width tests in every browser hold it.
+- VitePress 2.0.0-alpha.21 (peer and development pin; the landmark edits and the fixture sweep pass unchanged).
+
+## [0.0.1] - 2026-10-31
+
+### Added
+
+- First release. The VitePress default theme mapped onto `@meddleware/design-tokens` (colour mode, seasons, WCAG AAA contrast), a layout
+  with the Meddleware footer, the `baseConfig` site config, and landmark fixes for the default theme, extracted from the byte-identical
+  copies in docs-site and dev-site.

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 MeddleWare
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @meddleware/vitepress-theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Meddleware [VitePress](https://vitepress.dev) theme and site config. It is the default theme with every colour, surface and font
+taken from [`@meddleware/design-tokens`](https://github.com/meddleware-org/design-tokens), so a site follows the colour mode and the
+seasons and keeps the tokens' WCAG AAA contrast (7:1 for text and labels), plus a footer and the config the sites share.
+
+## Use
+
+```ts
+// docs/.vitepress/theme/index.ts
+export { default } from '@meddleware/vitepress-theme'
+```
+
+```ts
+// docs/.vitepress/config.ts
+import { baseConfig } from '@meddleware/vitepress-theme/config'
+
+export default baseConfig({
+  configUrl: import.meta.url, // docs/ is the source directory, ../dist the output
+  title: 'Meddleware Docs',
+  description: '…',
+  nav: [{ text: 'Guide', link: '/guide' }],
+  sidebar: { '/': [{ text: 'Guide', items: [{ text: 'Overview', link: '/' }] }] },
+  // appearance: 'dark' (default) | true | false, head: [...], extra: { ...anything else VitePress takes }
+})
+```
+
+A site that needs more extends the theme: `{ extends: MeddlewareTheme, enhanceApp() {…} }`.
+
+`baseConfig` sets the language (`en-GB`), clean URLs, the favicon, the browser-chrome colour (from the tokens), local search, the GitHub
+link, the high-contrast syntax themes (with comments as readable as the rest) and `ssr.noExternal` for `@meddleware/*`, which ship Vue
+components that import their own CSS. `themeConfig`, `vite` and `markdown` in `extra` are merged one level down.
+
+## What the theme does
+
+| | |
+| --- | --- |
+| `theme.css` | maps every `--vp-*` colour onto a token role; tone blocks and badges keep body-colour text with the tone as the border; nothing is purple |
+| `MeddlewareLayout.vue` | the default layout plus `AppFooter` and `CopyrightLine` (a `contentinfo` landmark) |
+| `landmarks.js` | a Vite plugin that gives home, `page` and 404 pages a `<main>`, and turns the mid-page doc footer into a `div` (it was a second `contentinfo`); exact edits that fail the build if VitePress changes |
+| `index.ts` | imports the tokens, the seasons and `@meddleware/ui/reset.css`, and sets the season from the calendar |
+
+The reset is declared in a cascade layer, and VitePress's own CSS is unlayered, so it wins wherever it styles an element.
+
+## Peers
+
+`vitepress` (exact: 2.x alpha), `vue`, `@meddleware/ui`, `@meddleware/design-tokens`.
+
+## Development
+
+`npm run build:site` builds the fixture site in `docs/`; `npm run test:e2e` runs axe (WCAG 2.2 AA and AAA) over it in every colour mode ×
+season (`E2E_BROWSERS=all` for five browsers); `npm run shots` captures the screenshot matrix.
+
+## Licence
+
+0BSD.

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Scope
+
+This policy covers `@meddleware/vitepress-theme`: the VitePress theme and site config for MeddleWare documentation sites. It runs at
+build time (the config, and a Vite plugin that edits two components of VitePress's default theme as they compile) and in the browser
+(the theme's components and CSS). It makes no network requests of its own and handles no user data.
+
+It does not cover a consuming site, VitePress, or the content a site publishes.
+
+## What it guarantees
+
+The theme maps VitePress's colours onto the design tokens and fixes two landmark problems in the default theme; its accessibility
+checks are automated (axe, WCAG 2.2 AA and AAA) over a fixture site and are not a substitute for testing a real site with assistive
+technology. The landmark edits are exact string replacements that fail the build, naming the file, if VitePress changes the text they
+rely on.
+
+## Supply chain
+
+Releases are published from this repository's `npm-publish.yml` with npm trusted publishing (OIDC and provenance); tokens are not
+used. The Vite plugin runs in a consumer's build, so a compromised release could run code there: report anything that suggests
+tampering.
+
+## Supported versions
+
+Only the latest published npm version receives fixes.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities. Use GitHub's private vulnerability reporting for this
+repository, or email dev@meddleware.co.uk.

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('vitepress').UserConfig<import('vitepress').DefaultTheme.Config>} SiteConfig
+ */
+/**
+ * @param {object} options
+ * @param {string} options.configUrl `import.meta.url` of the site's `docs/.vitepress/config.ts`: the source directory is `docs/` and the
+ *   output the repository's `dist/` (a Dockerfile copies `dist/` into the static server).
+ * @param {string} options.title
+ * @param {string} options.description
+ * @param {import('vitepress').DefaultTheme.NavItem[]} [options.nav]
+ * @param {import('vitepress').DefaultTheme.Sidebar} [options.sidebar]
+ * @param {'dark' | true | false | 'force-dark' | 'force-auto'} [options.appearance] The colour mode a first visit gets (the toggle always
+ *   works). Default `dark`, the estate's default.
+ * @param {SiteConfig['head']} [options.head] Extra `<head>` entries (the favicon and the browser-chrome colour are always there).
+ * @param {SiteConfig} [options.extra] Anything else, merged over the defaults (`themeConfig` and `vite` are merged one level down).
+ * @returns {SiteConfig}
+ */
+export function baseConfig({ configUrl, title, description, nav, sidebar, appearance, head, extra }: {
+    configUrl: string;
+    title: string;
+    description: string;
+    nav?: import("vitepress").DefaultTheme.NavItem[] | undefined;
+    sidebar?: import("vitepress").DefaultTheme.Sidebar | undefined;
+    appearance?: boolean | "dark" | "force-dark" | "force-auto" | undefined;
+    head?: SiteConfig["head"];
+    extra?: import("vitepress").UserConfig<import("vitepress").DefaultTheme.Config> | undefined;
+}): SiteConfig;
+export type SiteConfig = import("vitepress").UserConfig<import("vitepress").DefaultTheme.Config>;

package/dist/landmarks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A Vite plugin that applies {@link EDITS} to the default theme's components.
+ * @returns {import('vite').Plugin}
+ */
+export function landmarks(): import("vite").Plugin;
+/** @type {Record<string, (code: string) => string>} */
+export const EDITS: Record<string, (code: string) => string>;

package/package.json

@@ -1,6 +1,95 @@
 {
   "name": "@meddleware/vitepress-theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "type": "module",
+  "description": "The Meddleware VitePress theme and config: the default theme mapped onto the design tokens (colour mode, seasons, WCAG AAA contrast), a footer, and a shared site config.",
+  "license": "0BSD",
+  "author": "MeddleWare <dev@meddleware.co.uk>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meddleware-org/vitepress-theme.git"
+  },
+  "keywords": [
+    "vitepress",
+    "theme",
+    "design-tokens",
+    "accessibility"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./src/config.js"
+    },
+    "./theme.css": "./src/theme.css"
+  },
+  "sideEffects": [
+    "*.css",
+    "*.vue"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "type-check": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "build:site": "vitepress build docs",
+    "lint:css": "stylelint \"src/**/*.{css,vue}\"",
+    "lint:js": "eslint .",
+    "lint:html": "html-validate \"src/**/*.vue\"",
+    "lint": "npm run lint:css && npm run lint:js && npm run lint:html",
+    "test:e2e": "npm run build:site && playwright test",
+    "shots": "SHOTS=1 playwright test"
+  },
+  "peerDependencies": {
+    "@meddleware/design-tokens": "^0.1.13",
+    "@meddleware/ui": "^0.1.38",
+    "vitepress": "2.0.0-alpha.21",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@meddleware/design-tokens": "^0.1.13",
+    "@meddleware/frontend-config": "^0.0.2",
+    "@meddleware/ui": "^0.1.38",
+    "@playwright/test": "~1.64.1",
+    "@types/node": "~26.6.5",
+    "@vue/eslint-config-typescript": "^14.9.0",
+    "autoprefixer": "^10.6.2",
+    "eslint": "^10.13.0",
+    "eslint-plugin-vue": "^10.12.0",
+    "eslint-plugin-vuejs-accessibility": "^2.6.3",
+    "html-validate": "^11.17.0",
+    "html-validate-vue": "^9.3.1",
+    "jiti": "^2.7.0",
+    "postcss": "^8.5.32",
+    "postcss-html": "^2.0.0",
+    "stylelint": "^17.16.0",
+    "stylelint-config-standard": "^40.0.0",
+    "typescript": "~6.0.0",
+    "vitepress": "2.0.0-alpha.21",
+    "vitest": "~5.0.5",
+    "vue": "^3.5.44",
+    "vue-eslint-parser": "^10.4.1",
+    "vue-tsc": "~3.3.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "browserslist": [
+    "extends @meddleware/frontend-config/browserslist-config"
+  ],
+  "dependencies": {
+    "shiki": "^4.4.3"
+  }
+}

package/src/MeddlewareLayout.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+// The default layout with the Meddleware footer: the copyright line and the contact of the organisation, in a `contentinfo` landmark.
+import DefaultTheme, { useLayout } from 'vitepress/theme'
+import { AppFooter, CopyrightLine } from '@meddleware/ui'
+
+const { Layout } = DefaultTheme
+// VitePress's own footer hides itself on a page with a sidebar. This one stays (it carries the legal links), so on such a page it starts
+// where the content does, as the content does (theme.css), instead of lying under the fixed sidebar (WCAG 2.4.11).
+const { hasSidebar } = useLayout()
+</script>
+
+<template>
+  <Layout>
+    <template #layout-bottom>
+      <div class="mw-layout-footer" :class="{ 'has-sidebar': hasSidebar }">
+        <AppFooter>
+          <CopyrightLine symbol-variant="kopimi" organisation-name="Meddleware" rights-statement="jam" />
+        </AppFooter>
+      </div>
+    </template>
+  </Layout>
+</template>

package/src/config.js

@@ -0,0 +1,105 @@
+// @ts-check
+// The site config every Meddleware VitePress site shares: its language, URLs, appearance, colours in the browser chrome, local search,
+// social link, the high-contrast syntax themes, and the build settings that let VitePress render the design-system components.
+//
+//   // docs/.vitepress/config.ts
+//   import { baseConfig } from '@meddleware/vitepress-theme/config'
+//   export default baseConfig({ configUrl: import.meta.url, title: 'Meddleware Docs', description: '…', nav, sidebar })
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vitepress'
+import tokens from '@meddleware/design-tokens/tokens.json' with { type: 'json' }
+import githubLight from 'shiki/themes/github-light-high-contrast.mjs'
+import githubDark from 'shiki/themes/github-dark-high-contrast.mjs'
+import { landmarks } from './landmarks.js'
+
+/**
+ * A syntax theme with its comments in `colour`. The high-contrast GitHub themes keep every token at 7:1 except comments (5:1, which
+ * the theme treats as exempt); here a comment is text like any other.
+ * @param {import('shiki').ThemeRegistration} theme
+ * @param {string} colour
+ * @returns {import('shiki').ThemeRegistration}
+ */
+function readableComments(theme, colour) {
+  return {
+    ...theme,
+    name: `${theme.name}-readable-comments`,
+    tokenColors: (theme.tokenColors ?? []).map((t) =>
+      [t.scope ?? []].flat().includes('comment') ? { ...t, settings: { ...t.settings, foreground: colour } } : t,
+    ),
+  }
+}
+
+/**
+ * @typedef {import('vitepress').UserConfig<import('vitepress').DefaultTheme.Config>} SiteConfig
+ */
+
+/**
+ * @param {object} options
+ * @param {string} options.configUrl `import.meta.url` of the site's `docs/.vitepress/config.ts`: the source directory is `docs/` and the
+ *   output the repository's `dist/` (a Dockerfile copies `dist/` into the static server).
+ * @param {string} options.title
+ * @param {string} options.description
+ * @param {import('vitepress').DefaultTheme.NavItem[]} [options.nav]
+ * @param {import('vitepress').DefaultTheme.Sidebar} [options.sidebar]
+ * @param {'dark' | true | false | 'force-dark' | 'force-auto'} [options.appearance] The colour mode a first visit gets (the toggle always
+ *   works). Default `dark`, the estate's default.
+ * @param {SiteConfig['head']} [options.head] Extra `<head>` entries (the favicon and the browser-chrome colour are always there).
+ * @param {SiteConfig} [options.extra] Anything else, merged over the defaults (`themeConfig` and `vite` are merged one level down).
+ * @returns {SiteConfig}
+ */
+export function baseConfig({ configUrl, title, description, nav = [], sidebar = {}, appearance = 'dark', head = [], extra = {} }) {
+  const { themeConfig: extraTheme, vite: extraVite, markdown: extraMarkdown, ...rest } = extra
+  const { light, dark } = tokens.semantic
+  // The browser chrome follows the page: one colour when the site starts dark, a light and a dark one otherwise. Both are the page
+  // background of the tokens, so they cannot drift from the theme.
+  /** @type {import('vitepress').HeadConfig[]} */
+  const chrome =
+    appearance === 'dark' || appearance === 'force-dark'
+      ? [['meta', { name: 'theme-color', content: dark.bg }]]
+      : [
+          ['meta', { name: 'theme-color', content: light.bg, media: '(prefers-color-scheme: light)' }],
+          ['meta', { name: 'theme-color', content: dark.bg, media: '(prefers-color-scheme: dark)' }],
+        ]
+
+  return defineConfig({
+    title,
+    description,
+    lang: 'en-GB',
+    srcDir: fileURLToPath(new URL('..', configUrl)),
+    outDir: fileURLToPath(new URL('../../dist', configUrl)),
+    // The project's security audit lives in docs/audit (the audit corpus convention); it is not site content.
+    srcExclude: ['audit/**'],
+    cleanUrls: true,
+    lastUpdated: false,
+    appearance,
+    head: [
+      ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+      ...chrome,
+      ...head,
+    ],
+    markdown: {
+      // The high-contrast syntax themes with readable comments, so code keeps AAA contrast on the token surfaces in both colour modes.
+      theme: { light: readableComments(githubLight, light.muted), dark: readableComments(githubDark, dark.muted) },
+      ...extraMarkdown,
+    },
+    vite: {
+      ...extraVite,
+      // Landmark fixes for the default theme (see landmarks.js).
+      plugins: [landmarks(), ...(extraVite?.plugins ?? [])],
+      ssr: {
+        ...extraVite?.ssr,
+        // The design-system packages ship Vue components and import their own CSS, which Node cannot load: Vite must process them
+        // while rendering the static pages.
+        noExternal: [/^@meddleware\//, ...(Array.isArray(extraVite?.ssr?.noExternal) ? extraVite.ssr.noExternal : [])],
+      },
+    },
+    themeConfig: {
+      search: { provider: 'local' },
+      socialLinks: [{ icon: 'github', link: 'https://github.com/meddleware-org' }],
+      nav,
+      sidebar,
+      ...extraTheme,
+    },
+    ...rest,
+  })
+}

package/src/env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<object, object, unknown>
+  export default component
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// The Meddleware VitePress theme: the default theme + the design tokens (colour mode, seasons, AAA contrast) + a footer.
+//
+//   // docs/.vitepress/theme/index.ts
+//   export { default } from '@meddleware/vitepress-theme'
+//
+// A site that needs more extends it: `{ extends: MeddlewareTheme, enhanceApp() {…} }`.
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+import { useSeason } from '@meddleware/ui'
+import MeddlewareLayout from './MeddlewareLayout.vue'
+import '@meddleware/design-tokens/tokens.css'
+import '@meddleware/design-tokens/seasons.css'
+import '@meddleware/ui/reset.css'
+import './theme.css'
+
+const theme: Theme = {
+  extends: DefaultTheme,
+  Layout: MeddlewareLayout,
+  enhanceApp() {
+    // Browser only (a no-op while rendering the static pages): the season follows the calendar.
+    useSeason()
+  },
+}
+
+export default theme

package/src/landmarks.js

@@ -0,0 +1,57 @@
+// @ts-check
+// Landmark fixes for the VitePress default theme, applied to its source while Vite compiles it.
+//
+// Two of the default theme's pages fail WCAG's landmark rules, and the theme gives no slot to fix them from outside:
+//  - The home, `page` layout and 404 pages have no `<main>`: their content sits in a `div#VPContent`. The doc layout has its own
+//    `<main>`, so only the other layouts get one (two nested mains would be invalid).
+//  - The doc footer (edit link, last updated, previous/next) is a `<footer>` in the middle of the page, so it is a second `contentinfo`
+//    landmark next to the site footer. It is a plain `div`; the previous/next links are already a named `nav`.
+//
+// Each edit is an exact string replacement that throws when the text is not found: a VitePress upgrade that changes these files
+// fails the build, with the name of the file, instead of silently losing the fix. `tests/landmarks.test.ts` runs the edits against the
+// installed VitePress.
+
+/**
+ * @param {string} code
+ * @param {string} from
+ * @param {string} to
+ * @param {string} file For the error message.
+ */
+function replaceOnce(code, from, to, file) {
+  const first = code.indexOf(from)
+  if (first === -1 || code.indexOf(from, first + 1) !== -1) {
+    throw new Error(`@meddleware/vitepress-theme: cannot patch ${file}: expected exactly one occurrence of ${JSON.stringify(from)} (VitePress changed? update src/landmarks.js).`)
+  }
+  return code.replace(from, to)
+}
+
+/** @type {Record<string, (code: string) => string>} */
+export const EDITS = {
+  'VPContent.vue': (code) => {
+    let out = replaceOnce(code, 'const { isHome, hasSidebar } = useLayout();', "const { isHome, hasSidebar } = useLayout();\nconst landmark = page.value.isNotFound || ['page', 'home'].includes(frontmatter.value.layout) ? 'main' : 'div';", 'VPContent.vue')
+    out = replaceOnce(out, '<div\n    class="VPContent"', '<component\n    :is="landmark"\n    class="VPContent"', 'VPContent.vue')
+    return replaceOnce(out, '<component v-else :is="frontmatter.layout || \'doc\'" />\n  </div>\n</template>', '<component v-else :is="frontmatter.layout || \'doc\'" />\n  </component>\n</template>', 'VPContent.vue')
+  },
+  'VPDocFooter.vue': (code) => {
+    const out = replaceOnce(code, '<footer v-if="showFooter" class="VPDocFooter">', '<div v-if="showFooter" class="VPDocFooter">', 'VPDocFooter.vue')
+    return replaceOnce(out, '</footer>\n</template>', '</div>\n</template>', 'VPDocFooter.vue')
+  },
+}
+
+/**
+ * A Vite plugin that applies {@link EDITS} to the default theme's components.
+ * @returns {import('vite').Plugin}
+ */
+export function landmarks() {
+  return {
+    name: 'meddleware:vitepress-landmarks',
+    enforce: 'pre',
+    transform(code, id) {
+      if (id.includes('?')) return null
+      const normalised = id.replaceAll('\\', '/')
+      if (!normalised.includes('/theme-default/components/')) return null
+      const edit = EDITS[normalised.slice(normalised.lastIndexOf('/') + 1)]
+      return edit ? { code: edit(code), map: null } : null
+    },
+  }
+}

package/src/theme.css

@@ -0,0 +1,166 @@
+/*
+ * The VitePress default theme, mapped onto the Meddleware design tokens.
+ *
+ * Every colour, surface and font of the default theme is a role from @meddleware/design-tokens, so the site follows the colour mode
+ * (VitePress's `.dark` class on <html>, which the tokens honour) and the seasons, and keeps the tokens' WCAG AAA contrast (7:1 for
+ * text and labels) by construction: nothing here is a colour of its own, only a role or a mix of roles.
+ *
+ * Declared on `:root, .dark` and loaded after VitePress's own variables, so it wins over them at equal specificity.
+ *
+ * Tone rules, as in @meddleware/ui: text in a tone colour over a tint of that tone loses contrast, so a tone block or badge keeps
+ * body-colour text and shows the tone as its border. Tinted backgrounds ("-soft") are the --lift surface, on which every text role
+ * is verified at 7:1 by the token checks; only diff and warning lines in code blocks are tinted (they hold syntax-theme colours).
+ * Nothing in the palette is purple (VitePress's "important" tone is the accent here).
+ */
+
+:root,
+.dark {
+  --vp-font-family-base: var(--mw-font-sans);
+  --vp-font-family-mono: var(--mw-font-mono);
+
+  /* Surfaces and text. */
+  --vp-c-bg: var(--bg);
+  --vp-c-bg-alt: var(--lift);
+  --vp-c-bg-elv: var(--surface);
+  --vp-c-bg-soft: var(--surface);
+  --vp-c-border: var(--border);
+  --vp-c-divider: var(--border);
+  --vp-c-gutter: var(--lift);
+  --vp-c-text-1: var(--text);
+  --vp-c-text-2: var(--muted);
+  --vp-c-text-3: var(--muted);
+
+  /* Neutral ("default") family: buttons, code backgrounds. */
+  --vp-c-gray-1: var(--border);
+  --vp-c-gray-2: var(--lift);
+  --vp-c-gray-3: var(--surface);
+  --vp-c-gray-soft: var(--lift);
+
+  /* Brand: the accent. -1 is text on the page, -3 a fill with --accent-contrast text, -2 the hover state (toward the text colour, so
+     contrast only grows), -soft a tint. */
+  --vp-c-brand-1: var(--accent);
+  --vp-c-brand-2: color-mix(in srgb, var(--accent) 82%, var(--text));
+  --vp-c-brand-3: var(--accent);
+  --vp-c-brand-soft: var(--lift);
+
+  /* Tones. */
+  --vp-c-tip-1: var(--secondary);
+  --vp-c-tip-2: color-mix(in srgb, var(--secondary) 82%, var(--text));
+  --vp-c-tip-3: var(--secondary);
+  --vp-c-tip-soft: var(--lift);
+  --vp-c-note-1: var(--secondary);
+  --vp-c-note-2: color-mix(in srgb, var(--secondary) 82%, var(--text));
+  --vp-c-note-3: var(--secondary);
+  --vp-c-note-soft: var(--lift);
+  --vp-c-success-1: var(--ok);
+  --vp-c-success-2: color-mix(in srgb, var(--ok) 82%, var(--text));
+  --vp-c-success-3: var(--ok);
+  --vp-c-success-soft: var(--lift);
+  --vp-c-important-1: var(--accent);
+  --vp-c-important-2: color-mix(in srgb, var(--accent) 82%, var(--text));
+  --vp-c-important-3: var(--accent);
+  --vp-c-important-soft: var(--lift);
+  --vp-c-warning-1: var(--warning-text);
+  --vp-c-warning-2: color-mix(in srgb, var(--warning-text) 82%, var(--text));
+  --vp-c-warning-3: var(--warning-text);
+  --vp-c-warning-soft: var(--lift);
+  --vp-c-danger-1: var(--danger);
+  --vp-c-danger-2: color-mix(in srgb, var(--danger) 82%, var(--text));
+  --vp-c-danger-3: var(--danger);
+  --vp-c-danger-soft: var(--lift);
+  --vp-c-caution-1: var(--danger);
+  --vp-c-caution-2: color-mix(in srgb, var(--danger) 82%, var(--text));
+  --vp-c-caution-3: var(--danger);
+  --vp-c-caution-soft: var(--lift);
+
+  /* Buttons: a brand fill carries the label colour made for it, not white. */
+  --vp-button-brand-text: var(--accent-contrast);
+  --vp-button-brand-hover-text: var(--accent-contrast);
+  --vp-button-brand-active-text: var(--accent-contrast);
+  --vp-button-brand-bg: var(--accent);
+  --vp-button-brand-hover-bg: color-mix(in srgb, var(--accent) 82%, var(--text));
+  --vp-button-brand-active-bg: color-mix(in srgb, var(--accent) 66%, var(--text));
+  --vp-button-alt-text: var(--text);
+  --vp-button-alt-hover-text: var(--text);
+  --vp-button-alt-active-text: var(--text);
+
+  /* Custom blocks and badges: body-colour text; the tone is the border and the tint. */
+  --vp-custom-block-info-border: var(--border);
+  --vp-custom-block-tip-border: var(--secondary);
+  --vp-custom-block-tip-text: var(--text);
+  --vp-custom-block-note-border: var(--secondary);
+  --vp-custom-block-note-text: var(--text);
+  --vp-custom-block-important-border: var(--accent);
+  --vp-custom-block-important-text: var(--text);
+  --vp-custom-block-warning-border: var(--warning-text);
+  --vp-custom-block-warning-text: var(--text);
+  --vp-custom-block-danger-border: var(--danger);
+  --vp-custom-block-danger-text: var(--text);
+  --vp-custom-block-caution-border: var(--danger);
+  --vp-custom-block-caution-text: var(--text);
+  --vp-badge-info-border: var(--border);
+  --vp-badge-tip-border: var(--secondary);
+  --vp-badge-tip-text: var(--text);
+  --vp-badge-note-border: var(--secondary);
+  --vp-badge-note-text: var(--text);
+  --vp-badge-important-border: var(--accent);
+  --vp-badge-important-text: var(--text);
+  --vp-badge-warning-border: var(--warning-text);
+  --vp-badge-warning-text: var(--text);
+  --vp-badge-danger-border: var(--danger);
+  --vp-badge-danger-text: var(--text);
+
+  /* Code: inline code in body colour (links in code keep the accent); blocks on the surface, with the high-contrast syntax themes. */
+  --vp-code-color: var(--text);
+  --vp-code-bg: var(--lift);
+  --vp-code-block-bg: var(--surface);
+  --vp-code-block-color: var(--text);
+  --vp-code-line-highlight-color: var(--lift);
+  --vp-code-line-diff-add-color: color-mix(in srgb, var(--ok) 12%, var(--surface));
+  --vp-code-line-diff-remove-color: color-mix(in srgb, var(--danger) 12%, var(--surface));
+  --vp-code-line-warning-color: color-mix(in srgb, var(--warning-text) 12%, var(--surface));
+  --vp-code-line-error-color: color-mix(in srgb, var(--danger) 12%, var(--surface));
+
+  /* Home hero: the accent into the primary, both of which pass contrast on the page in every look. */
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(135deg, var(--accent), var(--primary));
+  --vp-home-hero-image-background-image: linear-gradient(135deg, var(--accent), var(--primary));
+  --vp-home-hero-image-filter: blur(var(--space-lg));
+}
+
+/* Text enlarged to 200% on a wide screen: the doc columns are laid out in pixels while their content grows, so the main column kept its
+   desktop width and the page scrolled sideways. Letting the flex children of the doc container shrink (and long lines wrap or scroll inside
+   their own blocks) keeps the page at the viewport's width. */
+.VPDoc .container,
+.VPDoc .container > *,
+.VPDoc .content-container,
+.VPDoc .content {
+  min-width: 0;
+}
+.VPDoc .container {
+  max-width: 100%;
+}
+
+/* A feature card on the home page is one link around a title, a description and an action. Links are underlined (a colour is never the only
+   cue), but underlining the whole paragraph makes the card unreadable: the title and the action carry the underline. */
+a.VPFeature {
+  text-decoration: none;
+}
+a.VPFeature .title,
+a.VPFeature .link-text {
+  text-decoration: underline;
+}
+
+/* The footer is below the page content, and the sidebar is fixed and runs the full height of the viewport (from 60rem): on a page that has
+ * one, the footer starts where the content does (the same offsets as VitePress's VPContent), or its links are covered. */
+@media (width >= 60rem) {
+  .mw-layout-footer.has-sidebar {
+    padding-inline-start: var(--vp-sidebar-width);
+  }
+}
+
+@media (width >= 90rem) {
+  .mw-layout-footer.has-sidebar {
+    padding-inline-start: calc((100% - var(--vp-layout-max-width)) / 2 + var(--vp-sidebar-width));
+  }
+}