# makeover: architecture
Theme loading and intent resolution for every make-family app. A theme file
declares colours by role; this crate turns that into the full set of intent
tokens, derived states included, and emits them as CSS or as colours for a
native renderer. No app derives a token itself.
## Modules
Every public item is re-exported at the crate root. The modules are internal
seams, and a caller never names one.
| `lib` | Root re-exports, `ThemeMeta`, `ThemeColors`, `COLOR_SECTIONS` |
| `load` | `ThemeId`, `LoadError`, reading and parsing theme files, the one directory scan, import, export and delete |
| `dirs` | `ThemeDirs`, the named search path; `find_theme_path`; the embedded and bundled theme sets |
| `intent` | `Token`, `SemanticTokens`, `resolve`, the `ratio` constants the derivations use, CSS emission of the token layer |
| `emphasis` | The tonal steps of the ink: `Emphasis`, `STEP_FLOOR` |
| `color` | `Rgb`, `Rgba`, `Oklab`, the perceptual steps, WCAG contrast |
| `sheet` | `all_themes_css` and `keyed_intent_css_vars`: every theme in one sheet, keyed by `data-theme` |
| `selection` | `Variant`, `ThemeSelection`, `ThemeDefaults`, `ContrastTier`, picker ordering |
| `font` | `Typography`, `FontSlot`, `FontFace`, product font overrides |
| `typography` | The house font tokens and their `@font-face` rules |
| `ansi` | Terminal palettes, quantisation, and which intent paints each ANSI slot |
| `css` | Escaping caller strings into CSS |
## Rules
- **A theme id is a `ThemeId`.** It is checked where it is made, so no
function taking one can be handed a path.
- **Every file is read through `load::read_theme`,** and every walk over the
directories is `load::scan`. A file that will not load is reported in
`Listed::broken`, never dropped silently.
- **A token is a `Token`, and its value an `Rgba`.** CSS text is produced only
at emission (`intent_css_declarations`, `SemanticTokens::css`). The stem a
stylesheet reads is `Token::as_str`.
- **Look ratios live in `ratio`.** A derivation names its constant; a number
inline in `resolve` is a bug.
- **Caller strings reach CSS only through `css`.** A theme file is
user-writable.
- **Emission is byte-stable.** Tokens and keyed blocks are ordered by stem and
by id, so a consumer can cache or diff the sheet.
## Data
| Shipped themes | `themes/*.toml`, embedded at compile time by `dirs` |
| Third-party attribution | `THIRD-PARTY-NOTICES.md`, checked by a test for every theme |
| Contrast floors | `tests/contrast_floors.rs` |