diff --git a/.github/workflows/ui-quality.yml b/.github/workflows/ui-quality.yml new file mode 100644 index 0000000..bf1ddad --- /dev/null +++ b/.github/workflows/ui-quality.yml @@ -0,0 +1,33 @@ +name: Web UI quality +on: [push, pull_request] +jobs: + ui: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v5 + with: + go-version: '1.25.x' + cache-dependency-path: api/go.sum + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: npm + cache-dependency-path: web/package-lock.json + - run: npm ci + working-directory: web + - run: npx playwright install --with-deps chromium + working-directory: web + - run: npm run typecheck + working-directory: web + - run: npm run test:ui + working-directory: web + - uses: actions/upload-artifact@v4 + if: always() + with: + name: ui-accessibility-and-reflow + path: | + web/.test-artifacts/after/ + web/.test-artifacts/results.json + web/test-results/ diff --git a/.gitignore b/.gitignore index a36d9fe..3ab9d21 100644 --- a/.gitignore +++ b/.gitignore @@ -9,10 +9,14 @@ api/coverage.out # Web web/node_modules web/.next +web/.next-test/ web/out web/.env.local web/.turbo web/tsconfig.tsbuildinfo +web/.test-artifacts/ +web/test-results/ +web/playwright-report/ # Android android/.gradle diff --git a/README.md b/README.md index 08dea88..cb194f8 100644 --- a/README.md +++ b/README.md @@ -124,3 +124,14 @@ Seed users (created only when the user table is empty): `GET /health` for probes. Full shape and scale discussion: [SYSTEM_DESIGN.md](./SYSTEM_DESIGN.md). Env: `PORT` (8080), `JWT_SECRET`, `DATABASE_URL` (`sqlite:inkwell.db` or `postgres://...`). + +## Web UI quality + +The web client has explicit form labels, keyboard bypass/focus styling, announced +feedback, and long-content reflow fixes. [Measured UI checks](docs/ui-quality.md) +record the before/after accessibility scans and 38 passing Playwright tests across +four viewport widths, including real Go API/SQLite workflows. Automated checks +are partial coverage, not a WCAG certification. + +For a real participant study, use the [moderator protocol](docs/usability-study.md) +and blank observation sheet. No participant study has been completed yet. diff --git a/docs/ui-quality-results.json b/docs/ui-quality-results.json new file mode 100644 index 0000000..a759d33 --- /dev/null +++ b/docs/ui-quality-results.json @@ -0,0 +1,2899 @@ +{ + "generatedAt": "2026-11-04T13:22:21.852Z", + "baselineCommit": "2b708be8691a885010b595430be7fa78d5ccc313", + "implementationWasUncommittedDuringRun": true, + "platform": "win32", + "versions": { + "next": "14.2.35", + "@playwright/test": "1.64.1", + "@axe-core/playwright": "4.14.0", + "axe-core": "4.14.0" + }, + "wcagTags": [ + "wcag2a", + "wcag2aa", + "wcag21a", + "wcag21aa" + ], + "before": { + "scans": 32, + "ruleViewportViolations": 32, + "affectedElementViewportInstances": 76, + "incompleteRuleViewportInstances": 36, + "pagesWithOverflow": [], + "browser": "156.0.8078.4", + "checks": [ + { + "route": "browse", + "width": 320, + "testedAt": "2026-11-04T13:14:05.743Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [ + { + "rule": "color-contrast", + "impact": "serious", + "targets": [ + [ + "aside > p" + ], + [ + "strong:nth-child(1)" + ], + [ + "strong:nth-child(2)" + ], + [ + "strong:nth-child(3)" + ], + [ + "code" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "browse", + "width": 390, + "testedAt": "2026-11-04T13:14:18.738Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [ + { + "rule": "color-contrast", + "impact": "serious", + "targets": [ + [ + "aside > p" + ], + [ + "strong:nth-child(1)" + ], + [ + "strong:nth-child(2)" + ], + [ + "strong:nth-child(3)" + ], + [ + "code" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "browse", + "width": 768, + "testedAt": "2026-11-04T13:14:28.283Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [ + { + "rule": "color-contrast", + "impact": "serious", + "targets": [ + [ + "aside > p" + ], + [ + "strong:nth-child(1)" + ], + [ + "strong:nth-child(2)" + ], + [ + "strong:nth-child(3)" + ], + [ + "code" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "browse", + "width": 1280, + "testedAt": "2026-11-04T13:14:39.157Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [ + { + "rule": "color-contrast", + "impact": "serious", + "targets": [ + [ + "aside > p" + ], + [ + "strong:nth-child(1)" + ], + [ + "strong:nth-child(2)" + ], + [ + "strong:nth-child(3)" + ], + [ + "code" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 320, + "testedAt": "2026-11-04T13:14:14.345Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 390, + "testedAt": "2026-11-04T13:14:24.357Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 768, + "testedAt": "2026-11-04T13:14:34.907Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 1280, + "testedAt": "2026-11-04T13:14:46.039Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 320, + "testedAt": "2026-11-04T13:14:16.099Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[value=\"Letters at Dusk\"]" + ], + [ + "input[value=\"Contemporary\"]" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "label:nth-child(1)" + ], + [ + "label:nth-child(3)" + ], + [ + "label:nth-child(5)" + ], + [ + "label:nth-child(7)" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 390, + "testedAt": "2026-11-04T13:14:25.566Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[value=\"Letters at Dusk\"]" + ], + [ + "input[value=\"Contemporary\"]" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "label:nth-child(1)" + ], + [ + "label:nth-child(3)" + ], + [ + "label:nth-child(5)" + ], + [ + "label:nth-child(7)" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 768, + "testedAt": "2026-11-04T13:14:36.483Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[value=\"Letters at Dusk\"]" + ], + [ + "input[value=\"Contemporary\"]" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "label:nth-child(1)" + ], + [ + "label:nth-child(3)" + ], + [ + "label:nth-child(5)" + ], + [ + "label:nth-child(7)" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 1280, + "testedAt": "2026-11-04T13:14:47.299Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[value=\"Letters at Dusk\"]" + ], + [ + "input[value=\"Contemporary\"]" + ], + [ + "textarea" + ] + ] + }, + { + "rule": "select-name", + "impact": "critical", + "targets": [ + [ + "select" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "label:nth-child(1)" + ], + [ + "label:nth-child(3)" + ], + [ + "label:nth-child(5)" + ], + [ + "label:nth-child(7)" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 320, + "testedAt": "2026-11-04T13:14:07.337Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[autocomplete=\"username\"]" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 390, + "testedAt": "2026-11-04T13:14:19.807Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[autocomplete=\"username\"]" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 768, + "testedAt": "2026-11-04T13:14:29.615Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[autocomplete=\"username\"]" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 1280, + "testedAt": "2026-11-04T13:14:41.059Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[autocomplete=\"username\"]" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 320, + "testedAt": "2026-11-04T13:14:17.504Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 390, + "testedAt": "2026-11-04T13:14:26.818Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 768, + "testedAt": "2026-11-04T13:14:37.815Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 1280, + "testedAt": "2026-11-04T13:14:48.474Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input" + ], + [ + "textarea" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 320, + "testedAt": "2026-11-04T13:14:12.963Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 390, + "testedAt": "2026-11-04T13:14:23.283Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 768, + "testedAt": "2026-11-04T13:14:33.757Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 1280, + "testedAt": "2026-11-04T13:14:44.786Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 320, + "testedAt": "2026-11-04T13:14:09.078Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[type=\"email\"]" + ], + [ + "input:nth-child(8)" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 390, + "testedAt": "2026-11-04T13:14:20.983Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[type=\"email\"]" + ], + [ + "input:nth-child(8)" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 768, + "testedAt": "2026-11-04T13:14:30.816Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[type=\"email\"]" + ], + [ + "input:nth-child(8)" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 1280, + "testedAt": "2026-11-04T13:14:42.248Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [ + { + "rule": "label", + "impact": "critical", + "targets": [ + [ + "input[type=\"email\"]" + ], + [ + "input:nth-child(8)" + ], + [ + "input[type=\"password\"]" + ] + ] + } + ], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "story", + "width": 320, + "testedAt": "2026-11-04T13:14:11.141Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + }, + { + "route": "story", + "width": 390, + "testedAt": "2026-11-04T13:14:22.146Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + }, + { + "route": "story", + "width": 768, + "testedAt": "2026-11-04T13:14:32.203Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + }, + { + "route": "story", + "width": 1280, + "testedAt": "2026-11-04T13:14:43.474Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + } + ], + "longContent": [ + { + "viewport": 320, + "content": 2957 + }, + { + "viewport": 320, + "content": 10371 + } + ] + }, + "after": { + "scans": 32, + "ruleViewportViolations": 0, + "affectedElementViewportInstances": 0, + "incompleteRuleViewportInstances": 36, + "pagesWithOverflow": [], + "browser": "156.0.8078.4", + "checks": [ + { + "route": "browse", + "width": 320, + "testedAt": "2026-11-04T13:20:32.585Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "browse", + "width": 390, + "testedAt": "2026-11-04T13:20:44.571Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "browse", + "width": 768, + "testedAt": "2026-11-04T13:20:53.349Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "browse", + "width": 1280, + "testedAt": "2026-11-04T13:21:02.040Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".lede" + ], + [ + ".chip[type=\"button\"]:nth-child(2)" + ], + [ + ".chip[type=\"button\"]:nth-child(3)" + ], + [ + ".chip[type=\"button\"]:nth-child(4)" + ], + [ + ".muted" + ], + [ + ".story-card:nth-child(1) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(2) > .cover > .genre-pill" + ], + [ + ".story-card:nth-child(3) > .cover > .genre-pill" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 320, + "testedAt": "2026-11-04T13:20:40.263Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 390, + "testedAt": "2026-11-04T13:20:49.988Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 768, + "testedAt": "2026-11-04T13:20:58.709Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "desk", + "width": 1280, + "testedAt": "2026-11-04T13:21:08.335Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 320, + "testedAt": "2026-11-04T13:20:42.051Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "h1" + ], + [ + "label[for=\"story-title\"]" + ], + [ + "label[for=\"story-genre\"]" + ], + [ + "label[for=\"story-synopsis\"]" + ], + [ + "label[for=\"story-status\"]" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p:nth-child(1)" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 390, + "testedAt": "2026-11-04T13:20:51.144Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "h1" + ], + [ + "label[for=\"story-title\"]" + ], + [ + "label[for=\"story-genre\"]" + ], + [ + "label[for=\"story-synopsis\"]" + ], + [ + "label[for=\"story-status\"]" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p:nth-child(1)" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 768, + "testedAt": "2026-11-04T13:20:59.838Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "h1" + ], + [ + "label[for=\"story-title\"]" + ], + [ + "label[for=\"story-genre\"]" + ], + [ + "label[for=\"story-synopsis\"]" + ], + [ + "label[for=\"story-status\"]" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p:nth-child(1)" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "editor", + "width": 1280, + "testedAt": "2026-11-04T13:21:09.913Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + "h1" + ], + [ + "label[for=\"story-title\"]" + ], + [ + "label[for=\"story-genre\"]" + ], + [ + "label[for=\"story-synopsis\"]" + ], + [ + "label[for=\"story-status\"]" + ], + [ + ".ghost" + ], + [ + "aside > button[type=\"button\"]:nth-child(2)" + ], + [ + "button[type=\"button\"]:nth-child(3)" + ], + [ + "p:nth-child(1)" + ], + [ + "footer > .wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 320, + "testedAt": "2026-11-04T13:20:34.013Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 390, + "testedAt": "2026-11-04T13:20:45.611Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 768, + "testedAt": "2026-11-04T13:20:54.404Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "login", + "width": 1280, + "testedAt": "2026-11-04T13:21:03.226Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 320, + "testedAt": "2026-11-04T13:20:43.409Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 390, + "testedAt": "2026-11-04T13:20:52.249Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 768, + "testedAt": "2026-11-04T13:21:00.916Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "profile", + "width": 1280, + "testedAt": "2026-11-04T13:21:11.376Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 320, + "testedAt": "2026-11-04T13:20:38.828Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 390, + "testedAt": "2026-11-04T13:20:48.856Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 768, + "testedAt": "2026-11-04T13:20:57.610Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "reader", + "width": 1280, + "testedAt": "2026-11-04T13:21:06.891Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + "p" + ], + [ + "p > a" + ], + [ + "h1" + ], + [ + ".prose" + ], + [ + ".muted" + ], + [ + ".pager > a" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 320, + "testedAt": "2026-11-04T13:20:35.341Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 390, + "testedAt": "2026-11-04T13:20:46.661Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 768, + "testedAt": "2026-11-04T13:20:55.479Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "register", + "width": 1280, + "testedAt": "2026-11-04T13:21:04.372Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + "span" + ], + [ + ".wrap" + ] + ] + } + ] + }, + { + "route": "story", + "width": 320, + "testedAt": "2026-11-04T13:20:37.092Z", + "overflow": { + "viewport": 320, + "content": 320 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + }, + { + "route": "story", + "width": 390, + "testedAt": "2026-11-04T13:20:47.772Z", + "overflow": { + "viewport": 390, + "content": 390 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + }, + { + "route": "story", + "width": 768, + "testedAt": "2026-11-04T13:20:56.542Z", + "overflow": { + "viewport": 768, + "content": 768 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + }, + { + "route": "story", + "width": 1280, + "testedAt": "2026-11-04T13:21:05.539Z", + "overflow": { + "viewport": 1280, + "content": 1280 + }, + "violations": [], + "manualReview": [ + { + "rule": "color-contrast", + "targets": [ + [ + ".nib" + ], + [ + ".kicker" + ], + [ + "h1" + ], + [ + ".byline" + ], + [ + "a[href$=\"iris\"]" + ], + [ + ".lede" + ], + [ + ".actions > a[href$=\"login\"]" + ], + [ + "h2" + ], + [ + "li:nth-child(1) > a > span:nth-child(1)" + ], + [ + "li:nth-child(1) > a > .muted" + ], + [ + "li:nth-child(2) > a > span:nth-child(1)" + ], + [ + "li:nth-child(2) > a > .muted" + ], + [ + "footer > .wrap" + ] + ] + }, + { + "rule": "link-in-text-block", + "targets": [ + [ + "a[href$=\"iris\"]" + ] + ] + } + ] + } + ], + "longContent": [ + { + "viewport": 320, + "content": 320 + }, + { + "viewport": 320, + "content": 320 + } + ] + }, + "tests": { + "startTime": "2026-11-04T13:20:23.235Z", + "duration": 56945.736, + "expected": 38, + "skipped": 0, + "unexpected": 0, + "flaky": 0 + }, + "limits": "Chromium on Windows; local Go API and SQLite. Repeated viewport instances are not unique defects. Incomplete axe rules need manual review. No real participant study, screen-reader test, native mobile-device test, or complete WCAG conformance is claimed." +} diff --git a/docs/ui-quality.md b/docs/ui-quality.md new file mode 100644 index 0000000..b2117f0 --- /dev/null +++ b/docs/ui-quality.md @@ -0,0 +1,45 @@ +# Web accessibility and responsive quality pass + +Measured locally on 2026-11-04. This is developer-led accessibility engineering and browser verification, **not user research or a WCAG certification**. + +## Changes grounded in baseline findings + +- Linked visible labels to login, registration, story, chapter and profile controls. Added registration requirements/autocomplete and explicit search semantics. +- Darkened muted text after axe measured 3.78:1 contrast in the demo panel. Added visible focus styling, a keyboard skip link, named navigation and current-page/filter states. +- Added announced errors, loading and save feedback, and guarded editor/profile actions against silent promise failures. +- Kept the existing reading-room design and basic breakpoints. Fixed long unbroken titles, names and chapter text that expanded a 320px viewport to 2,957px (story) and 10,371px (reader). Both cases now fit at 320px. Added narrow-screen navigation wrapping and reduced-motion behavior. +- Search preserves the latest result when requests complete out of order, and distinguishes a valid empty search from a load failure. + +## Actual local checks + +Playwright + axe tested browse, login, registration, story, reader, author desk, editor and profile at **320, 390, 768 and 1280 CSS pixels**. Authenticated pages use the real seeded Go API, not mocked responses. The test database is isolated under `web/.test-artifacts/`; normal API data and the normal Next build directory are not reused. + +| Check | Before | After | +| --- | ---: | ---: | +| Targeted axe rule/viewport violations across 32 combinations | 32 | 0 | +| Affected element/viewport instances | 76 | 0 | +| Ordinary page/viewport combinations with horizontal overflow | 0 | 0 | +| Long-content story width at 320px | 2,957px | 320px | +| Long-content reader width at 320px | 10,371px | 320px | + +The 32 violation instances are repeated rule/viewport observations, not 32 unique accessibility defects. There are still **36 incomplete rule/viewport observations** requiring manual review, including gradient-background contrast cases. Automated zero violations does not settle those checks. + +The final **38 tests passed with zero skips**: 32 screen/viewport cases plus keyboard bypass/focus, long-content reflow, search/filter/no-results, login-error recovery and keyboard submission, chapter creation/save/reload, and registration/profile persistence. A further axe scan runs with the chapter editor open. These verify browser → Go API → SQLite → API → rendered state. Source maps and synthetic credentials in local traces are test-only; raw traces/databases are ignored. + +TypeScript checking passed. See [machine-readable measurements](ui-quality-results.json); raw local scans and screenshots are under `web/.test-artifacts/before` and `after`. Selected actual screenshots: [mobile before](ui-quality/browse-before-320.png), [mobile after](ui-quality/browse-after-320.png), [desktop editor](ui-quality/editor-after-1280.png). + +## Reproduce + +```sh +cd web +npm ci +npx playwright install chromium +npm run typecheck +npm run test:ui +``` + +Go must be installed. Tests reserve ports 13000 and 18080 and refuse to reuse an existing server. They launch the Go API and Next test server and stop them after the suite. The checked-in GitHub Actions workflow installs Chromium/Linux dependencies and uploads the resulting scans and test report. A diagnostic baseline uses `AUDIT_BASELINE=1`; its collection assertions are intentionally disabled and must not be cited as passing accessibility checks. `node scripts/summarize-audit.mjs` requires both saved baseline files and a complete final 38-test result. + +## Human work still pending + +Use [the moderated study protocol](usability-study.md) and [blank observation sheet](usability-observations.csv). No participant results have been invented. Real screen-reader testing, manual review of incomplete axe findings, actual browser zoom, inclusive usability testing and browser/device coverage remain future work. The tests do not certify Section 508/WCAG compliance. diff --git a/docs/ui-quality/browse-after-320.png b/docs/ui-quality/browse-after-320.png new file mode 100644 index 0000000..00b6a76 Binary files /dev/null and b/docs/ui-quality/browse-after-320.png differ diff --git a/docs/ui-quality/browse-before-320.png b/docs/ui-quality/browse-before-320.png new file mode 100644 index 0000000..016d754 Binary files /dev/null and b/docs/ui-quality/browse-before-320.png differ diff --git a/docs/ui-quality/editor-after-1280.png b/docs/ui-quality/editor-after-1280.png new file mode 100644 index 0000000..f8ca13c Binary files /dev/null and b/docs/ui-quality/editor-after-1280.png differ diff --git a/docs/usability-observations.csv b/docs/usability-observations.csv new file mode 100644 index 0000000..4d7eea7 --- /dev/null +++ b/docs/usability-observations.csv @@ -0,0 +1 @@ +participant_code,device,viewport,task_id,outcome,elapsed_seconds,hints,observed_errors,anonymized_quote,ease_1_to_7,interpretation,proposed_change,retest_observation diff --git a/docs/usability-study.md b/docs/usability-study.md new file mode 100644 index 0000000..083be20 --- /dev/null +++ b/docs/usability-study.md @@ -0,0 +1,39 @@ +# Moderated usability study: reading and authoring + +Status: **protocol prepared; no participants tested yet**. Automated browser checks and developer inspection are not user research. + +## Questions + +Can a first-time reader find a story, start reading and save it? Can a first-time author create a story and recover saved chapter work? Which labels, navigation or feedback cause hesitation? Does either workflow become harder on a narrow screen or with keyboard navigation? + +Recruit 3–5 consenting people who have not used Inkwell, including readers and at least one person interested in writing. This is a small formative study, not representative market research. Offer participants their normal device and input method; never describe a developer simulating disability as a disabled participant. + +## Setup and consent + +Use the local seeded demo with synthetic content and disposable accounts, not a production service. Explain the purpose, approximate 20-minute duration, voluntary participation, ability to stop and that the product—not the person—is being evaluated. Ask permission before recording; anonymous notes alone are sufficient. Use participant codes such as P01, not names or emails, in the results. Ask what they expect a reading platform to let them do before showing the app. + +## Neutral tasks + +1. Find a mystery story that interests you and open its first chapter. +2. Continue to another chapter, then return to the story's chapter list. +3. Use the supplied demo account to keep a story so you can find it later. Then find your saved stories. +4. Create a new story with a title and short description; add a chapter and save a few sentences. +5. Leave the editor and reopen your work. Show how you know the last change was saved. + +Give the task goal, not the names of controls or a click sequence. Ask the participant to think aloud. Do not steer them toward a solution. If they ask for help, first ask what they expected; if you provide a hint, record it. Stop a task after three minutes or when the participant chooses to stop. Never record a timed-out task as an unaided success. + +## Record + +Use `usability-observations.csv`. For each task record device/viewport, completion (unaided / assisted / failed / stopped), elapsed seconds, number of hints, observed errors, an anonymized quote, and the participant's 1–7 ease rating. Note actual behavior separately from the facilitator's interpretation. Do not fill rows with invented participants or synthetic success rates. + +## Synthesis and retest + +Group observations into navigation, vocabulary, visual hierarchy, form feedback and recovery. Prioritize blockers, repeated confusion and accessibility barriers before preferences. For each change record the source observation codes, proposed explanation, implementation, and a retest. Compare only matching tasks and conditions. With this sample, describe counts and observations rather than population-wide improvement percentages. + +## Interview/accountability outline + +After personally completing the study, prepare a short story with: the user problem; your specific contribution; evidence that changed your design; the implementation tradeoff; how you tested it; what remains uncertain. Do not claim participants, feedback, presentations or collaboration that did not occur. For a presentation, use five slides: problem, baseline findings, changes, measured checks, next user test. Existing internship experience can supply separate collaboration examples, described in your own words. + +## Remaining accessibility checks + +Automated axe checks are partial coverage. Manually verify keyboard focus remains visible through every flow, error/status announcements with a real screen reader (NVDA/VoiceOver), text resizing, high-contrast settings and real 400% browser zoom. A 320 CSS-pixel viewport is a reflow check, not a complete accessibility certification. Include users with relevant access needs when possible and with consent. diff --git a/web/app/globals.css b/web/app/globals.css index 1b08454..c8cd928 100644 --- a/web/app/globals.css +++ b/web/app/globals.css @@ -3,7 +3,7 @@ --paper-2: #ebe4d6; --ink: #1b1712; --ink-soft: #4e463b; - --muted: #7a7166; + --muted: #645b50; --rule: #d9d0c1; --accent: #2c5c4f; --accent-2: #8c3a32; @@ -15,6 +15,7 @@ * { box-sizing: border-box; } html, body { margin: 0; padding: 0; } +html { scroll-padding-top: 12rem; } body { background: radial-gradient(1200px 500px at 10% -10%, #fff8ea 0%, transparent 50%), @@ -23,10 +24,17 @@ body { font-family: var(--sans); line-height: 1.5; min-height: 100vh; + overflow-wrap: anywhere; } a { color: inherit; text-decoration: none; } button, input, textarea, select { font: inherit; color: inherit; } +input, textarea, select { min-width: 0; max-width: 100%; } +:focus-visible { outline: 3px solid var(--accent); outline-offset: 3px; } +#main-content:focus { outline: 3px solid var(--accent); outline-offset: -3px; } +.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; } +.skip-link { position: fixed; top: 0.5rem; left: 0.5rem; transform: translateY(-200%); padding: 0.75rem 1rem; background: var(--ink); color: white; z-index: 100; } +.skip-link:focus { transform: none; } .site-header { position: sticky; @@ -58,7 +66,9 @@ button, input, textarea, select { font: inherit; color: inherit; } gap: 0.4rem; } .nib { color: var(--accent); font-size: 1.1rem; } -nav { display: flex; align-items: center; gap: 1rem; flex-wrap: wrap; } +nav { display: flex; align-items: center; gap: 1rem; flex-wrap: wrap; min-width: 0; } +nav a, nav button { min-width: 0; max-width: 100%; } +.hero > *, .story-hero > *, .editor-grid > * { min-width: 0; } nav a, .linkish { color: var(--ink-soft); background: none; @@ -129,7 +139,7 @@ nav a.active, nav a:hover, .linkish:hover { color: var(--ink); } .grid { display: grid; - grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); + grid-template-columns: repeat(auto-fill, minmax(min(250px, 100%), 1fr)); gap: 1.1rem; padding-bottom: 3rem; } @@ -266,6 +276,19 @@ textarea { min-height: 280px; resize: vertical; width: 100%; } cursor: pointer; } +@media (max-width: 600px) { + .site-header .row { align-items: flex-start; flex-direction: column; padding-top: 0.7rem; padding-bottom: 0.7rem; gap: 0.4rem; } + .site-header nav { width: 100%; } + .site-header nav a, .site-header nav button { min-height: 44px; display: inline-flex; align-items: center; } + .auth-card, .panel { margin: 1.5rem 0.75rem; padding: 1rem; } + .search { min-width: 0; flex-basis: 100%; } + .chapter-list a, .chapter-list .rowish, .pager { flex-wrap: wrap; } +} +@media (prefers-reduced-motion: reduce) { + .story-card { transition: none; } + .story-card:hover { transform: none; } +} + .site-footer { border-top: 1px solid var(--rule); color: var(--muted); diff --git a/web/app/layout.tsx b/web/app/layout.tsx index 7fc26bd..58bda74 100644 --- a/web/app/layout.tsx +++ b/web/app/layout.tsx @@ -17,8 +17,9 @@ export default function RootLayout({ children }: { children: ReactNode }) { return ( + Skip to content
-
{children}
+
{children}
diff --git a/web/app/login/page.tsx b/web/app/login/page.tsx index b17cbd5..aaacb8d 100644 --- a/web/app/login/page.tsx +++ b/web/app/login/page.tsx @@ -32,14 +32,14 @@ export default function LoginPage() {

Welcome back

Log in

- - setUsername(e.target.value)} autoComplete="username" /> - - setPassword(e.target.value)} autoComplete="current-password" /> - {err &&

{err}

} + + setUsername(e.target.value)} autoComplete="username" /> + + setPassword(e.target.value)} autoComplete="current-password" /> + {err &&

{err}

}
Need an account?
diff --git a/web/app/me/page.tsx b/web/app/me/page.tsx index 3d5bcbe..29896af 100644 --- a/web/app/me/page.tsx +++ b/web/app/me/page.tsx @@ -10,6 +10,8 @@ export default function MePage() { const [displayName, setDisplayName] = useState(""); const [bio, setBio] = useState(""); const [msg, setMsg] = useState(""); + const [err, setErr] = useState(""); + const [busy, setBusy] = useState(false); useEffect(() => { if (!getToken()) { @@ -20,20 +22,29 @@ export default function MePage() { setUser(u); setDisplayName(u.displayName); setBio(u.bio); - }); + }).catch((e) => setErr(e instanceof Error ? e.message : "Could not load profile.")); }, [router]); const save = async (e: FormEvent) => { e.preventDefault(); - const u = await api.patchMe({ displayName, bio }); - const token = getToken(); - if (token) setSession(token, u); - window.dispatchEvent(new Event("inkwell-auth")); - setUser(u); - setMsg("Profile saved."); + setBusy(true); + setErr(""); + setMsg(""); + try { + const u = await api.patchMe({ displayName, bio }); + const token = getToken(); + if (token) setSession(token, u); + window.dispatchEvent(new Event("inkwell-auth")); + setUser(u); + setMsg("Profile saved."); + } catch (e) { + setErr(e instanceof Error ? e.message : "Could not save profile. Try again."); + } finally { + setBusy(false); + } }; - if (!user) return

Loading desk…

; + if (!user) return

{err || "Loading desk…"}

; return ( @@ -42,13 +53,14 @@ export default function MePage() {

{user.followers} followers · {user.following} following

- - setDisplayName(e.target.value)} /> - -