Web standards

Components, state, accessibility and performance rules.

Development standardUpdated 21 days ago (29 Sept 2026) by Developer C

Download .md Done editing

Title

Type

How we build in this area: the conventions and decisions the team works to.

Summary

Body

# Web standards

## Components

- One job per component. If the name needs "and", split it.
- Props in, events out. A component does not reach into global state it was not
  given.
- Server-render by default; reach for a client component only when you need
  interactivity.

## State

- URL for anything shareable or reloadable.
- No duplicated source of truth. Derive, do not copy.
- An uncontrolled input that reflects server data needs a `key` tied to that
  data, or it will show a stale value after a save.

## Accessibility (non-negotiable)

- Every interactive element is reachable and operable by keyboard.
- Every input has a label — visually hidden is fine, absent is not.
- Focus is visible. Do not remove the outline without replacing it.
- Colour is never the only carrier of meaning.
- Text contrast is at least 4.5:1.

## Performance

- Measure before optimising.
- Images are sized and lazy below the fold.
- Watch the bundle. A date library is rarely worth 70 KB.

## Review checklist

- [ ] Works with the keyboard alone
- [ ] Inputs are labelled
- [ ] Loading and error states exist, not just the happy path
- [ ] No layout shift once data arrives
- [ ] Nothing secret in client-side code

Markdown with tables, code blocks and task lists.