From 047d918d43a5a809e3eec3d3cdbabfc7efb8a4d7 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:16:50 +0700 Subject: [PATCH] feat: accessibility statement, keyboard/screen-reader/chart/contrast fixes; 4.6.0 (#183) [skip-discuss] Accessibility pass for the website and the apps (WCAG 2.2 AA target) and the accessibility statement: root ACCESSIBILITY.md + docs/i18n/vi/ACCESSIBILITY.md, the accessibility issue form, a default PR template; focus management, the '/' shortcut switch, chart names and data tables, contrast tokens with a CI check, Windows contrast themes; a docs sync of verified mismatches; version 4.6.0 with the two deps sweeps since 4.5.0 (#176, #182). Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/accessibility.yml | 103 +++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 1 + .github/ISSUE_TEMPLATE/remove_game.yml | 2 +- .github/PULL_REQUEST_TEMPLATE/bug_fix.md | 1 + .../PULL_REQUEST_TEMPLATE/documentation.md | 3 +- .github/PULL_REQUEST_TEMPLATE/new_features.md | 1 + .github/pull_request_template.md | 28 +++ ACCESSIBILITY.md | 195 ++++++++++++++++++ CHANGELOG.md | 3 +- CLAUDE.md | 19 +- CONTRIBUTING.md | 6 +- NOTICE.md | 2 +- README.md | 9 +- README.vi.md | 7 +- SECURITY.md | 2 +- changelog/4.x/ver4.6.x.md | 100 +++++++++ data_game/LICENSE.md | 6 +- docs/THIRD_PARTY.md | 12 +- docs/dev_env.md | 1 + docs/i18n/vi/ACCESSIBILITY.md | 195 ++++++++++++++++++ docs/i18n/vi/CODE_OF_CONDUCT.md | 2 +- docs/i18n/vi/CONTRIBUTING.md | 8 +- docs/i18n/vi/DISCLAIMER.md | 2 +- docs/i18n/vi/EULA.md | 2 +- docs/i18n/vi/PrivacyPolicy.md | 2 +- docs/i18n/vi/SECURITY.md | 4 +- docs/i18n/vi/ToS.md | 2 +- docs/i18n/vi/dev_env.md | 3 +- docs/operations.md | 13 +- webapp/README.md | 5 +- webapp/package-lock.json | 4 +- webapp/package.json | 2 +- webapp/scripts/check-contrast.test.mjs | 92 +++++++++ webapp/scripts/gen_assets.py | 2 +- webapp/src-tauri/Cargo.lock | 2 +- webapp/src-tauri/Cargo.toml | 2 +- webapp/src-tauri/tauri.conf.json | 2 +- webapp/src/App.tsx | 80 ++++++- .../components/charts/accessibility-chart.tsx | 16 +- .../components/charts/ai-content-chart.tsx | 16 +- .../components/charts/ai-disclosure-chart.tsx | 20 +- .../components/charts/avg-session-chart.tsx | 11 +- webapp/src/components/charts/chart-card.tsx | 125 ++++++++++- .../src/components/charts/chart-skeletons.tsx | 41 +++- .../src/components/charts/chart-theme.test.ts | 28 +++ webapp/src/components/charts/chart-theme.ts | 27 +++ .../src/components/charts/chart-tooltip.tsx | 33 ++- .../charts/deletion-reasons-chart.tsx | 13 +- .../charts/deletions-over-time-chart.tsx | 12 +- .../components/charts/game-count-chart.tsx | 21 +- webapp/src/components/charts/genre-chart.tsx | 13 +- .../components/charts/genre-treemap-chart.tsx | 25 ++- .../src/components/charts/languages-chart.tsx | 11 +- .../src/components/charts/made-with-chart.tsx | 13 +- .../charts/online-offline-chart.tsx | 33 ++- webapp/src/components/charts/palette.ts | 28 ++- .../src/components/charts/platform-chart.tsx | 14 +- webapp/src/components/charts/rating-chart.tsx | 12 +- .../charts/recent-deleted-chart.tsx | 18 +- webapp/src/components/charts/status-chart.tsx | 22 +- .../charts/top-rated-count-chart.tsx | 12 +- .../src/components/charts/top-tags-chart.tsx | 10 +- webapp/src/components/ext-link.tsx | 12 +- webapp/src/components/focus-target.ts | 76 +++++++ webapp/src/components/games/filter-chips.tsx | 101 +++++++-- webapp/src/components/games/game-rows.tsx | 11 +- webapp/src/components/legal-gate.tsx | 37 +++- webapp/src/components/nsfw-dialog.tsx | 19 +- webapp/src/components/scroll-to-top.tsx | 7 +- webapp/src/components/site/display-menu.tsx | 26 ++- webapp/src/components/site/global-search.tsx | 83 +++++--- .../components/site/preference-controls.tsx | 82 ++++++-- webapp/src/components/site/site-footer.tsx | 7 + webapp/src/components/site/site-header.tsx | 38 +++- webapp/src/components/ui/badge.tsx | 2 +- webapp/src/components/ui/button.tsx | 6 +- webapp/src/components/ui/card.tsx | 13 +- webapp/src/components/ui/popover.tsx | 2 +- webapp/src/components/ui/sheet.tsx | 12 +- webapp/src/components/ui/tabs.tsx | 2 +- webapp/src/index.css | 98 ++++++++- webapp/src/lib/about.ts | 23 ++- webapp/src/lib/chart-table.test.ts | 29 +++ webapp/src/lib/chart-table.ts | 29 +++ webapp/src/lib/color.test.ts | 29 +++ webapp/src/lib/color.ts | 31 +++ webapp/src/lib/i18n/en.ts | 28 ++- webapp/src/lib/i18n/index.ts | 15 +- webapp/src/lib/i18n/vi.ts | 28 ++- webapp/src/lib/nsfw.ts | 16 +- webapp/src/lib/route-focus.test.ts | 48 +++++ webapp/src/lib/route-focus.ts | 39 ++++ webapp/src/lib/turnstile.ts | 2 + webapp/src/routes/about.tsx | 37 ++-- webapp/src/routes/charts.tsx | 4 +- webapp/src/routes/deleted.tsx | 16 +- webapp/src/routes/error-preview.tsx | 2 +- webapp/src/routes/game-detail.tsx | 19 +- webapp/src/routes/games.tsx | 27 ++- webapp/src/routes/settings.tsx | 42 ++-- webapp/src/routes/suggest.tsx | 37 +++- webapp/src/routes/welcome.tsx | 31 ++- webapp/src/stores/prefs.ts | 10 + webapp/worker/gate-page.ts | 2 +- 104 files changed, 2329 insertions(+), 348 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/accessibility.yml create mode 100644 .github/pull_request_template.md create mode 100644 ACCESSIBILITY.md create mode 100644 changelog/4.x/ver4.6.x.md create mode 100644 docs/i18n/vi/ACCESSIBILITY.md create mode 100644 webapp/scripts/check-contrast.test.mjs create mode 100644 webapp/src/components/focus-target.ts create mode 100644 webapp/src/lib/chart-table.test.ts create mode 100644 webapp/src/lib/chart-table.ts create mode 100644 webapp/src/lib/color.test.ts create mode 100644 webapp/src/lib/color.ts create mode 100644 webapp/src/lib/route-focus.test.ts create mode 100644 webapp/src/lib/route-focus.ts diff --git a/.github/ISSUE_TEMPLATE/accessibility.yml b/.github/ISSUE_TEMPLATE/accessibility.yml new file mode 100644 index 0000000..5009369 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/accessibility.yml @@ -0,0 +1,103 @@ +name: ♿ Accessibility barrier +description: Something on the website or in the apps doesn't work with your keyboard, screen reader, zoom, contrast settings or other assistive technology +title: "[Accessibility] " +labels: ["accessibility"] +body: + - type: markdown + attributes: + value: | + Thank you for taking the time to report this. Every report helps, even a partial one — describe what happened in your own words, and skip whatever you'd rather not share. Please don't include health information. + + Prefer email, or don't have a GitHub account? Write to **contact@poli0981.dev** (English or Vietnamese). What happens next, and the response targets, are in [ACCESSIBILITY.md](https://github.com/poli0981/free-games-itchio-list/blob/main/ACCESSIBILITY.md#7-reporting-an-accessibility-barrier). + + **Found a security vulnerability?** Please don't file it here: report it privately (see SECURITY.md). + + - type: dropdown + id: where + attributes: + label: Where did it happen? + description: Pick all that apply. + multiple: true + options: + - Website (freeitchgames.win) + - Desktop app — Windows + - Desktop app — macOS + - Desktop app — Linux + - Android app + - Not sure + validations: + required: true + + - type: input + id: page + attributes: + label: Page or screen + description: The address of the page, or the screen in the app. + placeholder: e.g. https://freeitchgames.win/charts, or "the Games list in the Android app" + + - type: textarea + id: details + attributes: + label: What were you trying to do, and what happened? + description: What you expected, what happened instead, and the steps to get there if you can. + placeholder: | + e.g. I pressed Tab to reach the "Platform" filter, but focus jumped back to the top of the page. + validations: + required: true + + - type: dropdown + id: kind + attributes: + label: What kind of barrier? (optional) + multiple: true + options: + - Keyboard (can't reach or use something, focus lost or hidden) + - Screen reader (missing or wrong name, nothing announced, wrong reading order) + - Zoom, text size or layout at large sizes + - Colour or contrast (including Windows contrast themes) + - Motion or animation + - Charts + - Language (read in the wrong language or voice) + - Speech input or switch access + - Something else + + - type: dropdown + id: severity + attributes: + label: How much does it get in your way? + description: Just your best guess; it may change during triage. + options: + - Critical — I can't do a main task at all (find, open or read a game, change settings) + - Serious — I can, but only with great effort or a workaround + - Moderate — annoying or inconsistent, but I get there + - Minor — a small polish issue + validations: + required: true + + - type: input + id: assistive-tech + attributes: + label: Assistive technology and version (if any) + placeholder: e.g. Windows Narrator, NVDA 2026.1, VoiceOver on iOS 26, TalkBack, keyboard only, Windows contrast theme + + - type: input + id: environment + attributes: + label: Device, operating system, browser or app version + description: The app version is shown on the About page. + placeholder: e.g. Windows 11 + Edge 142; Android 15 + app 4.6.0 + + - type: textarea + id: media + attributes: + label: Screenshot or recording (optional) + description: Paste or drag files here. Please hide any personal information. + + - type: checkboxes + id: conduct + attributes: + label: Code of Conduct + description: By submitting this issue you agree to follow the project's [Code of Conduct](https://github.com/poli0981/free-games-itchio-list/blob/main/CODE_OF_CONDUCT.md). + options: + - label: I agree to follow the Code of Conduct. + required: true diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 7c17981..8464b69 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -10,6 +10,7 @@ body: **Found a security vulnerability?** Please don't file it here — report it privately via https://github.com/poli0981/free-games-itchio-list/security/advisories/new or security@poli0981.dev. Want a game removed (or you're its creator)? Use the "Remove a Game" template instead. + Something doesn't work with your keyboard, screen reader, zoom or contrast settings? The "Accessibility barrier" template asks the right questions. - type: dropdown id: where diff --git a/.github/ISSUE_TEMPLATE/remove_game.yml b/.github/ISSUE_TEMPLATE/remove_game.yml index fed4409..87652b2 100644 --- a/.github/ISSUE_TEMPLATE/remove_game.yml +++ b/.github/ISSUE_TEMPLATE/remove_game.yml @@ -1,7 +1,7 @@ name: 🚫 Remove a Game (or copyright request) description: Ask to remove games from the catalog or correct their data, including requests from creators and rights holders (max 10 per issue) title: "[Remove Games] " -labels: ["removal"] +labels: ["delete-game"] body: - type: markdown attributes: diff --git a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md index 230451b..4886a45 100644 --- a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md +++ b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md @@ -21,6 +21,7 @@ Closes # (link issue number if any) - [ ] Tested locally — Python: `pytest`, `ruff check scripts tests webapp/scripts`, `python scripts/validate.py`; webapp: `npm test`, `npm run lint`, `npx tsc -b` - [ ] No new bugs introduced (hopefully) - [ ] No secrets, tokens or personal data in the diff +- [ ] Touched the UI? It still works with the keyboard alone and a screen reader ([checklist](https://github.com/poli0981/free-games-itchio-list/blob/main/ACCESSIBILITY.md#8-for-contributors)) - [ ] I agree my contribution is licensed under the MIT License (see `LICENSE`) - [ ] Followed the vibe (chill, no drama) diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md index bc39926..59bfcf5 100644 --- a/.github/PULL_REQUEST_TEMPLATE/documentation.md +++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md @@ -4,7 +4,7 @@ Not code or games? Fix my bad English, typos, or update legal docs — still sup ### What did you update? - [ ] Fix typo/grammar in README/docs -- [ ] Update DISCLAIMER/PRIVACY/TERMS/EULA/SECURITY/etc. +- [ ] Update DISCLAIMER/PRIVACY/TERMS/EULA/SECURITY/ACCESSIBILITY/etc. - [ ] Update the Vietnamese mirror (`README.vi.md`, `docs/i18n/vi/`) - [ ] Improve MY_STUFF or ACKNOWLEDGEMENTS - [ ] Add badges/screenshots @@ -19,6 +19,7 @@ References # (if any) ### Checklist - [ ] No breaking changes - [ ] Relative links still resolve; website links use `https://freeitchgames.win/` +- [ ] Headings in order, link text that says where it goes, alt text for images, header cells in tables - [ ] If I changed an English doc that has a Vietnamese mirror, I updated the mirror too (or said so above so someone else can) - [ ] I agree my contribution is licensed under CC BY 4.0, like the rest of the documentation - [ ] Keeps the self-deprecating vibe :D diff --git a/.github/PULL_REQUEST_TEMPLATE/new_features.md b/.github/PULL_REQUEST_TEMPLATE/new_features.md index b17d5c6..d762175 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_features.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_features.md @@ -22,6 +22,7 @@ References # (link if any) ### Checklist - [ ] Tested locally (Python: `pytest`, `ruff check scripts tests webapp/scripts`; webapp: `npm test`, `npm run lint`, `npm run knip`, `npx tsc -b`) - [ ] Doesn't break the daily refresh or the ingest workflow +- [ ] UI changes pass the [accessibility checklist](https://github.com/poli0981/free-games-itchio-list/blob/main/ACCESSIBILITY.md#8-for-contributors): keyboard, focus, labels in `en.ts` + `vi.ts`, contrast (`npm test`), reduced motion, one screen-reader check - [ ] New npm dependency? Added it to `webapp/src/lib/about.ts` so the About page lists it - [ ] Edited `webapp/wrangler.jsonc`? Ran `npm run cf:types` - [ ] I agree my contribution is licensed under the MIT License (see `LICENSE`) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..94587b4 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ + + +### What and why + +What does this change, and why? + +### Related issues + +Closes # (if any) + +### Checklist + +- [ ] Tested locally — Python: `pytest`, `ruff check scripts tests webapp/scripts`; webapp: `npm test`, `npm run lint`, `npm run knip`, `npx tsc -b` +- [ ] No secrets, tokens or personal data in the diff +- [ ] New UI text is in both `webapp/src/lib/i18n/en.ts` and `vi.ts`; a changed English doc has its Vietnamese mirror updated (or I said so above) +- [ ] I agree my contribution is licensed like the part it changes: MIT for code, CC BY 4.0 for data and docs + +### Accessibility (UI or docs changes — see [ACCESSIBILITY.md](https://github.com/poli0981/free-games-itchio-list/blob/main/ACCESSIBILITY.md#8-for-contributors)) + +- [ ] N/A — no UI or docs change +- [ ] Works with the keyboard alone: everything reachable, focus visible and never lost +- [ ] Every control has a name; nothing relies on colour alone; `npm test` (contrast check) passes +- [ ] Respects reduced motion; no new auto-playing motion +- [ ] Checked once with a screen reader (Narrator, NVDA, VoiceOver or TalkBack) +- [ ] Docs: headings in order, descriptive link text, alt text for images diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md new file mode 100644 index 0000000..242536a --- /dev/null +++ b/ACCESSIBILITY.md @@ -0,0 +1,195 @@ +# Accessibility + +Last updated: 2026-11-09 + +Applies from: the release of version 4.6.0 (the website and the desktop and Android apps). + +This is a hobby project run by one person, poli0981 (SkullMute), called "the Maintainer" below: a catalog of free itch.io games, on the website https://freeitchgames.win and in desktop and Android apps that show the same pages. Everyone should be able to use it, whether with a keyboard alone, a screen reader, zoom, a high-contrast theme, speech input or anything else. This statement says what works, how it is checked, what doesn't work yet, and how to tell the Maintainer when something gets in your way. + +A Vietnamese translation is available at [`docs/i18n/vi/ACCESSIBILITY.md`](docs/i18n/vi/ACCESSIBILITY.md). If the two differ, this English version prevails. + +> **TL;DR** +> +> - The goal is [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA for the website and the apps. That is a target, not a certificate: nobody outside the project has audited it. +> - Every page works with the keyboard alone and with a screen reader. The Maintainer tests with the keyboard only and Windows Narrator. +> - Colours meet the WCAG contrast ratios in the light and dark themes, and a test checks them on every change. Windows contrast themes are supported, and the site follows your system's "reduce motion" setting. +> - Every chart comes with a data table. +> - Known gaps are listed in [§6](#6-known-limitations). +> - Something in your way? Open an [accessibility issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) or email **contact@poli0981.dev**. + +## 1. Scope + +This statement covers: + +- **the website** https://freeitchgames.win: every public page (Home, Games, the game pages, Charts, Removed, Suggest, Settings, About, the error pages) and the verification page shown before them; +- **the desktop apps** (Windows, macOS, Linux) **and the Android app**, which show the same pages in the system's web view. + +It doesn't cover: + +- the games themselves, their itch.io pages, and what their creators wrote or made (titles, descriptions, tags, cover images); +- Cloudflare Turnstile, the third-party check on the verification page and on the Suggest form (Cloudflare is responsible for its accessibility); +- the Maintainer's admin page, which has one user; +- other sites the pages link to, GitHub included. + +## 2. Goals and priorities + +- **Target**: [WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA, as far as a one-person hobby project can get. +- **First**: the main tasks with a keyboard and a screen reader: find a game, read its details, open it on itch.io, change your settings, suggest a game. +- **Then**: readable text and controls (contrast, zoom, reflow), no motion you didn't ask for, and the right language for screen readers (English or Vietnamese). +- **Always**: new features keep all of this working (see [§8](#8-for-contributors)). + +## 3. What works today + +### Moving around + +- "Skip to content" is the first thing the Tab key reaches. +- Each page has named landmarks (header, main navigation, search, main content, pager, footer), one level-1 heading, and its own title. +- After you follow a link inside the site, focus moves to the new page's heading, so a screen reader announces the page and Tab continues from there. Going back returns focus to the link you used, for example the game you opened from the list. +- The sticky header never covers what has keyboard focus. + +### Keyboard + +- Everything works with the keyboard alone: menus, filters, dialogs and charts. +- Focus is always visible: a purple outline, or the system highlight in a contrast theme. +- Dialogs keep focus inside while they are open and return it to where you were when they close. +- "/" jumps to the search box. You can switch this shortcut off in **Settings → Accessibility**, which helps with speech input or if the key clashes with your screen reader or your browser's quick find. +- When a control disappears after you use it (clearing a search, removing a filter), focus moves to the next sensible place instead of getting lost. + +### Screen readers + +- Every control has a name, in English or Vietnamese. Icons are hidden from screen readers. +- The number of results, search suggestions, loading states and form messages are announced. +- On wide screens the game list is a table with column headers; on phones it is a simple list. +- Links that open a new tab (in the apps: your browser) say so. +- Text in the other language, such as the language names and the English-only names of the legal documents, is marked with its language. + +### Seeing the content + +- Text and controls meet the WCAG 2.2 AA contrast ratios in both themes: 4.5:1 for text, 3:1 for field borders, the focus outline and chart colours. The test [`webapp/scripts/check-contrast.test.mjs`](webapp/scripts/check-contrast.test.mjs) checks the colours on every change. +- Light, dark or system theme, compact or normal rows, and hidden scrollbars: all in Settings. +- Windows contrast themes (forced colours): the selected tab, pressed toggles, the current page and switches use the system's highlight colours. +- Zoom is never blocked. At 400 % zoom or in a 320-pixel-wide window the phone layout takes over, and the page doesn't scroll sideways. +- Links inside sentences are underlined. Nothing is shown by colour alone: states also change the text, an outline or an underline. + +### Motion + +- With "reduce motion" switched on in your system, animations, chart entrances and smooth scrolling are off. +- On the website, covers are normally shown as still images (animated covers are turned into stills). +- Apart from loading placeholders, nothing moves on its own. + +### Charts + +- Each chart is named after its heading. Focus it and use the left and right arrow keys: the value you move to is read out. +- Under every chart, **Data table** opens the same numbers as a table, with each part's share for the pie charts. + +### Language + +- The pages are in English or Vietnamese (Settings), and the page language follows your choice, so screen readers pick the right voice. Numbers and dates follow it too. + +## 4. How it is tested + +- **By the Maintainer, by hand** (November 2026): the website on Windows 11 and the Windows desktop app, with the keyboard only (mouse switched off) and Windows Narrator. No blocking problems were found. +- **For 4.6.0**: the main pages and dialogs were walked through with the keyboard, and their accessibility tree was checked (names, roles, headings, landmarks, announcements) in English and Vietnamese, on a desktop and a phone-sized screen. +- **Automatically, on every change**: the contrast test above and the app's unit tests (where focus goes after a page change, the chart tables). +- **Before each release**: a short smoke test. That means a keyboard pass through the main tasks, a screen reader spot check, 200 % zoom and a narrow window, reduced motion, and a Windows contrast theme. +- **Not yet**: automated browser scans (such as axe or Lighthouse) in CI, and testing by people who use a wide range of assistive technology every day. Help is welcome. + +## 5. Supported environments + +| | Versions | +|---|---| +| Website | Current Chrome, Edge, Firefox and Safari on computers and phones. The oldest versions the site is built for are Chrome and Edge 111, Firefox 114, and Safari and iOS 15.4. | +| Desktop apps | Windows 10 and 11 (Microsoft Edge WebView2), macOS (WebKit 16.4 or newer), Linux (WebKitGTK 4.1) | +| Android app | Android 11 or newer | + +Assistive technology: + +- **Tested**: Windows Narrator on Windows 11, and keyboard-only use. +- **Expected to work, not regularly tested**: NVDA and JAWS on Windows, VoiceOver on macOS and iOS, TalkBack on Android, browser zoom, Windows contrast themes, speech input. They rely on the same standard markup. +- **Limited**: Orca in the Linux desktop app, because WebKitGTK supports screen readers less well than the browsers do. + +## 6. Known limitations + +- **Creators' text isn't marked with its language.** Game titles, descriptions and tags come from itch.io in many languages, and a screen reader reads them in the page's language. +- **Cover images have a generic description** ("Game name cover"). What the image shows isn't described. +- **Charts**: the arrow keys only move left and right. The genre treemap can't be stepped through, but its numbers are in its data table and in the Genres chart. Chart text has a fixed pixel size, so a larger default font size in your browser doesn't change it (page zoom does). +- **Desktop apps**: there are no zoom keys inside the app, the window can't be maximized, and it can't be made smaller than 900 × 600. If you need larger text, use your system's display scaling or the website in a browser. +- **Android app**: pinch-to-zoom is off. The website can be zoomed in your phone's browser. +- **Animated covers in the apps**: the apps load covers straight from itch.io, so an animated cover keeps playing there. +- **Cloudflare's checks**: the verification check (website only) and the anti-spam check on the Suggest form are Cloudflare Turnstile widgets. They usually pass without anything to do. If one ever asks for something you can't do, email the Maintainer. +- **GitHub pages**: the policies, this statement and the issue forms live on GitHub, so GitHub's own accessibility applies there. +- **No external audit**, and one maintainer. + +## 7. Reporting an accessibility barrier + +If something stops you or slows you down, please say so. Partial reports help too. + +- **GitHub**: open an [Accessibility barrier issue](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml). +- **Email**: **contact@poli0981.dev**. No GitHub account needed; English or Vietnamese both work. + +Details that help, as far as you're comfortable sharing them (never send health information): + +- what you were trying to do, and what happened instead; +- the page (its address) or the app and its version, shown on the About page; +- your device, operating system and browser; +- the assistive technology you use and its version, if any; +- a screenshot or a recording, if you can. + +How much it gets in your way: + +| Severity | Meaning | +|---|---| +| Critical | You can't do a main task at all, for example open a game or read its details. | +| Serious | You can, but only with great effort or a workaround. | +| Moderate | It's annoying or inconsistent, but you get there. | +| Minor | A small polish issue. | + +What happens next. These are targets, not guarantees, since this is a solo hobby project: + +- **Acknowledgement** within 7 days, often sooner. +- **A fix or a workaround**: Critical within 30 days, Serious within 60 days, Moderate and Minor in a later release. +- **Website fixes** go live when they are deployed; **app fixes** come with the next release. +- You'll be asked whether the fix works for you, and credited in the release notes if you want. + +Security vulnerabilities don't belong in a public issue: see [SECURITY.md](SECURITY.md). + +## 8. For contributors + +Changes to the interface must keep [§3](#3-what-works-today) true: + +- **Keyboard**: every control can be reached and used, focus stays visible and never gets lost. +- **Names**: every control has a label, with its text in both `webapp/src/lib/i18n/en.ts` and `vi.ts`. +- **Colour**: use the theme tokens. `npm test` checks contrast (4.5:1 for text, 3:1 for borders, focus and chart colours), and colour is never the only signal. +- **Motion**: respect `prefers-reduced-motion`; the shared CSS rule and `SERIES_ANIMATION` already do. +- **Screen reader**: check the change once with one (Narrator, NVDA, VoiceOver or TalkBack). +- **Markup**: prefer native elements and the Radix / shadcn components already in use, and add ARIA only when it's needed. + +Documentation: headings in order, link text that says where it goes, alt text for images, header cells in tables, and the Vietnamese translation updated (or say in the pull request that it isn't). + +The [pull request template](.github/pull_request_template.md) has the checklist. + +## 9. Finding accessible games + +The catalog shows the accessibility features that creators list on their itch.io pages, such as subtitles, configurable controls or colour-blind modes: + +- on each game's page, under "Accessibility"; +- as the Accessibility filter on the Games page, for example https://freeitchgames.win/games?access=Subtitles; +- in the "Accessibility Features" chart (Charts → Discovery). + +Creators declare these features themselves, and the project doesn't verify them. If a game's information is wrong, report it with the "Bug Report" issue template. + +## 10. References + +- [Open Source Guides: Accessibility best practices for your project](https://opensource.guide/accessibility-best-practices-for-your-project/) +- [Open Source Accessibility toolkit](https://github.com/open-source-accessibility/accessibility-toolkit): this statement follows the outline of its ACCESSIBILITY.md example, in its own words. +- [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) +- [W3C: Developing an accessibility statement](https://www.w3.org/WAI/planning/statements/) + +## 11. Contact + +- **Accessibility barriers**: the [issue form](https://github.com/poli0981/free-games-itchio-list/issues/new?template=accessibility.yml) or **contact@poli0981.dev**. +- **Everything else**: see the addresses in [README → Legal](README.md#legal). + +## 12. Final vibes + +One person, one catalog, every way of browsing it. If something here doesn't work the way you use the web, the Maintainer would really like to hear it — that's how this list gets better. 🚀 diff --git a/CHANGELOG.md b/CHANGELOG.md index e6aeb64..09b1577 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,12 +3,13 @@ All notable changes to this project, newest first. The notes of each release live in [`changelog/`](changelog/), one file per minor version: `changelog/.x/ver..x.md`. -**Latest release: [4.5.0](changelog/4.x/ver4.5.x.md#450---2026-10-27-rate-limits-for-the-whole-site) (2026-10-27) — Rate limits for the whole site.** +**Latest release: [4.6.0](changelog/4.x/ver4.6.x.md#460---2026-11-09-accessibility) (2026-11-09) — Accessibility.** ## 4.x | Version | Date | Highlights | |---|---|---| +| [4.6.0](changelog/4.x/ver4.6.x.md#460---2026-11-09-accessibility) | 2026-11-09 | Accessibility: statement, keyboard and screen-reader fixes, chart data tables, WCAG contrast | | [4.5.0](changelog/4.x/ver4.5.x.md#450---2026-10-27-rate-limits-for-the-whole-site) | 2026-10-27 | Rate limits for the whole site (HTTP 429), WAF guide | | [4.4.3](changelog/4.x/ver4.4.x.md#443---2026-10-26-dependency-and-security-updates) | 2026-10-26 | Dependency and security updates (build-tool advisories closed) | | [4.4.2](changelog/4.x/ver4.4.x.md#442---2026-10-22-toolchain-upgrade-code-scan-fixes) | 2026-10-22 | Toolchain upgrade (TypeScript 7, Node 26, Python 3.15), code-scan fixes | diff --git a/CLAUDE.md b/CLAUDE.md index 0f5814f..e73dfd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,14 +60,15 @@ Local admin without Access: put `DEV_ADMIN_EMAIL=you@example.com` in `webapp/.de - Cache: react-query persisted to IndexedDB (`webapp.query-cache`, 7 days) by `lib/data/persister.ts` — byte 0 = format (1 deflate-raw, 0 plain), then the JSON; a legacy string is dropped; writes throttled 1 s and skipped when no data object changed. Persisted: `db`, `deleted`, `count-history` and only the `desc` files the current catalog names (`shouldPersistQuery`); stale `desc` queries are removed after a `db` success. `CACHE_BUSTER = ${APP.version}:data-v2`. **`gcTime` must stay >= persist `maxAge`.** - Layout: `components/site/*` (sticky top nav + global search with the `/` shortcut + display menu + phone sheet menu; footer) — the window scrolls, not `
`. `/` is the Welcome page (`routes/welcome.tsx`). - `/games`: search, filters, sort and page live in the URL — `lib/game-filters.ts` (`parseQuery` / `toParams` drop defaults; params `q genre platform status tag lang input engine ai access rating browser sort page`; `ai` treats "N/A" / a missing field as its own "Not disclosed" value and lists its options in a fixed order (`aiRank`); unit-tested) — rendered by `components/games/*` (filter chips with facet counts that ignore their own filter, a desktop ARIA table / phone list chosen by `useIsMobile`, 100 per page; the detail page's breadcrumb links back to the same list via router state). Counts show the whole catalog ("2,729 of 2,811") because 18+ games are hidden by default. -- `components/charts/` (19 charts, 4 lazy tabs loaded with `lib/lazy-preload.ts` — preloaded when idle or on hover/focus, rendered without a Suspense fallback once loaded — and kept mounted once shown (gotcha 33; skeletons in `chart-skeletons.tsx` match the cards), every series spreading `SERIES_ANIMATION` (300 ms, no delay; a test checks), **no barrel `index.ts`**; every Recharts tooltip/cursor comes from `chart-theme.ts` + `chart-tooltip.tsx`, every pie legend from `LEGEND_BASE` there; below `md` the charts get 12 px legends / 11 px ticks from a media block in `index.css`, the tab bar is one row of equal tabs, and Languages / Avg session switch to horizontal bars via `useIsMobile`), `components/game-thumb.tsx` (`lib/thumbnail.ts` → `/img/160|640/...` on the web, the original URL in Tauri), `components/legal-gate.tsx` (a non-dismissable Radix dialog **over** the page, so deep links land where they pointed; links flagged `inGate` in `lib/about.ts`; re-prompts when `LEGAL_VERSION` in `stores/prefs.ts` changes; no "Leave" button in Tauri). -- Styling: **Tailwind v4** via `@tailwindcss/vite` (no PostCSS, no `tailwind.config`); tokens are hex CSS variables in `src/index.css` (`:root` / `.dark`, `@theme inline`; `--brand-soft`, `--thumb`, `--success`, `--scrollbar-thumb(-hover/-active)` besides the shadcn set) and must match the approved mockup. Themed scrollbars (`@layer base`, only under `(hover: hover) and (pointer: fine)`): `::-webkit-scrollbar*` for Chromium/Safari, `scrollbar-color` / `scrollbar-width: thin` for Firefox only (gotcha 28); "Hide scrollbars" = unlayered `html[data-scrollbars='hidden']` rules (`hooks/useScrollbarsEffect.ts`). On mouse devices `` reserves the scrollbar gutter, released while a dialog locks scrolling (gotcha 35). The theme: `stores/theme.ts` (synced across tabs, site ↔ admin), `hooks/useThemeEffect.ts` (`.dark` + the `theme-color` metas), an inline pre-paint script in both HTML entries (gotcha 34), and the display menu's button shows `components/theme-icon.ts`'s icon for the theme in use. Self-hosted Geist / Geist Mono (`@fontsource-variable/*`, CSP `font-src 'self'`). Numbers and dates go through `lib/format.ts` (`useFormat`: en-GB / vi-VN). `webapp/scripts/gen_assets.py` redraws favicon, PWA icons and `og.png` from the same tokens and the Geist fonts in `node_modules`. +- `components/charts/` (19 charts, 4 lazy tabs loaded with `lib/lazy-preload.ts` — preloaded when idle or on hover/focus, rendered without a Suspense fallback once loaded — and kept mounted once shown (gotcha 33; skeletons in `chart-skeletons.tsx` match the cards), every series spreading `SERIES_ANIMATION` (300 ms, no delay; a test checks), **no barrel `index.ts`**; every Recharts tooltip/cursor comes from `chart-theme.ts` + `chart-tooltip.tsx`, every pie legend from `LEGEND_BASE` there; every chart container spreads `chartAria(id)` (named by its card's h2 + description + arrow-key hint), every `` has `rootTabIndex={-1}`, every `ChartCard` gets an `id` and a `table` (a lazy `
` "Data table" built with `lib/chart-table.ts`), and the tooltip reads its text into the card's polite live region through `ChartAnnounce` (a ref, no re-render — gotcha 33); `chart-theme.test.ts` checks all four; below `md` the charts get 12 px legends / 11 px ticks from a media block in `index.css`, the tab bar is one row of equal tabs, and Languages / Avg session switch to horizontal bars via `useIsMobile`), `components/game-thumb.tsx` (`lib/thumbnail.ts` → `/img/160|640/...` on the web, the original URL in Tauri), `components/legal-gate.tsx` (a non-dismissable Radix dialog **over** the page, so deep links land where they pointed; links flagged `inGate` in `lib/about.ts`; re-prompts when `LEGAL_VERSION` in `stores/prefs.ts` changes; no "Leave" button in Tauri). +- Styling: **Tailwind v4** via `@tailwindcss/vite` (no PostCSS, no `tailwind.config`); tokens are hex CSS variables in `src/index.css` (`:root` / `.dark`, `@theme inline`; `--brand-soft`, `--thumb`, `--success`, `--scrollbar-thumb(-hover/-active)` besides the shadcn set) and must match the approved mockup — except where WCAG 2.2 AA needed more (4.6.0): `--primary` #6a48f5 (white text 5.44:1), `--primary-text` for purple text (#9a83ff in dark), `--input` #8a8a93 / #6b6b75 for field borders and the off switch (3:1), `--destructive-solid` for filled destructive buttons; `--brand` keeps the mockup's #7c5cff for the logo (as do the favicon, `og.png`, the app icons and the gate page's logo). `webapp/scripts/check-contrast.test.mjs` fails CI when a token pair or a chart colour (`components/charts/palette.ts`) drops below 4.5:1 (text) / 3:1 (borders, ring, chart marks); `lib/color.ts` does the maths. A `@media (forced-colors: active)` block gives selected tabs / pressed toggles / the current page / the active option and switches the system highlight (Windows contrast themes). Themed scrollbars (`@layer base`, only under `(hover: hover) and (pointer: fine) and (forced-colors: none)`): `::-webkit-scrollbar*` for Chromium/Safari, `scrollbar-color` / `scrollbar-width: thin` for Firefox only (gotcha 28); "Hide scrollbars" = unlayered `html[data-scrollbars='hidden']` rules (`hooks/useScrollbarsEffect.ts`). On mouse devices `` reserves the scrollbar gutter, released while a dialog locks scrolling (gotcha 35). The theme: `stores/theme.ts` (synced across tabs, site ↔ admin), `hooks/useThemeEffect.ts` (`.dark` + the `theme-color` metas), an inline pre-paint script in both HTML entries (gotcha 34), and the display menu's button shows `components/theme-icon.ts`'s icon for the theme in use. Self-hosted Geist / Geist Mono (`@fontsource-variable/*`, CSP `font-src 'self'`). Numbers and dates go through `lib/format.ts` (`useFormat`: en-GB / vi-VN). `webapp/scripts/gen_assets.py` redraws favicon, PWA icons and `og.png` from the same tokens and the Geist fonts in `node_modules`. - `lib/gate.ts` (web only): when a tab comes back into view or a cover fails and the verification pass may have run out (`webapp.gate` hint), it asks `GET /api/verify` and reloads into the verification page; `lib/reload.ts` is the shared at-most-every-30-s reload guard. - `hooks/useSeoHead.ts` sets canonical + robots per route (index.html has no static canonical/og:url on purpose). +- Accessibility (statement: root `ACCESSIBILITY.md`; target WCAG 2.2 AA): after an in-app navigation `App.tsx`'s ScrollManager moves focus to the new page's h1 (`lib/route-focus.ts` decides: not on first load or query-only changes; a #hash focuses its section; Back focuses the link last used on that entry), waiting for lazy routes with `components/focus-target.ts` (`whenPresent`, 10 s; `focusElement` adds `tabindex=-1` + `data-focus-target`, which hides the ring). Dialogs without a trigger return focus themselves (18+: the opener, `requestNsfw(returnFocus)`; legal gate: the page h1); menus that navigate `preventDefault` their `onCloseAutoFocus` (gotcha 46). The "/" shortcut is a pref (`slashShortcut`, Settings → Accessibility; WCAG 2.1.4). `CardTitle` renders an h2. `ExtLink` appends "(opens in a new tab)" / "(opens in your browser)" for screen readers. English-only strings shown on a Vietnamese page carry `lang="en"`; `` turns `vi` only once the VI dictionary is in. `html { scroll-padding-top }` keeps focus clear of the sticky header. No a11y linter: `eslint-plugin-jsx-a11y` peers ESLint ≤ 9. - `lib/i18n/` — `en.ts` is the source of truth; `vi.ts` is `Record` and must never be static-imported (lazy chunk). - `stores/` — Zustand: `prefs` (`webapp.prefs`: language, density, `hideScrollbars`, legal acceptance…), `theme` (`webapp.theme`). - `lib/about.ts` — keep `THIRD_PARTY` up to date when adding npm deps; `LEGAL_LINKS`; `APP.version`. -- Code split (`vite.config.ts` rolldown `codeSplitting.groups`): `vendor-react` (priority 100 — must claim React first), `vendor-query`, `vendor-ui`. There is deliberately **no vendor-charts group** (it pulled React/clsx in and put Recharts on the first load); Recharts stays in the lazy chart chunks. Initial load ≈ 179 KB gzip (JS + CSS, gzip -9; 4.2 added ~4.6 KB for the pack loader, persister and `useQueries`) plus ~51 KB of Geist woff2; catalog data on a first visit ≈ 264 KB (main packs + log + history), descriptions ≈ 170 KB on demand. `fflate` is a lazy chunk, never preloaded. Web build `target` is Safari/iOS 15.4 (Radix class static blocks otherwise break iOS 15); Tauri uses the default. +- Code split (`vite.config.ts` rolldown `codeSplitting.groups`): `vendor-react` (priority 100 — must claim React first), `vendor-query`, `vendor-ui`. There is deliberately **no vendor-charts group** (it pulled React/clsx in and put Recharts on the first load); Recharts stays in the lazy chart chunks. Initial load ≈ 189 KB gzip (JS + CSS, gzip -9, measured for 4.6.0; 4.2 added ~4.6 KB for the pack loader, persister and `useQueries`, 4.6 ~3 KB for focus management and the accessibility strings) plus ~51 KB of Geist woff2; catalog data on a first visit ≈ 264 KB (main packs + log + history), descriptions ≈ 170 KB on demand. `fflate` is a lazy chunk, never preloaded. Web build `target` is Safari/iOS 15.4 (Radix class static blocks otherwise break iOS 15); Tauri uses the default. ## Editable vs read-only fields @@ -106,7 +107,7 @@ Draft-first: **never** `gh release create` by hand before CI — tauri-action v1 ## Licenses & policies -Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contribution — excluding creators' descriptions, cover images, names/trademarks (`data_game/LICENSE.md`, `LICENSES/CC-BY-4.0.txt`); docs **CC BY 4.0**; map + non-affiliation in `NOTICE.md`. Policies (EN in `docs/`, VI mirrors in `docs/i18n/vi/`, English controls): ToS (website + data + content removal), EULA (desktop/Android binaries only; also `webapp/src-tauri/installer/EULA.rtf`), Privacy Policy, Disclaimer, `SECURITY.md`, `CODE_OF_CONDUCT.md`. When a policy changes, bump `LEGAL_VERSION` (`webapp/src/stores/prefs.ts`) and the dates in `about.legal.desc` (EN/VI) so the legal gate asks again. Contact addresses `contact@ / legal@ / privacy@ / security@ / takedown@poli0981.dev` are aliases of the maintainer's Google Workspace mailbox (not Cloudflare Email Routing; the Privacy Policy lists Google as the email processor). The maintainer's site https://poli0981.dev/ and channel hub https://poli0981.dev/links/ are linked from the About page (`DEV` in `lib/about.ts`). +Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contribution — excluding creators' descriptions, cover images, names/trademarks (`data_game/LICENSE.md`, `LICENSES/CC-BY-4.0.txt`); docs **CC BY 4.0**; map + non-affiliation in `NOTICE.md`. Policies (EN in `docs/`, VI mirrors in `docs/i18n/vi/`, English controls): ToS (website + data + content removal), EULA (desktop/Android binaries only; also `webapp/src-tauri/installer/EULA.rtf`), Privacy Policy, Disclaimer, `SECURITY.md`, `CODE_OF_CONDUCT.md`. `ACCESSIBILITY.md` (root: GitHub's accessibility community health file; VI mirror `docs/i18n/vi/ACCESSIBILITY.md`) is a statement, not a policy to accept — no `LEGAL_VERSION` bump when it changes, but keep its §3 (what works) and §6 (known limitations) in step with the code; barriers come in through `.github/ISSUE_TEMPLATE/accessibility.yml` (label `accessibility`) or contact@. When a policy changes, bump `LEGAL_VERSION` (`webapp/src/stores/prefs.ts`) and the dates in `about.legal.desc` (EN/VI) so the legal gate asks again. Contact addresses `contact@ / legal@ / privacy@ / security@ / takedown@poli0981.dev` are aliases of the maintainer's Google Workspace mailbox (not Cloudflare Email Routing; the Privacy Policy lists Google as the email processor). The maintainer's site https://poli0981.dev/ and channel hub https://poli0981.dev/links/ are linked from the About page (`DEV` in `lib/about.ts`). ## Known gotchas (cost a release each — don't relearn) @@ -154,6 +155,12 @@ Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contri 42. **miniflare (wrangler's local runtime) pins `undici` exactly, so Dependabot can't fix an undici alert** until a wrangler release moves the pin. The stopgap is `overrides.undici` in `webapp/package.json` (4.4.3–4.5.0 carried `^7.30.1` over wrangler 4.152's 7.29.1; dropped with wrangler 4.156, whose miniflare pins 7.30.1). Only miniflare uses undici; nothing of it reaches the site, the Worker or the apps. Remove such an override once `npm ls undici` without it shows the fixed version, and before miniflare moves to a new undici major (the override would hold it back). 43. **The Workers rate-limit binding counts per machine, not per data centre.** Measured on production right after the 4.5.0 deploy (CDG): 1,000 requests in 53 s, each `curl` on a new connection, against `RL_SITE` 120/60 s → **no 429 at all**; 200 requests on **one** keep-alive connection → 93 × 200, then 429s. A data centre has many machines, each counts locally and syncs late, so a client that keeps one connection (browsers over HTTP/2, scripts with keep-alive) is held to the limit, while one that opens a new connection per request is spread across machines and barely counted. The zone's WAF rule counts across the data centre: it is the limit that holds against floods. Test the Worker limits over one connection (`curl URL URL …` in one invocation, or `--next`), never with `xargs curl`; under `wrangler dev` (miniflare: one process) every request counts. The WAF rule (300 / 10 s, set 2026-10-27) needs > 30 requests a second, which `xargs curl` doesn't reach from a home line: use the runbook's Node `fetch` one-liner (800 requests in 4.9 s → 111 × 200, 201 × Worker 429, 488 × WAF 1015). +44. **Tailwind v4's `outline-hidden` adds a visible 2 px outline in forced-colours mode.** On a focus variant that is the point (inputs keep a system-coloured focus ring in Windows contrast themes); used unconditionally on a container (`
`, the games list, popovers) it drew a permanent frame there. Containers use `outline-none`, fields `focus-visible:outline-hidden`. +45. **Vitest stubs CSS imports — `./index.css?raw` is an empty string in tests.** A test that reads a stylesheet lives in `webapp/scripts/*.test.mjs` and uses `node:fs` (`check-contrast.test.mjs`; `src/` has no Node types). +46. **Radix FocusScope gives focus back to the trigger in a `setTimeout` after unmount.** A link inside a menu or sheet that navigates would have focus pulled back to the menu button, away from the new page's h1: `SheetContent` / `PopoverContent` call `e.preventDefault()` in `onCloseAutoFocus` when the path changed. A modal opened without a Radix trigger (the 18+ dialog) drops focus to `` unless `onCloseAutoFocus` focuses something. Radix 1.3.1 sets no `aria-modal` (it hides the rest with `aria-hidden`). +47. **Name Recharts charts with `aria-labelledby`, not their `title` prop** (`title` also shows a native browser tooltip over the whole chart); `Treemap`'s props type has no `role`. A custom tooltip loses Recharts' live region, and the tooltip box is `visibility: hidden` while inactive, so announcements go through the card (`ChartAnnounce`). +48. **The tool permissions refuse loading third-party code into the preview page** (an axe-core `