ShellDocs.Tokens

ShellDocs.Tokens is a Razor Class Library that ships a single CSS file (tokens.css) declaring the palette + spacing scale the entire framework consumes. Split out so ShellUI (and any third-party design system) can share the same tokens without depending on the full ShellDocs.Components RCL.

Why it's separate

Design-system interoperability is a real concern in the .NET ecosystem : MudBlazor, Radzen, shadcn/ui-style component libraries all want to agree on --primary and --background. Isolating the tokens into their own package means a consumer can adopt ShellDocs' design language even if they don't want the full framework.

Install

dotnet add package ShellDocs.Tokens --prerelease

Then reference the CSS in your App.razor:

html 
<link rel="stylesheet" href="_content/ShellDocs.Tokens/tokens.css" />

shelldocs init does this automatically.

What's inside

Two :root blocks : one for light mode, one for :root.dark. All the essentials, plus semantic aliases:

Prop Type Default Description
--background oklch — Page background.
--foreground oklch — Primary text color.
--card oklch — Card / elevated surface background.
--card-foreground oklch — Text on card surfaces.
--muted oklch — Subtle background (hover states, tags, code blocks).
--muted-foreground oklch — Muted text (secondary, hints, timestamps).
--primary oklch — Brand accent : links, primary buttons, highlights.
--primary-foreground oklch — Text on primary surfaces.
--border oklch — Default border color.
--accent oklch — Secondary accent : badges, chips, focus rings.
--destructive oklch — Danger : error states, delete buttons.
--radius rem — Base border-radius. Chrome uses `calc(var(--radius) + N)` for varied roundness.
--font-sans stack — Sans-serif stack for prose + UI.

Overriding tokens

Tokens are CSS custom properties : override anywhere with normal CSS specificity.

css 
:root {
    --primary: oklch(0.6 0.2 20);
    --radius: 0.5rem;
}

:root.dark {
    --primary: oklch(0.7 0.18 20);
}

Because every component uses var(--primary) etc. by name, that one override retints buttons, links, focus rings, TOC bars, sidebar highlights : everything : in both light and dark modes.

Dark mode

Toggled via a .dark class on the <html> element. ShellDocs.Components' ThemeToggle handles the flip + persists to localStorage. Your App.razor includes a small bootstrap script that reads the saved preference before Blazor hydrates:

html 
<script>
    (function () {
        var saved = null;
        try { saved = localStorage.getItem('shelldocs-theme'); } catch (e) {}
        var systemDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
        if ((saved || (systemDark ? 'dark' : 'light')) === 'dark') {
            document.documentElement.classList.add('dark');
        }
    })();
</script>

shelldocs init injects this automatically.

Interoperability with ShellUI

If your ShellUI components install via Tailwind (the current recommended path), ShellUI's Tailwind config reads the same --primary / --background / --border tokens. Nothing to configure : <ShellUI.Button> mid-markdown picks up your ShellDocs palette automatically.

Learn more

Configuration
Setting your brand palette on top of the tokens.
ShellDocs.Components
What consumes these tokens.