blob: ebc0ee8e3a32e9245454cf4eeac7eddbce44a4f1 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
# Design: Prose Heading `//` Prefix
**Date:** 2026-04-18
**Status:** Approved
## Context
danix.xyz uses a hacker/terminal aesthetic throughout. Article and single page body headings (H2–H6) currently render in Oxanium font with no visual marker. The goal is to prefix all prose headings with `// ` in JetBrains Mono to reinforce the terminal/comment idiom — matching the hacker identity of the site.
## Requirements
- All headings H2–H6 inside `.prose` content (site-wide — all singles and pages)
- H1 is excluded (used for page/article titles, already styled distinctly)
- Prefix `//` must be `aria-hidden="true"` — screen readers announce only the heading text
- Heading DOM hierarchy (H2→H6) must be preserved exactly
- WCAG 2.1 AA compliant: heading text contrast ≥ 4.5:1 (measured at 14.72:1 on dark theme)
- The prefix is decorative — exempt from contrast requirements per WCAG 1.4.3
- Must work in both dark and light themes
## Approach: Hugo render-heading hook
Create `layouts/_default/_markup/render-heading.html` — Hugo's Markdown render hook for headings. For H2–H6, wrap the heading in the correct `<hN>` tag and inject `<span aria-hidden="true" class="heading-prefix">//</span>` before the text. H1 passes through unmodified.
Style the `.heading-prefix` span in `main.css`:
- Font: `JetBrains Mono` (Tailwind `font-mono`)
- Color: `var(--accent)` (purple)
- Weight: `400` (lighter than heading bold — creates comment-marker feel)
- Size: `0.8em` relative to heading (scales automatically across H2–H6)
- Opacity: `0.7` (decorative dimming — exempt from contrast check)
- `margin-right: 0.35em`
No changes needed to any layout template. No JS. CSS is the only addition beyond the new hook file.
## Files
| File | Action |
|------|--------|
| `themes/danix-xyz-hacker/layouts/_default/_markup/render-heading.html` | Create (new) |
| `themes/danix-xyz-hacker/assets/css/main.css` | Add `.heading-prefix` rule |
## A11y Checklist
- [x] `aria-hidden="true"` on prefix span — screen reader reads "Section Title, heading level 2" not "slash slash Section Title"
- [x] Heading text contrast 14.72:1 dark / verified light theme passes
- [x] DOM heading order unchanged
- [x] `prefers-reduced-motion` not relevant (no animation)
- [x] Decorative prefix contrast exempted under WCAG 1.4.3
## Verification
1. `hugo server` — navigate to any article or single page
2. Headings H2–H6 show `// Title` in JetBrains Mono with purple dimmed prefix
3. H1 (page title) unchanged
4. Toggle dark/light theme — prefix visible and not garish in both
5. Run browser accessibility inspector — prefix span reports `aria-hidden: true`
6. `npm run build` — CSS compiles cleanly
|
