> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cskn.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Theming

> Recolor and restyle the kit with design tokens.

Every themed component is styled from tokens. Override the ones that matter for your brand and leave the rest on the neutral defaults.

```tsx theme={null}
<UIProvider
  theme={{
    colors: {
      light: { primary: '#1F6F4B', bg: '#EFE9DD', text: '#1a1a1a' },
      dark: { primary: '#4ade80', bg: '#0b0b0d' },
    },
    radius: { md: '4px' },
    font: { sans: '"Instrument Serif", Georgia, serif' },
  }}
>
```

Light and dark colors are set separately. With `colorScheme="system"` the provider follows the OS preference.

## Tokens

### Colors

Each of `colors.light` and `colors.dark` has:

| Token | Used for |
| - | - |
| `bg` | Page background |
| `surface` | Raised surfaces: cards, inputs, sheets |
| `surfaceAlt` | Secondary surface: hover, subtle fills |
| `text` | Body text |
| `textMuted` | Labels, captions |
| `textFaint` | Placeholders, disabled text |
| `border` | Hairlines and dividers |
| `borderStrong` | Focused fields, active outlines |
| `primary` / `primaryText` | Brand fill and the text on it |
| `danger` / `dangerText` | Destructive fill and the text on it |
| `success` | Positive accent |
| `ring` | Focus ring, also the TV focus highlight |
| `overlay` | Scrim behind modals and sheets |

### Everything else

| Token | Default |
| - | - |
| `radius.sm / md / lg / xl / pill` | `6px` / `10px` / `16px` / `24px` / `999px` |
| `font.sans` | The system UI stack |
| `font.mono` | The system monospace stack |
| `font.display` | Headlines; falls back to `font.sans` |
| `control.height / heightSm / heightLg` | `44px` / `34px` / `54px` |
| `ring.width / offset` | `3` / `2` (px) |
| `shadow.sm / md / lg` | Soft drop shadows |
| `spaceUnit` | `4` (px) |

## Using tokens in your own styles

Tokens are CSS variables, so your own components can follow the theme:

```tsx theme={null}
import { color } from '@cskn/ui';

<div style={{ background: color('surface'), color: color('text') }} />
<div style={{ borderColor: 'var(--cskn-color-border)', borderRadius: 'var(--cskn-radius-md)' }} />
```

| Variable | Token |
| - | - |
| `--cskn-color-<name>` | Every color above |
| `--cskn-radius-sm` … `--cskn-radius-pill` | Radii |
| `--cskn-font-sans`, `--cskn-font-mono`, `--cskn-font-display` | Fonts |
| `--cskn-control-h`, `--cskn-control-h-sm`, `--cskn-control-h-lg` | Control heights |
| `--cskn-ring-width`, `--cskn-ring-offset` | Focus ring |
| `--cskn-shadow-sm` … `--cskn-shadow-lg` | Shadows |
| `--cskn-space` | Spacing unit |
| `--cskn-series-1` … `--cskn-series-8` | Chart palette |

`useTheme()` returns the resolved values in JavaScript.

## Building a theme editor

The tokens are introspectable, so an editor can generate its controls and feed the result straight back for a live preview:

```tsx theme={null}
import { tokenManifest, getTokenValue, themeFromEntries, defaultTheme, UIProvider } from '@cskn/ui';

const edits: Record<string, string | number> = {};

tokenManifest.forEach((token) => {
  // token.path: 'colors.dark.primary'; token.type: 'color' | 'length' | 'number' | 'font'
  renderControl(token, getTokenValue(defaultTheme, token.path));
});

<UIProvider theme={themeFromEntries(edits)}>{preview}</UIProvider>
```

Other helpers: `mergeTheme(base, override)` and `themeToCss(theme, scope?)`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.