# Theming

CSS variables are used for styling the components and creating Tailwind CSS utility classes.

## Convention

We use a simple `background` and `foreground` convention for colors. The `background` variable is used for the background color of the components, and the `foreground` variable is used for the color of the text. Note that the `background` suffix is often omitted.

> **Info:** The css variables are extremely similar to shadcn, making it easy to convert to use starwind, or to use both in your project.

## CSS Variables

Below are all the variables in use, with comments for each variable describing what it does. By default, all colors used are [default tailwind colors](https://tailwindcss.com/docs/colors#default-color-palette-reference).

```css title="src/styles/starwind.css"
/* allows you to use "dark:" variant in your html and have it match the .dark css variables */
@custom-variant dark (&:where(.dark, .dark *));

/* ... */

:root {
  /* default color of <body> background and text */
  --background: var(--color-neutral-50);
  --foreground: var(--color-neutral-950);

  /* Background and text color for <Card> */
  --card: var(--color-neutral-50);
  --card-foreground: var(--color-neutral-950);

  /* Colors for popovers like <SelectContent> and <TooltipContent> */
  --popover: var(--color-neutral-50);
  --popover-foreground: var(--color-neutral-950);

  /* Primary colors for <Button>, etc. when variant="primary" */
  --primary: var(--color-blue-700);
  --primary-foreground: var(--color-neutral-50);

  /* Primary color that is accessible for text on the background color */
  --primary-accent: var(--color-blue-800);

  /* Secondary colors for <Button>, etc. when variant="secondary" */
  --secondary: var(--color-neutral-200);
  --secondary-foreground: var(--color-neutral-950);

  /* Secondary color that is accessible for text on the background color */
  --secondary-accent: var(--color-neutral-950);

  /* Muted colors use for <TabsList>, <Avatar>, etc. */
  --muted: var(--color-neutral-100);
  --muted-foreground: var(--color-neutral-600);

  /* Accents like hover effects on <SelectItem> */
  --accent: var(--color-neutral-200);
  --accent-foreground: var(--color-neutral-900);

  /* Various component colors for variant="info" */
  --info: var(--color-sky-300);
  --info-foreground: var(--color-sky-950);

  /* Various component colors for variant="success" */
  --success: var(--color-green-300);
  --success-foreground: var(--color-green-950);

  /* Various component colors for variant="warning" */
  --warning: var(--color-amber-300);
  --warning-foreground: var(--color-amber-950);

  /* Various component colors for variant="error" */
  --error: var(--color-red-700);
  --error-foreground: var(--color-neutral-50);

  /* Default border color */
  --border: var(--color-neutral-200);

  /* Border colors for inputs like <Input>, <Textarea>, <SelectTrigger>  */
  --input: var(--color-neutral-200);

  /* Used for focus outline */
  --outline: var(--color-blue-600);

  /* Border radius for various elements */
  --radius: 0.5rem;
}

/* overriding above variables when a parent has the class "dark" */
.dark {
  --background: var(--color-neutral-950);
  --foreground: var(--color-neutral-50);
  /* etc... */
}
/* ... */
```

## Adding new colors

You can add additional color themes by creating a new Tailwind CSS `variant`, and adding it with new variable assignments to the `@theme`.

```css title="src/styles/starwind.css" ins={5,20-46}
/* allows you to use "dark:" variant in your html and have it match the `.dark` css variables */
@custom-variant dark (&:where(.dark, .dark *));

/* allows you to use "newcolor:" variant in your html and have it match the `.my-new-color` css variables */
@custom-variant newcolor (&:where(.my-new-color, .my-new-color *));

/* ... */

:root {
  /* base variables (light mode) */
}

.dark {
  /* dark mode variables */
}

/* overriding above variables when a parent has the class "my-new-color" */
/* edit these variables to whatever you want them to be in that context */
.my-new-color {
  --background: var(--color-neutral-950);
  --foreground: var(--color-neutral-50);
  --card: var(--color-neutral-950);
  --card-foreground: var(--color-neutral-50);
  --popover: var(--color-neutral-950);
  --popover-foreground: var(--color-neutral-50);
  --primary: var(--color-blue-700);
  --primary-foreground: var(--color-neutral-50);
  --secondary: var(--color-fuchsia-300);
  --secondary-foreground: var(--color-neutral-950);
  --muted: var(--color-neutral-900);
  --muted-foreground: var(--color-neutral-400);
  --accent: var(--color-neutral-900);
  --accent-foreground: var(--color-neutral-100);
  --info: var(--color-sky-300);
  --info-foreground: var(--color-sky-950);
  --success: var(--color-green-300);
  --success-foreground: var(--color-green-950);
  --warning: var(--color-amber-300);
  --warning-foreground: var(--color-amber-950);
  --error: var(--color-red-800);
  --error-foreground: var(--color-neutral-50);
  --border: var(--color-neutral-800);
  --input: var(--color-neutral-800);
  --outline: var(--color-blue-600);
}
/* ... */
```

## Adding new theme variables

Following standard Tailwind CSS v4 variable naming conventions, you can add new Tailwind CSS variables to the `@theme` block. 

> **Tip:** You should add this to the `@theme inline` block specifically, so you can reference your variables defined for `:root` and `.dark`.

```scss title="src/styles/starwind.css" ins={3,13,18}
@theme inline {
  /* will allow you to use `border-canvas`, `bg-canvas`, etc. */
  --color-canvas: var(--acme-canvas-color);

  /* standard Starwind UI variables */
	--color-background: var(--background);
	--color-foreground: var(--foreground);
  /* etc... */
}

:root {
  --acme-canvas-color: oklch(0.967 0.003 264.542);
  /* etc... */
}

.dark {
  --acme-canvas-color: oklch(0.21 0.034 264.665);
  /* etc... */
}
```

## Relevant Tailwind docs

- [Dark mode](https://tailwindcss.com/docs/dark-mode)
- [Custom variants](https://tailwindcss.com/docs/functions-and-directives#custom-variant-directive)
- [@theme inline keyword](https://tailwindcss.com/docs/colors#referencing-other-variables)
- [Theme variables](https://tailwindcss.com/docs/theme)