starlight-theme-md3

English | 简体中文

A Material Design 3 / Material You inspired theme for Astro Starlight. It keeps Starlight's defaults intact and layers Material color, shape, surface, state, and typography tokens through CSS variables and a Starlight plugin.

The theme does not require Tailwind configuration and does not depend on @material/web at runtime. Users install the package and keep the Starlight integration shape as plugins: [md3Theme()].

Compatibility

[email protected] targets Astro 7 and Starlight 0.41 or newer. It therefore requires Node.js 22.12 or newer. Use the 0.1.x release line for Astro 6 / Starlight 0.40 projects.

Preview

Install

Using npm:

npm install starlight-theme-md3

Using pnpm:

pnpm add starlight-theme-md3

Create A New Project

To start from a preconfigured Starlight project:

Using npm:

npm create starlight-theme-md3@latest

Using pnpm:

pnpm create starlight-theme-md3

The creator follows the same shape as Astro's official create flow. It asks for a project directory when one is not provided, can install dependencies, can initialize git, and does not pin a packageManager in the generated project.

Useful flags:

Using npm:

npm create starlight-theme-md3@latest my-docs -- --install --git
npm create starlight-theme-md3@latest my-docs -- --no-install --no-git
npm create starlight-theme-md3@latest my-docs -- --yes
npm create starlight-theme-md3@latest my-docs -- --dry-run

Using pnpm:

pnpm create starlight-theme-md3 my-docs -- --install --git
pnpm create starlight-theme-md3 my-docs -- --no-install --no-git
pnpm create starlight-theme-md3 my-docs -- --yes
pnpm create starlight-theme-md3 my-docs -- --dry-run

Usage

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({
					seed: '#00a99d',
					variant: 'tonalSpot',
					density: 'compact',
					shape: 'medium',
				}),
			],
		}),
	],
});

Options

| Option | Values | Default | Status | | --- | --- | --- | --- | | preset | neutral, playful, highContrast | none | Named option bundles | | seed | #rgb or #rrggbb | none | Generates light/dark color roles | | variant | tonalSpot, expressive, content | tonalSpot | Seed palette style | | accent | teal, purple, blue, green, orange, rose | teal | Named fallback presets | | density | compact, comfortable | compact | Preview token override | | shape | small, medium, large | medium | Preview token override | | contrast | standard, medium, high | standard | State, outline, and selected-tone emphasis | | tonalSurface | boolean | true | Preview token override | | motion | boolean | true | Preview token override | | colorPicker | boolean or picker options | false | Optional author/visitor runtime color picker | | experimentalComponents | boolean | false | Reserved |

preset fills in default options only. Explicit options such as seed, shape, or tonalSurface override the preset.

Theme Interaction Configuration

Light, dark, and automatic appearance modes are always available through the theme switcher. No plugin option is required for them: the desktop top app bar and mobile navigation drawer both use an icon-and-label button. Opening either control shows the same fully labelled Dark, Light, and Auto menu. When the optional color picker is enabled, mobile presents its 48px color-swatch button beside the configured social links instead of adding a full-width row.

Use motion and colorPicker to configure the optional interaction layers:

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

| Setting | Effect | | --- | --- | | motion: true | Enables MD3 state layers, pointer ripples, menu/drawer motion, TOC tracking, and route feedback. | | motion: false | Removes decorative motion and skips the motion runtime; focus and accessible control semantics remain. | | colorPicker: false | Ships only the deployed seed or accent palette. | | colorPicker.mode | Chooses whether the runtime palette tool is available to authors, visitors, both, or neither. |

The theme also follows prefers-reduced-motion. This media preference reduces motion even when motion is enabled.

Runtime color picker

The picker is opt-in and does not add a runtime dependency when disabled. Use both to provide an author preview tool during astro dev and a visitor picker in production:

md3Theme({
	seed: '#00a99d',
		colorPicker: {
			mode: 'both',
			persist: true,
		},
});

| Mode | Development | Production | | --- | --- | --- | | off | Hidden | Hidden | | author | Live preview and Copy config | Hidden | | visitor | Visitor controls | Visitor controls | | both | Author controls | Visitor controls |

Visitor changes are previewed before Apply. With persist: true, applied palettes are stored in the browser and restored before first paint; Reset returns to the palette deployed by the site author. The picker uses a bundled, dependency-free saturation/value surface, hue track, and hex field. Browsers do not expose the real operating-system accent color reliably, so the color source intentionally offers only the deployed default and an explicit custom color.

Global Color

Set the theme's global color from the Starlight plugin options:

md3Theme({
	seed: '#6750a4',
	variant: 'tonalSpot',
});

seed is the preferred Material You path. It generates the light and dark Material color roles through @material/material-color-utilities. Change this one value to recolor the whole theme.

If you do not pass seed, the theme falls back to named accent palettes:

md3Theme({
	accent: 'blue',
});

The source defaults live in src/styles/md3/tokens.css; runtime color roles from seed or accent are generated in src/index.ts and override those fallbacks for the active theme.

Design Direction

• Token-first: map Material You system colors to Starlight's CSS custom properties.
• Docs-native: preserve Starlight's accessible navigation, search, table of contents, and content collections.
• Expressive but quiet: use tonal surfaces, rounded components, and soft elevation without making docs feel like a marketing page.
• No Material Web runtime: reference Material Web token and component guidance without depending on @material/web.
• CSS before overrides: add Astro component overrides only when CSS cannot express the design safely.

CSS Layer Model

The package declares Starlight's built-in layers before its own MD3 layers. System and component tokens live in md3.tokens, Starlight variable mappings live in md3.bridge, and rendered surfaces are styled through md3.layout, md3.prose, md3.components, md3.code, and md3.utilities. This keeps Starlight's DOM and behavior intact while allowing the theme to reliably style high-impact surfaces.

Project Structure

.
├── docs/
│   ├── README.zh-CN.md
│   └── readme/
├── public/
├── src/
│   ├── content/
│   │   └── docs/
│   ├── index.ts
│   ├── styles/
│   │   └── md3/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Commands

Run commands from the project root. npm and pnpm forms are listed side by side for easier reference; the repository continues to commit only pnpm-lock.yaml.

| Action | npm | pnpm | | :----- | :-- | :--- | | Install dependencies | npm install | pnpm install | | Start the demo server at localhost:4321 | npm run dev | pnpm dev | | Build the theme package to ./dist/ | npm run build:theme | pnpm build:theme | | Build the demo site to ./demo-dist/ | npm run build:demo | pnpm build:demo | | Build the package and demo | npm run build | pnpm build | | Audit core MD3 color contrast | npm run check:contrast | pnpm check:contrast | | Run Playwright visual regression tests | npm run test:screenshots | pnpm test:screenshots | | Update Playwright snapshots | npm run test:screenshots:update | pnpm test:screenshots:update | | Run astro check | npm run typecheck | pnpm typecheck | | Verify package contents | npm pack --dry-run | pnpm pack --dry-run | | Run an Astro CLI command | npx astro ... | pnpm astro ... | | Show Astro CLI help | npx astro --help | pnpm astro -- --help |

Deploy Demo

The demo site can be deployed to GitHub Pages with .github/workflows/deploy-pages.yml. Enable Settings → Pages → Source: GitHub Actions in the repository, then push to main or run the workflow manually.

The workflow reads the Pages origin and base path from actions/configure-pages and passes them to Astro through ASTRO_SITE and ASTRO_BASE, so project pages such as https://<user>.github.io/<repo>/ build with the correct base path.

Pull requests can receive an isolated Netlify Deploy Preview while GitHub Pages continues to host the production demo. Connect the repository to Netlify once; the checked-in netlify.toml pins builds to the repository root, builds the current pull request with its preview origin, and publishes demo-dist/. Leave Netlify's Package directory empty. See Pull Request Previews for the maintainer setup and expected GitHub status.

Current Status

• Starlight is installed with Astro and configured in astro.config.mjs.
• src/index.ts exposes the local Starlight plugin.
• src/styles/md3/ contains the split CSS source.
• src/styles/md3/component-tokens.css exposes local --md3-comp-* tokens for high-impact Starlight components.
• src/styles/md3/motion.css adds restrained MD3-style state layers, pointer-origin ripple feedback, and short navigation pending feedback.
• dist/css/index.css is bundled from src/styles/md3/index.css with Lightning CSS.
• src/palette.ts generates seed color roles with @material/material-color-utilities.
• fixtures/package-consumption/ verifies the packed package in a separate Starlight project.
• dist/ contains the package output after npm run build:theme or pnpm build:theme.
• demo-dist/ contains the demo output after npm run build:demo or pnpm build:demo.
• Concept, implementation, Theme Lab, component sample, and token reference docs live in src/content/docs/.
• Playwright screenshot tests cover homepage, Theme Lab, Implementation Overview, plugin options, search dialog, mobile drawer, and mobile table-of-contents states in light/dark modes.
• GitHub Actions CI runs install, typecheck, contrast, build, package consumption, and pack dry-run.
• The separate Visual Regression workflow runs Playwright screenshot tests manually when a UI review needs CI artifacts.

Current Limits

• tonalSpot and content use Material Color Utilities core palettes. expressive keeps the public option but currently uses a HCT-based approximation because the package's newer DynamicScheme entrypoints still fail under the target Node ESM resolver.
• Component overrides are intentionally deferred until CSS-only styling reaches a real limitation.
• The package is v0.x; option names and visual tokens may change while the theme stabilizes.