Skip to content

Every page, the docs included, is styled from a few --site-* CSS custom properties in astro-project-site/theme.css. Starlight’s own palette (--sl-color-*), fonts and header height are mapped from them, so one set of tokens restyles the landing page, the gallery, the docs and the live examples together. The full list with defaults: Theme tokens.

The example below previews a set of tokens on a miniature page. Edit the values; Apply to this page sets them on this page’s <html>, so the docs around you (sidebar, links, code, the header) restyle live. Reset, Restore, or leaving the page undoes it.

tokens.css
--site-accent: #ffb347;
--site-bg: #17151d;
--site-surface: #211e29;
--site-text: #f2eee8;
--site-muted: #a9a3b4;
--site-border: #322e3c;
--site-code-bg: #0e0c12;
--site-code-text: #f2eee8;
--site-radius: 4px;
--site-font-heading: Georgia, serif;
Brand tokens, previewed and applied #

The derived tokens (--site-accent-soft, --site-accent-strong, --site-link, --site-on-accent, …) are recomputed from the ones you set. Applied inline on <html>, the values win in both themes; in a stylesheet you set each theme separately, below.

List a CSS file in customCss; it loads on every page after theme.css:

astro.config.mjs
customCss: ['./src/styles/brand.css'],
src/styles/brand.css
/* Dark theme: the default when the OS has no preference. */
:root {
--site-accent: #ffb347;
--site-bg: #17151d;
--site-surface: #211e29;
--site-text: #f2eee8;
--site-muted: #a9a3b4;
--site-border: #322e3c;
--site-radius: 4px;
}
/* Light theme. */
:root[data-theme='light'] {
--site-accent: #c2541b;
--site-bg: #fbf8f2;
--site-surface: #f3ede2;
--site-text: #23212c;
--site-muted: #5d5a6b;
--site-border: #e4ded3;
}
  • Brand tokens (set these): --site-accent, --site-bg, --site-surface, --site-text, --site-muted, --site-border, --site-code-bg, --site-code-text; fonts --site-font-body, --site-font-heading, --site-font-mono; shape and space --site-radius, --site-space, --site-max-width, --site-header-height.
  • Derived tokens (usually leave alone): --site-accent-soft, --site-accent-strong, --site-on-accent, --site-link, --site-focus, --site-radius-sm, --site-shadow.

Only the accent? theme: { accent: '#c2541b', accentDark: '#ffb347' } in the config does that without CSS, and wins over a customCss value for --site-accent.

The build checks a theme.accent (hex, rgb() or hsl()) against the theme it lands in and warns when links, the primary button’s text, the current nav item or the focus ring would fall below WCAG 2.2 AA contrast (4.5:1 for text, 3:1 for the focus ring), naming the pair and the ratio. The build still runs; pick a darker accent for the light theme, or a lighter accentDark, until the warning goes away.

The theme is <html data-theme="light|dark">, shared with Starlight: the switch in the header (on every page) stores the choice in localStorage['starlight-theme'], so a choice made on the landing page carries over to the docs and back. “Auto” follows the OS. Write :root for dark and :root[data-theme='light'] for light, like theme.css does.

The defaults are system font stacks. To use a web font, self-host it (no third-party request), declare it, and point the tokens at it:

src/styles/brand.css
@font-face {
font-family: 'Inter';
src: url('/fonts/InterVariable.woff2') format('woff2'); /* public/fonts/InterVariable.woff2 */
font-weight: 100 900;
font-display: swap;
}
:root {
--site-font-body: 'Inter', system-ui, sans-serif;
--site-font-heading: 'Inter', system-ui, sans-serif;
}

Check the font’s licence allows redistribution (most open fonts, e.g. OFL, do) and keep its licence file next to it.

customCss files are ordinary global CSS on every page, so you can style anything. Two more hooks:

  • Docs-only CSS: starlight: { customCss: ['./src/styles/docs.css'] } is appended after yours, on docs pages only.
  • Components: the built-in components keep their styles scoped; to change markup, override them.
astro-project-site

A whole site for your open-source project, from one Astro integration.

© 2026 astro-project-site · v0.1.0-beta.6 · MIT licence. This site is built with itself.