Theming

Three layers, in order of preference

1. CSS variables in src/styles/custom.css — colours, fonts, widths, radii.
2. Component overrides in src/components/ — markup changes, registered in astro.config.mjs under starlight({ components: { … } }).
3. Forking a Starlight component — last resort. It breaks on every minor upgrade.

Everything in layer 1 and 2 survives pnpm update.

Brand tokens

:root {
  --sl-font: 'Inter', system-ui, sans-serif;
  --sl-color-accent: #4f46e5;
  --sl-color-accent-low: #1e1b4b;
  --sl-color-accent-high: #c7d2fe;
  --sl-content-width: 48rem;
}

Starlight derives most of the palette from those three accent values, so light and dark mode both follow from one edit. Anything still off gets a targeted :root[data-theme='light'] / [data-theme='dark'] block.

Component overrides

Component	Used here for
Hero	the splash page gradient and pill buttons
SocialIcons	the v1 ⇄ latest switcher in the header

To override another one, copy the original from node_modules/@astrojs/starlight/components/<Name>.astro into src/components/, edit it, and add it to the components map. Record every override in this table so upgrades are auditable.