# 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