docs: a main landmark, a switcher named by its text, code blocks off the landmark list, buttons that keep their own language, a localized Open-in prompt, and a CI rule for the locale chrome

[objectstack-fleet]

Fixes #308

The docs accessibility baseline. axe 4.14.0 reported four failures on every docs page in every locale, English included. This PR fixes all four, localizes the "Open in ChatGPT / Claude" prompt, and adds a CI rule for the #298 and #305 results. It also fixes the inverse language-of-parts defect that #305 introduced. It builds on #305's fumadocs-ui patch and ui-text keys, which are on main since #314.

Branch and rebase

• Branch. staged/issue-308: 5 commits on main at cf449fa. The tip is 42da2b1.
  1. fa284b5: main landmark, switcher name, GitHub icon, code-block role, Open-in prompt
  2. 023372c: the CI rule
  3. 3159847: the table-of-contents bar
  4. 33d9a32: the inverse fix and its rule
  5. 42da2b1: the CI guard counts docs pages only
• Rebase. The first three commits were cut on Docs chrome still speaks English inside localized pages: fumadocs' hard-coded aria-labels, English page-tree names without lang="en", no zh-Hant 404 copy #305's staged commit (1f5ea81) and rebased with git rebase --onto origin/main 1f5ea81 staged/issue-308.
  • There were no conflicts. git range-diff shows all three commits as =.
  • pnpm-lock.yaml, package.json and patches/ are byte-identical between 1f5ea81 and cf449fa, so the patch hash needed no regeneration at the rebase.
  • The patch changed again in commit 4. Its hash was refreshed with pnpm install, and pnpm install --frozen-lockfile exits 0.
• Overlap with Docs legal pages: /de, /ja, /es, /fr and /ko privacy and terms show English text without lang="en", and zh-Hant shows English instead of text derived from zh-Hans #312. Docs legal pages: /de, /ja, /es, /fr and /ko privacy and terms show English text without lang="en", and zh-Hant shows English instead of text derived from zh-Hans #312 also edits check-locale-surface.mjs (a self-contained legal-* block).
  • Applying Docs legal pages: /de, /ja, /es, /fr and /ko privacy and terms show English text without lang="en", and zh-Hant shows English instead of text derived from zh-Hans #312's own two commits onto this tip in memory (git merge-tree --merge-base 4da46c5) gives no conflict.
  • With Docs legal pages: /de, /ja, /es, /fr and /ko privacy and terms show English text without lang="en", and zh-Hant shows English instead of text derived from zh-Hans #312's legal-page fixtures, this file's "docs pages not built" case failed, because the guard counted any HTML. Commit 5 makes the guard ask for docs pages only. The merged self-test then passes: 48 cases over 25 rules.
  • A direct merge of staged/issue-312 conflicts only because that branch still carries Docs chrome still speaks English inside localized pages: fumadocs' hard-coded aria-labels, English page-tree names without lang="en", no zh-Hant 404 copy #305 as 4da46c5 rather than main's cf449fa.

What changed

Finding	Fix	Where
landmark-one-main: the docs layout had no main landmark	DocsPage passes its other props to the article element it renders, so the docs page sets role="main" there. This is a fumadocs option; no patch hunk. The landmark covers the breadcrumb, title, body and footer; the sidebar and the table of contents stay outside it.	app/[lang]/docs/[[...slug]]/page.tsx
label-content-name-mismatch: the language switcher shows "English" but was named "Choose a language"	Named "English — Choose a language", "Deutsch — Sprache wählen", "简体中文 — 选择语言". The visible text comes first, and both halves come from the i18n context, so no new key is needed.	patch hunk, layouts/shared/slots/language-select.js
svg-img-alt: the GitHub icon was an unnamed svg role="img"	Every link that renders it is already named "GitHub", so the icon is decorative and gets aria-hidden.	patch hunk, layouts/shared/index.js
landmark-unique: every code block's scroll area was an unnamed role="region"	The role is removed. tabIndex: 0 stays, so keyboard scrolling still works.	patch hunk, components/codeblock.js
landmark-unique at phone width: the table-of-contents bar was a second banner header	The bar is now a div element.	patch hunk, layouts/docs/page/slots/toc.js
The Open-in prompt sentence was English in every locale	It is now the ui-text key pageActionsOpenInLLMPrompt, with upstream 16.9.0's key name, {url} placeholder and English text. It is translated in six locales and generated for zh-Hant. table() holds every locale's placeholders to English.	lib/ui-text.ts, lib/ui-text/*.json, components/ai/page-actions.tsx, page.tsx
No CI gate for #298/#305's locale-chrome results	Four rules over the prerendered HTML: english-chrome-name, untranslated-entry-unmarked, translated-entry-marked-english and localized-name-marked-english. Guards and a live control keep them from passing when they measured nothing. 12 new self-test cases.	.github/scripts/check-locale-surface.mjs
Localized heading-anchor and code-copy names were read with English rules inside a fallback page's body	See "The inverse language-of-parts fix" below.	patch hunks components/heading.js, components/codeblock.js

No new ci.yml step is needed. The existing "Locale surface" step already runs this gate after the build, and pnpm turbo run test runs its self-test.

Decisions

• Main landmark through a DocsPage prop, not the patch. Upstream 16.16.2 wraps the article in a main element of its own. On that upgrade, delete role="main", or the page will have two main landmarks. The page comment and the patch header both say this.
• Language switcher in the patch, not slots.languageSelect.root. A slot would have to be passed to every layout instance; the patch covers every trigger.
• Code blocks lose their landmark role instead of getting names. Untitled blocks have nothing to be named by, titles repeat within a page, and ten code landmarks per page would bury the real ones.
• Prompt through ViewOptions' labels prop, like its neighbours, not through the fumadocs i18n context. No fumadocs component reads it.
• How the CI rule finds what it compares. The English chrome set and each locale's own set are read from the built pages, so a name fumadocs adds later is covered with no edit. Page-tree entries are links outside the page body whose text contains the target page's title. The oracle for "untranslated" is the content tree.

The inverse language-of-parts fix

#305 localized the names of the heading-anchor and code-copy buttons. On a fallback page both buttons sit in the page body, which #298 marks lang="en", so "Ankerlink kopieren" was read with English rules. That is WCAG 3.1.2, the inverse of what #305 fixed.

Both buttons now take locale from the useI18n() they already read and render it as their own lang. This is in the two #305 hunks of patches/fumadocs-ui@16.8.12.patch. Inside an English body, the button's own lang keeps its name in the locale's language.

The new rule, localized-name-marked-english, fails when one of a locale's own names sits inside a lang="en" region with no lang of its own. "Own names" means the names that resolve to the locale on its built pages, minus the English set.

Built tree	localized-name-marked-english	Gate exit
main at cf449fa	3963: per Latin-script locale 520 anchor + 115 copy names over 55 fallback pages; zh-Hans and zh-Hant 336 + 58 over 31. Those two names only.	1
This branch at 33d9a32 / 42da2b1	0 (10 own names per locale compared)	0

These counts are higher than the 453 + 101 and 276 + 44 measured before the rebase. #301's content pass on main left more fallback pages (55 and 31, up from 53 and 29) and more headings.

The hydrated DOM confirms it: on /de/docs/operate/backup, 7 anchor buttons and 1 copy button resolve to de inside the en body. English pages are unchanged in what they announce.

Self-test cases:

• red: the ja fallback anchor button with its own lang removed;
• green: the same name reaching the body through a wrapper's lang.

The live control now feeds this shape too. With a reader blind to lang on names, the self-test shows it red.

Evidence

The before state is main at cf449fa, built CI-shaped. The after state is this branch at 33d9a32. git diff 33d9a32 42da2b1 touches only the gate script.

axe 4.14.0. One page per section (quickstart, use/records, build/data, configure/authentication, deploy/docker, operate/backup, resources/faq, reference/cli), in en, zh-Hans and de, light and dark. That is 48 runs per width.

Rule	1440 main	1440 after	390 main	390 after
landmark-one-main	48 runs / 48 nodes	0	48 / 48	0
label-content-name-mismatch	48 / 48	0	0 *	0 *
svg-img-alt	48 / 48	0	0 *	0 *
landmark-unique	24 / 24	0	48 / 72	0

* At 390px the switcher and the GitHub icon sit in the closed drawer. With the drawer open (en, zh-Hans, de quickstart):

• on main: label-content-name-mismatch, svg-img-alt and landmark-unique fire;
• on this branch: none of the four.

No new violations. Compared run by run, no rule has more nodes on this branch than on main, at either width. Removed:

• at 1440px: region 2416 nodes, plus the four rules above;
• at 390px: landmark-no-duplicate-banner 48, landmark-unique 72, landmark-one-main 48, region 2416.

color-contrast (9 runs, 48 nodes) and scrollable-region-focusable at 390px (16 runs, 18 nodes) are unchanged.

CI rule, red and green.

Built tree	english-chrome-name	untranslated-entry-unmarked	localized-name-marked-english	Exit
main built at cec227a (before #305)	6239	5974	n/a (rule added later)	1
#305's tree with searchOpen mapped to "Open Search" and the page-tree transform bypassed (ablation, restored)	1120	5974	n/a	1
main at cf449fa	0	0	3963	1
this branch, 42da2b1	0	0 (717 marked in zh-Hans and zh-Hant, 950 in each other locale)	0	0

Screenshots. en and zh-Hans at 1440 and 390, main versus this branch:

• the switcher;
• the open drawer;
• a code block;
• the 390px table-of-contents bar.

All 12 before/after pairs are byte-identical PNGs. Nothing visible changed.

Browser. next start, JS on, 0 console or hydration errors.

• The Open-in prompt was read from the live popover in all eight locales, on a fallback page and a translated page each. The English prompt is unchanged.
• gen-zh-hant --check goes red on a one-character drift in the new zh-Hant string.
• The {url} guard throws on a locale string that drops the placeholder.

Gates (HEAD 42da2b1)

• pnpm install --frozen-lockfile: exit 0
• pnpm turbo run type-check --continue --force: Tasks 1 successful; VERDICT command-exit 0
• NEXT_PRIVATE_STANDALONE=true pnpm turbo run build --force: 1038/1038 static pages; Tasks 1 successful; VERDICT command-exit 0 (332 OG font-fetch proxy warnings, the same count as main's build)
• pnpm turbo run test --force: ✓ 10 self-test(s) passed; VERDICT command-exit 0
• check-locale-surface.mjs: exit 0. --self-test: ✓ 43 case(s) over 22 rule(s)
• check-positioning.mjs: ✓ 4 copies equal their constants; the brand is right in 659 pages and 2 llms bodies
• check-search-locales.mjs: ✓ all 8 locales answer 200, find "permissions", find every own page by its title within the first 3 pages, and find nothing for a nonce
• gen-zh-hant.mjs --check: ✓ zh-Hant: 60 generated file(s) match the zh-Hans sources byte for byte
• Translations:
  • Ownership (workflow argv git diff --name-status --no-renames origin/main...HEAD, --actor hotlong): exit 0 (inert with no bot login); armed: ✓ 13 file(s) changed, no translation artifacts touched
  • Bot-actor control (armed, --actor = the bot login): exit 1, "English sources and site code are authored by humans. Split them out."
  • Freshness: ✓
  • Output --files: ✓ (256 pre-existing findings; the same 256 on main with an empty file list)
  • Output --self-test: ✓
• check-node-floor.mjs and --self-test: ✅; check-half-states.mjs --self-test: ✓ 1551 cases pass

Not run here: the Worker packaging and size step, and smoke-docs.mjs. They are not in this card's gate list; CI runs both.

Acceptance notes

• Legal pages: duplicate main landmark. /privacy and /terms render the page's own main element inside HomeLayout's. That is Docs legal pages: /de, /ja, /es, /fr and /ko privacy and terms show English text without lang="en", and zh-Hant shows English instead of text derived from zh-Hans #312's, and this PR does not touch those pages.
• Desktop table of contents. At 1280px and wider, #nd-toc is outside every landmark: axe region, one node per run, unchanged from main.
• Overflowing tables. At 390px a wide table's overflow wrapper is not focusable: scrollable-region-focusable, 18 nodes in 16 of 48 runs. Unchanged from main.
• Folder names. The CI rule reads links, so folder names (the breadcrumb's crumbs, sidebar folder buttons) are not covered. Every folder has a localized meta title today.

Pushed head

fa2390f on claude/pm-dispatch-objectos-ju9td1, a fast-forward with no force. It starts at the remote branch head 69f7f1e, merges origin/main @ 553ef7b (#315, which is #307; after the merge the diff against main is empty), and cherry-picks the five commits fa284b5..42da2b1, which were rebased onto cf449fa. git diff origin/main fa2390f is byte-identical to git diff cf449fa 42da2b1; no path is shared with #315.

---

Generated by Claude Code