This document defines Oak-specific standards for developers for building and reviewing components, in addition to generic best practices around semantics, accessibility, and TypeScript.

These standards apply to:

• new components
• changes to existing components

Exceptions should be explicitly called out and agreed in the PR.

Figma alignment

Figma and Oak Components should stay aligned so that designers and developers can reliably navigate between the two.

Naming alignment

• [ ] Component naming is aligned between Figma and Oak Components where possible
  • We currently don’t have formal naming guidelines
  • Match Figma and component name to support discoverability. Figma does not use the Oak prefix, but names should otherwise align:
    • OakTooltip (component) → Tooltip (Figma)
    • OakCard (component) → Card (Figma)

Visual alignment

• [ ] Spacing, typography and colours match Figma design:
  • If they don’t, confirm the source of truth with a designer
  • Either update the component or ask for Figma to be updated
• [ ] Responsive layouts match Figma design
  • If they don’t, confirm the source of truth and update accordingly

Behaviour & accessibility

• [ ] Component behaviour (interactions, keyboard navigation, aria labels) matches what’s outlined in Figma
  • If behaviour differs, challenge why:
    • Was it never built?
    • Is it no longer needed?
  • Resolve by updating the component or Figma
  • Note: Figma should outline any component-specific accessibility requirements in addition to general accessibility standards

Code standards

These are Oak-specific standards, on top of general TypeScript, semantic HTML, and accessibility best practices.

Component Documentation