Guide menu

Basic settings

Theme usage

This guide is for the team editing the site — not for end visitors.

For visitors

The sun/moon icon in the header toggles light and dark mode. The choice is saved in the browser (localStorage) and remembered on the next visit. If the visitor has not chosen yet, the site follows their system preference (light or dark).

CSS layers (Astro)

Styles are split so public pages do not load guide-only CSS. Astro bundles by import tree — what a layout imports is what the browser loads.

  • src/styles/core.css — theme tokens (:root / .dark), .section-container, motion FOUC, tw-animate-css. Imported in BaseLayout (every public page).
  • src/styles/site.css — imports core.css first, then Tailwind (@source for site paths only). Imported in BaseLayout.
  • src/styles/docs.css — Tailwind for guide components and pages. Imported in DocsLayout and DocsArticle (guide routes only).
  • New site section styles → Tailwind classes in the component; extend @source in site.css if needed. Guide-only styles → docs.css or docs components.

Changing brand colors

All theme colors live in src/styles/core.css. Light mode uses the :root block; dark mode uses the .dark block. Each variable (e.g. --background, --primary) maps to Tailwind tokens such as bg-background and text-primary.

When building new sections or components, use these tokens — do not hardcode hex colors like #ffffff or text-black.

  • Primary button: bg-primary text-primary-foreground
  • Page background: bg-background text-foreground
  • Muted text: text-muted-foreground

Logos

In src/config/site.ts set logo (light theme) and logoDark (dark theme). The header shows the correct file automatically.

Technical reference

Toggle component: src/components/header/ThemeToggle.tsx. To avoid a flash of the wrong theme on first load, BaseLayout runs a small inline script before the page paints.