CSS and theme reference

The built site loads /assets/site.css, which imports /assets/tokens.css. To customize a project, set site.customCss to a local stylesheet. The build copies it to /assets/project.css and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.

site:
  title: Example documentation
  customCss: ./styles/project.css

:root {
  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
  --color-accent: #2458a6;
  --color-link: #2458a6;
  --width-site: 92rem;
}
.page-head h1 { letter-spacing: -.02em; }

Pages link these stylesheets in order, and later files win: /assets/site.css (which imports tokens.css and header.css), a preset's /assets/theme.css, the generated /assets/palette.css, the generated /assets/fonts.css, then /assets/project.css. Themes lists when each one is present.

To use your own font files, set theme.fonts instead of writing @font-face rules here. The build then copies the files, preloads the body font, and sets --font-body, --font-heading, and --font-code for you.

Use tokens for broad changes and the generated classes below for a particular region. The project stylesheet is copied as one file; relative images or @import files are not copied automatically. Use site-root URLs for separately hosted assets. Markdown twins contain content, not CSS.

Before writing CSS, check whether a theme preset, palette, or color mode already covers the change. Project CSS loads after all three, so the tokens below override them. The build checks palette colors for contrast. It does not check colors set here.

Inline badges use --color-field-surface, --color-ink, and --color-border for neutral; info, success, warning, and new use the matching callout note, tip, warning, and important tokens. Register a color in badges.variants to add or override a variant with checked light and dark text contrast. The generated /assets/badges.css loads after palette CSS and before project CSS.

Typography, shape, and width tokens

Use these tokens to adjust text, corner shapes, and content widths.

Each preset's font stack starts with its bundled font, followed by a matching fallback face named after it, such as "Inter Fallback". The fallback is a local system font resized to the bundled font's metrics, so text keeps its place while the font loads. fonts.css defines these faces; with theme.fonts: system, the build omits them and the stacks fall through to system fonts.

The root text size is 16px and line height is 1.65 in site.css. Override :root in the project stylesheet if the whole site needs different type scale. Article paragraphs, headings, and code blocks also have local sizes that can be overridden by their selectors.

Core color tokens

These tokens control the main surface, text, and accent colors.

Borders, fields, and navigation tokens

These tokens control boundaries, input fields, and navigation states.

Status, code, and callout tokens

Use these tokens to style status messages, code examples, and callouts.

Preset-specific tokens

Some presets define extra tokens in their own stylesheet. They apply only when that preset is active:

The default site code theme colors code text with --code-foreground and tokens with --code-token-keyword, --code-token-string, --code-token-string-expression, --code-token-constant, --code-token-function, --code-token-parameter, --code-token-link, --code-token-comment, and --code-token-punctuation. Palettes set the token colors from their dark set; --code-foreground and the comment and punctuation colors follow --color-code-text and --color-code-muted. Project CSS can override any of them. A named Shiki theme puts its colors directly on highlighted tokens instead. A light Shiki theme also sets the code block background; a dark theme leaves it to --color-code-block. To change those colors, set outputs.html.highlighting.theme to another bundled theme or use a custom highlighting adapter. The code highlighting guide documents those settings.

Layout and component selectors

Use these selectors when a change needs to target a specific region or component state.

The navigation filter appears when JavaScript runs; without it, the navigation tree still works. Tabs use .is-enhanced after their script adds selection behavior. Walkthroughs use .is-split when their script shows the code pane. The default --walkthrough-dim, 0.84, keeps 4.5:1 contrast in every built-in palette. The CSS includes focus-visible styles, forced-color adjustments, reduced-motion handling, and print rules. Keep those states usable when overriding component styles.

Page attributes

The html element carries attributes that project CSS can use to target one theme, mode, or layout:

shoal is the default preset, so a default site has no data-theme. To target shoal either way, use :root:is(:not([data-theme]), [data-theme="shoal"]):

:root:is(:not([data-theme]), [data-theme="shoal"]) .mast { border-top-color: #7c3aed; }
[data-masthead="inked"] .brand { letter-spacing: .12em; }
[data-layout="landing"] .content .hero { min-height: 28rem; }

Responsive behavior

Above 72rem, every page reserves the same right column so the article stays in place when moving between pages with and without a ToC. A ToC appears there as a sticky outline, and the API data panel shares that rail. At 72rem and below, the rail moves below the article column. At 48rem and below, the navigation and the outline become two compact buttons, Menu and On this page, side by side above the article. Each opens to the full width, and both start closed so the page title is on the first screen. The page's tocDepth frontmatter controls which headings appear in the outline, and 0 hides it. See the frontmatter guide for examples.

As the reader scrolls, the outline marks the current section with aria-current="location". Style it with .page-toc a[aria-current].

The reader script adds a link icon beside each article heading from level two to four. Selecting it copies the section URL and puts it in the address bar. Without clipboard access, the icon works as an ordinary link. The icon isn't part of the page source, so it doesn't appear in Markdown twins or search results.

Page transitions

In browsers that support cross-document view transitions, the reading column fades between pages while the masthead and sidebar stay in place. Other browsers load pages as usual. The fade is off when the reader's system asks for reduced motion. To turn it off for every reader, add this rule to project CSS:

@view-transition { navigation: none; }

The publication label adjusts automatically. A single channel, version, and language leaves the top-right spot empty. When one dimension varies, only that dimension appears. Set site.editionBadge: always to show all three values or site.editionBadge: never to hide the label. auto is the default.