Web Design

Design Philosophy

The UI SHALL be semantic-first: structure and meaning come from HTML elements, not from CSS classes or JavaScript behaviour.
The project MUST NOT rely on client-side JavaScript for core functionality. Pages SHALL be fully usable with JavaScript disabled.
Visual design SHALL be expressed through CSS custom properties and minimal, composable utility styles.

All rendered HTML SHALL conform to WCAG 2.1 AA.
Text and interactive elements SHALL meet a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text (>=18.66px bold or >=24px).
Interactive targets (links, buttons) SHALL have a minimum target size of 44x44 CSS pixels, or sufficient spacing to compensate per WCAG 2.5.8.
Focus indicators SHALL be visible on all interactive elements (`:focus-visible` outline).
When adding or modifying UI components, agents SHOULD verify contrast ratios against the page background and component background using computed values rather than assumptions.

Semantic HTML elements SHALL be preferred over `div`/`span` where an appropriate element exists (e.g. `nav`, `header`, `main`, `footer`, `time`).
Images SHALL have descriptive `alt` text; decorative images SHALL use `alt=""` with `role="presentation"`.
Skip navigation links SHALL be provided.
ARIA landmarks and labels SHALL be used where native semantics are insufficient.

Layout SHALL use modern CSS (grid, flexbox) without framework dependencies.
Colour tokens SHALL be defined as CSS custom properties to enable consistent theming and ease contrast verification.
Media queries SHALL ensure usability from 320px viewport width upward.

Source code highlighting SHALL be server-rendered at request time. No client-side JavaScript highlighter SHALL be used.
The highlighting engine uses hilite + textmate-language with bundled TextMate grammars (48 languages).
The colour theme lives in `lib/static/syntax-theme.css` (currently Zenburn Dark, high-contrast variant) and is decoupled from structural styles.
CSS selectors use `[class*="-keyword"]` attribute matching for language-agnostic theming.