* 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>
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 fromsrc/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.tsfails 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) andprefers-contrast: moreare 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.tsandsrc/styles/global.csstogether, 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:a11yruns in the requiredbuildcheck, 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 intests/a11y/.tests/palette.test.tschecks 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).