Custom CSS

Holocron includes Tailwind CSS automatically. You can add your own styles on top.

How to load your CSS

Default Holocron site

Create style.css at your project root. Holocron auto-detects the first matching file and imports it after its own styles.

my-docs/
├── docs.json
├── style.css
└── index.mdx

With custom entry and another filename

If you use a custom entry and your CSS file has a different name, import it in your server file:

12// src/server.tsx
import './style.css'

Dark mode overrides

Use @variant dark inside your CSS instead of Tailwind's dark: utility classes:

12345678910111213/* style.css */
@reference "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

:root {
  --card: #ffffff;
  --card-foreground: #0a0a0a;

  @variant dark {
    --card: #1a1a1a;
    --card-foreground: #fafafa;
  }
}

This keeps dark mode values colocated with their light mode counterparts in CSS variables. Holocron toggles dark mode with the .dark class on <html>, so any CSS file using @variant dark must define the same @custom-variant dark directive.

Responsive overrides

You can also change variables by breakpoint:

12345678/* style.css */
:root {
  --bleed: 16px;

  @variant lg {
    --bleed: 32px;
  }
}

Do not import Tailwind again

Holocron already adds @import 'tailwindcss' internally. If your CSS also imports it, you get duplicate style layers that break layout and cascade order.

Instead, use @reference to access Tailwind's theme variables, @apply, and @variant without emitting duplicate styles:

12345678910111213/* style.css */
@reference "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

:root {
  --primary: #e11d48;
  --background: #fafafa;

  @variant dark {
    --background: #0a0a0a;
    --primary: #fb7185;
  }
}

Best practices

Prefer CSS variables over class selectors. Holocron exposes CSS variables for colors, typography, spacing, code blocks, and layout. Override these in :root for clean, stable customization that survives Holocron updates. See Theme for the full list.

123456/* Stable — uses documented CSS variables */
:root {
  --code-block-background: var(--muted);
  --code-block-border: 1px solid var(--border-subtle);
  --weight-heading: 700;
}

Avoid targeting internal class names and DOM structure. Selectors like .slot-sidebar-left nav > div:first-child > a or figure[class~='group/code'] button[aria-label='Copy code'] are coupled to Holocron's internal markup. These will break when Holocron refactors its components; there is no stability guarantee for internal class names, DOM nesting, or aria labels.

If you do need a class-based override as a last resort, keep it isolated and add a comment noting it may break on upgrade:

1234/* FRAGILE: targets internal sidebar DOM, may break on Holocron updates */
.slot-sidebar-left nav a {
  border-radius: var(--radius-sm);
}