# Theming

fabrica re-brands and re-themes with **no rebuild**: structure lives in
`assets/base.css` (custom properties only, no literal colours), and a theme is a
single CSS file that defines those properties. This document catalogues the tokens
a theme sets. The layout-token families (`--fb-bg`, `--fb-accent`, …) are wired up
in the web phase; the **syntax-highlight** family below is live as of the highlight
phase and is documented here first because it is generated by `crates/highlight`.

## Syntax highlight classes

`crates/highlight` emits a fixed, stable set of CSS classes — never inline colours
and never tree-sitter capture names. Every grammar's captures are folded onto this
set through one table (`crates/highlight/src/classes.rs`), so a theme styles code by
targeting these twelve classes and nothing else:

| Class | Token | Typical captures folded in |
| --- | --- | --- |
| `hl-keyword` | `--fb-hl-keyword` | `keyword`, `keyword.control.*`, `label` |
| `hl-function` | `--fb-hl-function` | `function`, `function.macro`, `method` |
| `hl-type` | `--fb-hl-type` | `type`, `type.builtin`, `constructor`, `namespace` |
| `hl-string` | `--fb-hl-string` | `string`, `escape`, `char`, `regex` |
| `hl-number` | `--fb-hl-number` | `constant.numeric.*`, `number`, `float`, `boolean` |
| `hl-comment` | `--fb-hl-comment` | `comment` |
| `hl-constant` | `--fb-hl-constant` | `constant`, `constant.builtin` |
| `hl-variable` | `--fb-hl-variable` | `variable`, `property`, `parameter`, `field` |
| `hl-operator` | `--fb-hl-operator` | `operator` |
| `hl-punctuation` | `--fb-hl-punctuation` | `punctuation.*` |
| `hl-attribute` | `--fb-hl-attribute` | `attribute`, `annotation`, `decorator` |
| `hl-tag` | `--fb-hl-tag` | `tag` |

A theme maps each class to a colour via its `--fb-hl-*` token, e.g.

```css
:root {
  --fb-hl-keyword: #c678dd;
  --fb-hl-string:  #98c379;
  /* … */
}
.hl-keyword { color: var(--fb-hl-keyword); }
```

Captures with no entry in the table render as ordinary text inside their line, so an
unstyled grammar never produces stray markup. Highlighting is line-addressable:
every emitted line is independently balanced HTML, so blob-view anchors (`#L12`) and
per-side diff rows can slice by line number without breaking spans.

## Layout tokens

The full `--fb-*` layout-token catalogue (`--fb-bg`, `--fb-bg-raised`,
`--fb-border`, `--fb-fg`, `--fb-accent`, `--fb-success`, `--fb-warning`,
`--fb-danger`, `--fb-diff-add-bg`, `--fb-diff-del-bg`, …) is documented alongside
the web shell, where `base.css` and the embedded `dark`/`light` themes are
introduced. A theme that sets only the documented tokens must yield a complete,
coherent UI — that is the acceptance test for themeability.