Getting Started

starlight-theme-md3 is a Starlight plugin. It appends a Material Design 3 inspired CSS layer to your docs site without replacing Starlight’s content, navigation, search, or MDX component model.

npm install starlight-theme-md3

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import md3Theme from 'starlight-theme-md3';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [md3Theme()],
    }),
  ],
});

md3Theme({
  seed: '#00a99d',
  variant: 'expressive',
  density: 'compact',
  shape: 'medium',
  tonalSurface: true,
  motion: true,
});

Use seed when you want the theme to generate a light and dark color scheme from one color. If seed is omitted, the accent option provides named fallback presets for primary color roles.

The light, dark, and automatic appearance switcher is always present. It uses a labelled control in both the desktop top app bar and mobile navigation drawer; both open the same labelled menu. When enabled, the runtime color picker uses a compact color-swatch button beside social actions on mobile.

md3Theme({
  motion: true,
  colorPicker: {
    mode: 'both',
    persist: true,
  },
});

motion enables the theme’s state layers, ripples, navigation motion, and route feedback while continuing to respect prefers-reduced-motion. colorPicker is optional: use author for development-only palette work, visitor for a public picker, or both to use the appropriate mode in each environment.

• Adds Material-style system tokens with --md-sys-* names.
• Bridges common Starlight --sl-* variables to those tokens.
• Styles high-impact docs surfaces: header, sidebar, table of contents, prose, code, asides, cards, tabs, badges, and pagination.
• Leaves Starlight’s runtime and content model intact.