---
inclusion: auto
---

# 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.

## Accessibility (WCAG 2.1 AA)

- 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

- 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.

## CSS

- 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.

## Syntax Highlighting

- 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.

## Pages

- The repository navigation SHALL expose only: Summary, Commits,
  Files.
- The Summary page SHALL display only the inline README.
- There SHALL be no dedicated branches, tags, or README pages.