Theme Lab

Theme Lab gathers dense examples on one page. It keeps Starlight’s default navigation, table of contents, markdown, and component markup active while the theme applies Material Design 3 color roles, tonal surfaces, shape, state layers, and compact documentation density.

中文长文档需要稳定、克制、可反复阅读的排版。这里包含中文段落，用来展示行高、字重、链接、代码、列表和表格在真实资料页中的阅读节奏。Material You 的动态色不应该压过内容，选中态和容器层级也不应该让读者分心。

The active sidebar item and this page’s table of contents should use the same primary role family. Hover states should feel quiet, selected states should be obvious, and the final TOC item should still become active near the bottom of the document.

Sidebar states

Getting StartedTheme LabPlugin Options

TOC states

OverviewComponentsFinal Check

State layers

PressedDisabled

Badges And Inline Tone

defaultnotetipsuccesscautiondanger

Inline code, strong text, links, and badges must remain legible in both light and dark themes. A docs theme should make state clear without turning each small element into a competing call to action.

Seed Preview

primary

secondary

tertiary

surface-container

error

Asides

Cards

System tokens

Color, type, shape, elevation, motion, and state are exposed as reusable CSS variables.

Starlight bridge

The theme maps Material roles onto Starlight’s existing custom properties.

Documentation density

Spacing stays compact enough for reference pages while preserving generous hit targets.

Dynamic color

Seed colors generate tonal roles through Material Color Utilities.

Plugin optionsReview seed, variant, density, shape, tonal surface, and motion options.

Tables

Surface	Expected role	What to notice
Page shell	`surface-container-lowest`	Chrome stays visually behind the content sheet
Header	`surface-container`	Top app bar reads as a stable app surface
Sidebar selected item	`secondary-container`	Selection is clear without dominating the page
TOC active item	`primary`	Active section remains easy to scan
Table header	`surface-container-high`	Header separates from table body
Code block	`surface-container-low`	Syntax colors remain readable

Tabs

System tokens are the public theme contract. Component selectors should consume these roles instead of hard-coded colors.

Code Blocks

Inline plugins: [md3Theme()] remains the intended user API. Users should not need to configure Tailwind to use the theme.

import starlight from '@astrojs/starlight';
import md3Theme from 'starlight-theme-md3';

export default {
  integrations: [
    starlight({
      plugins: [
        md3Theme({
          seed: '#00a99d',
          variant: 'tonalSpot',
          density: 'compact',
        }),
      ],
    }),
  ],
};

Chinese Paragraphs

这一段用于观察中文正文在紧凑文档布局中的表现。标题不应该过大，正文不应该显得松散，列表、表格和代码块之间也需要有清楚的层次。对于长期维护的技术文档来说，稳定的阅读节奏比一眼惊艳更重要。

中文链接例如 Design Tokens 应该与英文链接拥有一致的颜色和下划线策略。--md-sys-color-primary 这类 token 出现在中文句子里时，行高和背景不应该产生跳动。

Steps

Generate seed color roles with Material Color Utilities.
Bridge generated roles into Starlight’s existing variables.
Render real Starlight components without adding a runtime UI library.
Keep light, dark, desktop, and mobile surfaces visually consistent.

Final Scrollspy Check

This final heading demonstrates the table of contents behavior near the bottom of a long page. When the page is scrolled to the end, this item should become the active entry.