# Configuration

Configure Yumma CSS for your project.

## Install the CLI

Yumma CSS includes the Yumma CLI, which generates production-ready styles.

```bash
pnpm add yummacss -D
```

## Set Up

Initialize a configuration file in your project.

```bash
pnpm dlx yummacss init
```

This creates a `yumma.config.mjs` file at your project root, pointing at your project's own folders. The same configuration file powers the CLI & the bundler plugins (`@yummacss/vite` & `@yummacss/postcss`).

```mjs title="yumma.config.mjs" mark={4-5}
import { defineConfig } from "yummacss";

export default defineConfig({
  source: ["./src/**/*.{js,jsx,ts,tsx,mdx,html}"],
  output: "./src/styles.css",
});
```

### Source

A collection of paths for your template files (e.g., `.js`, `.tsx`, `.html`). The CLI scans these files for utilities to include in the final CSS file.

> Use glob patterns to include subfolders & specific file types.

```mjs title="yumma.config.mjs" mark={4}
import { defineConfig } from "yummacss";

export default defineConfig({
  source: ["./src/**/*.html"],
});
```

### Output

Specifies the output path for the compiled CSS file.

> Only the CLI uses `output`. The bundler plugins ignore it & inject the
> generated CSS through the `@yummacss;` marker instead.

```mjs title="yumma.config.mjs" mark={4}
import { defineConfig } from "yummacss";

export default defineConfig({
  output: "./src/styles.css",
});
```

### Normalize

Determines whether to include base styles normalization.

```mjs title="yumma.config.mjs" mark={4}
import { defineConfig } from "yummacss";

export default defineConfig({
  normalize: true, // default: true
});
```

### Theme

Extends or overrides default design tokens.

#### Colors

Define custom color families. The compiler automatically generates a 13-step scale (the base, plus shades `1` to `12`) unless a full palette is explicitly provided.

> Use `percentage` to control how much the shade is lightened or darkened.

```mjs title="yumma.config.mjs" mark={4-12}
import { defineConfig } from "yummacss";

export default defineConfig({
  theme: {
    colors: {
      brand: "#9333EA",
      percentage: {
        light: 14,
        dark: 14,
      },
    },
  },
});
```

A color may also be a light/dark pair, which compiles to CSS `light-dark()` & resolves per color scheme. Both sides are scaled independently, so every shade of a paired color is itself a pair.

```mjs title="yumma.config.mjs" mark={6}
import { defineConfig } from "yummacss";

export default defineConfig({
  theme: {
    colors: {
      surface: { light: "#ffffff", dark: "#111214" },
    },
  },
});
```

> As soon as one color is paired, `color-scheme: light dark` is declared on
> `:root` so the page follows the operating system. Override it with the [Color
> Scheme](/docs/color-scheme) utilities. See [Dark Mode](/docs/dark-mode)
> for the full walkthrough.

#### Screens

Define custom media query breakpoints or override existing ones.

```mjs title="yumma.config.mjs" mark={4-13}
import { defineConfig } from "yummacss";

export default defineConfig({
  theme: {
    screens: {
      sm: "40rem",
      md: "48rem",
      lg: "64rem",
      xl: "80rem",
      xxl: "96rem",
      "3xl": "112rem",
    },
  },
});
```

#### States

Name your own variants for attributes your components set. Each name becomes a prefix like `h:`. See [States](/docs/states).

```mjs title="yumma.config.mjs" mark={4-7}
import { defineConfig } from "yummacss";

export default defineConfig({
  theme: {
    states: {
      closing: "[data-ending-style]",
    },
  },
});
```

#### Fonts

Add font stacks. Each name becomes an `ff:` class, and a name that matches a built-in family replaces it. See [Font Family](/docs/font-family).

```mjs title="yumma.config.mjs" mark={4-7}
import { defineConfig } from "yummacss";

export default defineConfig({
  theme: {
    fonts: {
      display: '"Esteban", serif',
    },
  },
});
```

#### Keyframes

Define animations, each written as the body of a CSS `@keyframes` rule. Each name becomes an `an:` class. See [Animation Name](/docs/animation-name).

```mjs title="yumma.config.mjs" mark={4-7}
import { defineConfig } from "yummacss";

export default defineConfig({
  theme: {
    keyframes: {
      spin: "to { rotate: 360deg; }",
    },
  },
});
```

### Safelist

An array of utility classes that should always be generated in the final CSS output, regardless of whether they are present in your source files. Use this for classes that are added dynamically via JavaScript.

> Use `safelist` for classes generated dynamically at runtime. For example, in
> React, a class assembled at runtime such as `` `d-${direction}` `` cannot be
> detected by the file scanner, making a safelist necessary.

```mjs title="yumma.config.mjs" mark={4}
import { defineConfig } from "yummacss";

export default defineConfig({
  safelist: ["bg:red", "c:white", "fw:700"],
});
```

## Generate Styles

The CLI scans files specified in `source` & generates a CSS file based on the utilities used.

### HTML Input

```tsx title="index.tsx"
<button className="bg:white c:black bw:1">Button</button>
```

### CSS Output

Running the `build` or `watch` command generates the following CSS:

```css title="styles.css"
.bg\:white {
  background-color: #ffffff;
}

.bw\:1 {
  border-width: 1px;
}

.c\:black {
  color: #000000;
}
```

## CLI Commands

The Yumma CSS CLI provides commands to manage your project.

> Create a `yumma.config.mjs` file before running these commands. If there is
> none, run `yummacss init`.

### Build

Compile your Yumma CSS files once.

```bash
pnpm dlx yummacss build
```

### Watch

Watch for file changes & recompile automatically.

```bash
pnpm dlx yummacss watch
```