Design Tokens

The prototype defines Material-style --md-sys-* tokens first, then maps the Starlight --sl-* variables to those roles. This follows Material Web’s CSS custom property approach without requiring Material Web components at runtime.

The theme declares Starlight’s public layers first, then the MD3 layers:

@layer starlight.base, starlight.reset, starlight.core, starlight.content,
  starlight.components, starlight.utils, md3.tokens, md3.bridge, md3.base,
  md3.layout, md3.prose, md3.components, md3.code, md3.motion,
  md3.utilities;

This keeps the package CSS override-friendly while preserving Starlight’s component structure and accessibility behavior.

The demo and fallback tokens use seed: '#00a99d' with the tonalSpot variant. This gives the first visual pass a clearer Material You role relationship: a distinct primary, quieter secondary, blue-leaning tertiary, and more neutral surface containers. Purple remains available as a named accent and expressive preset, but it is no longer the default visual baseline. When a seed is configured, the plugin generates primary, secondary, tertiary, error, surface, outline, inverse, and scrim roles for both dark and light themes through @material/material-color-utilities.

tonalSpot and content use Material Color Utilities core palettes. expressive currently keeps a HCT-based approximation because the package’s newer DynamicScheme modules still rely on imports that are not stable across the target Node and bundler matrix.

The public token surface is intentionally smaller than the selector-specific styling used by the demo. System tokens are the safest override layer. Component tokens are available for focused customization, but may still change while the package is v0.x.

The theme now exposes the complete Material-style type role matrix: display, headline, title, label, and body, each with large, medium, and small sizes. The tokens include size, line-height, weight, and tracking; tracking is kept at 0 for this documentation theme to avoid cramped text in mixed English and Chinese content.

The theme keeps the default density compact, but prose rhythm now has explicit tokens for line height, paragraph gaps, heading gaps, list gaps, block gaps, and table cell padding. This lets documentation stay information-dense while keeping the MD3 quality of calm, readable spacing.

Motion is tokenized and intentionally quiet. The theme uses Material-style state layers, pointer-origin ripples, sidebar disclosure motion, TOC tracker motion, anchored menu transitions, search container-transform motion, homepage entrance motion for the hero and homepage surfaces, short pressed feedback, and content-only same-site route transitions. The route transition runs only after same-origin theme navigation, leaving the header, search, and primary chrome stable. Interior documentation pages avoid initial page-entry animation, hover translation, decorative scale effects, and blanket transition: all rules.

When prefers-reduced-motion: reduce is active, the theme reduces motion token durations and route delay to 0ms. The plugin’s motion: false option applies the same token override and skips the interactive motion runtime without requiring users to write CSS.

Tonal surface is the default depth tool. Shadows are reserved for interactive or modal surfaces.

• Prefer seed, variant, density, shape, contrast, tonalSurface, and motion plugin options for broad theme changes.
• Prefer --md-sys-* tokens for site-wide color, type, shape, elevation, and motion overrides.
• Use --md3-comp-* tokens only when a specific Starlight surface needs a targeted adjustment.
• Treat helper classes such as .md3-showcase as documentation examples rather than a supported customization API.

The plugin keeps the package CSS static and writes preset-level customizations into an unlayered inline <style data-starlight-theme-md3="options"> entry in Starlight’s document head. Those values override the layered package defaults without requiring users to import generated CSS.