feat(docs): fix prose contrast and personalize image-pull docs (BUNYIP-407) #409

Merged

longjacksonle merged 1 commit from feat/BUNYIP-407-docs-contrast-personalize into main

2026-07-30 00:41:14 +02:00

longjacksonle commented

2026-07-30 00:32:54 +02:00

Owner

What

Closes BUNYIP-407. Two docs improvements on the public /docs pages.

1. Prose contrast (WCAG AA)

.docs-article had no explicit text color, so rendered doc prose inherited the surrounding container color and blended into the background. It now pins color: hsl(var(--foreground)) (the high-contrast body token). Light theme foreground 120 22% 16% on background 120 21% 96% and dark theme foreground 120 21% 96% on background 120 8% 9% both clear the AA 4.5:1 target comfortably.

2. Personalized image-pull docs

The docker login step in downloading-apps.md now shows --username <username>. A signed-in reader sees their own Bunyip account email (the docker login username) substituted in place of the placeholder and highlighted via a new .docs-fill class. A ?raw=1 toggle reverts to the generic placeholder view, with a link to switch either direction. Signed-out rendering is unchanged: personalization is gated on a present user.

The substitution runs on the already-rendered, HTML-escaped output and builds the highlighted value through Maud, so a crafted username cannot inject markup.

Tests

personalize_docs_escapes_crafted_username - a <script> username is HTML-escaped, not injected.
personalize_docs_substitutes_and_highlights - placeholder replaced and wrapped in .docs-fill.
downloading_apps_carries_username_placeholder - guards the doc against drifting away from the substitution token.

just check-container is green (fmt + clippy -D warnings + build + full workspace tests).

Verification

Signed-out: personalization gated on c.user.is_some(), so the page renders exactly as before (only the CSS contrast change applies).
Signed-in: reader sees their email highlighted in the login command, with a toggle to the generic version.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LerAorB26HGHLfjC9iDUbd

## What Closes BUNYIP-407. Two docs improvements on the public `/docs` pages. ### 1. Prose contrast (WCAG AA) `.docs-article` had no explicit text color, so rendered doc prose inherited the surrounding container color and blended into the background. It now pins `color: hsl(var(--foreground))` (the high-contrast body token). Light theme foreground `120 22% 16%` on background `120 21% 96%` and dark theme foreground `120 21% 96%` on background `120 8% 9%` both clear the AA 4.5:1 target comfortably. ### 2. Personalized image-pull docs The `docker login` step in `downloading-apps.md` now shows `--username <username>`. A signed-in reader sees their own Bunyip account email (the docker login username) substituted in place of the placeholder and highlighted via a new `.docs-fill` class. A `?raw=1` toggle reverts to the generic placeholder view, with a link to switch either direction. Signed-out rendering is unchanged: personalization is gated on a present user. The substitution runs on the already-rendered, HTML-escaped output and builds the highlighted value through Maud, so a crafted username cannot inject markup. ## Tests - `personalize_docs_escapes_crafted_username` - a `<script>` username is HTML-escaped, not injected. - `personalize_docs_substitutes_and_highlights` - placeholder replaced and wrapped in `.docs-fill`. - `downloading_apps_carries_username_placeholder` - guards the doc against drifting away from the substitution token. `just check-container` is green (fmt + clippy -D warnings + build + full workspace tests). ## Verification - Signed-out: personalization gated on `c.user.is_some()`, so the page renders exactly as before (only the CSS contrast change applies). - Signed-in: reader sees their email highlighted in the login command, with a toggle to the generic version. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01LerAorB26HGHLfjC9iDUbd

longjacksonle added 1 commit

2026-07-30 00:32:54 +02:00

feat(docs): fix prose contrast and personalize image-pull docs (BUNYIP-407)

E2E / Playwright against deployment (pull_request) Successful in 1m36s

Details

Check / fmt + clippy + build + tests (pull_request) Successful in 8m17s

Details

Create release / Create release from merged PR (pull_request) Has been skipped

Details

dda63fa94b

The rendered `/docs/{slug}` prose had no explicit text color, so it inherited whatever the surrounding container used and read as low-contrast against the page background. Pin `.docs-article` to `hsl(var(--foreground))`, the high-contrast body token, so prose meets WCAG AA (4.5:1) in both the light and dark themes.

Personalize the image-pull guide for a signed-in reader: the `docker login` command now carries a `--username <username>` placeholder, and a signed-in reader sees their own Bunyip account email (which is the docker login username) substituted in and highlighted via a new `.docs-fill` class. A `?raw=1` toggle reverts to the generic placeholder view, and the page offers a link to switch either way. Signed-out rendering is unchanged: personalization is gated on a present user.

The substituted username is HTML-escaped through Maud before splicing into the already-rendered HTML, so a crafted username cannot inject markup; a test covers this. Additional tests assert the doc still carries the placeholder token and that substitution highlights the value.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LerAorB26HGHLfjC9iDUbd

longjacksonle scheduled this pull request to auto merge when all checks succeed

2026-07-30 00:35:49 +02:00