CSS Customization

The Pagesmith visual layer is built on CSS custom properties, making it straightforward to adjust colors, typography, spacing, and code block styling without modifying source files. This reference covers the design token system, import paths, and techniques for overriding the default theme.

Tip

AI quick-start: Tell your AI agent “change the accent color to blue” or “customize the font to Inter” and it will generate the correct CSS overrides using the design token system.

Design Tokens

All visual tokens are defined as CSS custom properties on :root in the core package’s token file. The default theme and all built-in styles reference these properties.

Color Tokens

Colors use the light-dark() function, so they automatically adapt to the user’s system preference. The color-scheme: light dark declaration on :root enables this behavior.

1:root {2  color-scheme: light dark;34  /* Backgrounds */5  --color-bg: light-dark(#f5f4f0, #111110);6  --color-bg-alt: light-dark(#efefeb, #1a1a18);7  --color-bg-elevated: light-dark(#f5f4f0, #1e1e1c);8  --color-bg-code: light-dark(#efefeb, #1a1a18);9  --color-bg-hover: light-dark(#efefeb, #222220);1011  /* Text */12  --color-text: light-dark(#111110, #f5f4f0);13  --color-text-secondary: light-dark(#333330, #ccccca);14  --color-text-muted: light-dark(#7a7a72, #888882);1516  /* Borders */17  --color-border: light-dark(#d0cfc9, #2a2a28);18  --color-border-subtle: light-dark(#e5e4de, #222220);19  --color-border-hover: light-dark(#c0bfb9, #3a3a38);2021  /* Accent (links, highlights) */22  --color-accent: light-dark(#d4381e, #e04a2e);23  --color-accent-hover: light-dark(#b82e16, #f05a3e);24  --color-accent-subtle: light-dark(rgba(212, 56, 30, 0.06), rgba(224, 74, 46, 0.08));2526  /* Code */27  --color-code-bg: light-dark(#efefeb, #1a1a18);28  --color-code-text: light-dark(#333330, #ccccca);2930  /* Blockquotes */31  --color-blockquote-border: light-dark(#d0cfc9, #333330);32  --color-blockquote-bg: light-dark(#efefeb, #1a1a18);3334  /* UI overlays */35  --color-overlay-bg: light-dark(rgba(0, 0, 0, 0.3), rgba(0, 0, 0, 0.5));36  --color-header-bg: light-dark(rgba(245, 244, 240, 0.85), rgba(17, 17, 16, 0.85));37  --color-text-inverse: light-dark(#f5f4f0, #111110);38}

Shadow Tokens

1:root {2  --shadow-color: light-dark(rgba(0, 0, 0, 0.04), rgba(0, 0, 0, 0.2));3  --shadow-color-md: light-dark(rgba(0, 0, 0, 0.04), rgba(0, 0, 0, 0.25));4  --shadow-color-lg: light-dark(rgba(0, 0, 0, 0.06), rgba(0, 0, 0, 0.3));5  --shadow-sm: 0 1px 2px var(--shadow-color);6  --shadow-md: 0 4px 6px var(--shadow-color-md);7  --shadow-lg: 0 10px 25px var(--shadow-color-lg);8}

Typography Tokens

1:root {2  /* Font families */3  --font-sans: "Open Sans", system-ui, -apple-system, "Segoe UI", sans-serif;4  --font-mono: "JetBrains Mono", "Fira Code", Menlo, Consolas, monospace;56  /* Font sizes */7  --font-size-xs: 0.75rem;8  --font-size-sm: 0.875rem;9  --font-size-base: 1rem;10  --font-size-lg: 1.125rem;11  --font-size-xl: 1.25rem;12  --font-size-2xl: 1.5rem;13  --font-size-3xl: 2rem;14}

Spacing and Layout Tokens

1:root {2  --radius-sm: 2px;3  --radius-md: 4px;4  --radius-lg: 6px;5  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);6  --transition-normal: 250ms cubic-bezier(0.4, 0, 0.2, 1);7  --header-height: 60px;8}

CSS Import Paths

@pagesmith/site exposes several CSS entry points through its package exports map. These are used directly by @pagesmith/docs but can also be imported in custom sites built on @pagesmith/site’s app-facing surface.

Import Path	Contents
`@pagesmith/site/css/content`	Prose typography, inline code, viewport base, reset
`@pagesmith/site/css/standalone`	Full standalone bundle: reset + prose + code + layout + TOC
`@pagesmith/site/css/viewport`	Responsive viewport base only
`@pagesmith/site/css/fonts`	Bundled Open Sans and JetBrains Mono font-face declarations

In a Vite-based project, import these directly in your CSS:

1@import "@pagesmith/site/css/content";2@import "@pagesmith/site/css/fonts";

Or in JavaScript/TypeScript:

1import "@pagesmith/site/css/content";2import "@pagesmith/site/css/fonts";

Overriding Theme Styles

Adding Custom CSS

For @pagesmith/docs sites, the recommended approach is to create a custom CSS file and import it in a layout override. Since the docs theme compiles its own stylesheet, direct injection requires a layout override that adds your stylesheet to the HTML head.

For sites built on @pagesmith/site, add your overrides after the Pagesmith imports:

1@import "@pagesmith/site/css/content";23/* Override accent color */4:root {5  --color-accent: light-dark(#2563eb, #60a5fa);6  --color-accent-hover: light-dark(#1d4ed8, #93c5fd);7}

Specificity Tips

The design token system is intentionally flat — most styles reference custom properties rather than deeply nested selectors. To override effectively:

Change a token value: Redefine the custom property on :root. This propagates everywhere.
Change one component: Target the specific element class. The default theme uses BEM-style class names.
Avoid !important: Redefining the custom property is almost always sufficient.

1/* Change just the sidebar background */2.sidebar {3  --color-bg-alt: light-dark(#ffffff, #0a0a0a);4}56/* Change prose link color without affecting navigation */7.prose a {8  --color-accent: light-dark(#0969da, #58a6ff);9}

Theme Colors in Config

The theme.lightColor and theme.darkColor config fields control the <meta name="theme-color"> tag, which affects browser chrome (address bar color) on mobile devices. These do not change CSS custom properties:

1{2  theme: {3    lightColor: "#ffffff",4    darkColor: "#0a0a0a",5  },6}

Color Schemes and Themes

Pagesmith uses a class-based multi-theme system with two orthogonal axes on <html>:

Color scheme (color-scheme-auto | color-scheme-light | color-scheme-dark) — controls which side of light-dark() the browser picks
Theme variant (theme-paper | theme-high-contrast) — overrides design tokens for distinct visual styles

How The Customization Layers Fit Together

Notice that most visual changes flow through CSS custom properties: color-scheme classes choose the light-dark() branch, theme variants and your own overrides adjust token values, and theme.lightColor / theme.darkColor stay separate as browser-chrome metadata.

CSS customization layers showing base tokens and root overrides feeding resolved custom properties, which drive the shipped Pagesmith CSS bundles and final UI, while theme-color config only affects browser chrome

The @pagesmith/docs theme includes built-in UI for switching both axes (header dropdown + footer selector), with preferences persisted to localStorage. See the Theming reference for the full system, built-in themes, and how to create custom theme variants.

How light-dark() Works

The light-dark() function takes two values: the first for light mode, the second for dark mode. The browser selects the appropriate value based on the color-scheme property:

1/* light-dark(light-value, dark-value) */2--color-bg: light-dark(#f5f4f0, #111110);

Overriding Per-Scheme Colors

To change colors for only one scheme, redefine the token with a new light-dark() value:

1:root {2  /* Change background in dark mode only, keep light mode default */3  --color-bg: light-dark(#f5f4f0, #0d1117);4}

Forcing a Single Scheme

To force light-only or dark-only mode, use the color scheme class or CSS:

1:root {2  color-scheme: light; /* Force light mode */3}

This causes all light-dark() functions to use their first argument. Alternatively, use theme.defaultColorScheme: 'light' in pagesmith.config.json5 for @pagesmith/docs sites, or set the color-scheme-light class on <html> for core sites.

Code Block Styling

Syntax-highlighted code blocks are rendered by the built-in Pagesmith renderer during markdown processing. Shared code block chrome comes from the shipped Pagesmith CSS bundles, while Shiki token colors are injected into the HTML output and the shared Pagesmith content runtime wires copy/collapse behavior in the browser.

Default Themes

The default syntax highlighting themes are github-light and github-dark. Pagesmith maps them to the site’s color-scheme classes so code blocks follow the same light/dark toggle as the rest of the UI.

Configure different themes in your config:

1{2  markdown: {3    shiki: {4      themes: {5        light: "github-light",6        dark: "github-dark-dimmed",7      },8    },9  },10}

Any theme supported by Shiki is available. Popular options include one-dark-pro, dracula, nord, catppuccin-latte, and catppuccin-mocha.

Code Block Font and Size

The built-in renderer and shared code block styles read CSS custom properties for font settings and chrome:

1/* These properties are consumed by the Pagesmith code block styles */2--ps-font-sans    → UI elements (file titles, line numbers)3--ps-font-mono    → Code text4--ps-font-size-sm → Code font size (default: 0.875rem)

The default code block chrome uses these variables:

CSS Variable	Used For
`--ps-font-sans`	Toolbar labels, line numbers, copy/collapse controls
`--ps-font-mono`	Code text
`--ps-font-size-sm`	Code text and toolbar sizing
`--ps-radius-lg`	Code block border radius
`--ps-color-border-subtle`	Borders and subtle chrome accents

To adjust code block appearance, define the --ps-* custom properties:

1:root {2  --ps-font-mono: "Fira Code", monospace;3  --ps-font-size-sm: 0.8rem;4  --ps-radius-lg: 8px;5}

Inline Code

Inline code (backtick-delimited) is styled by the core CSS, not the code block renderer. Override inline code appearance through the standard custom properties:

1:root {2  --color-code-bg: light-dark(#f0f0f0, #1a1a2e);3  --color-code-text: light-dark(#333333, #e0e0e0);4}

Typography Customization

Changing the Body Font

Override --font-sans to change the body text font. If using a custom font, load it via @font-face or a CSS import:

1@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");23:root {4  --font-sans: "Inter", system-ui, sans-serif;5}

Changing the Code Font

Override --font-mono for both inline code and code blocks (via the --ps-font-mono alias):

1:root {2  --font-mono: "Fira Code", "Cascadia Code", monospace;3  --ps-font-mono: var(--font-mono);4}

Font Size Scale

The type scale uses rem units anchored to the browser’s base font size (typically 16px). Override individual steps:

1:root {2  --font-size-base: 1.0625rem; /* 17px */3  --font-size-sm: 0.9375rem; /* 15px */4  --font-size-lg: 1.1875rem; /* 19px */5}

CSS Architecture

The docs theme CSS is organized as follows:

1main.css2  foundations/3    reset.css           → CSS reset (box-sizing, margins)4    color-scheme.css    → Color scheme classes (auto/light/dark)5    fonts.css           → @font-face for bundled fonts6    tokens.css          → Design tokens (custom properties)7    themes.css          → Theme variant overrides (paper, high-contrast)8  content/9    prose.css           → Prose typography (headings, paragraphs, lists, tables)10    toc.css             → Table of contents sidebar styles11    alerts.css          → GitHub-flavored alert boxes12    page-meta.css       → Last updated, edit link, breadcrumbs13  code/14    inline.css          → Inline code styling (backtick code)15  layout/16    grid.css            → Page grid (header, sidebar, content, TOC)17    header.css          → Site header and navigation18    sidebar.css         → Sidebar navigation19    footer.css          → Page footer20    home.css            → Home page hero and features21  components/22    search.css          → Search modal styles23    theme-toggle.css    → Header dropdown and footer theme selector24    not-found.css       → 404 page styles

The full theme CSS is bundled and minified by LightningCSS during pagesmith-docs build, producing a single assets/style.css file in the output directory. LightningCSS handles vendor prefixing, nesting compilation, and minification targeting Chrome 100+, Firefox 100+, and Safari 16+.