git:20261030.8facd13 to git:20261031.658a487

# Working on the web app

## Reuse and architecture

- Before adding code or dependencies, search existing utilities, hooks, shared

components, styles, and installed packages. Inspect implementations, call sites,

and relevant tests, not just names.

- Prefer reuse or small, backward-compatible options/variants over duplication;

preserve defaults and runtime boundaries. Add focused abstractions/dependencies

only when existing code cannot reasonably fit; remove superseded implementations.

- Inspect installed TanStack packages before routing, server-state, long-list,

form, shortcut, debounce/throttle, or interaction-heavy work. Prefer Router for

routing, Query for server state/request lifecycle, Virtual for long/dynamic lists.

- Reuse suitable installed facilities instead of custom replacements. Propose

missing TanStack packages first, explaining avoided complexity and maintainability

or performance benefits; never install packages by default.

## Design tokens and shared styles

- Check `src/styles/_includes/themes.sass`, `variables.sass`, and existing components

first. Reuse semantic tokens/shared components for colors, gradients, spacing,

typography, radii, shadows, and motion where suitable.

- Choose tokens by purpose, not matching values: overlay/pressed-shadow colors are

not unrelated surfaces/floating shadows. Avoid component-local copies, one-off

colors, derived palette variants, and redundant aliases. Explain and agree on

genuinely missing tokens before defining them centrally with dark/light values.

- Keep necessary geometry local, not a global token per measurement. `currentColor`,

transparency, and black/white coverage masks are not new palette colors.

- Defaults are starting points: keep foundations/behavior consistent while allowing

deliberate density, hierarchy, and emphasis differences. Use small, explicit,

reusable variants/modifiers owned by the component/pattern, with existing tokens

and preserved interaction states/accessibility behavior. Do not change global

defaults for local layouts or scatter equivalent overrides across controls.

- Decide label typography, icon size, geometry, and hit area separately; align

controls and balance visual weight. Main icons, brand marks, and secondary

indicators need not match label size; verify rendered optical corrections.

- Keep targets accessible regardless of glyph size: meet WCAG 2.2 AA target sizing,

consider enhanced 44px touch targets where feasible, and prevent overlapping

hit areas.

Check narrow layouts, long labels, both themes, and keyboard focus without

inconsistently shrinking controls.

References: [Fluent layout](https://fluent2.microsoft.design/layout),

[GOV.UK modifications](https://design-system.service.gov.uk/get-started/extending-and-modifying-components/),

WCAG [minimum](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)

and [enhanced](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) target sizing.

## Performance and lifecycle

- Require smooth interaction, bounded memory, and idle efficiency. Reuse facilities

before custom effects/interaction infrastructure; profile suspected bottlenecks

before speculative optimization.

- Explicitly own and clean up every listener, observer, timer, animation frame,

browser animation, and async operation. Cancel obsolete work, prevent stale async

completions, and release resources on unmount.

- Never rely solely on animation/transition events for cleanup: closing must release

content/effects with reduced motion, interruptions, zero durations, and rapid toggles.

- Prefer suitable CSS/browser-managed animations. Keep per-frame work outside React

state; run loops only while useful, pausing unnecessary work when hidden,

off-screen, inactive, or under reduced motion. Bound canvas resolution, particle

counts, and drawing frequency.

- Keep typing/scroll/pointer/resize hot paths small: batch layout reads before writes,

coalesce measurements, and avoid broad listeners causing unrelated layout/renders.

- Virtualize long/dynamic collections; bound DOM, including large text and structured

row payloads. Scope caches/registries and define eviction; hiding entries does not

bound memory.

- Verify relevant changes in production builds with realistic content and repeated

navigation, open/close, typing, and scrolling. Check cleanup/reduced motion;

distinguish retained caches/normal heap fluctuation from reproducible leaks.

Report measurements and verification limits.