# Theme and design tokens

> Edit your project's colors, fonts, text styles and link styles in midcode, and see the CSS each one writes, with Tailwind 4 and without it.

- Page: https://midcode.app/docs/styling/theme
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

A project's theme is the short list of things its pages share: its colors, its fonts, a few named text styles, the way its links look. In midcode they're in the Assets tab of the left panel, under "Styles", in four groups: Colors, Fonts, Text styles and Link styles. The search field at the top of Assets filters them by name. Nothing in the interface is called "Design panel": that name only appears in the comment midcode writes at the top of `.midcode/theme.css`, and it means this list.

Changing one there changes it everywhere it's used, because it is the same variable or class your code uses. Each change is one edit: `⌘Z` undoes it, and [Publish](https://midcode.app/docs/publish/publish.md) lists it (`--color-brand → #e0481f`, "New text style .lead").

## Where the theme lives

| Project | The file |
| --- | --- |
| Tailwind 4 | Your own CSS: the file with the `@theme` block, `app/globals.css` for instance. A token is edited in the file it's declared in. |
| No Tailwind, or Tailwind 3 | `.midcode/theme.css`, which midcode creates with [your first style edit](https://midcode.app/docs/styling/without-tailwind.md). |

Both are read the same way: variables inside `@theme`, and style rules beside it. `.midcode/theme.css` starts out like this:

```css title=".midcode/theme.css"
/*
 * This project's theme in midcode: the colors, fonts, sizes and text styles made in the Design panel.
 * midcode builds midcode.css from this file and from the mid: classes in the code.
 *
 *   --color-brand: #ff5b2e;   →  mid:bg-brand, mid:text-brand
 *   --font-display: "Inter";  →  mid:font-display
 */
@theme {
}
```

It's a file like any other: you or an agent can edit it by hand, and midcode rebuilds `midcode.css` when it changes.

## Colors

Every `--color-*` in `@theme` is a color of the project.

1. Open the Colors group and click the plus, "Add color".
2. Type a name. midcode shows the classes it gives you as you type: `bg-brand · text-brand`.
3. Pick the color and click "Add color".

The variable goes after the last color of the block:

```diff title="app/globals.css"
 @theme {
   --color-linen: #f7f2e7;
   --color-ink: #1a1a1a;
+  --color-brand: #ff5b2e;
   --font-display: "Fraunces", serif;
 }
```

Without Tailwind the same line goes in `.midcode/theme.css`:

```diff title=".midcode/theme.css"
 @theme {
+  --color-brand: #ff5b2e;
 }
```

To change a color, click it and use the picker. Only the value changes:

```diff
-  --color-brand: #ff5b2e;
+  --color-brand: #e0481f;
```

Right-click a color for "Copy name", "Copy value" and "Remove".

To use it, open any color control in the right panel: your colors are under "Project colors", and choosing one writes `text-brand` or `bg-brand` (`mid:text-brand` without Tailwind). The "Custom" tab writes the value itself, `text-[#e0481f]`.

## Fonts

Every `--font-*` in `@theme` shows in the Fonts group with its stack in a field. Edit the field and midcode rewrites the value of the variable. Right-click a font for "Copy name" and "Remove".

There's no button to add a font. Write it in `@theme` yourself and it appears, both here and in the Font list of the right panel, where choosing it writes `font-display`:

```css
@theme {
  --font-display: "Fraunces", serif;
}
```

midcode edits the name of the stack, not the font files. Loading the font (`next/font`, an `@font-face` rule, a `<link>`) stays in your code.

## Text styles

A text style is a named bundle of type settings used across the site: a class, or an `@utility`, with at least two of `font-size`, `font-family`, `font-weight`, `line-height`, `letter-spacing`, `text-transform` and `font-style`. midcode finds the ones your CSS already has.

1. Open Text styles and click the plus, "New text style".
2. Type a name and click "Add style".
3. Set its Font, Size, Weight, Line, Tracking and Case. Each field writes one declaration, and an emptied field removes it.

In a Tailwind 4 project the style is a class, written right after the last text style of your CSS (same file, same layer) or at the end of the theme's file:

```css title="app/globals.css"
.lead {
  font-size: 16px;
  line-height: 1.5;
  font-weight: 400;
}
```

Without Tailwind it's a utility, because a plain `.lead` could be a class your site already has:

```css title=".midcode/theme.css"
@utility lead {
  font-size: 16px;
  line-height: 1.5;
  font-weight: 400;
}
```

To apply one, select a text and choose it in the Style row of the Typography section. midcode adds the class to the element: `lead`, or `mid:lead` without Tailwind. The button beside the row, "Edit this style (changes it everywhere)", opens the same fields without leaving the element.

```diff title="app/page.tsx"
-<p className="mt-4 max-w-xl">We make furniture that lasts.</p>
+<p className="mt-4 max-w-xl lead">We make furniture that lasts.</p>
```

## Link styles

A link style is a color, a hover color and an underline, for links across the site. In CSS it's a class with a `:hover` rule that sets a color or an underline. midcode finds those too.

1. Open Link styles and click the plus, "New link style".
2. Type a name, then choose Color, Hover and Underline. A color is "Same as text" or one of your colors. Underline is "Never", "On hover" or "Always".
3. Click "Add style".

With Tailwind 4:

```css title="app/globals.css"
.link-quiet {
  color: var(--color-ink);
  text-decoration: none;
  text-underline-offset: 0.2em;
  transition: color 0.15s;
}
.link-quiet:hover {
  color: var(--color-brand);
  text-decoration: underline;
}
```

Without Tailwind, the hover is nested in the utility:

```css title=".midcode/theme.css"
@utility link-quiet {
  color: currentColor;
  text-decoration: none;
  text-underline-offset: 0.2em;
  transition: color 0.15s;
  &:hover {
    color: currentColor;
    text-decoration: underline;
  }
}
```

To apply one, select a link and choose it in the Style row of the Link section of the right panel.

## Sizes, radii and spacing

midcode reads three more kinds of token and uses them in the right panel. They have no group in Styles: edit them in the CSS.

| In `@theme` | What it's for |
| --- | --- |
| `--text-hero: 72px` | A size called `hero` in the Size list, beside Tailwind's `xs` to `9xl`. Written `text-hero`. |
| `--radius-card: 12px` | A radius called `card`. A corner of 12 px is written `rounded-card`. |
| `--spacing: 0.25rem` | The step every spacing class counts in. A value in `px` or `rem`. |

## Removing a token or a style

"Remove" first counts where the name is still used in your code and asks: "It's used 4 times in the code. Those places will fall back to the default until you change them." Confirm, and midcode deletes the variable's line, or the style's whole rule (a link style's `:hover` rule goes with it). It doesn't touch the places that used it.

## What midcode writes

Every edit changes only its own characters: a value, one declaration, or one new rule placed beside the others of its kind. The rest of the file, comments and formatting included, stays as it was.

| You do | With Tailwind 4 | Without Tailwind |
| --- | --- | --- |
| Add or change a color | `--color-brand: …;` in the `@theme` of your CSS | The same line in `.midcode/theme.css` |
| Change a font's stack | The value of `--font-display` | The same |
| New text style | `.lead { … }` | `@utility lead { … }` |
| New link style | `.link-quiet { … }` and `.link-quiet:hover { … }` | `@utility link-quiet { … &:hover { … } }` |
| Apply a style to an element | The class `lead` | The class `mid:lead` |
| Use a color on an element | `text-brand`, `bg-brand` | `mid:text-brand`, `mid:bg-brand` |

Without Tailwind, a change to `.midcode/theme.css` also rewrites `midcode.css`. There, a color that some class uses becomes the variable `--mid-color-brand`, and a style that some element carries becomes the rule `.mid\:lead`. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Limits

- In a Tailwind 4 project the plus buttons show once your CSS has an `@theme` block. If it has none, add an empty `@theme { }`.
- The picker writes a hex value. A color you wrote as `oklch(…)`, or as a `var(…)` pointing at another variable, becomes a hex once you change it here.
- Text sizes, radii and the spacing step are read, not edited, in this list.
- A text style or a link style can't be different per breakpoint, variant or state: applying one always writes the plain class.
- A style your CSS defines again inside a media query is read once, and the fields edit its first rule.
- Without Tailwind, the variables of your theme are written to `midcode.css` with the prefix: `--mid-color-brand`, `--mid-font-display`. A link style whose color is one of your colors, or a text style whose font is one of your fonts, is written as `var(--color-brand)` or `var(--font-display)`, which that file doesn't define, so the link or the text keeps its inherited color or font. Until that's fixed, choose "Same as text" in the style's fields, or write the prefixed name in `.midcode/theme.css` by hand: `color: var(--mid-color-brand)`.