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. Use the 0.1.x release line for Astro 6 / Starlight 0.40 projects.

Preview

Install

npm install starlight-theme-md3

Create A New Project

To start from a preconfigured Starlight project:

pnpm create starlight-theme-md3

Equivalent npm command:

npm create starlight-theme-md3@latest

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:

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 | | experimentalComponents | boolean | false | Reserved |

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

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

All commands are run from the root of the project, from a terminal:

| Command | Action | | :------------------------ | :----------------------------------------------- | | pnpm install | Installs dependencies | | pnpm dev | Starts demo dev server at localhost:4321 | | pnpm build:theme | Builds package files to ./dist/ | | pnpm build:demo | Builds the demo site to ./demo-dist/ | | pnpm build | Builds both the package and demo site | | pnpm check:contrast | Audits core MD3 foreground/background pairs | | pnpm test:screenshots | Compares Playwright visual snapshots locally or in the manual visual regression workflow | | pnpm test:screenshots:update | Updates Playwright visual snapshots | | pnpm typecheck | Runs astro check | | pnpm pack --dry-run | Verifies package contents | | pnpm astro ... | Run CLI commands like astro add, astro check | | pnpm astro -- --help | Get help using the Astro CLI |

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.

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 pnpm build:theme.
• demo-dist/ contains the demo output after 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.