Starlight Components

Use this page as a regression checklist when changing tokens or component overrides. It keeps the long tail of Starlight UI in one place.

Cards

Docs navigation

Cards use compact type, quiet surfaces, and icon backgrounds that rotate through the Starlight accent palette.

Theme tokens

Cards, code blocks, tabs, and file trees share the --code-background surface token.

Search ready

The theme keeps hover states restrained so dense docs pages remain easy to scan.

Link Cards

Getting Started Install the theme, add the plugin, and extend the docs schema.

Customize the Theme Tune color modes, typography, layout dimensions, and component surfaces.

Plugin API Review plugin options, frontmatter extensions, and package exports.

Asides

Note

Default asides work well for neutral notes that should be visible without becoming the visual center of the page.

Theme QA

Keep this page open while adjusting tokens. The fastest way to catch a mismatch is to see every state together.

Contrast check

Review light and dark mode after changing --foreground, --muted-foreground, --border, or --code-background.

Danger

Do not judge a docs theme only by headings and paragraphs. Tabs, file trees, badges, and code frames need the same care.

Badges

• Default
• Note
• Success
• Tip
• Caution
• Danger
• Small
• Medium
• Large

Code

src/styles/global.css

@layer lucode {
  :root[data-theme='dark'] {
    --background: oklch(14.5% 0 0);
    --foreground: oklch(98.5% 0 0);
    --code-background: oklch(20.5% 0 0);
  }
}

File Tree

• Directorydocs

  • Directorysrc

    • Directorycontent

      • Directorydocs

        • Directoryguides

          • getting-started.md
          • configuration.md
          • theming.md
        • Directoryshowcase

          • starlight-components.mdx
          • splash-pages.mdx
          • typography.md
  • astro.config.mjs
• Directorypackages

  • Directorylucode-starlight

    • Directorycomponents

      • custom
      • overrides
    • Directorystyles

      • base.css
      • theme.css

Icons

Link Buttons

Get Started

Customize

Theme Components

Official Component Docs

Steps

1. Install the plugin

   Add lucode-starlight to Starlight’s plugins array.

2. Extend the schema

   Add ExtendDocsSchema if you want typed splash hero layouts and announcements.

3. Tune the tokens

   Override CSS custom properties from your app stylesheet.

4. Inspect the showcase

   Review this page and the typography page before shipping a custom palette.

Tabs

bun

bun add lucode-starlight
bun run docs

npm

npm install lucode-starlight
npm run dev

pnpm

pnpm add lucode-starlight
pnpm dev

bun

Synced tabs keep repeated install, dev, and build examples aligned for readers.

npm

The same tab stays selected here, which is useful on setup-heavy docs pages.

pnpm

The theme does not require a specific package manager.