Skip to content
China Explained

Styling

Styling

Section titled “Styling”

Astro supports normal CSS, scoped styles inside .astro components, imported global CSS, CSS modules, preprocessors, Tailwind, and other styling integrations. Start with plain CSS unless the project has a clear reason to add more.

For documentation sites, the most important styling goal is not novelty. It is readable pages, predictable navigation, accessible contrast, code blocks that scan well, and a visual system that can evolve without rewriting content.

Scoped component styles

Section titled “Scoped component styles”

Styles written inside an Astro component are scoped by default:

<section class="hero">
  <h1>Fast content sites</h1>
  <p>HTML first, interactivity when needed.</p>
</section>


<style>
  .hero {
    padding: 4rem 1rem;
  }


  .hero h1 {
    max-width: 12ch;
  }
</style>

The .hero styles apply to this component’s rendered markup instead of leaking across the whole site. This is useful for local layout, reusable cards, custom sections, and one-off page pieces.

Scoped styles are not a replacement for a design system. They are a way to keep component-specific rules near the component.

Global styles

Section titled “Global styles”

Global styles are better for rules that should affect the whole site:

  • design tokens
  • typography
  • resets
  • prose styling
  • theme variables
  • shared layout primitives
  • Starlight CSS custom properties

In Astro, global CSS is usually imported from a layout, a top-level page, or an integration config. In a Starlight site, customCss can load global CSS that customizes the docs UI.

Use global CSS intentionally. If a rule only exists for one component, keep it scoped.

CSS variables

Section titled “CSS variables”

CSS variables are a simple way to keep visual decisions consistent:

:root {
  --site-accent: #2563eb;
  --site-surface: #ffffff;
  --site-border: #d4d4d8;
  --site-radius: 8px;
}


.card {
  border: 1px solid var(--site-border);
  border-radius: var(--site-radius);
  background: var(--site-surface);
}

Tokens are especially useful for documentation because the same content appears across many page types: conceptual pages, tutorials, references, FAQ, and resources. The design can change without rewriting Markdown.

Styling Starlight

Section titled “Styling Starlight”

Starlight exposes CSS variables and extension points so you can customize the docs shell without rebuilding it from scratch. A minimal config looks like this:

import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';


export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs',
      customCss: ['./src/styles/custom.css'],
    }),
  ],
});

Use Starlight customization for the documentation experience: color tokens, typography, navigation surfaces, code blocks, and content width. Use custom Astro components when a page needs a special section or interactive surface.

Tailwind and other tools

Section titled “Tailwind and other tools”

Tailwind can work well in Astro, especially for product pages and teams that already use utility classes. It is not required for Astro and not required for Starlight.

Choose based on team workflow:

ApproachGood fit
Plain CSSSmall sites, docs, predictable styling, low tooling
Scoped stylesComponent-local layout and reusable UI
CSS variablesThemes, tokens, Starlight customization
TailwindTeams already using utility-first CSS
CSS modulesComponentized apps with class-name isolation preferences

Avoid mixing too many styling systems without a reason. A docs site with global tokens, scoped component styles, and a small custom CSS file is often easier to maintain than a stack of overlapping tools.

Current site pattern

Section titled “Current site pattern”

This site keeps content and URL structure unchanged while changing visual style through data-theme-pack on the <html> element. A style switcher stores the selected pack in localStorage, and CSS files under src/styles/themes/ define tokens for each pack.

That means style packs are presentations of the same document, not separate pages. Search engines see one URL; readers choose the interface they prefer.

When building a similar style system, keep these boundaries clear:

  • Content should not change when the style pack changes.
  • URLs should not multiply for visual variants.
  • Contrast must stay readable in every pack.
  • Code blocks, sidebars, and tables need explicit attention.
  • Motion and glow effects should never make long-form reading harder.

Common styling problems

Section titled “Common styling problems”
SymptomWhat to check
Component styles affect unrelated pagesRule is global when it should be scoped
Starlight colors do not changeWrong variable name or CSS file not loaded by customCss
Dark mode has unreadable textToken pair lacks contrast
Code blocks look detached from themeCode colors and surfaces were not customized together
Layout shifts between pagesComponents lack stable spacing or width rules

References

Section titled “References”