# Theming

Using CSS variables and theme tokens.

Source: https://webjs.dev/ui/docs/theming

Want to build your theme visually? Use [Create](https://webjs.dev/ui/create) to preview colors, radius, fonts, and icons, then generate a preset for your project.

We use CSS variables for theming.

This gives you semantic theme tokens like `background`, `foreground`, and `primary` that components use by default. Override those tokens in your CSS to change the look of your app without rewriting component classes.

```ts
<div class="bg-background text-foreground"></div>
```

`init` writes the tokens into the stylesheet named by `tailwind.css` in your `components.json` file, `styles/globals.css` by default.

```json title="components.json"
{
  "$schema": "https://ui.webjs.dev/schema.json",
  "style": "default",
  "tailwind": {
    "css": "styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  }
}
```

Tailwind maps these tokens into utilities like `bg-background`, `text-foreground`, `border-border`, and `ring-ring`.

Dark mode works by overriding the same tokens inside a `.dark` selector. See the [dark mode docs](https://webjs.dev/ui/docs/dark-mode) for setting and toggling the `.dark` class.

An app made with `webjs create` compiles `public/input.css`, which imports `styles/globals.css`, so the tokens there are the ones the page uses. The gallery's own palette and fonts are written into that theme block too, and nothing in `app/layout.ts` overrides it, so `init --preset` or an edit to the block repaints the app straight away.

## Token Convention

We use semantic background and foreground pairs. The base token controls the surface color and the `-foreground` token controls the text and icon color that sits on that surface.

The background suffix is omitted for the surface token. For example, `primary` pairs with `primary-foreground`.

Given the following CSS variables:

```css
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
```

The `background` color of the following component will be `var(--primary)` and the `foreground` color will be `var(--primary-foreground)`.

```ts
<div class="bg-primary text-primary-foreground">Hello</div>
```

## Theme Tokens

These tokens live in your CSS file under `:root` and `.dark`.

| Token | What it controls | Used by |
| --- | --- | --- |
| background / foreground | The default app background and text color. | The page shell, page sections, and default text. |
| card / card-foreground | Elevated surfaces and the content inside them. | `cardClass()`, dashboard panels, settings panels. |
| popover / popover-foreground | Floating surfaces and the content inside them. | Popover, `<ui-dropdown-menu>`, `<ui-context-menu>`, and other overlays. |
| primary / primary-foreground | High-emphasis actions and brand surfaces. | Default button, selected states, badges, and active accents. |
| secondary / secondary-foreground | Lower-emphasis filled actions and supporting surfaces. | Secondary buttons, secondary badges, and supporting UI. |
| muted / muted-foreground | Subtle surfaces and lower-emphasis content. | Descriptions, placeholders, empty states, helper text, and subdued surfaces. |
| accent / accent-foreground | Interactive hover, focus, and active surfaces. | Ghost buttons, menu highlight states, hovered rows, and selected items. |
| destructive / destructive-foreground | Destructive actions and error emphasis. | Destructive buttons, invalid states, and destructive menu items. |
| border | Default borders and separators. | Cards, menus, tables, separators, and layout dividers. |
| input | Form control borders and input surface treatment. | `inputClass()`, `textareaClass()`, `<ui-select>`, and outline-style controls. |
| ring | Focus rings and outlines. | Buttons, inputs, checkboxes, menus, and other focusable controls. |
| chart-1 ... chart-5 | The default chart palette. | Charts and chart-driven dashboard blocks. |
| sidebar / sidebar-foreground | The base sidebar surface and default sidebar text. | The `<ui-sidebar>` container and its default content. |
| sidebar-primary / sidebar-primary-foreground | High-emphasis actions inside the sidebar. | Active items, icon tiles, badges, and sidebar CTAs. |
| sidebar-accent / sidebar-accent-foreground | Hover and selected states inside the sidebar. | Sidebar menu hover states, open items, and interactive rows. |
| sidebar-border | Sidebar-specific borders and separators. | Sidebar headers, groups, and internal dividers. |
| sidebar-ring | Sidebar-specific focus rings. | Focused controls inside the sidebar. |
| radius | The base corner radius scale. | Cards, inputs, buttons, popovers, and the derived `radius-*` tokens. |

The kit's theme also defines `destructive-foreground`, the text color on a destructive surface.

The chart tokens are covered in more detail in the [Chart docs](https://webjs.dev/ui/docs/components/chart).

## Radius Scale

`--radius` is the base radius token for your theme.

We derive a small radius scale from it so components can use consistent corner sizes while still sharing a single source of truth.

```css title="styles/globals.css"
@theme inline {
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
}
```

This means:

- `radius-lg` is the base value.
- Smaller radii scale down from `--radius`.
- Larger radii scale up from `--radius`.
- Changing `--radius` updates the entire radius scale.

## Adding New Tokens

To add a new token, define it under `:root` and `.dark`, then expose it to Tailwind with `@theme inline`.

```css title="styles/globals.css"
:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}
```

You can now use `bg-warning` and `text-warning-foreground` in your components.

```ts
<div class="bg-warning text-warning-foreground"></div>
```

A registry item can carry tokens of its own as `cssVars`. When `add` installs it, it adds each token your `:root`, `.dark` or `@theme inline` block lacks and leaves the ones you already define alone. That is how the sidebar brings its `--sidebar-*` tokens to an app whose theme predates them.

## Base Colors

`tailwind.baseColor` controls the default token values generated for your project when you run `init`.

The available base colors are: **Neutral**, **Stone**, **Zinc**, **Mauve**, **Olive**, **Mist**, and **Taupe**.

```bash
npx @webjsdev/ui init --base-color zinc
```

`init` writes the theme once, between a `/* @webjsdev/ui theme */` and a `/* @webjsdev/ui theme end */` comment, and a later plain run leaves it alone, since the tokens are yours to edit. To switch the base color of an existing project, run `init --base-color <name> --overwrite`, which replaces the block in place (and also resets the aliases and helper files), or change the values by hand. A block without the end comment, written by an older version, is never replaced, only reported.

## Presets

To choose the style, the colors, the radius, the fonts and the icon library together, build a design system in [Create](https://webjs.dev/ui/create) and apply the code it prints. `init --preset` replaces the theme block with the preset's tokens and records the rest in `components.json`.

```bash
npx @webjsdev/ui init --preset <code>
```

## Default Theme CSS

The following is the full default `neutral` theme, exactly as `init` installs it. Copy it into your global CSS file and adjust the tokens as needed.

```css title="styles/globals.css"
/* @webjsdev/ui theme */
/* Generated by `webjsui init`. Edit freely - you own this. */

@theme inline {
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
}

/* Custom variants for component data attributes */
@custom-variant data-open (&:where([data-state="open"]));
@custom-variant data-closed (&:where([data-state="closed"]));
@custom-variant data-checked (&:where([data-state="checked"]));
@custom-variant data-unchecked (&:where([data-state="unchecked"]));
@custom-variant data-active (&:where([data-state="active"]));
@custom-variant data-disabled (&:where([data-disabled]:not([data-disabled="false"])));
@custom-variant data-selected (&:where([data-selected="true"]));
@custom-variant data-horizontal (&:where([data-orientation="horizontal"]));
@custom-variant data-vertical (&:where([data-orientation="vertical"]));
@custom-variant dark (&:is(.dark *));

@keyframes accordion-down {
  from { height: 0; }
  to { height: var(--accordion-panel-height, auto); }
}
@keyframes accordion-up {
  from { height: var(--accordion-panel-height, auto); }
  to { height: 0; }
}

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.97 0.01 17);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.81 0.10 252);
  --chart-2: oklch(0.62 0.19 260);
  --chart-3: oklch(0.55 0.22 263);
  --chart-4: oklch(0.49 0.22 264);
  --chart-5: oklch(0.42 0.18 265);
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.371 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --destructive-foreground: oklch(0.58 0.22 27);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
  --chart-1: oklch(0.81 0.10 252);
  --chart-2: oklch(0.62 0.19 260);
  --chart-3: oklch(0.55 0.22 263);
  --chart-4: oklch(0.49 0.22 264);
  --chart-5: oklch(0.42 0.18 265);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.439 0 0);
}

@layer base {
  /* Focus: a themed, keyboard-only (:focus-visible), never-removed outline, in
     the --ring colour, applied globally. `outline-ring/50` themes only the
     COLOUR and leaves outline-style: auto, which the browser draws as its OWN
     ring (it can look thick/white and ignore the colour). So force a SOLID
     outline on focus, at a consistent width + offset, so the themed --ring/50
     colour actually renders the same on every element. A shadow-DOM component
     sets its own focus (a document rule cannot cross the shadow boundary). */
  * {
    @apply border-border outline-ring/50;
  }
  :focus-visible {
    outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
    outline-offset: 2px;
  }
  /* Native <select> options paint transparent over the browser popup when no
     rule applies, so in dark mode Chrome's dark popup plus the inherited text
     colour makes every unselected option disappear. Canvas / CanvasText are
     the system colours the browser would have painted anyway, so this stops
     relying on inheritance to pull them through. Two ELEMENT selectors
     (specificity 0,0,2) and no wrapper requirement on purpose: a bare
     <select class=${nativeSelectClass()}> with no wrapper is legitimate, and
     any single class overrides this. */
  select option,
  select optgroup {
    background-color: Canvas;
    color: CanvasText;
  }
}

/* @webjsdev/ui theme end */
```

The file you compile also needs Tailwind itself, imported first:

```css
@import "tailwindcss";
```

## Without CSS Variables

Every component's classes name the theme tokens (`bg-primary`, `text-muted-foreground`), so the tokens are the one place a color is decided, and changing them is how you restyle the kit. `tailwind.cssVariables` is accepted in `components.json` for compatibility, and `init` always writes `true`.
