Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions docs/accessibility.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# MiniCrafter accessibility

Audit date: 2026-11-10 · Game version: 33 · Tools: axe-core 4.12.1 (injected with Playwright, as in `tests/smoke.mjs`), plus a manual pass at 1280×720 (desktop) and 812×375 sideways with `?touch=1` (phone).

MiniCrafter is a 3D block game. Looking around and placing blocks needs sight and a mouse, keyboard or touch screen, so it is **not playable with a screen reader**. This page says what we do support, what we checked, and what is still open.

## What we support (for schools)

- **Whole-menu keyboard use.** Every menu, panel and setting can be reached and used with Tab, Shift+Tab, Enter and Space. Pop-up panels (worlds, Play Together, account, inventory, crafting, quest book, photo, pet, What's new, report) move focus into the panel, keep Tab inside it, and close with **Esc**. Focus goes back to the button you used.
- **Visible focus.** A thick yellow ring shows where the keyboard focus is.
- **Big touch targets.** On phones and tablets every button, tab, field, slider and the hotbar slots are at least 44×44 px.
- **Readable HUD.** Text drawn over the game (hints, messages, mode badge, level number, armor line, hotbar numbers) has a dark backing and is at least 4.5:1 against any sky, including pure white.
- **Not colour alone.** Hearts change shape (♥ full, ♡ empty) as well as colour. Quest progress shows "3 / 5" next to its bar. Finished quests show a ✅ and filled stars. The selected chip also gets a white border.
- **Reduced motion.** If the device asks for it (`prefers-reduced-motion`), fades and slides are switched off, the quest-complete card does not zoom in, the red damage flash is softer and shorter, and celebration confetti is skipped. The game has no camera bob or screen shake.
- **Labels.** Every icon-only button has an accessible name. The ✕ close button on every panel is labelled "Close". Health, air and food are announced as "Health: 7 of 10 hearts". Messages and hints are announced by screen readers.
- **Language and structure.** The page language is set (`lang="en"`). Panels are named dialogs. Headings run in order inside each panel.
- **Legal pages and the features page** pass axe-core with no violations.
- **No tracking or outside content** that could get in the way of assistive tools: the game loads nothing from other sites.

Not supported yet: playing with a screen reader, a text-size setting, remapping keys, one-switch / eye-control play, and zooming the page on phones (see the open items below). If your school needs any of these, tell us.

## Findings

Severity: **High** blocks a group of players, **Medium** makes things hard, **Low** is a polish or best-practice item. "Fixed" means fixed in game version 33.

| # | Issue | Where | Severity | Status |
|---|---|---|---|---|
| 1 | Esc did not close Play Together, account, My worlds, What's new, report or the adventure gate (it only worked in-game) | Menu pop-ups | High | Fixed |
| 2 | Keyboard focus stayed on the button behind a pop-up; Tab walked through the hidden menu underneath | All pop-ups | High | Fixed (focus moves in, Tab stays in, focus returns) |
| 3 | Focus ring was the browser's 1 px default line | Everywhere | Medium | Fixed (3 px ring) |
| 4 | HUD text had only a text-shadow and no backing: 1.2–2.5:1 on a bright sky (hint, toast, armor line, mode badge, level number) and 2.5:1 for hotbar numbers | HUD | High | Fixed (6.4–8.7:1 on white; hotbar counts 5.0:1) |
| 5 | Touch targets under 44 px: menu mode buttons (36), "Another idea" (30), sliders (16), selects (35), account tabs (30), Play Together chips (28), Back/Done (38), links (16), Bit's Run/Stop/speed (38–41), ✕ at short heights (40), hotbar slots (38–40) | Phone | Medium | Fixed (44 px minimum with `?touch=1` / touch devices; hotbar and XP bar nudged up 12 px on short phone screens) |
| 6 | Selected colour chip: white text on pink, 4.0:1 (axe `color-contrast`) | Play Together | Medium | Fixed (dark or white label by colour) |
| 7 | "Survival only" tags in the quest book were 2.5:1 (the dimming made them faint) | Quest book | Medium | Fixed |
| 8 | Hearts: empty vs full relied on red vs dark red | Survival HUD | Medium | Fixed (♡ vs ♥ shape, plus a spoken label) |
| 9 | Health, air and food had no text alternative | Survival HUD | Medium | Fixed |
| 10 | Toast, hint and quest-complete card were not announced | HUD | Medium | Fixed (`role="status"`) |
| 11 | No reduced-motion handling for the quest-complete zoom, fades, confetti, damage flash (only the "turn your phone" hint had it) | HUD, game | Medium | Fixed |
| 12 | Scrollable quest list and recipe list could not be scrolled with the keyboard (axe `scrollable-region-focusable`) | Quest book, crafting | Medium | Fixed |
| 13 | Pop-ups were plain `div`s: no dialog role or name | All pop-ups | Medium | Fixed |
| 14 | Fields with only a placeholder (World name, Seed, adult-check answer) | Worlds, gate | Low | Fixed (`aria-label`) |
| 15 | Colour-picker groups had a label but no role | Play Together | Low | Fixed |
| 16 | Axe `region`: content outside landmarks (menu, game view, HUD) | Everywhere | Low | Mostly fixed (menu is `main`, pop-ups are dialogs, game view is labelled). The in-game HUD still reports it. Not fixed: HUD is overlay chrome, and a screen reader cannot play the game anyway |
| 17 | Axe `meta-viewport`: pinch-zoom is switched off (`user-scalable=no`) | All game screens | Medium | **Not fixed.** On phones the canvas uses touch gestures and the browser zoom would fight them. Needs a design decision; see follow-ups |
| 18 | Smallest text is 11.5 px (item names under inventory blocks, "Quests (Q)" key hint, hotbar numbers 11 px) | Inventory, HUD | Low | Not fixed. Fits the layout and passes contrast; a text-size setting is the real fix |
| 19 | "Oops!" screen uses a second `h1` | Death screen | Low | Not fixed (it is a separate screen, so order is still fine) |
| 20 | Quest tracker layout on phones (fold, mini view and a `#quest-view` setting) | `#quest-tracker` | Not an accessibility fault | Out of scope here. Handled in PR #44, which is not covered by this audit. Re-check its header height (32–40 px before that change) against 44 px once it lands |
| 21 | Hotbar slots, block grid and crafting slots are not keyboard-reachable (1–9 and the wheel select hotbar slots, the inventory uses the mouse/touch) | Inventory, crafting | High | Not fixed (follow-up) |
| 22 | The 3D game cannot be played with a screen reader | Game | High | Not fixed (follow-up) |
| 23 | No in-game text-size setting | Settings | Medium | Not fixed (follow-up) |

Axe results across the start menu (with settings open), Play Together, account (log in and create), What's new, report, My worlds, trade, adventure gate, rotate prompt, death, inventory, crafting, quest book, pet panel, photo mode, the HUD with Bit's panel, `features.html`, `privacy.html`, `terms.html` and `stats.html`:

- Before: `color-contrast` (2 screens), `scrollable-region-focusable` (2 screens), `meta-viewport` and `region` everywhere. The static pages had no violations.
- After: only `meta-viewport` (item 17) and a few `region` hits on the HUD (item 16).

## Manual checklist

| Check | Desktop | Phone (812×375, `?touch=1`) |
|---|---|---|
| Touch targets ≥ 44 px | Not required for a mouse; all controls ≥ 24 px (WCAG 2.5.8) | Pass after the fix. The quest tracker header is the one exception (item 20) |
| HUD contrast ≥ 4.5:1 over a bright sky | Pass (computed against white, the worst case) | Pass |
| Smallest text | 11.5 px (item 18) | 11.5 px |
| Icon-only buttons have `aria-label` | Pass (pause, undo, inventory, fly, emoji, photo, respawn, jump, down, ✕) | Pass |
| Tab order through the menus | Play, Play Together, account, My worlds, Quest book, idea, mode buttons, settings, controls, report, links: matches the screen | Same |
| Esc closes every panel | Pass after the fix (item 1) | No Esc key on phones. Every panel has a ✕ and tapping outside it closes it |
| Focus visible | Pass after the fix | Pass |
| `prefers-reduced-motion` | Pass after the fix | Pass |
| Not colour alone | Pass after the fix | Pass |
| Page language and headings | `lang="en"`; one `h1` per screen; `h2` then `h3` inside panels | Same |

## Follow-ups (bigger items, not in this change)

1. **Keyboard access to slots.** Make the hotbar, block picker and crafting slots focusable with arrow keys (roving tabindex), so players who cannot use a mouse can build.
2. **Text-size setting** (Small / Normal / Large) in Settings, which also fixes item 18.
3. **Pinch-zoom on menus.** Allow page zoom while a menu is open and keep it off while playing (item 17).
4. **Screen-reader play.** Announce what the player is looking at, what is nearby and how to move. This is a large design job. Bit the robot's Blockly editor also needs its own check.
5. **Key remapping and one-switch play.**
6. **Quest tracker target size** once the phone layout change lands.
7. Add axe to `tests/` so a new violation fails the build (the audit script injected axe-core by hand; it is not stored in the repo).

## How to re-run the audit

Start the game with `node server/dev.mjs` (set `PORT` to change it). In Playwright, open the page, inject `axe.min.js` from the `axe-core` package (`await page.addScriptTag({ path })`), run `axe.run(document)` on each screen, and open each pop-up first, either with its button or by taking `hidden` off its `.overlay`. For the phone check use an 812×375 viewport and `?touch=1`.
20 changes: 10 additions & 10 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
</script>
</head>
<body>
<div id="game"></div>
<div id="game" role="img" aria-label="MiniCrafter game view (the 3D world)"></div>

<div id="water-overlay" class="hidden"></div>
<div id="damage-flash"></div>
Expand All @@ -50,14 +50,14 @@
<div id="knock" class="hidden"><span id="knock-text"></span><button id="knock-yes" type="button">Let in <kbd>L</kbd></button><button id="knock-no" type="button">Not now <kbd>N</kbd></button></div>
<div id="emoji-bar" class="hidden"></div>
<div id="debug" class="hidden"></div>
<div id="toast"></div>
<div id="toast" role="status"></div>
<div id="mode-badge" class="hidden">FLYING</div>
<div id="hint"></div>
<div id="hint" role="status"></div>
<div id="quest-tracker">
<button id="qt-head" type="button"><span id="qt-stars">⭐ 0</span><span class="qt-key">Quests (Q)</span></button>
<div id="qt-list"></div>
</div>
<div id="celebrate"><div class="c-title">Quest complete!</div><div class="c-name"></div><div class="c-stars"></div><div class="c-reveal"></div></div>
<div id="celebrate" role="status"><div class="c-title">Quest complete!</div><div class="c-name"></div><div class="c-stars"></div><div class="c-reveal"></div></div>
<div id="status" class="hidden">
<div id="hearts"></div>
<div class="status-right"><div id="bubbles"></div><div id="hunger"></div></div>
Expand All @@ -68,7 +68,7 @@
<div id="hotbar"></div>
</div>

<div id="menu" class="overlay">
<div id="menu" class="overlay" role="main">
<div class="panel menu-panel">
<div class="menu-main">
<div class="brand">
Expand Down Expand Up @@ -169,8 +169,8 @@ <h2>👫 Play Together</h2>
<p class="note">Build with family and friends, up to 4 players. There's no chat, just emoji, and the host lets each player in.</p>
<div class="tg-me">
<div>You are <b id="tg-name"></b></div>
<div id="tg-colors" class="chips" aria-label="Pick a colour"></div>
<div id="tg-animals" class="chips" aria-label="Pick an animal"></div>
<div id="tg-colors" class="chips" role="group" aria-label="Pick a colour"></div>
<div id="tg-animals" class="chips" role="group" aria-label="Pick an animal"></div>
</div>
<div id="tg-login" class="tg-login hidden">
<p>🔒 <b>Log in to play together.</b> It keeps Play Together safe: only people with an account can make or join a game.</p>
Expand Down Expand Up @@ -332,8 +332,8 @@ <h2>🗂 My worlds</h2>
<div id="world-list"></div>
<h3 class="w-h3">✨ Make a new world</h3>
<div class="new-world">
<input id="nw-name" type="text" maxlength="30" placeholder="World name">
<input id="nw-seed" type="text" maxlength="40" placeholder="Seed (optional: same seed = same world)">
<input id="nw-name" type="text" maxlength="30" placeholder="World name" aria-label="World name">
<input id="nw-seed" type="text" maxlength="40" placeholder="Seed (optional: same seed = same world)" aria-label="Seed (optional)">
<div class="seg"><button id="nw-creative" type="button" class="on">Creative</button><button id="nw-survival" type="button">Survival</button><button id="nw-adventure" type="button">⚔️ Adventure</button></div>
<label id="nw-hardcore-row" class="hc hidden"><input id="nw-hardcore" type="checkbox"> ☠️ Hardcore: one life only</label>
<button id="nw-create" class="go" type="button">Create</button>
Expand Down Expand Up @@ -408,7 +408,7 @@ <h2 id="rotate-title">Turn your phone sideways</h2>
<h2>⚔️ Adventure mode is for older players</h2>
<p class="note">It has night creatures that fight back, hunger, tougher falls and losing your things when you faint. Grown-ups, please answer:</p>
<p class="gate-q" id="gate-q"></p>
<input id="gate-a" type="number" inputmode="numeric" placeholder="Answer">
<input id="gate-a" type="number" inputmode="numeric" placeholder="Answer" aria-label="Your answer">
<p class="note" id="gate-err"></p>
<div class="rb-row"><button id="gate-cancel" type="button">Back</button><button id="gate-ok" class="go" type="button">Continue</button></div>
</div>
Expand Down
57 changes: 57 additions & 0 deletions src/a11y.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
// Accessibility helpers (see docs/accessibility.md): pop-ups behave like proper dialogs
// (named, keyboard focus moves in, Tab stays inside, Esc closes) and one place to ask
// whether the player prefers reduced motion.
export const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)');

// Menu-level pop-ups: Esc presses their Back/Done button (in-game panels have their own Esc handling).
const ESC_CLOSES = [['together', 'tg-close'], ['account', 'acc-done'], ['worlds', 'w-done'], ['news', 'news-done'], ['report', 'report-done'], ['gate', 'gate-cancel']];
const FOCUSABLE = 'button, a[href], input:not([type=hidden]), select, summary, textarea, [tabindex="0"]';
const shown = (el) => el.getClientRects().length > 0 && getComputedStyle(el).visibility !== 'hidden';

/** Call once, after every overlay exists in the page. */
export function initA11y(overlayIds) {
const $ = (id) => document.getElementById(id);
let n = 0;
for (const id of overlayIds) {
const ov = $(id);
const panel = ov?.querySelector('.panel');
if (!ov || !panel) continue;
const h = panel.querySelector('h1, h2');
if (h) { if (!h.id) h.id = `a11y-title-${++n}`; ov.setAttribute('aria-labelledby', h.id); }
if (!ov.getAttribute('role')) ov.setAttribute('role', 'dialog');
ov.setAttribute('aria-modal', 'true');
panel.tabIndex = -1;
let opener = null;
new MutationObserver(() => {
if (!ov.classList.contains('hidden')) {
// Opened: remember where the player was, then move keyboard focus into the pop-up.
const a = document.activeElement;
opener = a && a !== document.body && !ov.contains(a) ? a : null;
requestAnimationFrame(() => { if (!ov.classList.contains('hidden') && !ov.contains(document.activeElement)) panel.focus({ preventScroll: true }); });
} else if (opener) {
// Closed: hand focus back to the menu button that opened it (never to in-game controls).
if (opener.isConnected && $('menu').contains(opener) && shown(opener)) opener.focus({ preventScroll: true });
opener = null;
}
}).observe(ov, { attributes: true, attributeFilter: ['class'] });
}
// Long lists that scroll must be reachable by keyboard even when they hold no buttons.
for (const [id, label] of [['qb-list', 'Quests'], ['recipes', 'Recipes']]) { const el = $(id); if (el) { el.tabIndex = 0; el.setAttribute('role', 'region'); el.setAttribute('aria-label', label); } }
for (const id of ['tg-status', 'loading']) $(id)?.setAttribute('aria-live', 'polite');

document.addEventListener('keydown', (e) => {
const open = [...document.querySelectorAll('.overlay[aria-modal]:not(.hidden)')].pop();
if (!open) return;
if (e.key === 'Escape') {
const hit = ESC_CLOSES.find(([ov]) => ov === open.id);
if (hit) { e.preventDefault(); $(hit[1]).click(); }
} else if (e.key === 'Tab') {
const items = [...open.querySelectorAll(FOCUSABLE)].filter((el) => !el.disabled && shown(el));
if (!items.length) return;
const first = items[0], last = items[items.length - 1];
if (!open.contains(document.activeElement) || document.activeElement === open.querySelector('.panel')) { e.preventDefault(); (e.shiftKey ? last : first).focus(); }
else if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
}
}, true);
}
Loading
Loading