CSS overrides

When the theme config is not enough, write CSS. The stylesheet is built so that plain, unlayered CSS from your app always wins, and every rendered element carries a stable pd-* class and a small set of state attributes you can rely on.

Cascade layers#

pzzadocs/styles.css wraps all of its rules in three cascade layers, declared in this order:

@layer pzzadocs.base, pzzadocs.components, pzzadocs.utilities;

Layered rules always lose to unlayered rules, regardless of specificity. That means a one-class selector in your globals.css overrides anything the framework ships without !important and without matching its selectors. Import the framework stylesheet first so the layer order is established before your own CSS runs:

import "pzzadocs/styles.css";
import "./globals.css";

If your own styles also use layers, declare them after pzzadocs.* or keep the overrides unlayered.

Token overrides#

The theme config and a global stylesheet reach the same custom properties. Here is the stylesheet default for two tokens, and the same tokens overridden from app/globals.css:

:root {
  --pd-foreground: #111111;
  --pd-border: #e4e4e4;
}

.dark {
  --pd-foreground: #ececec;
  --pd-border: #242424;
}

:root {
  --pd-foreground: #000000;
  --pd-border: #dddddd;
  --pd-radius: 6px;
  --pd-content-width: 80ch;
}

.dark {
  --pd-foreground: #ffffff;
  --pd-border: #2a2a2a;
}

Keep light values on :root and dark values under .dark (the framework also recognises [data-theme="dark"], see Dark mode). The full token list with defaults is in the design tokens reference.

The identical override through the config looks like this:

theme: {
  radius: 6,
  layout: { contentWidth: "80ch" },
  colors: {
    light: { foreground: "#000000", border: "#dddddd" },
    dark: { foreground: "#ffffff", border: "#2a2a2a" },
  },
}

When to use which#

• Use theme in the config when PzzaDocs is the only consumer of the values. Everything about the site lives in one typed object, the tokens are emitted by ThemeStyles on the server, and you get autocomplete for every key.
• Use globals.css when the values already exist in your design system (for example --pd-foreground: var(--color-text)), when you need media queries or container queries around a token, or when you are overriding non-token rules anyway and want the overrides in one place.

Both can be combined. A globals.css declaration on :root and the ThemeStyles declaration on :root have the same specificity, so the one that appears later in the document wins; ThemeStyles is rendered inside <body>, after your linked stylesheets, so config values win over globals.css for the same token.

Class reference#

Class names are part of the public styling API and only change in a major release. Combine them with the state attributes below to target a specific state.

Layout#

Sidebar#

Page#

Components#

State attributes#

.pd-sidebar-item[data-active] {
  font-weight: 600;
}

.pd-callout[data-type="warn"] {
  border-left: 2px solid var(--pd-border-strong);
}

.pd-tab-trigger[data-state="active"] {
  color: var(--pd-foreground);
}

Custom chrome#

For changes that CSS alone cannot express, the layout components accept extra classes and slots:

• DocsLayout takes tree, config, children, and optionally className, sidebarFooter (rendered under the sidebar tree), sidebarBanner (rendered above it), headerStart, headerEnd, and labels (translated UI strings, see Localization).
• Header takes config, and optionally tree, transparentMode, icons, className, start (rendered after the nav tabs) and end (rendered before the search trigger).
• Sidebar, TOC and DocsPage accept className. DocsPage also takes locale (date format of the footer timestamp) and labels.
• RootProvider takes theme, search, and labels.

The footer attribution line is part of the framework and is always rendered.