docs: an accessibility statement, its issue form and a PR template

ACCESSIBILITY.md sits at the root beside SECURITY.md. GitHub reads it from
.github/, the root or docs/ and shows it as the repository's Accessibility
tab. It covers:
- WCAG 2.2 AA as a target, not a claim.
- What works today and what does not, with a way around each limitation
  where there is one.
- The browsers, apps and assistive technology actually used (keyboard,
  Narrator, NVDA).
- How to report a barrier without saying anything about yourself.
- Replies on SECURITY.md's terms: first within a week, blockers first, no
  fixed deadlines.
- The rules for contributors and coding agents.

.github/ISSUE_TEMPLATE/accessibility.yml files a report under the new
`accessibility` label, with no required final checkbox. The pull request
template is the short checklist, and completes the community profile.
CLAUDE.md says the statement is a claim about the code, and names the two
limitations that look solved but are not.

.gitattributes keeps the new file out of source archives like the other
community files. It also stops leaving out Contact, PRIVACY_POLICY and ToS:
the web build reads every legal document and stops when one is missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-11-09 08:43:33 +07:00
1 parent fc201981de
commit b5b8b4eb12
5 files changed
+359 -3

No files matched your search

+3 -3
View File
@@ -15,11 +15,11 @@
CODE_OF_CONDUCT.md export-ignore
CONTRIBUTING.md export-ignore
SECURITY.md export-ignore
/docs/Contact.md export-ignore
/docs/PRIVACY_POLICY.md export-ignore
ACCESSIBILITY.md export-ignore
CHANGELOG.md export-ignore
README.md export-ignore
/docs/ToS.md export-ignore
# The legal documents stay IN the archive: the web build reads all of them
# (web/build/legal-versions.ts) and stops when one is missing.
*.csv export-ignore
*.log export-ignore
+75
View File
@@ -0,0 +1,75 @@
name: ♿ Accessibility barrier
description: Something on the site or in the apps you can't use, or can only use with trouble - keyboard, screen reader, zoom, contrast, motion
title: "[A11y] "
labels: ["accessibility"]
body:
- type: markdown
attributes:
value: |
Thanks for telling me. You don't have to say anything about yourself or why - just what got in the way.
Screenshots and recordings are welcome, never required. Rather not post in public? Email **contact@poli0981.dev**.
Not an accessibility problem? **Bug report** is the form you want.
How these reports are handled: [ACCESSIBILITY.md](https://github.com/poli0981/free-steam-games-list/blob/main/ACCESSIBILITY.md).
- type: dropdown
id: surface
attributes:
label: Where?
options:
- "Website — https://free-steam-games.win/"
- "Desktop app (Windows / macOS / Linux)"
- "Android app"
- "This repository (README, docs, games/*.md leaderboards)"
- "Somewhere else (say below)"
validations:
required: true
- type: input
id: page
attributes:
label: Page or link
description: The address, or the page's name in the app (Games, Settings, a game's page...).
placeholder: https://free-steam-games.win/games/730
- type: textarea
id: barrier
attributes:
label: What were you trying to do, and what got in the way?
description: Plain words are fine. Steps help if it only happens sometimes.
placeholder: |
I wanted to open a game from the Games list with the keyboard only.
Every row takes two Tab presses, and I lost track of which game I was on.
validations:
required: true
- type: dropdown
id: impact
attributes:
label: How much does it get in the way?
options:
- "I can't do it at all"
- "I can, but it's hard or slow"
- "Annoying, but I can live with it"
- "Not sure"
validations:
required: true
- type: input
id: assistive-tech
attributes:
label: Assistive technology or settings (optional)
description: e.g. NVDA, Narrator, VoiceOver on iOS, TalkBack, keyboard only, 200% zoom, high contrast, reduce motion.
- type: input
id: environment
attributes:
label: Browser or app version, and OS (optional)
description: The app version shows as "Steam · v…" under "F2P Tracker" in the sidebar (in the menu on small screens).
placeholder: Firefox on Windows 11 · v2.5.0
- type: textarea
id: extra
attributes:
label: Anything else? (optional)
description: A workaround you found, or a screenshot or recording if you'd like to add one.
+32
View File
@@ -0,0 +1,32 @@
<!--
Thanks for the PR! One person reviews these by hand, so a short "what and why" goes a long way.
Everything here is public and permanent: keep personal info (email, real name, account IDs) out of it.
Written with an AI assistant? Fine - so was most of this repo. You still checked the boxes yourself.
Delete the sections that don't apply.
-->
## What and why
<!-- A sentence or two. "Closes #123" if it fixes an issue. -->
## Checks
- [ ] Web (`web/`): `npm run typecheck && npm test && npm run build && node scripts/verify-dist.mjs --web`
- [ ] Pipeline (`scripts/`): `python -m pytest scripts/tests`
- [ ] Docs or queued links only - nothing to run
## Accessibility (interface changes)
The longer version is in [ACCESSIBILITY.md](https://github.com/poli0981/free-steam-games-list/blob/main/ACCESSIBILITY.md#for-contributors).
- [ ] Works with the keyboard alone, and focus stays visible
- [ ] Controls and icon buttons have a name a screen reader can read; images have `alt` (`alt=""` when decorative)
- [ ] Nothing new is shown by colour or a hover tooltip alone, and text stays readable in both themes
- [ ] Still usable 360 px wide, at 200% zoom and with reduce motion on
- [ ] No new `svelte-ignore a11y_*`, or the description says why
- [ ] New text is in both `en.json` and `vi.json`
## Queued games (`scripts/temp_info.jsonl`)
- [ ] One store link per line, nothing else
- [ ] Free to play on Steam right now - not a demo, not a paid game
+235
View File
@@ -0,0 +1,235 @@
# Accessibility
This file is about using this project with a keyboard, a screen reader, zoom,
high contrast or reduced motion, or with anything else that is not a mouse and
a default screen. It covers:
- the website, <https://free-steam-games.win/>;
- the desktop and Android apps, which are the same interface running in the
system's web view;
- the data as plain text: [`data/`](data/) (JSONL), the CSV/JSON export on the
Games page, and the Markdown leaderboards in [`games/`](games/).
It does not cover Steam's own pages, Cloudflare's Turnstile widget (the
website's human check) or GitHub itself. Those belong to Valve, Cloudflare and
GitHub.
One person maintains this as a hobby, and nobody has audited it. So this is not
a certificate. It is a list of what is known to work, what is known not to, and
how to say so when something gets in your way.
## The goal
**[WCAG 2.2](https://www.w3.org/TR/WCAG22/) Level AA** is the target. It is a
target, not a claim: the app has not been audited against it, and the
limitations below mean it does not meet it today.
What matters most, in this order:
1. Finding and opening a game (search, filters, the games list, a game's page)
with a keyboard, a screen reader or zoom.
2. Nothing said with colour alone, or only in a mouse-hover tooltip.
3. No traps, including the first-run screens every visitor has to get past.
4. The reader's own settings win: language, reduced motion, light or dark,
zoom.
## What works today
Checked against the code on 2026-11-09 (website and apps 2.5.0).
- **Language.** The page declares its language, and changes it when you
switch between English and Vietnamese.
- **Structure.** "Skip to content" is the first thing the keyboard reaches.
The header and both navigation menus are labelled, and the menus mark the
page you are on. Each page has one main heading and its own title, and
moving to another page announces the new title.
- **Keyboard.** Links and controls show a focus ring (one exception, below).
<kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>K</kbd> opens a command palette that
works like a search box with a list: arrow keys, <kbd>Enter</kbd>,
<kbd>Esc</kbd>. The menu drawer on small screens, the palette and the
desktop update dialog keep focus inside while they are open, close with
<kbd>Esc</kbd>, and put focus back where it was.
- **Names.** Buttons that only show an icon have a text name. Switches (the
language and theme buttons, the scrollbar options, the choices on *Random
games*, the anti-cheat families) say whether they are on.
- **Charts.** Each chart is announced as an image named by its title. Some
also give the numbers as text: *Top online* and *Top offline* list 100 games
under their charts, *Genres* lists the top 24, *Tags* writes out 40 of its
60 words with their counts, and the anti-cheat chart links to a real table
that also says, in words, which anti-cheat runs at kernel level.
- **Images, sound and motion.** Game art is decorative (`alt=""`); the game's
name is always written next to it. Nothing plays sound or video. With your
system's *reduce motion* setting on, page animations and transitions are cut
short and scrolling jumps instead of gliding.
- **Zoom and small screens.** The website never blocks pinch-zoom. Below
tablet width the games table turns into cards, and a test checks that every
grid falls back to one column on a phone.
- **Settings.** Theme (dark by default, light, or follow the system), English
or Vietnamese, and hidden scrollbars. Hidden scrollbars still scroll from
the keyboard.
- **Plain text.** Every game has its own page. The Games page exports what you
have filtered as CSV or JSON. The whole dataset is plain JSONL in
[`data/`](data/), and the two leaderboards are Markdown tables in
[`games/`](games/).
## Known limitations
Known, and not fixed yet. Where there is another way to get the same thing, it
says so.
- **The games table is not a table to a screen reader.** Its rows are links
dressed up as table rows with no table around them, and three of its columns
have no header text. Each row takes two <kbd>Tab</kbd> presses, because the
Steam icon inside it is a second stop. Only the rows on screen exist in the
page, so a screen reader's browse mode and the browser's find-in-page see
only those.
*Instead:* narrow the list with search and the filters, open a game's own
page, or export to CSV/JSON. The [Markdown leaderboards](games/) are
ordinary tables.
- **The first-run screens.** Before the site opens you get the terms screen,
then (website only) a human check. Neither moves keyboard focus into itself
or keeps it there, so <kbd>Tab</kbd> walks through the hidden page behind
first. The terms screen is also not announced as a dialog, and each screen
adds a second main heading while it is open. The human check is Cloudflare
Turnstile, in a frame this project does not control. If it says your
browser is unsupported, there is no retry button.
*Instead:* the desktop and Android apps never show the human check, and
everything in the catalogue is readable on GitHub.
- **Charts.** Values, tooltips and legends are drawn on a canvas and need a
pointer. Several charts have no text version: DRM, languages, platforms,
players, reviews, release years, delisted games, most of *Stats*, and the
genre chart on the dashboard. Several tell categories apart by colour alone.
Chart animations ignore *reduce motion*.
*Instead:* the CSV/JSON export, or the raw data.
- **Colour.**
- Kernel-level anti-cheat is shown only by a red badge instead of an amber
one: in the games table, the cards, a game's page and *Random games*.
*Instead:* the [anti-cheat list](https://free-steam-games.win/charts/anti-cheat/list)
says it in words.
- In the light theme, links, primary buttons, warnings and some badges are
below the 4.5:1 contrast WCAG asks of text.
*Instead:* the dark theme, which is the default.
- The borders of text boxes and drop-downs are below 3:1 in both themes.
- Contrast themes (forced colours) get no special support.
- **Hover-only hints.** The 💀 on a dead game and the warning icon in a table
row explain themselves only in a mouse-hover tooltip. A screen reader just
reads "skull".
*Instead:* **Hide dead** on the Games page takes dead games out of the
list.
- **Changes that are not announced:** the number of results after you filter,
the page number, and loading or error messages. The pop-up notifications'
own labels ("Notifications", "Close toast") stay in English when the app is
in Vietnamese.
- **Text in another language is not marked as such.** The legal documents
exist only in English. Game names and descriptions are in whatever language
the developer wrote them. None of it is tagged, so a screen reader reads it
in the interface language's voice.
- **Zoom.**
- On the website, the games list and the cards sit in boxes sized to the
window, so at 300-400% zoom they shrink to almost nothing. Long values
are cut off with "…", and a few small labels have fixed pixel sizes.
- The desktop app has page zoom turned off: <kbd>Ctrl</kbd>+<kbd>+</kbd>
does nothing. As far as the code shows, the Android app does not
pinch-zoom either.
- *Instead:* game pages and the CSV/JSON export; the website in a browser;
or your system's magnifier or text size.
- **The command palette's search box** shows no focus ring.
- **No automated accessibility tests.** Svelte's accessibility warnings show
up in development but do not fail the build.
## Supported environments
| Where | Runs on | Checked by hand |
| --- | --- | --- |
| Website | Any current browser | Chrome, Edge, Firefox and Brave on Windows 11; Safari, Chrome and Brave on iOS 26 (iPhone 14 Pro, iPhone 13 Pro Max) |
| Desktop app | WebView2 (Windows), WKWebView (macOS), WebKitGTK (Linux) | Windows 11. The macOS and Linux builds are not checked by hand. |
| Android app | Android System WebView, Android 11 or newer | Emulator (Android 11 to 16) and a vivo 1907 (Android 12) |
The apps get their accessibility from the system's web view. What a screen
reader can do in them is roughly what it can do in Edge on Windows, Safari on
macOS, or Chrome on Android. The full device list is in
[`docs/pc_spec.md`](docs/pc_spec.md).
**Assistive technology used so far:** the keyboard alone, and the Narrator and
NVDA screen readers on Windows.
**Not tried yet:** JAWS, VoiceOver (macOS, iOS), TalkBack (Android), Orca
(Linux). Reports from any of them are especially welcome.
## Reporting a barrier
Open an issue with the
**[♿ Accessibility barrier](https://github.com/poli0981/free-steam-games-list/issues/new?template=accessibility.yml)**
form. You don't have to say anything about yourself or any disability: what
you were trying to do, and what got in the way, is enough. Screenshots and
recordings are welcome, but never required.
Rather not post in public, or no GitHub account? Email
**contact@poli0981.dev**.
What helps, if you have it:
- the page: its address, or its name in the app;
- what you tried to do, and what happened instead;
- the browser or app, and its version. The app version is shown as
"Steam · v…" under "F2P Tracker" in the sidebar, or in the menu on a small
screen;
- your operating system, and any assistive technology or setting involved
(screen reader, zoom level, high contrast, reduced motion);
- how much it gets in the way: you can't do it at all, it's hard or slow, or
it's just annoying.
A security problem is not an accessibility report: see
[`SECURITY.md`](SECURITY.md).
## What to expect
One person, as a hobby, in a timezone that is probably not yours. It's the same
deal as [`SECURITY.md`](SECURITY.md).
- A first reply usually within a week.
- Something that stops you using a part of the site or the apps comes first.
Then things that make it hard or slow, then the cosmetic ones.
- No fixed deadline for a fix. If there is a way around the problem, the reply
says so.
- Reports get the `accessibility` label. The issue stays open until the fix is
live: on the website as soon as it is merged, in the desktop and Android
apps with their next release.
- Credit in the [CHANGELOG](CHANGELOG.md) if you want it.
## For contributors
The same rules for people and for coding agents. For any change to the
interface:
- Use it with the keyboard alone. Everything should be reachable with
<kbd>Tab</kbd>, in a sensible order, with focus always visible and nothing
that traps it.
- Give every control a name a screen reader can read: a visible label, or an
`aria-label` on an icon button. Images get `alt`, empty (`alt=""`) when they
only decorate.
- Never say something with colour alone, or only in a hover tooltip.
- Check it 360 px wide, at 200% zoom, in both themes, and with *reduce motion*
on.
- Build overlays and pop-ups on Bits UI's `Dialog` (focus trap,
<kbd>Esc</kbd>, focus returned), not a hand-made `div`.
- Put new text in both `web/src/i18n/locales/en.json` and `vi.json`.
- Read the accessibility warnings `npm run check` prints. CI does not fail on
them, so nobody else will. Add no new `svelte-ignore a11y_*` without giving
a reason in the pull request.
The [pull request template](.github/pull_request_template.md) has the short
version as a checklist. Coding agents also follow [`CLAUDE.md`](CLAUDE.md),
which says to keep this file true.
## Keeping this honest
- **Owner:** the maintainer, [@poli0981](https://github.com/poli0981).
- A change that fixes a limitation above, or adds one, updates this file in the
same pull request.
- This file is read through again whenever an app release changes the
interface.
- Ideas for the statement itself go to
[Discussions › Ideas](https://github.com/poli0981/free-steam-games-list/discussions/categories/ideas),
or an issue.
*Last reviewed: 2026-11-09 (website and apps 2.5.0).*
+14
View File
@@ -1202,6 +1202,20 @@ scraping pipeline (`scripts/`) driven by GitHub Actions.
- **`safe` is classified by `lib/safety.ts`** (`y`, `n`, `?` = not reviewed,
`""` = never set). `/games`, `/stats` and `/health` all use it; `?` is a
to-do, not missing data, so /health reports it as its own group.
- **`ACCESSIBILITY.md` (root) is a claim about this code, like this file.**
Its "What works today" and "Known limitations" lists were checked against
the code on 2026-11-09. A change that fixes a limitation, or adds one,
edits the list and its "Last reviewed" line in the same pull request.
Reports arrive through `.github/ISSUE_TEMPLATE/accessibility.yml` (label
`accessibility`), and the About page links both the form and the statement.
Two of its limitations look solved and are not:
- `GamesTable.svelte`'s comment says the grid "keeps the table SEMANTICS",
but its rows are `<a role="row">` with no `table`/`grid` parent.
- The desktop app cannot zoom: Tauri's `zoomHotkeysEnabled` defaults to
false and `tauri.conf.json` does not set it.
Svelte's a11y warnings never fail CI (`svelte-check` runs without
`--fail-on-warnings`), so read them.
## Admin SPA (`web/admin/`)