| 1 | # Theming |
| 2 | |
| 3 | fabrica re-brands and re-themes with **no rebuild**: structure lives in |
| 4 | `assets/base.css` (custom properties only, no literal colours), and a theme is a |
| 5 | single CSS file that defines those properties. This document catalogues the tokens |
| 6 | a theme sets. The layout-token families (`--fb-bg`, `--fb-accent`, …) are wired up |
| 7 | in the web phase; the **syntax-highlight** family below is live as of the highlight |
| 8 | phase and is documented here first because it is generated by `crates/highlight`. |
| 9 | |
| 10 | ## Syntax highlight classes |
| 11 | |
| 12 | `crates/highlight` emits a fixed, stable set of CSS classes — never inline colours |
| 13 | and never tree-sitter capture names. Every grammar's captures are folded onto this |
| 14 | set through one table (`crates/highlight/src/classes.rs`), so a theme styles code by |
| 15 | targeting these twelve classes and nothing else: |
| 16 | |
| 17 | | Class | Token | Typical captures folded in | |
| 18 | | --- | --- | --- | |
| 19 | | `hl-keyword` | `--fb-hl-keyword` | `keyword`, `keyword.control.*`, `label` | |
| 20 | | `hl-function` | `--fb-hl-function` | `function`, `function.macro`, `method` | |
| 21 | | `hl-type` | `--fb-hl-type` | `type`, `type.builtin`, `constructor`, `namespace` | |
| 22 | | `hl-string` | `--fb-hl-string` | `string`, `escape`, `char`, `regex` | |
| 23 | | `hl-number` | `--fb-hl-number` | `constant.numeric.*`, `number`, `float`, `boolean` | |
| 24 | | `hl-comment` | `--fb-hl-comment` | `comment` | |
| 25 | | `hl-constant` | `--fb-hl-constant` | `constant`, `constant.builtin` | |
| 26 | | `hl-variable` | `--fb-hl-variable` | `variable`, `property`, `parameter`, `field` | |
| 27 | | `hl-operator` | `--fb-hl-operator` | `operator` | |
| 28 | | `hl-punctuation` | `--fb-hl-punctuation` | `punctuation.*` | |
| 29 | | `hl-attribute` | `--fb-hl-attribute` | `attribute`, `annotation`, `decorator` | |
| 30 | | `hl-tag` | `--fb-hl-tag` | `tag` | |
| 31 | |
| 32 | A theme maps each class to a colour via its `--fb-hl-*` token, e.g. |
| 33 | |
| 34 | ```css |
| 35 | :root { |
| 36 | --fb-hl-keyword: #c678dd; |
| 37 | --fb-hl-string: #98c379; |
| 38 | /* … */ |
| 39 | } |
| 40 | .hl-keyword { color: var(--fb-hl-keyword); } |
| 41 | ``` |
| 42 | |
| 43 | Captures with no entry in the table render as ordinary text inside their line, so an |
| 44 | unstyled grammar never produces stray markup. Highlighting is line-addressable: |
| 45 | every emitted line is independently balanced HTML, so blob-view anchors (`#L12`) and |
| 46 | per-side diff rows can slice by line number without breaking spans. |
| 47 | |
| 48 | ## Layout tokens |
| 49 | |
| 50 | The full `--fb-*` layout-token catalogue (`--fb-bg`, `--fb-bg-raised`, |
| 51 | `--fb-border`, `--fb-fg`, `--fb-accent`, `--fb-success`, `--fb-warning`, |
| 52 | `--fb-danger`, `--fb-diff-add-bg`, `--fb-diff-del-bg`, …) is documented alongside |
| 53 | the web shell, where `base.css` and the embedded `dark`/`light` themes are |
| 54 | introduced. A theme that sets only the documented tokens must yield a complete, |
| 55 | coherent UI — that is the acceptance test for themeability. |