starlight-theme

Starlight Theming

Starlight exposes its entire visual design through CSS custom properties. Override any variable to change colors, typography, and layout — with or without Tailwind.

When to Use

• Changing the color palette (accent color, grays, backgrounds)
• Swapping fonts or adjusting text sizes
• Applying a consistent brand identity
• Integrating Tailwind CSS into a Starlight project

When Not to Use

• Replacing entire UI sections (header, footer, sidebar) — use starlight-custom-component instead
• Per-page layout changes without global theming intent

Mindset

Starlight styles live in CSS cascade layers. Unlayered CSS always wins.

1. CSS custom properties are the API. Set --sl-* variables on :root to change every element that reads them. See css-variables-reference.md for the full list.
2. Cascade layers determine priority. Any CSS you add without an @layer block is unlayered and automatically takes precedence over Starlight's named layers.
3. Tailwind requires different wiring. The @astrojs/starlight-tailwind compatibility package must be imported before Tailwind's own CSS or Starlight's styles break.

Approach 1: Custom CSS File

Step 1 — Create the file:

/* src/styles/custom.css */
:root {
  --sl-color-accent-low: #1a1a4e;
  --sl-color-accent: #3d52d5;
  --sl-color-accent-high: #b4bffe;
  --sl-font: 'Inter', sans-serif;
  --sl-content-width: 50rem;
}

:root[data-theme='dark'] {
  --sl-color-bg: #0f172a;
}

Step 2 — Register in astro.config.mjs:

starlight({
  customCss: ['./src/styles/custom.css'],
})

Approach 2: Tailwind CSS Integration

npx astro add tailwind
npm install @astrojs/starlight-tailwind

Replace src/styles/global.css with:

@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
  --font-sans: 'Inter';
  --color-accent-500: var(--color-indigo-500);
  /* Map full accent and gray scales — see references for complete example */
}