# ShellDocs.Tokens

> The design-system CSS variables. shadcn-compatible names, drop-in interop with ShellUI and any Tailwind-shaped design system.

Source: https://shelldocs.shellui.dev/docs/packages/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 CLI**

```bash
dotnet add package ShellDocs.Tokens --prerelease
```

**PackageReference**

```xml
<PackageReference Include="ShellDocs.Tokens" Version="0.1.17-alpha" />
```

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:

| Name | 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. |
| `--font-mono` | `stack` |  | Monospace stack for code + inline code. |

## 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](https://shelldocs.shellui.dev/docs/getting-started/configuration.md): Setting your brand palette on top of the tokens.
- [ShellDocs.Components](https://shelldocs.shellui.dev/docs/packages/components.md): What consumes these tokens.