# Theming

Starwind components use semantic CSS variables from `src/styles/starwind.css`. Change those
variables to update the application theme without editing every component.

The stylesheet maps variables such as `--background` and `--primary` to Tailwind utilities such as
`bg-background` and `text-primary`. Dark mode overrides the same variables inside `.dark`.

## Customize Your Theme

Edit values under `:root` for the default theme and `.dark` for dark mode. This example changes the
primary color while keeping readable foreground and accent colors.

```css title="src/styles/starwind.css"
:root {
  --primary: var(--color-violet-700);
  --primary-foreground: var(--color-white);
  --primary-accent: var(--color-violet-800);
}

.dark {
  --primary: var(--color-violet-500);
  --primary-foreground: var(--color-neutral-950);
  --primary-accent: var(--color-violet-300);
}
```

Components that use the primary tokens update automatically. You can also use the mapped utilities
in application code:

```html
<div class="bg-primary text-primary-foreground">Primary surface</div>
```

## Token Convention

Most surface tokens use a background and foreground pair. The base token controls the surface. The
`-foreground` token controls text and icons placed on it. The surface token omits the
`-background` suffix, so `primary` pairs with `primary-foreground`.

## Theme Tokens

| Token | What it controls |
| --- | --- |
| `background` / `foreground` | The page background and default text. |
| `card` / `card-foreground` | Cards and their content. |
| `popover` / `popover-foreground` | Selects, menus, tooltips, and other floating content. |
| `primary` / `primary-foreground` | Primary actions and high-emphasis surfaces. |
| `primary-accent` | Primary text, links, and accents that need contrast on the page background. |
| `secondary` / `secondary-foreground` | Secondary actions and supporting surfaces. |
| `secondary-accent` | Secondary text and accents that need contrast on the page background. |
| `muted` / `muted-foreground` | Subtle surfaces, descriptions, and placeholders. |
| `accent` / `accent-foreground` | Hovered, focused, and selected surfaces. |
| `info` / `info-foreground` | Informational component variants. |
| `success` / `success-foreground` | Successful component variants. |
| `warning` / `warning-foreground` | Warning component variants. |
| `error` / `error-foreground` | Error and destructive component variants. |
| `border` | Default borders and separators. |
| `input` | Form-control borders. |
| `outline` | Focus outlines and rings. |
| `radius` | The base value for the generated corner-radius scale. |

The installed stylesheet also defines Sidebar-specific tokens. See the
[Sidebar component](/docs/components/sidebar/#theming) when you need to customize that surface.

## Add Another Color Theme

Create a class that overrides the tokens you want to change. Add a custom variant only when you
also want to use utilities such as `brand:bg-primary`.

```css title="src/styles/starwind.css"
@custom-variant brand (&:where(.brand, .brand *));

.brand {
  --primary: var(--color-fuchsia-700);
  --primary-foreground: var(--color-white);
  --primary-accent: var(--color-fuchsia-800);
  --secondary: var(--color-fuchsia-100);
  --secondary-foreground: var(--color-fuchsia-950);
}
```

Apply the class to the region that should use the theme:

```html
<section class="brand">
  <!-- Starwind components in this section inherit the overrides. -->
</section>
```

## Add a Theme Token

Define the light and dark values, then map the variable inside `@theme inline` so Tailwind creates
the matching utilities.

```css title="src/styles/starwind.css"
@theme inline {
  --color-canvas: var(--canvas);
}

:root {
  --canvas: oklch(0.967 0.003 264.542);
}

.dark {
  --canvas: oklch(0.21 0.034 264.665);
}
```

You can now use utilities such as `bg-canvas`, `text-canvas`, and `border-canvas` where their CSS
properties accept a color.

## Related Guides

- [Dark Mode](/docs/getting-started/dark-mode/)
- [Tailwind dark mode](https://tailwindcss.com/docs/dark-mode)
- [Tailwind custom variants](https://tailwindcss.com/docs/functions-and-directives#custom-variant-directive)
- [Tailwind theme variables](https://tailwindcss.com/docs/theme)