Customizing Starlight Colors and Styling

This tutorial will teach you how to customize the appearance of your Astro Starlight documentation site, from basic color changes to advanced component styling.

What is Starlight?

Starlight is the official Astro framework for building documentation sites. It provides:

• 🎨 Built-in theming with automatic light/dark mode
• 📱 Responsive design out of the box
• 🔍 Full-text search powered by Pagefind
• 🌐 Internationalization support
• ♿ Accessibility-first design
• 📊 Auto-generated navigation from file structure
• 🎯 SEO optimization

Think of Starlight as “the framework for documentation sites” - opinionated, feature-rich, and production-ready.

Prerequisites

Before starting this tutorial, you should have:

• An Astro project with Starlight installed
• Basic knowledge of CSS custom properties (CSS variables)
• A code editor open to your project

Step 1: Create Your Custom CSS File

First, create a dedicated file for your custom styles:

mkdir -p apps/docs/src/styles
touch apps/docs/src/styles/custom.css

Step 2: Link the CSS File to Starlight

Open your astro.config.mjs and add the customCss option:

apps/docs/astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
      customCss: [
        './src/styles/custom.css', // Add this line
      ],
      // ... rest of your config
    }),
  ],
});

Step 3: Customize Your Brand Colors

Add your brand colors by overriding Starlight’s CSS custom properties:

apps/docs/src/styles/custom.css

:root {
  /* Accent colors - your primary brand color */
  --sl-color-accent-low: #e0e7ff;    /* Light backgrounds */
  --sl-color-accent: #6366f1;         /* Main accent color */
  --sl-color-accent-high: #4f46e5;    /* Hover/active states */

  /* Text colors */
  --sl-color-text: #1e293b;           /* Body text */
  --sl-color-text-accent: #4f46e5;    /* Links and accents */

  /* Background colors */
  --sl-color-bg: #ffffff;             /* Main background */
  --sl-color-bg-nav: #f8fafc;         /* Navigation bar */
  --sl-color-bg-sidebar: #f1f5f9;     /* Sidebar */
}

Save the file and check your browser - the colors should update automatically!

Step 4: Add Dark Mode Support

Starlight automatically handles dark mode switching. You just need to define the colors:

/* Dark mode overrides */
:root[data-theme='dark'] {
  /* Brighter accents work better on dark backgrounds */
  --sl-color-accent-low: #312e81;
  --sl-color-accent: #818cf8;
  --sl-color-accent-high: #a5b4fc;

  /* Light text on dark backgrounds */
  --sl-color-text: #e2e8f0;
  --sl-color-text-accent: #a5b4fc;

  /* Dark backgrounds */
  --sl-color-bg: #0f172a;
  --sl-color-bg-nav: #1e293b;
  --sl-color-bg-sidebar: #1e293b;
}

Test it: Click the theme toggle in your docs to switch between light and dark modes!

Step 5: Customize Typography

Override the font families and sizes:

:root {
  /* Font families */
  --sl-font: 'Inter', system-ui, sans-serif;
  --sl-font-mono: 'Fira Code', 'Consolas', monospace;

  /* Font sizes (optional) */
  --sl-text-base: 1rem;
  --sl-text-lg: 1.125rem;
  --sl-text-xl: 1.25rem;
}

Pro tip: Use system font stacks for faster loading, or load web fonts from Google Fonts or your design system.

Step 6: Style Individual Components

Customize specific Starlight components with CSS selectors:

/* Rounded code blocks */
.expressive-code {
  border-radius: 0.5rem;
  margin: 1.5rem 0;
}

/* Smooth link transitions */
a:not(.card-link) {
  transition: color 0.2s ease;
}

a:not(.card-link):hover {
  color: var(--sl-color-accent-high);
}

/* Sidebar borders */
.sidebar-content {
  border-right: 1px solid var(--sl-color-hairline);
}

/* Table of contents */
.right-sidebar {
  border-left: 1px solid var(--sl-color-hairline);
}

Advanced: Using Design Tokens

If you have a design token system (like Style Dictionary), integrate it:

/* Import your design tokens */
@import '@packages/design-tokens/dist/css/variables.css';

/* Map tokens to Starlight variables */
:root {
  --sl-color-accent: var(--color-primary-500);
  --sl-color-accent-high: var(--color-primary-600);
  --sl-color-accent-low: var(--color-primary-100);

  --sl-color-text: var(--color-text-primary);
  --sl-color-bg: var(--color-background-primary);

  --sl-font: var(--font-family-base);
}

This ensures consistency between your documentation and application UI.

Complete Color Reference

Starlight provides these CSS custom properties for theming:

Accent Colors

• --sl-color-accent-low - Light accent backgrounds
• --sl-color-accent - Primary accent (links, buttons)
• --sl-color-accent-high - Accent highlights/hover

Text Colors

• --sl-color-text - Body text
• --sl-color-text-accent - Accent text
• --sl-color-white - Pure white
• --sl-color-gray-1 to --sl-color-gray-6 - Gray scale
• --sl-color-black - Pure black

Background Colors

• --sl-color-bg - Main background
• --sl-color-bg-nav - Navigation background
• --sl-color-bg-sidebar - Sidebar background
• --sl-color-bg-inline-code - Inline code background

Border Colors

• --sl-color-hairline-light - Light borders
• --sl-color-hairline - Default borders
• --sl-color-hairline-shade - Darker borders

Hot Reloading

Starlight uses Astro’s hot module replacement (HMR):

1. Make changes to your CSS file
2. Save the file
3. Watch your browser update automatically (usually within 1-2 seconds)

No restart needed! The dev server stays running and hot-reloads your styles.

Troubleshooting

Colors not updating?

1. Check the file path in astro.config.mjs is correct
2. Try a hard refresh: Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux)
3. Restart the dev server if HMR gets stuck

Dark mode not working?

1. Verify you’re using :root[data-theme='dark'] selector
2. Check that you’re overriding the correct variables
3. Use browser DevTools to inspect the applied styles

Fonts not loading?

1. Ensure font files are in the public/ directory
2. Or use web fonts from a CDN (Google Fonts, etc.)
3. Add font-face declarations before defining --sl-font

Next Steps

Now that you know how to customize Starlight:

• Explore component overrides: Replace default Starlight components with your own
• Add custom layouts: Create branded layouts for special pages
• Integrate with Tailwind: Use utility classes alongside Starlight
• Create brand themes: Build multiple theme files for different brands

Related Documentation

• Starlight CSS Guide
• Starlight Components
• Astro Styling
• Design Tokens Overview

Summary

In this tutorial, you learned:

✅ What Starlight is and its key features
✅ How to create and link a custom CSS file
✅ How to customize brand colors for light and dark modes
✅ How to override typography settings
✅ How to style individual components
✅ How to integrate with existing design token systems

Your documentation site now has a custom appearance that matches your brand identity!