Files
poli0981-dev/ACCESSIBILITY.md
poli0981andClaude Opus 5.5 484907439a feat(content): content labels, an age check, blurred images and a warning banner (#138)
* feat(content): content labels, an age check, blurred images and a warning banner

Posts, chapters and albums can carry content labels and an age rating:
- Labels (src/lib/content-labels.ts, names in src/i18n `labels`): horror, blood,
  jumpscare, violence, self-harm, death — banner and blurred images; politics,
  religion, strong-language, flashing-lights, spoilers — banner only. `contentWarning`
  moves from stories to every long-form entry and albums, and single gallery photos can
  carry their own (R2 list or captions.json). Unknown labels fail the build.
- Banner (ContentNotice.astro, replaces ContentWarning.astro): names every label in the
  page's language, skipped by search. Images in a labelled region are blurred in plain
  CSS by default — nothing sharp flashes before a script — and a real "Hiện ảnh"
  checkbox un-blurs them through :has(), so it works with the keyboard and with
  JavaScript off. A region without pictures shows no such line.
- Age check (AgeGate.astro, src/lib/age-gate.ts) for `ageRating` 13+/16+/18+: the text
  sits in a closed <details> (search indexes the title, not the text); its summary asks
  in a native modal <dialog> — focus starts on "No", Esc cancels and never means yes,
  "No" explains and offers to choose again — and the answer is kept in localStorage
  only (age thresholds, never an age or birth date). It never pops up on its own, and
  without JavaScript the summary simply opens the text.
- Everywhere else: story/post/album cards name the labels (blurred covers), the lightbox
  shows labelled photos blurred behind "Hiện ảnh", RSS descriptions start with the
  warning in the item's language, OG cards carry it for blog posts too, JSON-LD
  contentRating. The post page now uses the cover's alt text when there is one.
- Admin: a `multiselect` field for labels (with Vietnamese names), an age-rating select,
  and per-photo labels in the gallery manager.
- Content (poli0981/content 98f7692): privacy policy §6 lists the age-check answer;
  "Đêm không tiếng" chapters 1–2 are rated 16+.
- Tests: label and age-check logic, admin validation, labels kept on album save, RSS
  prefix; the accessibility suite scans the gate folded and asked, checks focus, Esc,
  No/Yes/reset and the keyboard reveal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(a11y): appendChild for the blur probe (astro check's DOM typing)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(content): findings from an independent review of the labels branch

- Album pages: the lightbox now sits outside the labelled section, whose blur rule also
  blurred the viewer's photo — its "show" button removed the veil but not the blur.
- Age check: the browser opens a <details> by itself (find-in-page, a #:~:text= link
  from a search engine, an #id inside the text); without a "yes" on record the gate now
  folds it straight back. After "Chọn lại" → "Có", focus moves to the summary instead of
  being lost with the row that just hid.
- Search indexes nothing inside the gate, not even its status lines, which could have
  become the excerpt of a page the reader has not been let into.
- Albums take their labels and age rating from BOTH language entries (same photos, two
  pages; the stricter rating wins), on the album page and on its card.
- An age-rated post folds its cover away with the text (PostCover.astro), and post and
  album cards blur the cover of age-rated items too. The album card names the cover
  photo's own labels, not only the album's.
- Tests: the gate re-folds an unasked open and keeps focus after choosing again;
  albumWarning merges both languages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 08:30:09 +07:00

9.5 KiB

Accessibility

How accessibility is handled on poli0981.dev: what the site aims for, what is in place, how it is tested, what is known not to work, and how to report a barrier.

The statement written for visitors, in English and Vietnamese, is on the site at /legal/accessibility (and /en/legal/accessibility). This file is the repository's copy, with the notes for people who work on the code — if the two ever disagree about what a visitor can expect, the site wins.

Tiếng Việt: tuyên bố trợ năng dành cho khách truy cập nằm ở /legal/accessibility. Gặp rào cản? Gửi email tới accessibility@poli0981.dev hoặc dùng nút "Báo lỗi" ở cuối mọi trang.

Reporting a barrier

Email accessibility@poli0981.dev, or use Report a bug at the bottom of every page — it needs no account and lands in a private tracker. If you use GitHub, you can open an issue with the Accessibility template.

It helps to say which page, what you were trying to do, what happened instead, and which browser and assistive technology you use. You do not have to diagnose anything, and you never need to tell me about a disability.

Expect a reply within 7 days. Reports are handled in this order:

  • Critical — blocks a core task (reading a page, moving around the site, reporting a problem)
  • Serious — major difficulty, but there is another way to do it
  • Moderate — annoying or inconsistent
  • Minor — little impact

This is a personal site maintained by one person, in their spare time, so there is no fixed date for every fix. You will be told what is planned, and a workaround if there is one.

Target

WCAG 2.2 Level AA, used as the guide for design and review. The site has not been audited by a third party, and this is not a claim of conformance.

What is in place

  • Keyboard. Every page works with the keyboard alone. There is a skip link (src/components/SkipLink.astro) and one focus ring for everything (src/styles/global.css). The menu sheet, the search and the photo viewer trap focus while open, close with Esc and hand focus back to what opened them; the report form is a native <dialog>. / opens the search. The page's scroll padding keeps whatever takes focus clear of the sticky header, the mobile tab bar and the legal notice.
  • Screen readers. Each page declares its language, and text in the other language carries its own: the language switch, and each half of a legal page, which holds both languages (src/lib/legal-lang.ts). There is one <h1> per page and heading levels do not skip. Every <nav> has its own name, taken from src/i18n. Icon-only controls are named, and a name starts with the text that is visible (WCAG 2.5.3). The search is an ARIA combobox. Live regions announce search results, the photo viewer's position and caption, and the report form's status.
  • Colour and contrast. In both palettes, text is at least 4.5:1 on every surface it sits on, and the line colour used where a boundary has to be seen is at least 3:1; tests/palette.test.ts fails the build if one drops below. Decorative hairlines are fainter. The current page and a chosen option are never shown by colour alone. Windows High Contrast (forced-colors) and prefers-contrast: more are handled.
  • Motion. One global rule collapses every animation under prefers-reduced-motion, and scripted motion follows it (src/lib/motion.ts). Nothing loops or plays by itself; a YouTube video loads only after its play button is pressed.
  • Zoom and reflow. Type is fluid and in rem, zooming is never locked, and pages reflow down to a 320 px viewport.
  • Touch. The tab bar's targets are 56 px tall, the header's controls 40 px and the footer's icons 44 px. Text links in the footer and the sidebars are about 24 px tall or less and meet WCAG 2.5.8 through the space around them.
  • Reading. Stories have their own settings: three text sizes and a paper, sepia or dark background.
  • Content warnings. A labelled post, chapter or album opens with a banner that names its labels (horror, violence, politics…) in words, not by colour or icon alone. For the visual labels, images in the page are blurred until "Show images" is ticked. That control is a real checkbox, and the blur is plain CSS, so it works from the keyboard and without JavaScript. Blurring is a courtesy layer, not access control: the images are still downloaded.
  • Age check. An age-rated text is folded inside a <details> element. With JavaScript, its summary asks for the reader's age in a native modal <dialog>: focus starts on "No", Esc cancels and never counts as "yes", and focus returns to the summary. If the reader says no, focus moves to a line that explains why and offers to choose again. Nothing pops up on its own. Without JavaScript the summary opens the text. The answer stays in the browser (localStorage); see the privacy policy.

Tested with

How What
Keyboard only Chrome, Edge and Brave on Windows 11
Windows Narrator Edge, Chrome and Brave on Windows 11
VoiceOver Safari on iPhone
Automated axe-core in Chrome, on every pull request (see "For contributors")

Not yet tested by the maintainer: NVDA, JAWS, TalkBack, VoiceOver on macOS, and voice control. They are expected to work; a report saying otherwise is welcome.

The site supports the current versions of Chrome, Edge, Firefox and Safari, on desktop and mobile.

Known limitations

  • Bot check. A first visit passes through a Cloudflare Turnstile check. It usually needs no action, but it is a third-party component this repository cannot change. Anyone it stops can write to the address above.
  • Videos. Videos are YouTube embeds. Captions are whatever YouTube provides for each video; there are no transcripts.
  • Older images. Gallery photos must have a caption in both languages (the build fails otherwise). A few images inside older posts may still lack a text alternative.
  • Offline mini-game. The game on the offline page is drawn on a canvas. It can be played with the Space key, but a screen reader cannot follow it. It is an extra, not content.
  • Search needs JavaScript. Without it, every page is still reachable from the menu and the footer links.
  • The admin (admin.poli0981.dev) is a single-owner tool and is not covered by this document.
  • Automated checks run in Chrome only, and no tool can judge everything: a passing run is necessary, not sufficient. The live widgets (latest video, now playing) have no data in the test build, so their markup is checked by hand.

For contributors

A change to the interface is expected to keep all of this true:

  • It works with the keyboard alone, start to finish; focus is visible and never lands under a fixed bar.
  • Anything that opens closes with Esc and hands focus back to what opened it.
  • Icon-only controls have a name that starts with their visible text, taken from src/i18n.
  • State and "you are here" are not shown by colour alone. A new colour goes into src/lib/palette.ts and src/styles/global.css together, where the palette test checks it.
  • Headings do not skip a level; images have an alt, empty only when they are decorative.
  • New animation has a still branch under prefers-reduced-motion.
  • It has been looked at 320 px wide, at 200% zoom, in dark and light, in Vietnamese and English, and listened to once with a screen reader.

What the pipeline checks:

  • npm run test:a11y runs in the required build check, so a pull request with a violation cannot be merged. It scans every page listed in the build's sitemap with axe-core (WCAG 2.2 A and AA rules plus axe's best practices), a page of each template again in the light theme and at phone width, and the menu, search, photo viewer, report dialog, reading settings and legal notice while they are open. It then walks the keyboard contract — the skip link, focus traps, Esc and focus return, focus not hidden under a bar in either direction — checks that no page scrolls sideways at 320 px (and a sample at 360 and 390 px), and checks the forced-colours rules. The tests are in tests/a11y/.
  • tests/palette.test.ts checks the text and line colours of both palettes against AA.
  • Lighthouse reports an accessibility score on pull requests; it is advisory.

To run the suite locally, build and serve the site, then run it from a second terminal:

npm run build
npm run preview
npm run test:a11y

It drives the Chrome that is already installed; set A11Y_CHANNEL=msedge to use Edge instead. If a rule cannot be met, say why in the pull request rather than switching the rule off.

Ownership and review

Maintained by Kokone (poli0981), the site's only maintainer, who triages reports and keeps this file and the site's statement in step. Both are reviewed with every release that changes the interface and at least once a year (17_MAINTENANCE.md).

Last reviewed: 2026-11-10 (v2.2.0).