fix(a11y): contrast, focus ring, radiogroup keys, live region and document language

Five findings from the Phase 4 adversarial review, all of them things a green
build cannot see.

tokens.css redefined --accent in both dark blocks but never --accent-fg, so
dark mode painted white on #8b6dff -- 3.67:1, under the 4.5:1 docs/06 §5
requires. That hit the ThemeToggle's selected chip and every primary button.
Dark ink on the same violet measures 4.84:1.

ThemeToggle's `overflow: hidden` clipped the global :focus-visible ring, which
base.css draws at outline-offset: 2px, i.e. entirely outside the clip region.
The theme control had no keyboard focus indicator at all. Corner rounding is
per-child now and the ring is inset.

ThemeToggle also claimed role="radiogroup"/"radio" while implementing neither
roving tabindex nor arrow keys, so a screen reader announced "radio button,
1 of 3", switched to forms mode, and then the arrows did nothing while all
three stayed separate tab stops -- the inverse of the pattern (WCAG 4.1.2).
Arrow/Home/End now work and only the selected radio is a tab stop. The handler
sits on the radios, not the group: a keydown handler on a non-focusable
container never fires.

Toast built its role="status" region and its text in one DOM insertion. Screen
readers derive announcements from mutations to a region that was ALREADY
present, so success toasts were never announced. Two permanently-mounted
regions now, polite and assertive, with only their text changing -- two rather
than one with a swapped aria-live, because changing politeness at runtime is
not reliably picked up.

applyLocale never touched <html lang>, and both entrypoints ship lang="en", so
a screen reader read Vietnamese and Japanese with an English voice. It also
fixes the toast's dismiss button, which was labelled "Cancel" -- there is
nothing to call off, the operation already finished.

Also routes the last three hardcoded English aria-labels ("Sections",
"Preview" x2) through the dictionary. They date from Phase 2, but full EN/VI/JA
coverage is this phase's exit criterion.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-26 13:33:00 +07:00
1 parent 16bbba371d
commit 2937f4edf0
11 files changed
+138 -10

No files matched your search

+1 -1
View File
@@ -143,7 +143,7 @@
<p class="muted">{t('import.reading', { name: session.filename })}</p>
{:else if session.kind === 'parsed'}
<div class="split">
<section aria-label="Preview">
<section aria-label={t('import.preview')}>
<TreePreview roots={session.result.roots} status={prepared?.status ?? new WeakMap()} />
</section>
<section class="side">
+1 -1
View File
@@ -25,7 +25,7 @@
];
</script>
<nav aria-label="Sections">
<nav aria-label={t('common.sections')}>
{#each TABS as tab (tab.route)}
<button
class:active={getRoute() === tab.route}
+57 -2
View File
@@ -20,17 +20,57 @@
light: '☀',
dark: '☾',
};
let buttons: HTMLButtonElement[] = $state([]);
/**
* The radiogroup keyboard pattern, which the ARIA roles above promise.
*
* Without this the roles are a lie: a screen reader announces "radio button,
* 1 of 3" and switches to forms mode, then the arrow keys do nothing and all
* three are separate tab stops — the inverse of the pattern (WCAG 4.1.2).
*
* Bound to each radio rather than the group, because only the radios are
* focusable — a keyboard handler on a non-focusable container never fires,
* which is exactly what svelte-check's `a11y_interactive_supports_focus`
* warns about.
*/
function onKeyDown(event: KeyboardEvent): void {
const index = THEME_CHOICES.findIndex((choice) => choice.value === value);
if (index === -1) return;
let next: number | undefined;
if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
next = (index + 1) % THEME_CHOICES.length;
} else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
next = (index - 1 + THEME_CHOICES.length) % THEME_CHOICES.length;
} else if (event.key === 'Home') {
next = 0;
} else if (event.key === 'End') {
next = THEME_CHOICES.length - 1;
}
if (next === undefined) return;
event.preventDefault();
const choice = THEME_CHOICES[next];
if (choice === undefined) return;
onchange(choice.value);
buttons[next]?.focus();
}
</script>
<div class="group" class:compact role="radiogroup" aria-label={t('settings.theme')}>
{#each THEME_CHOICES as choice (choice.value)}
{#each THEME_CHOICES as choice, index (choice.value)}
<button
bind:this={buttons[index]}
type="button"
role="radio"
aria-checked={value === choice.value}
aria-label={compact ? t(choice.labelKey) : undefined}
tabindex={value === choice.value ? 0 : -1}
class:selected={value === choice.value}
onclick={() => onchange(choice.value)}
onkeydown={onKeyDown}
>
{#if compact}
<span aria-hidden="true">{GLYPH[choice.value]}</span>
@@ -42,11 +82,14 @@
</div>
<style>
/* No `overflow: hidden` here. It clipped the global :focus-visible ring,
which base.css draws at outline-offset: 2px — entirely outside the clip
region — leaving the theme control with no keyboard focus indicator at all.
The corner rounding it was for is done per-child instead. */
.group {
display: inline-flex;
border: 1px solid var(--border);
border-radius: var(--radius-sm);
overflow: hidden;
}
button {
@@ -60,8 +103,20 @@
font-size: var(--fs-1);
}
button:first-child {
border-top-left-radius: var(--radius-sm);
border-bottom-left-radius: var(--radius-sm);
}
button:last-child {
border-right: none;
border-top-right-radius: var(--radius-sm);
border-bottom-right-radius: var(--radius-sm);
}
/* Inset so the ring stays inside the group's own border box. */
button:focus-visible {
outline-offset: -2px;
}
button:hover {
+32 -4
View File
@@ -5,15 +5,43 @@
const toast = $derived(getVisibleToast());
</script>
<!-- Both live regions are ALWAYS in the DOM and only their text changes.
A live region inserted into the page already populated is not reliably
announced — screen readers derive announcements from mutations to a region
that was already present, so the earlier "whole thing inside {#if}" shape
meant success toasts were silently skipped.
Two fixed regions rather than one with a swapped aria-live, because
changing a live region's politeness at runtime is not reliably picked up.
Assertive interrupts, which is right for a failure and wrong for a
confirmation — the same split Callout already makes. -->
<div class="sr-only" role="status" aria-live="polite">
{toast !== undefined && toast.tone !== 'danger' ? toast.message : ''}
</div>
<div class="sr-only" role="alert" aria-live="assertive">
{toast?.tone === 'danger' ? toast.message : ''}
</div>
{#if toast !== undefined}
<!-- role follows Callout's convention: an error interrupts, a status waits. -->
<div class="toast {toast.tone}" role={toast.tone === 'danger' ? 'alert' : 'status'}>
<span>{toast.message}</span>
<button aria-label={t('common.cancel')} onclick={() => dismissToast(toast.id)}>✕</button>
<div class="toast {toast.tone}">
<!-- Hidden from assistive tech: the live regions above already carry it,
and announcing it twice is worse than not styling it. -->
<span aria-hidden="true">{toast.message}</span>
<button aria-label={t('common.dismiss')} onclick={() => dismissToast(toast.id)}>✕</button>
</div>
{/if}
<style>
.sr-only {
position: absolute;
width: 1px;
height: 1px;
overflow: hidden;
clip-path: inset(50%);
white-space: nowrap;
}
.toast {
position: fixed;
right: var(--sp-4);
+2 -1
View File
@@ -1,6 +1,7 @@
<script lang="ts">
import type { BookmarkNode } from '../core/model';
import type { NodeStatus } from '../core/diff';
import { t } from '../i18n/index.svelte';
import TreePreviewNode from './TreePreviewNode.svelte';
interface Props {
@@ -13,7 +14,7 @@
<!-- Read-only preview. Folders below depth 2 start collapsed and mount their
children lazily, so the DOM never holds the whole tree (docs/05 §9). -->
<ul class="tree" role="tree" aria-label="Preview">
<ul class="tree" role="tree" aria-label={t('import.preview')}>
{#each roots as node, i (i)}
<TreePreviewNode {node} {status} depth={1} />
{/each}
+5
View File
@@ -21,6 +21,10 @@ const dict = {
about: 'About',
busy: 'An import is in progress',
cancel: 'Cancel',
// Distinct from `cancel`: this only hides a notification about something
// that already finished — there is nothing left to call off.
dismiss: 'Dismiss',
sections: 'Sections',
},
popup: {
import: 'Import bookmarks…',
@@ -31,6 +35,7 @@ const dict = {
import: {
dropHint: 'Drop a bookmark file or click to browse — .html, .json, .csv · max {size}',
reading: 'Reading {name}…',
preview: 'Preview',
folderName: 'Imported {date}',
start: 'Import {n} bookmarks',
backingUp:
+3
View File
@@ -14,6 +14,8 @@ export default {
about: '概要',
busy: 'インポートを実行中です',
cancel: 'キャンセル',
dismiss: '閉じる',
sections: 'セクション',
},
popup: {
import: 'ブックマークをインポート…',
@@ -25,6 +27,7 @@ export default {
dropHint:
'ブックマークファイルをドロップするかクリックして選択してください — .html、.json、.csv · 最大 {size}',
reading: '{name} を読み込んでいます…',
preview: 'プレビュー',
folderName: 'インポート {date}',
start: '{n} 件のブックマークをインポート',
backingUp:
+3
View File
@@ -11,6 +11,8 @@ export default {
about: 'Giới thiệu',
busy: 'Đang có tiến trình nhập',
cancel: 'Hủy',
dismiss: 'Đóng',
sections: 'Các mục',
},
popup: {
import: 'Nhập bookmark…',
@@ -21,6 +23,7 @@ export default {
import: {
dropHint: 'Kéo thả tệp bookmark hoặc bấm để chọn — .html, .json, .csv · tối đa {size}',
reading: 'Đang đọc {name}…',
preview: 'Xem trước',
folderName: 'Đã nhập {date}',
start: 'Nhập {n} bookmark',
backingUp:
+16 -1
View File
@@ -17,7 +17,7 @@ import {
type ThemePreference,
writeSettings,
} from '../browser/storage';
import { setLocale } from '../i18n/index.svelte';
import { getLocale, setLocale } from '../i18n/index.svelte';
import { resolveLocale } from '../i18n/resolve-locale';
const SAVE_DEBOUNCE_MS = 200;
@@ -144,6 +144,7 @@ async function save(): Promise<SaveOutcome> {
function applyLocale(): void {
if (settings.locale !== 'auto') {
setLocale(settings.locale);
applyDocumentLanguage();
return;
}
// A failing i18n lookup must not stop settings from loading — fall back to
@@ -155,6 +156,20 @@ function applyLocale(): void {
uiLanguage = 'en';
}
setLocale(resolveLocale(uiLanguage));
applyDocumentLanguage();
}
/**
* Keep `<html lang>` in step with the UI language.
*
* Both entrypoint documents ship `lang="en"`, so without this a screen reader
* reads Vietnamese and Japanese text with an English voice and pronunciation
* rules — the strings change and the announced language does not.
*/
function applyDocumentLanguage(): void {
const root = globalThis.document?.documentElement;
if (root === undefined) return;
root.lang = getLocale();
}
/**
+6
View File
@@ -38,6 +38,10 @@
--fg: #e8eaee;
--fg-muted: #9aa3b0;
--accent: #8b6dff;
/* Dark mode lightens --accent for contrast against --bg, which drops white
ink on it to 3.67:1 — under the 4.5:1 docs/06 §5 requires. --accent-fg must
be redefined alongside it; dark ink on #8b6dff measures 4.84:1. */
--accent-fg: #16181d;
--danger: #ff6b7d;
--success: #3ecf8e;
--warn: #e2b93b;
@@ -51,6 +55,8 @@
--fg: #e8eaee;
--fg-muted: #9aa3b0;
--accent: #8b6dff;
/* Keep in step with the [data-theme='dark'] block above. */
--accent-fg: #16181d;
--danger: #ff6b7d;
--success: #3ecf8e;
--warn: #e2b93b;
+12
View File
@@ -154,6 +154,18 @@ describe('settings store', () => {
expect(getLocale()).toBe('ja');
});
it('keeps <html lang> in step with the UI language', async () => {
// Both entrypoint documents ship lang="en"; without this a screen reader
// reads VI/JA text with an English voice and pronunciation rules.
await updateSettings({ locale: 'vi' });
expect(document.documentElement.lang).toBe('vi');
await updateSettings({ locale: 'ja' });
expect(document.documentElement.lang).toBe('ja');
vi.spyOn(fakeBrowser.i18n, 'getUILanguage').mockReturnValue('en-GB');
await updateSettings({ locale: 'auto' });
expect(document.documentElement.lang).toBe('en');
});
it('still loads when the browser i18n lookup throws', async () => {
vi.spyOn(fakeBrowser.i18n, 'getUILanguage').mockImplementation(() => {
throw new Error('not implemented');