tosijs-ui 1.16.40 → 1.17.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 1.17.0-beta.1
+
+> Prerelease, published under the `beta` dist-tag: install with `tosijs-ui@beta`. `latest` stays
+> on 1.16.41. It carries the accessibility half of 1.17.0; the SEO work and #245/#246 follow.
+
+- **An opt-in accessibility mode for doc sites (#3521).** `accessibility: 'wcag22-aa'` in the
+  site config makes the build do what it can decide on its own and report what it cannot, on the
+  site, in print and in the ePub:
+  - an image alone in its paragraph, followed by an italic-only paragraph, renders as a
+    `<figure>` with that text as its `<figcaption>`;
+  - every page has exactly one `<h1>`, its title: a page's first heading is promoted when its
+    title came from it, a later `#` becomes `##`, and the rest shift to start at `##`;
+  - the build lists, by file and line, each image with no alt text and no caption, each heading
+    that skips a level, and each link named "here" or the like, and fails on them under `strict`.
+
+  Off by default; a site that does not set it renders exactly as before.
+- **The mode audits the built site with axe.** A full build opens every page in Chromium and runs
+  axe-core's WCAG 2.2 AA rules, listing each failure by page, rule and element and failing under
+  `strict`. It needs `playwright` and `axe-core` in your project; without them the build says the
+  audit did not run rather than reporting a pass. Never under a dev server.
+- **Accessible ePubs (#3522).** In the mode, the book's package document declares its access
+  modes, features, hazards and a summary (EPUB Accessibility 1.1), derived from the build: it
+  claims alternative text only when every image has alt text or a caption. Conformance to WCAG
+  2.2 AA is claimed only when DAISY Ace, installed in your project, has checked the finished book
+  and passed it. `epub: { accessibility: { summary, hazards, certifiedBy } }` overrides the
+  defaults. Checked against real Ace: this site's own book passes.
+- **Every ePub, mode or not: the right language, readable links, landmarks.** Each chapter, the
+  nav, the contents and the cover said `xml:lang="en"` whatever the book's language, and the
+  package said none, so a reading system pronounced a French book as English. Links were
+  `#0088cc` (3.9:1 on white) and marked by colour alone; they are now 6.6:1 and underlined.
+  The nav gains a landmarks list (cover, contents, start of the text) and its table of contents
+  `role="doc-toc"`.
+- **`altText`: a hook that supplies alt text for undescribed images.** With the mode on, it is
+  called for each image the build would report, and its answer becomes that image's alt text in
+  the built site, `docs.json` and the ePub. It never writes a source file. It runs on every
+  build, so cache anything slow by `src`.
+- **The doc-site search trigger's name contains its visible text (#3569).** Its `aria-label`
+  was "Search (⌘K)" beside visible text "Search ⌘K", which fails WCAG 2.5.3 (a voice-control user
+  says what they see) on every page of every doc site. A `<tosi-palette>` field trigger is now
+  named by its text, an icon trigger keeps an `aria-label`, and the shortcut is announced through
+  `aria-keyshortcuts`. The frame's axe test now runs every WCAG 2.2 A and AA rule, not four.
+- **The header's site name is no longer a heading.** It was an `<h2>` above every page's own
+  `<h1>`, so it was each page's first heading. It is now `<span class="site-name">` and looks the
+  same; site CSS that styled `header h2` should target `header .site-name`.
+
+## 1.16.41
+
+- **A `noindex` page is left out of `llms.txt`.** The sitemap and the markdown copies already
+  left it out, but `llms.txt` still listed it, so an agent reading the index was sent to pages
+  the author had asked not to be found.
+- **Every page on ui.tosijs.net has a written description, and the terse titles say what the
+  component is.** 63 pages described themselves with whatever their first paragraph said ("A
+  mapboxgl wrapper.", sentences cut off at 155 characters), which is what search results, link
+  previews and `llms.txt` showed. Short nav labels such as "map" and "table" keep their place in
+  the nav and get a fuller `<title>` through `headTitle`. The kitchen sink and the two layout
+  demo pages are `noindex`. The practice behind the rewrite is proposed for the shared coding
+  practices (tosijs-coding-practices #3561).
+
 ## 1.16.40
 
 - **An example with no script runs under a strict CSP (#245, #246).** A pure-HTML example still

package/bin/make-icon-data.js

@@ -86,7 +86,7 @@ byte-identical files, so it never shows up as spurious diff noise.
 > your prettier config, which it now honours) — not the output.
 */
 
-/*{ "parent": "icons", "order": 30 }*/
+/*{ "parent": "icons", "order": 30, "description": "A build tool that turns folders of SVG files into the icon-data module behind the tosijs-ui icon system, optimizing the paths as it goes." }*/
 
 import fs from 'fs'
 import path from 'path'

package/bin/release-notes.ts

@@ -60,7 +60,7 @@ commit whose diff never touched the file it named. Cheap to detect, and the fail
 catches is expensive.
 */
 
-/*{ "parent": "Appendices" }*/
+/*{ "parent": "Appendices", "description": "tosijs-release-notes builds CHANGELOG sections from tagged bullets in commit messages, and fails a release when one is left unwritten." }*/
 
 import { $ } from 'bun'
 import {

package/dist/ab-test.js

@@ -75,7 +75,7 @@ randomize()
 - `condition` attribute determines which value in `AbTest.conditions` controls the element
 - `not` reverses the condition (so `<tosi-ab not condition="foo">` will be visible if `conditions.foo` is `false`)
 */
-/*{ "parent": "Helper Libraries" }*/
+/*{ "parent": "Helper Libraries", "description": "<tosi-ab> shows or hides content by condition, so you can run A/B tests or feature flags by setting AbTest.conditions." }*/
 import { withAttributes } from 'tosijs';
 const abTestConditions = {};
 export class AbTest extends withAttributes({

package/dist/affix.js

@@ -142,7 +142,7 @@ and `describePlacement({ position, inside })` convert between the attribute and
 `{ position, inside }`, and `affixCell(placement)` gives the grid cell and alignment a
 placement takes.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-affix> attaches a toolbar, badge or caption to one edge of its content, laid out beside it rather than floated, so it never covers it." }*/
 import { Component, elements } from 'tosijs';
 const { slot } = elements;
 const POSITIONS = new Set([

package/dist/babylon-3d.js

@@ -220,7 +220,7 @@ be used to load `.glb` files. Setting `src` calls this for you on connect.
 
 `<tosi-3d>.loadUI(options: B3dUIOptions)` loads babylonjs guis, which you can create programmatically or using the [babylonjs gui tool](https://gui.babylonjs.com/).
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-3d> Babylon.js wrapper (deprecated) — tosijs-ui", "description": "Deprecated: <tosi-3d> is a thin Babylon.js wrapper kept for compatibility. New 3D work should use the tosijs-3d package." }*/
 import { elements, withAttributes } from 'tosijs';
 import { scriptTag } from './via-tag.js';
 import { icons, svg2DataUrl } from './icons.js';

package/dist/bodymovin-player.js

@@ -101,7 +101,7 @@ And of course just access the element's `animation` property to [use the bodymov
 
 Also see the [documentation for advanced interactions](https://lottiefiles.github.io/lottie-docs/advanced_interactions/)
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-lottie> Lottie animation player — tosijs-ui", "description": "<tosi-lottie> plays Lottie (bodymovin) animations like an <img>: set src or json, and use the bodymovin API through its animation property." }*/
 import { withAttributes } from 'tosijs';
 import { scriptTag } from './via-tag.js';
 export class BodymovinPlayer extends withAttributes({

package/dist/carousel.js

@@ -68,7 +68,7 @@ This is a minimalist carousel component that supports the usual stuff.
 
 <tosi-css-var-editor element-selector="tosi-carousel"></tosi-css-var-editor>
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "A minimal carousel with optional arrows and dots, several items per page, looping, and auto-advance that holds still while someone is looking." }*/
 import { elements, vars, withAttributes } from 'tosijs';
 import { icons } from './icons.js';
 import { prefersReducedMotion } from './reduced-motion.js';

package/dist/code-editor.js

@@ -111,7 +111,7 @@ Only `@codemirror/state` and `@codemirror/view` are re-exported — the two you
 view. The language, lint and search packages are internal composition details; ask if you need
 one exposed.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-code> CodeMirror 6 code editor — tosijs-ui", "description": "<tosi-code> embeds a CodeMirror 6 editor for JavaScript, TypeScript, CSS, HTML and Markdown, with undo, a diff view and a change event." }*/
 import { elements, varDefault, withAttributes, } from 'tosijs';
 import { tosiDiff } from './diff.js';
 const { div } = elements;

package/dist/color-input.js

@@ -27,7 +27,7 @@ colorInput.addEventListener('change', () => {
 
 <tosi-css-var-editor element-selector="tosi-color"></tosi-css-var-editor>
 */
-/*{ "parent": "Form Components" }*/
+/*{ "parent": "Form Components", "description": "<tosi-color> is a colour input that also edits opacity, so it can produce translucent colours that the native colour picker cannot." }*/
 import { Component, elements, Color, vars, } from 'tosijs';
 const { input } = elements;
 const defaultColor = Color.fromCss('#8888');

package/dist/crud.js

@@ -304,7 +304,7 @@ for every instance; each one re-checks it the next time it is resized.
 - `change` — the selection or the saved record changed.
 - `error` — a store operation failed.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-crud> pairs a searchable table with a schema-driven form over a store you supply (REST, IndexedDB or an array) for list-and-edit screens." }*/
 import { elements, withAttributes } from 'tosijs';
 import { tosiTable } from './data-table.js';
 import { tosiSchemaForm } from './schema-form.js';

package/dist/data-table.js

@@ -1241,7 +1241,7 @@ As well as any column names you want localized — these are also used as the ac
 (`aria-label`) of each editable cell, so an editable table wants them present even if you are
 happy with the untranslated headers.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-table> virtual data table — tosijs-ui", "description": "A virtual data table for very large datasets: sortable, resizable, pinnable columns inferred from the data, keyboard navigation and row detail." }*/
 import { elements, vars, varDefault, tosiValue, getListItem, getListBinding, tosi, withAttributes, } from 'tosijs';
 import { trackDrag } from './track-drag.js';
 import { naturalSorter } from './natural-compare.js';

package/dist/dialog.js

@@ -143,7 +143,7 @@ preview.append(
 ```
 
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-dialog> wraps the native <dialog> element with an OK button, a footer slot, and promise-based alert, confirm and prompt helpers." }*/
 import { Component, elements, on, vars, varDefault } from 'tosijs';
 import { findHighestZ } from './track-drag.js';
 const { dialog, button, header, footer, tosiSlot, h3, p, label, input, div } = elements;

package/dist/diff.js

@@ -101,7 +101,7 @@ and writable if you want to drive it yourself. Resolutions **reset when either t
 changes** — decisions belong to the diff they were made about.
 
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-diff> shows a unified, line-by-line diff between two strings, with removed and added lines marked, as in a code review." }*/
 import { elements, vars, varDefault, withAttributes, } from 'tosijs';
 const { div, span, button } = elements;
 /** Group a line diff into context runs and change blocks, in display order. */

package/dist/doc-browser.d.ts

@@ -1,3 +1,4 @@
+import { type AccessibilityMode } from './doc-system/render.js';
 import { TestResults } from './live-example/test-harness.js';
 import { type ExamplePolicy } from './doc-system/example-policy.js';
 export declare const hasTestBlock: (text: string | undefined, policy?: ExamplePolicy) => boolean;
@@ -123,6 +124,11 @@ export interface DocBrowserOptions {
      * strings, like every other piece of the doc system's own text.
      */
     searchPlaceholder?: string;
+    /**
+     * `SiteConfig.accessibility` (#3521): render figures with captions and exactly one `<h1>`
+     * per page, as the static build does, so a hydrated page matches it.
+     */
+    accessibility?: AccessibilityMode;
     /**
      * Header-bar links. When provided, these replace the legacy `projectLinks` icon
      * set in the header (each renders as an icon if `icon` names a known icon, else

package/dist/doc-browser.js

@@ -98,12 +98,12 @@ The search opens on Cmd-K (Ctrl-K off a Mac) anywhere on the page. A host that o
 or embeds more than one browser, passes `searchShortcut: ''` (or another key in
 `<tosi-palette>`'s `shortcut` form).
 */
-/*{ "parent": "Documentation System", "order": 50 }*/
+/*{ "parent": "Documentation System", "order": 50, "description": "createDocBrowser() renders a documentation corpus as a searchable browser with live, self-testing examples: a lighter alternative to Storybook." }*/
 import { elements, vars, varDefault, bindings, getListItem, tosi, StyleSheet, } from 'tosijs';
 import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, wikilinkTargets, } from './doc-system/routing.js';
 import { buildNavTree } from './doc-system/nav-tree.js';
 import { navSectionStyleSpec } from './doc-system/nav-styles.js';
-import { renderDocMarkdown } from './doc-system/render.js';
+import { renderDocMarkdown, } from './doc-system/render.js';
 import { pageTitle } from './doc-system/doc-title.js';
 import { unsettledExamples, tallyExamples, closePage, } from './doc-system/test-completion.js';
 import { LiveExample, testManager, pageTestCount, enableTests, disableTests, } from './live-example.js';
@@ -149,7 +149,7 @@ export const hasTestBlock = (text, policy = 'auto') => typeof text === 'string'
     // Cheap reject first: lexing every doc in a large corpus is not free.
     text.includes('test') &&
     collectCodeTokens(text).some((t) => t.lang === 'test' && isLiveFence('test', t.mode, policy));
-const { div, span, a, header, button, template, h2, img, ul, li } = elements;
+const { div, span, a, header, button, template, img, ul, li } = elements;
 /*
 Test colors, and the text color that goes ON each — because contrast is a PAIR.
 
@@ -395,7 +395,7 @@ let docBrowserSeq = 0;
 // Likewise for the nav's aria-controls ids.
 let navIdCounter = 0;
 export function createDocBrowser(options) {
-    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', searchPlaceholder = 'Search', navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', searchPlaceholder = 'Search', accessibility, navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
     // window.history/location, so an embedded or nested browser can't hijack the
     // host page's URL (or recurse into it).
@@ -906,7 +906,10 @@ export function createDocBrowser(options) {
                 alignItems: 'center',
                 borderBottom: 'none',
             },
-        }, logoMark(logo, projectLinks), h2(projectName)));
+        }, logoMark(logo, projectLinks), 
+        // Not a heading: the site name above every page made it each page's first heading,
+        // an <h2> ahead of the page's own <h1> (#3521).
+        span({ class: 'site-name' }, projectName)));
     }
     headerContent.push(span({ class: 'elastic' }), searchBox);
     // A header link renders as an icon (if `icon` names a known icon) or its label.
@@ -1054,6 +1057,8 @@ export function createDocBrowser(options) {
             docContent.innerHTML = renderDocMarkdown(doc.text, {
                 bakes: doc.bakes ? new Map(doc.bakes) : undefined,
                 wikilinks,
+                accessible: !!accessibility,
+                title: doc.title,
             });
         }
         /*
@@ -1345,7 +1350,7 @@ export function createDocBrowser(options) {
             return;
         editUI.view = view;
         if (view === 'preview') {
-            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks });
+            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks, accessible: !!accessibility, title: editUI.doc.title });
             rewriteContentLinks();
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
             focusableCodeBlocks(docContent);

package/dist/doc-system/book-html.d.ts

@@ -8,7 +8,7 @@ export interface BookDoc {
     parent?: string;
     hidden?: boolean;
 }
-export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\na { color: #08c; text-decoration: none; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/*\nPrism token colours for the book \u2014 a LIGHT palette, deliberately distinct from the site's.\n\nThe site has TWO palettes, one per mode. A book has one background and it is light: the\npre rule above is #f6f8fa, an ePub reader may impose white or sepia, and paper is paper.\nReusing the site palette here would be light-on-light \u2014 invisible body text dressed as syntax\nhighlighting, which is the exact failure a nested diff hit in tosijs-ui#143.\n\nContrast-checked against #f6f8fa; the comment green is the weakest at ~4.6:1, still above\nWCAG AA for body text. Colours are literal rather than custom properties because this\nstylesheet ships inside an ePub, where custom properties are not reliably supported.\n\nNO BACKTICKS in this comment: it lives inside a JS template literal, so one would end the\nstring and drop the rest of the stylesheet into code. (It did. Same shape as a block comment\nending a doc comment early \u2014 punctuation that means something to the container.)\n*/\n.token.comment, .token.prolog, .token.cdata { color: #5c6f5c; font-style: italic; }\n.token.punctuation { color: #666; }\n.token.string, .token.char, .token.attr-value, .token.regex { color: #a03030; }\n.token.number, .token.boolean, .token.constant { color: #0b7285; }\n.token.keyword, .token.important, .token.atrule { color: #0a5bb5; }\n.token.function, .token.class-name { color: #7a4b00; }\n.token.operator, .token.entity, .token.url { color: #444; }\n.token.tag, .token.selector, .token.builtin { color: #0a6b52; }\n.token.attr-name, .token.property { color: #2a5db0; }\n.token.deleted { color: #b02020; }\n.token.inserted { color: #2a6b2a; }\n.token.bold { font-weight: bold; }\n.token.italic { font-style: italic; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #08c; font-weight: bold; }\n/* footnotes / endnotes + wikilinks */\nsup.footnote-ref { font-size: 0.7em; line-height: 0; }\nsup.footnote-ref a { text-decoration: none; }\n.footnotes { margin-top: 2em; font-size: 0.9em; }\n.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }\n.footnote-backref { text-decoration: none; }\na.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }\n";
+export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\n/* 6.6:1 on white, and underlined: colour alone does not mark a link in running text (#3522, DAISY Ace) */\na { color: #0a5bb5; text-decoration: underline; text-underline-offset: 0.15em; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/*\nPrism token colours for the book \u2014 a LIGHT palette, deliberately distinct from the site's.\n\nThe site has TWO palettes, one per mode. A book has one background and it is light: the\npre rule above is #f6f8fa, an ePub reader may impose white or sepia, and paper is paper.\nReusing the site palette here would be light-on-light \u2014 invisible body text dressed as syntax\nhighlighting, which is the exact failure a nested diff hit in tosijs-ui#143.\n\nContrast-checked against #f6f8fa; the comment green is the weakest at ~4.6:1, still above\nWCAG AA for body text. Colours are literal rather than custom properties because this\nstylesheet ships inside an ePub, where custom properties are not reliably supported.\n\nNO BACKTICKS in this comment: it lives inside a JS template literal, so one would end the\nstring and drop the rest of the stylesheet into code. (It did. Same shape as a block comment\nending a doc comment early \u2014 punctuation that means something to the container.)\n*/\n.token.comment, .token.prolog, .token.cdata { color: #5c6f5c; font-style: italic; }\n.token.punctuation { color: #666; }\n.token.string, .token.char, .token.attr-value, .token.regex { color: #a03030; }\n.token.number, .token.boolean, .token.constant { color: #0b7285; }\n.token.keyword, .token.important, .token.atrule { color: #0a5bb5; }\n.token.function, .token.class-name { color: #7a4b00; }\n.token.operator, .token.entity, .token.url { color: #444; }\n.token.tag, .token.selector, .token.builtin { color: #0a6b52; }\n.token.attr-name, .token.property { color: #2a5db0; }\n.token.deleted { color: #b02020; }\n.token.inserted { color: #2a6b2a; }\n.token.bold { font-weight: bold; }\n.token.italic { font-style: italic; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #0a5bb5; font-weight: bold; }\n/* footnotes / endnotes + wikilinks */\nsup.footnote-ref { font-size: 0.7em; line-height: 0; }\nsup.footnote-ref a { text-decoration: none; }\n.footnotes { margin-top: 2em; font-size: 0.9em; }\n.footnotes hr { border: none; border-top: 1px solid #ccc; margin: 1em 0; }\n.footnote-backref { text-decoration: none; }\na.wikilink { text-decoration: none; border-bottom: 1px dotted currentColor; }\n";
 export declare const PRINT_CSS = "\n@page { margin: 18mm 16mm; }\n.book-cover { display: block; margin: 0 auto; max-width: 100%; max-height: 100vh; page-break-after: always; break-inside: avoid; }\n.book-title { text-align: center; margin: 30vh 0 1em; }\n.book-toc { page-break-after: always; }\n.book-toc h2 { page-break-before: avoid; }\n.book-toc ol { list-style: none; padding-left: 0; }\n.book-toc ol ol { padding-left: 1.2em; }\n.book-toc a { color: inherit; }\n.chapter { page-break-before: always; }\n";
 export declare function escapeHtml(s: string): string;
 export declare function slugify(s: string): string;
@@ -27,6 +27,8 @@ export interface BookHtmlOptions {
     /** full stylesheet (defaults to DEFAULT_BOOK_CSS + PRINT_CSS) */
     css?: string;
     lang?: string;
+    /** `SiteConfig.accessibility`: figures and one `<h1>` per chapter (#3521) */
+    accessible?: boolean;
     /** inject a script that opens the print dialog once the page has loaded */
     autoPrint?: boolean;
 }

package/dist/doc-system/book-html.js

@@ -28,7 +28,8 @@ h1 { font-size: 1.8em; }
 h2 { font-size: 1.4em; }
 h3 { font-size: 1.2em; }
 p { margin: 0.6em 0; }
-a { color: #08c; text-decoration: none; }
+/* 6.6:1 on white, and underlined: colour alone does not mark a link in running text (#3522, DAISY Ace) */
+a { color: #0a5bb5; text-decoration: underline; text-underline-offset: 0.15em; }
 ul, ol { margin: 0.6em 0; padding-left: 1.4em; }
 blockquote {
   margin: 0.8em 0;
@@ -96,7 +97,7 @@ ol.toc li { margin: 0.3em 0; }
 ol.toc > li > a { font-weight: bold; }
 /* per-example "run this live" deep link */
 .example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }
-.example-live-link a { color: #08c; font-weight: bold; }
+.example-live-link a { color: #0a5bb5; font-weight: bold; }
 /* footnotes / endnotes + wikilinks */
 sup.footnote-ref { font-size: 0.7em; line-height: 0; }
 sup.footnote-ref a { text-decoration: none; }
@@ -155,6 +156,8 @@ export function buildBookHtml(docs, opts) {
     const chapters = flatten(roots)
         .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)), {
         wikilinks,
+        accessible: opts.accessible,
+        title: node.doc.title,
     })}\n</section>`)
         .join('\n');
     return `<!DOCTYPE html>

package/dist/doc-system/data-client.js

@@ -1,4 +1,4 @@
-/*{ "parent": "Documentation System", "order": 85 }*/
+/*{ "parent": "Documentation System", "order": 85, "description": "Open and save a project's data files from a dev-server page, for in-browser tools such as level or scene editors, optionally committing each save." }*/
 /*#
 # data client
 

package/dist/doc-system/doc-system-styles.js

@@ -393,9 +393,13 @@ export function docSystemStyleSpec(theme = {}) {
             margin: `${vars.spacing} 0 ${vars.spacing200}`,
             padding: 0,
         },
-        'header h2': {
+        'header .site-name': {
             color: vars.brandTextColor,
             whiteSpace: 'nowrap',
+            fontWeight: '700',
+            fontSize: 'calc(var(--font-size) * var(--h2-scale))',
+            lineHeight: 'calc(var(--line-height) * var(--h2-scale))',
+            margin: 'calc(var(--spacing) * var(--h2-scale)) 0',
         },
         h2: {
             color: vars.brandColor,

package/dist/doc-system/doc-system.js

@@ -55,7 +55,7 @@ A self-contained, controllable embed (e.g. docs in a floating panel):
 </tosi-doc-system>
 ```
 */
-/*{ "parent": "Documentation System", "order": 40 }*/
+/*{ "parent": "Documentation System", "order": 40, "description": "<tosi-doc-system> hydrates pre-rendered static doc pages into a fast single-page doc browser, keeping full HTML for search engines and no-JS readers." }*/
 import { StyleSheet, elements, tosi, vars, withAttributes, } from 'tosijs';
 import * as tosijsModule from 'tosijs';
 import { createDocBrowser, } from '../doc-browser.js';
@@ -332,11 +332,13 @@ export class TosiDocSystem extends withAttributes({
                 let projectName = '';
                 let bookVolumes;
                 let ebooks;
+                let accessible = false;
                 try {
                     const parsed = JSON.parse(this.config || '{}');
                     projectName = parsed.projectName || '';
                     bookVolumes = parsed.bookVolumes || undefined;
                     ebooks = parsed.ebooks;
+                    accessible = !!parsed.accessibility;
                 }
                 catch {
                     // ignore — fall through to document.title
@@ -372,6 +374,7 @@ export class TosiDocSystem extends withAttributes({
                             title: bookTitle,
                             cover: bookCover,
                             autoPrint: false,
+                            accessible,
                         }));
                         win.document.close();
                         /*
@@ -609,6 +612,7 @@ export class TosiDocSystem extends withAttributes({
             logo: config.logo,
             navbarLinks: navbarLinks.length ? navbarLinks : undefined,
             searchPlaceholder: config.searchPlaceholder,
+            accessibility: config.accessibility,
             contentElement,
         });
         // Add the settings (theme + language) menu — except in a nested demo, where

package/dist/doc-system/highlight-styles.js

@@ -1,4 +1,4 @@
-/*{ "parent": "Documentation System", "order": 80 }*/
+/*{ "parent": "Documentation System", "order": 80, "description": "The syntax-highlighting token colours as a stylesheet you can import and retheme, for code highlighted outside <tosi-highlight>." }*/
 /*#
 # highlight-styles
 

package/dist/doc-system/render.d.ts

@@ -3,12 +3,31 @@ export interface ExampleBake {
     js: string;
 }
 export type ExampleBakes = Map<string, ExampleBake>;
+/** `SiteConfig.accessibility`. One level for now; the name says which standard it targets. */
+export type AccessibilityMode = 'wcag22-aa';
+/**
+ * The accessibility mode's token rewrites (#3521), exported so the build's report reads exactly
+ * the structure the page renders.
+ */
+export declare function accessibleTokens(tokens: any[], title?: string): any[];
 export declare function unwrapLoneCustomElements(html: string): string;
 export declare function renderDocMarkdown(text: string, opts?: {
     bakes?: ExampleBakes;
     /** the corpus's `wikilinkTargets`; without it a `[[target]]` is slugified as written */
     wikilinks?: Map<string, string>;
+    /**
+     * The accessibility mode (#3521): figures with captions, and exactly one `<h1>`. `title` is
+     * the page title, rendered as that `<h1>` when the markdown has none.
+     */
+    accessible?: boolean;
+    title?: string;
 }): string;
+/**
+ * A doc's tokens as the accessibility mode renders them, for the build's report: the same
+ * lexer and the same rewrites as `renderDocMarkdown`, so the report and the page cannot
+ * disagree about what is a figure or which heading is the `<h1>`.
+ */
+export declare function accessibleDocTokens(text: string, title?: string): any[];
 /**
  * Derive a clean <meta name="description"> from a doc's first prose paragraph.
  * Skips the title heading, code fences, tables, quotes, html and image/link-only

package/dist/doc-system/render.js

@@ -10,13 +10,131 @@ give that example a stable anchor — see the docMarked renderer below.
 */
 import { Marked, Renderer } from 'marked';
 import { parseFenceInfo } from './example-policy.js';
-import { HeadingIds, headingSlug } from './heading-id.js';
+import { HeadingIds, headingSlug, headingText } from './heading-id.js';
 import { pathForSlug, slugify } from './routing.js';
 const baseRenderer = new Renderer();
 let currentBakes;
 let currentWikilinks;
 // Per-parse, reset in `preprocess` below (same pattern as the footnote state).
 let headingIds = new HeadingIds();
+let currentA11y;
+const isBlank = (t) => (t.type === 'text' && !String(t.raw).trim()) || t.type === 'br';
+/** The image token of a paragraph whose only content is one image, else undefined. */
+function loneImage(tokens) {
+    const content = tokens.filter((t) => !isBlank(t));
+    return content.length === 1 && content[0].type === 'image'
+        ? content[0]
+        : undefined;
+}
+/** The em token of a paragraph whose only content is italic text, else undefined. */
+function loneEmphasis(tokens) {
+    const content = tokens.filter((t) => !isBlank(t));
+    return content.length === 1 && content[0].type === 'em'
+        ? content[0]
+        : undefined;
+}
+function figureFrom(paragraph) {
+    // `![…](…)` and `*caption*` on consecutive lines are one paragraph to marked.
+    const content = paragraph.tokens.filter((t) => !isBlank(t));
+    if (content.length === 2 &&
+        content[0].type === 'image' &&
+        content[1].type === 'em')
+        return {
+            type: 'figure',
+            raw: paragraph.raw,
+            image: content[0],
+            caption: content[1],
+        };
+    return undefined;
+}
+function withFigures(tokens) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'blockquote' && Array.isArray(token.tokens)) {
+            token.tokens = withFigures(token.tokens);
+        }
+        if (token.type !== 'paragraph') {
+            out.push(token);
+            continue;
+        }
+        const joined = figureFrom(token);
+        if (joined) {
+            out.push(joined);
+            continue;
+        }
+        const image = loneImage(token.tokens);
+        let next = i + 1;
+        while (tokens[next]?.type === 'space')
+            next += 1;
+        const caption = image &&
+            tokens[next]?.type === 'paragraph' &&
+            loneEmphasis(tokens[next].tokens);
+        if (caption) {
+            out.push({
+                type: 'figure',
+                raw: tokens
+                    .slice(i, next + 1)
+                    .map((t) => t.raw)
+                    .join(''),
+                image,
+                caption,
+            });
+            i = next;
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+function withOneTitle(tokens, title) {
+    const headings = tokens.filter((t) => t.type === 'heading');
+    /*
+    A page with no `#` takes its title from its first heading, whatever its level, so that
+    heading IS the title: promote it rather than print the same words twice.
+    */
+    const lead = headings[0];
+    const first = headings.find((t) => t.depth === 1) ??
+        (lead && title && headingText(lead).trim() === title.trim()
+            ? lead
+            : undefined);
+    // The shift comes from the sub-headings as written; a demoted `#` is not one of them.
+    const below = headings
+        .filter((h) => h !== first && h.depth > 1)
+        .map((h) => h.depth);
+    const shift = below.length ? Math.min(...below) - 2 : 0;
+    if (first)
+        first.depth = 1;
+    for (const h of headings) {
+        if (h === first)
+            continue;
+        if (h.depth === 1)
+            h.depth = 2;
+        else if (shift > 0)
+            h.depth -= shift;
+    }
+    if (!first && title)
+        return [
+            {
+                type: 'heading',
+                raw: '',
+                depth: 1,
+                text: title,
+                tokens: [
+                    { type: 'text', raw: title, text: escapeHtml(title), escaped: true },
+                ],
+            },
+            ...tokens,
+        ];
+    return tokens;
+}
+/**
+ * The accessibility mode's token rewrites (#3521), exported so the build's report reads exactly
+ * the structure the page renders.
+ */
+export function accessibleTokens(tokens, title) {
+    return withOneTitle(withFigures(tokens), title);
+}
 const docMarked = new Marked();
 docMarked.use({
     renderer: {
@@ -86,6 +204,13 @@ let footnoteDefs = new Map();
 let footnoteOrder = [];
 docMarked.use({
     hooks: {
+        processAllTokens(tokens) {
+            if (!currentA11y)
+                return tokens;
+            const rewritten = accessibleTokens([...tokens], currentA11y.title);
+            // A TokensList carries `links` (reference definitions); keep it.
+            return Object.assign(rewritten, { links: tokens.links });
+        },
         preprocess(markdown) {
             footnoteDefs = new Map();
             footnoteOrder = [];
@@ -106,6 +231,15 @@ docMarked.use({
         },
     },
     extensions: [
+        {
+            // Built only by `accessibleTokens` above; there is no syntax of its own to tokenize.
+            name: 'figure',
+            renderer(token) {
+                const image = this.parser.parseInline([token.image]);
+                const caption = this.parser.parseInline(token.caption.tokens);
+                return `<figure>${image}<figcaption>${caption}</figcaption></figure>\n`;
+            },
+        },
         {
             // [[slug]] / [[slug|label]] → link to /slug/. Not matched inside code spans
             // (Marked tokenizes those first). Given the corpus's `wikilinkTargets`, a target is
@@ -209,14 +343,24 @@ export function unwrapLoneCustomElements(html) {
 export function renderDocMarkdown(text, opts = {}) {
     currentBakes = opts.bakes;
     currentWikilinks = opts.wikilinks;
+    currentA11y = opts.accessible ? { title: opts.title } : undefined;
     try {
         return unwrapLoneCustomElements(docMarked.parse(text));
     }
     finally {
         currentBakes = undefined;
         currentWikilinks = undefined;
+        currentA11y = undefined;
     }
 }
+/**
+ * A doc's tokens as the accessibility mode renders them, for the build's report: the same
+ * lexer and the same rewrites as `renderDocMarkdown`, so the report and the page cannot
+ * disagree about what is a figure or which heading is the `<h1>`.
+ */
+export function accessibleDocTokens(text, title) {
+    return accessibleTokens([...docMarked.lexer(text)], title);
+}
 /**
  * Derive a clean <meta name="description"> from a doc's first prose paragraph.
  * Skips the title heading, code fences, tables, quotes, html and image/link-only

package/dist/doc-system/site/a11y-audit-cli.d.ts

@@ -0,0 +1 @@
+export {};