Crea · reference

Everything that decides how a realm looks

One page for the Theme table, the pages that dress each piece of furniture (the dock, the navrail, the sidebars) and the two that hold the project's own faces and marks, the per-kind windows, the menus, the exported looks, and the stylesheet themes you write by hand — plus the files all of it is stored in.

·What this page is

A realm is Crea's word for a project: an ordinary folder the writer chose. Its folder is the database — every preference on this page is a file inside it, so a look survives Crea being uninstalled, travels on a USB stick, and can be handed to another writer by copying a folder.

Nothing here is stored in app storage. That is deliberate: a look is a property of this project, not of the machine it happens to be open on.

1Where a look lives

<realm>/
├── .genesis/
│   ├── ui-prefs.json          ← every preference on this page, as one block
│   ├── folder-colors.json     ← the file/folder palette (NOT a theme, §18)
│   ├── icons/.packs/          ← installed icon packs (zip + index)
│   ├── themes/
│   │   ├── <name>.json        ← an exported look: a customisation block (§8)
│   │   └── <id>/theme.css     ← a CSS theme: a stylesheet you author (§13)
│   └── fonts/                 ← font files the Font picker offers (§5)
├── .characters/               ← the Cast
├── .timeline/                 ← Timeline events
├── .media/                    ← images, and subfolders as albums
└── <anything else>            ← the writer's own notes and pictures

🔴 .genesis/themes/ holds two species of theme, told apart by shape on disk: a .json file is a saved look (a whole customisation Crea writes), and a <id>/ folder containing theme.css is a CSS theme (a stylesheet a person authors). The picker groups them separately, because they behave differently — see §3.

2The theme table — 35 tokens, four groups

Customisation › Theme is one grid of colour rows under four headings. It edits the half the table's own toggle names (dark or light); it is not the app's theme switch, and switching the app switches the half shown. Stored as customisation.theme.dark[token] and …theme.light[token].

A token missing from a half means the app's own colour for it, which is also what a reset restores: absence is the default, never a copied constant. Each row's Default writes the value of the project's theme — not the built-in look — see §3.

App palette — the nine that matter most

These nine are also the authoring surface for a CSS theme (§15): every other token below has a default that already points at one of them.

Chrome — the strips, the fields, the scroll bar

Two header tokens were removed rather than left empty: header-logo (2026-10-25) coloured the ◆ that the app's artwork replaced — the drawing carries its own amber — and header-text (2026-10-26) coloured the CREA word when the owner took that word out of the header. A token whose only consumer is gone is a settings row that writes a value and paints nothing.

Buttons — four groups, one per kind of press

Borders — the window frame and the app's seams

How a row resets

Default beside a swatch writes the project theme's value for that one token; the toolbar's reset is a menu of three answers — Reset dark, Reset light, Reset all — each disabled when that half carries nothing. A project on Genesis resets to the app's built-in look; a project wearing a saved look resets to that file; a project on a CSS theme writes no override at all, and the theme underneath shows through. See §16.

3Theme choice — one dropdown, three species

Project › Theme names the look this project is wearing, and it is stored as customisation.themeName. Choosing is applying — there is no separate Apply button. The list is grouped because the species behave differently:

🔴 The stored name is also the reset baseline. Every "reset to default" in Customisation writes this theme's value — the way a document's local formatting resets to its style — which is the whole reason the choice is persisted rather than just applied.

Open CSS themes folder is the only door into .genesis/themes/: nothing else in the interface can print an absolute path, and the folder is dot-prefixed inside a dot-prefixed folder. Rescan re-lists it and re-reads the theme currently on screen, which is the authoring loop (§16).

4The furniture pages — Navrail, Dock, Sidebar

Customisation's children are Look & Feel, Font, Icons, Navrail, Dock, Sidebar, Menus, Theme, Windows and Characters. Each one is a piece of furniture and carries only the controls that piece actually draws: a writer who opens Navrail is looking at the navrail, not at the app.

Look & Feel — three toggles, the layout and the frame's marks

Navrail — the same furniture under the other layout's name

The default layout's rail is the dock's counterpart, so it answers the same four questions with the opposite defaults — float, length, radius and alignment; a dock has a fifth, its edge, because it can move to any of the four — and the difference is the whole point: a dock floats and hugs its entries, a navrail is welded to the wall and runs the height of the desk. It had no shape of its own until 2026-10-27 — its width was an inline style in the markup, which no stylesheet and no setting could reach — so a theme could restyle its fill but not its body.

Dock — where the bar sits, and how big it is

Five fields decide the dock's shape, and one sizes its marks. Everything else — its fill, its border, its lettering, its shadow, its translucent blur — is CSS, and a theme may rewrite all of it (§11).

Sidebar — floating panels, in either layout

The Files, Characters and Help panels can be attached to the edge they slide from or floating over the desk, with a gap and a corner — the same distinction the dock makes, which is why it is the same shape of setting. Three fields decide the panel's shape, and two more plus a face dress what it draws; everything else about it is CSS (§11).

5Fonts — four faces, three pages

All four write customisation.fonts (or the sidebar's own top-level field) and they are the project's: shared by both arrangements, so switching layout never changes a face. What differs is where the control sits — each face lives on the page of the thing it dresses, and the one that dresses a layout-specific piece of furniture sits on that furniture's page. Every field opens the same picker with two sources: SYSTEM lists installed families (through the Local Font Access API, with a curated fallback when the permission is refused) and PROJECT lists font files in the realm's .genesis/fonts/, filtered to .ttf .otf .woff .woff2. A project font has never been installed, so choosing one loads it from its bytes and registers an @font-face under a name of Crea's own.

Stored shape is { source: "system" | "project", value: "…" }, or null for Default. Both sides normalise it, so a hand-edited ui-prefs.json cannot put an unreadable value in front of the interface. Each of the four has its own Reset to default, and the picker always shows the face it is wearing — Inter, JetBrains Mono, or Default (…).

🔴 Project fonts are not served over the media scheme. That would mean a font-src entry in the content policy plus CORS headers on an image-only scheme — three changes to a security boundary to move a few kilobytes. A blob: URL is same-origin, so the policy gains one word instead.

6Per-kind windows

Each window kind owns a frame block — the header strip, its 1px rule, the name on it, and a corner radius. radius: null means not chosen: square in the default layout, 8px in os, because a window floating on a dock desk with a hard square corner reads as a panel. An explicit 0 stays square in both — a layout must not overrule a number it was given. The stepper shows the effective radius, so the control and the drawn window cannot disagree.

7Menus, icons, density

Crea's density is a constant: the same row heights in every panel, from one file. Three sets of numbers are the named exceptions, and each is a project preference rather than a second density scale. All three are saved per layout (2026-10-26) — they are the furniture of an arrangement, so the dock's menu text and the rail's icon sizes are two separate answers. Menus keeps its own page, because a menu belongs to no side; the five icon sizes are split across the pages of the things they size (§4), and the two rail labels follow the layout: Dock icons in os, Navrail icons in default.

Menus — text and marks

One pair serves both menu spellings — the dialog menus and the file tree's hand-built one — and the row height is derived, never stored: max(--h-row, --icon-menu + 8px, --menu-text × 1.6), which is 24px at the defaults. Ask for a 24px word or a 32px mark and the row grows instead of clipping. A menu is an overlay read one-handed, so it is the one list in the app not bounded by the standard row height.

Five icon sizes, four pages

🔴 Each token sizes its own container, not only its glyph. The cell around a mark is max(…, --icon-… + n px), so asking for a 24px mark grows the box rather than drawing outside it — a glyph that outgrows a fixed box is either clipped or spilling, and both read as a rendering fault rather than as a large icon.

🔴 The control hugs its value. The stepper and the segmented group are width: fit-content, because a flex child of a column stretches on the cross axis — which painted [+] 5 [-] with an empty box to its right, and a three-option group with a long blank rail after the last cell. A width, not an alignment: the same controls sit in centred rows, and pushing them to the start would move them out from under their labels.

The two sidebars also keep their own long-standing type tokens — a 28px row and 13px names, larger than the app's 22px row — because the writer reads those two lists all day.

8Export a look

Export theme, beside the reset menu, writes the whole current customisation — both theme halves included — to .genesis/themes/<name>.json:

{
  "version": 1,
  "name": "Lighthouse",
  "savedAt": 1761000000000,
  "customisation": { /* the entire block, normalised */ }
}

Applying one is a replace, not a merge: the file holds every key it knows about, so it hands the project a complete look, and a token the file says nothing about falls back to the app's own value rather than standing on the applying project's old override.

The dialog is the one panel that is deliberately not un-themed: it is a look being named, so it wears the look. A theme is shared by copying one file; Delete asks first. The name is sanitised to a–z A–Z 0–9 _ - and spaces, which is also what makes it impossible for a saved look and a CSS theme folder to be called the same thing.

9The full block, as written

{
  "sidebarFont": null,               // ← §5, its own top-level field
  "customisation": {
    "theme": {
      "dark":  { "bg": "#131313", "accent": "#e8a838", "header-muted": "#8a8a8a" },
      "light": { /* … */ }        // ← both halves; the active one is editable
    },
    "themeName": "Genesis",          // ← "Genesis" | a saved look | "css:<id>"
    "layout": "os",                  // ← "os" | absent = default
    "layouts": {                      // ← the furniture, per arrangement (§11)
      "default": {
        "iconBoxes": false,          // true → boxes; false sets data-icon-boxes="off"
        "headerIcons": false,        // true → the frame's code is drawn as a mark
        "icons": { "navrail": 20, "app": 17, "header": 10, "sidebar": 20, "files": 18 },
        "menus": { "text": 13, "icon": 16 },
        "dock": { "float": true, "position": "bottom", "radius": null, "width": "fit", "align": "center" },
        "navrail": { "float": false, "radius": null, "width": "full", "align": "start" },
        "sidebar": { "float": false, "span": "full", "radius": null },
        "windows": { "note": { "border": null, "top": null, "text": null, "radius": null }, /* …one per kind */ }
      },
      "os": {
        "iconBoxes": true,           // ← an independent set of the same numbers
        "headerIcons": true,
        "icons": { /* … */ }, "menus": { /* … */ },
        "dock": { "float": false, "position": "left", "width": "full", "align": "start", /* … */ },
        "navrail": { /* … this desk's rail, if it ever stops being attached */ },
        "sidebar": { "float": true, "span": "fit", /* ← the layout's own seed */ },
        "windows": { /* … */ }
      }
    },
    /* the flat eight — windows · icons · menus · dock · navrail · sidebar · headerIcons
       · iconBoxes — are a MIRROR of layouts[layout]. They are written by the normaliser,
       never by a control, so a reader that asks customisation().icons gets the active
       layout's sizes and no call site had to learn that a split happened. */
    "fonts": { "app": null, "rail": null, "markdown": null },
    "characters": { "indent": 2, /* type sizes and weights */ },
    "windows": { /* the active layout's frames — see layouts above */ },
    "dock": { /* the active layout's dock — see layouts above */ },
    "navrail": { /* the active layout's rail — see layouts above */ },
    "sidebar": { /* the active layout's sidebars — see layouts above */ }
  }
}

🔴 The furniture travels with its layout; the look does not. layouts holds windows, icons, menus, dock, navrail, sidebar, headerIcons and iconBoxes — the eight things that describe how an arrangement is built. Everything else in the block (theme, fonts, characters, editor) is the project's and is shared by both. A project written before the split has no layouts at all, and both maps are seeded from its flat block — so a writer's numbers survive whichever layout they open next.

🔴 A change is written to the layout it was made in. setCustomisation computes furnitureTouched from the patch's own keys (FURNITURE_SECTIONS plus the two scalars) and copies the target layout's block before merging, so a 12px radius set in os cannot round the windows in default. A { layout } patch touches none of them, so it is a read that re-derives the mirror and invents nothing.

Two normalisers own this shape — one in src/lib/prefs.js and one in electron/vault.cjs — and they are deliberately twins. Both sides read the file, so a hand-edited ui-prefs.json cannot reach the renderer unvetted, and a renderer a version ahead cannot write a shape the main process would then misread.

10Porting a pre-theme project

Projects written before 2026-10-22 may still carry the old subordinate blocks. They still paint: the app normalises them and applies them under the theme half, so a token the active half claims wins, and a legacy value remains the painter only where the table has none. A port is a rename of those values into theme.dark / .light — which is what gives them the per-half answer the old blocks never had.

"customisation": {
  "chrome":  { "rail": { "bg", "text" }, "header": { "bg" },
               "footer": { "bg" }, "sidebar": { "bg", "text", "icon" },
               "scrollbar": { "thumb" }, "input": { "bg", "text", "border" } },
  "buttons": { "save": {…}, "delete": {…}, "normal": {…}, "special": {…} },
  "borders": { "window", "app", "appBorder" }
}

Three header tokens are new with the merge and have no legacy key: header-muted, sidebar-header-icon and input-label — plus the Close pair.

11Layouts, and what is saved per layout

data-layout="os" turns the navrail into a dock of marks: the rail's three-letter codes become a dock's marks on the edge chosen in Customisation › Dock, the app's own header controls become marks instead of words, HELP moves up into the header and the footer strip is not drawn at all. The absence of the attribute is the default layout — codes in the rail, a footer, and words in the header.

os is also the half of the app that owns most of the radii: its windows default to 8px, its dock corners, its live square is a circle, and its menus are drawn with a 4px corner. default's windows are square until the writer chooses a number, and its menus stay square — but neither layout is welded to its furniture any more: the navrail, the dock and the sidebars each float, fit and round on their own, in either arrangement (§4). Nothing in the interface casts a shadow, and nothing animates except a drag and the three dots after SAVING — motion is what a press never gets, and the dots are the interface reporting work it has not finished.

Furniture is per layout; look is per project

A layout is not a skin over one arrangement — it is a second arrangement, and some numbers only mean anything inside one of them. So they are stored there (customisation.layouts.<layout>, §9):

🔴 A change is written to the layout it was made in. Leave os set to rounded windows with 24px dock marks, switch to default, and the windows there are still square with the rail's own sizes — because nothing about the first arrangement was a statement about the second. Colours and fonts do not move, for the mirror-image reason: a navy navrail is not a decision about furniture.

Restyling the rail — the hooks a stylesheet gets

Both layouts draw the same element, and a stylesheet can restyle or replace it without knowing which one is on screen. Every entry carries two slots, and which one is visible is a variable rather than a branch in the markup — so a CSS theme can swap them for one entry, for one layout, or for the whole app.

A theme that wants marks in default needs two declarations and nothing else:

--rail-code-display: none;
--rail-mark-display: grid;

Naming an entry is the same idea one step down. data-rail-code is stable across both layouts and both themes, because it is the control's identity rather than its drawing — but a rule that re-points --icon-rail on one entry stops listening to the writer's own picker for that entry. "Dock icons resizes all icons except gallery icons" was exactly this: a theme had pinned GAL to a fixed size. Scale from the token instead, and the setting still reaches it:

.crea-rail-entry[data-rail-code="GAL"] .crea-rail-mark > svg {
  width: calc(var(--icon-rail, 20px) * 1.2);
  height: calc(var(--icon-rail, 20px) * 1.2);
}

Scope a size to an entry's mark rather than to :root. The app writes --icon-rail inline on <html> from Dock icons, and inline wins over any stylesheet — so a global value would silently overrule the writer's own picker, while a nearer one is a deliberate exception.

🔴 This is the one part of the rail that is a contract. The classes and the three data attributes are what a stylesheet is allowed to rely on; everything inside an entry besides the two slots is the app's own and may change. Tokens are still preferable to either (§15) — but a dock you can redesign is the point of a dock that is drawn from CSS rather than from a component's opinion.

Restyling the dock — the bar, its entries, the sidebars

The five Dock shape settings say whether the bar floats, where it is and how big it is (a sixth sizes its marks). Everything else about it is CSS, and it is published on purpose: a taskbar, a launcher, a shelf and a floating pill are four different objects with one shared skeleton, and a setting for each of them would be a settings pane nobody could finish. So the markup is a fixed set of hooks, the placement is keyed by an attribute rather than written into a Tailwind class, and a stylesheet is allowed to take it from there.

A full-width taskbar

Set Dock width → Full width and untick Float the dock — a full-width bar can float (a shelf with a gap), but a taskbar is welded to its edge, and the two settings are separate questions. Then set Dock icons position — that is the one mode where the bar has spare length to distribute, and html[data-dock-align] is what a theme can lean on for the rest. Give it a taskbar's body — a raised strip rather than a floating pill:

/* a taskbar, whether or not the writer asked for full width */
nav.crea-os-dock {
  background: linear-gradient(to bottom, #3b6ea5 0%, #245edb 8%, #1f4fbf 92%, #16357f 100%);
  border: 1px solid #0f2c66;
  border-radius: 0;
  box-shadow: inset 0 1px 0 #6f9fd8;
}
nav.crea-os-dock .crea-os-dock-entry {
  border-radius: 2px;
}
nav.crea-os-dock .crea-os-dock-entry:hover {
  background: rgba(255 255 255 / 0.28);
}
nav.crea-os-dock .crea-os-dock-entry.is-live {
  background: rgba(0 0 0 / 0.28);
  box-shadow: inset 1px 1px 0 rgba(0 0 0 / 0.5);
}

A left launcher, the way Ubuntu draws one

Dock position → Left, then take the bar's own frame away and let the marks sit on a dark rail with a coloured live border:

html[data-dock-position="left"] nav.crea-os-dock {
  background: #2c001e;
  border: 0;
  border-radius: 0;
  padding: 4px 2px;
}
html[data-dock-position="left"] .crea-os-dock-entry {
  border-radius: 8px;
}
html[data-dock-position="left"] .crea-os-dock-entry.is-live {
  background: rgba(255 255 255 / 0.12);
}
/* the launcher's running marker: a bar on the *inner* edge, not a dot */
html[data-dock-position="left"] .crea-os-dock-dot {
  border-radius: 0;
  width: 3px;
  height: 28px;
}

A macOS shelf — translucent, blurred, and a little round

Nothing in the app casts a shadow by default; a shelf is the one object that earns one, and a theme is exactly where that argument belongs. backdrop-filter needs no content policy change — it reads the pixels behind the element, it does not fetch anything.

nav.crea-os-dock {
  background: color-mix(in srgb, var(--rail-bg) 55%, transparent);
  backdrop-filter: blur(18px) saturate(160%);
  border: 1px solid rgba(255 255 255 / 0.18);
  border-radius: 18px;
  box-shadow: 0 10px 30px rgba(0 0 0 / 0.35);
}
nav.crea-os-dock .crea-os-dock-entry {
  border-radius: 12px;
  transition: transform 120ms ease-out;
}
nav.crea-os-dock .crea-os-dock-entry:hover {
  transform: translateY(-2px);
}

Blurred, transparent sidebars

The two drawers are siblings of the desk, not of any window, so a translucent sidebar shows the canvas through it — and the same treatment on both sides is one rule, because the hook is shared and the side is an attribute:

.crea-dock-aside {
  background: color-mix(in srgb, var(--sidebar-bg) 72%, transparent);
  backdrop-filter: blur(14px);
}
/* the right drawer reads a shade cooler than the two on the left */
.crea-dock-aside[data-dock-side="right"] {
  background: color-mix(in srgb, var(--sidebar-bg) 60%, #0b1220);
}

🔴 Two things a theme must not do here. It must not set --dock-radius, --dock-span, --dock-depth, --navrail-radius, --navrail-span, --sidebar-radius or --icon-rail at :root — the app writes those inline from the writer's own pickers, and a stylesheet that wins over them makes a live control do nothing. And it must not remove overflow: hidden from the bar: that property is what clips a fill to the radius the writer chose. Scope to nav.crea-os-dock, .crea-navrail, .crea-dock-aside or an entry's data-rail-code, and both stay true.

A theme that wants its paper to look floating specifically — a card on the desk rather than a panel fixed to the wall — says so with the attribute, so an attached sidebar keeps its own treatment:

/* only while the writer has them floating (Sidebar › Float the sidebars) */
html[data-sidebar-float="on"] .crea-dock-aside {
  background: var(--sidebar-bg);
  box-shadow: 0 2px 0 color-mix(in srgb, var(--border) 45%, transparent);
}

🔴 Do not paint the gap yourself. A floating panel's inset is --sidebar-gap; on the left the app adds --dock-edge and on the right --dock-edge-right, in either float state, so a sidebar clears a dock parked on the edge it is drawn from. Every one of those is read by unlayered rules in the app's own stylesheet; a theme that writes inset or left on the drawer overrules the dock's own width and the two objects land on each other — the one thing the geometry exists to prevent.

A floating navrail, in the other layout

The default layout's rail is the same furniture as the dock, so it takes the same four answers — Customisation › Navrail — with the opposite defaults: attached, full height, start. Its body is .crea-navrail, and a theme reaches it by attribute rather than by overriding the writer's numbers:

/* only while the writer has the navrail floating (Navrail › Float the navrail) */
html[data-navrail-float="on"] .crea-navrail {
  background: color-mix(in srgb, var(--rail-bg) 88%, transparent);
  backdrop-filter: blur(12px);
}

/* a fitted strip is as long as its codes; a full-height one has length to place them in */
html[data-navrail-fill="fit"] .crea-navrail {
  align-self: start;
}
html[data-navrail-align="end"] .crea-navrail-body {
  justify-content: end;
}

🔴 The rail keeps its box in the flow. A floating navrail is a margin and a frame, not an absolutely positioned overlay: the rail is the shell's first flex child, so taking it out of the flow would paint it over the desk instead of pushing the desk across. A theme that makes it position: absolute will bury whatever window sits at the left edge — and it will look correct in a project with no windows open.

12Icon packs

Customisation › Icon packs. A pack is a zip bundle installed from a URL to .genesis/icons/.packs/<id>.zip, with a central-directory index beside it (<id>.json). Downloading that zip is the only network request the app makes outside its own media scheme, it is a plain GET, and it goes to a file: nothing is installed or executed at render time.

An icon the writer chooses is extracted once to .genesis/icons/<pack>/, and its whole entry path is kept in the filename (outline--book.svg) because packs routinely ship an outline and a filled copy of the same name. Removing a pack deletes the bundle and keeps the picks — a zip is cache, the picked files are the writer's, and deleting them would strip the glyph from every row wearing one.

Lucide is built in and is not a pack: it has nothing to download and cannot be removed. A pack's preview SVG is sanitised twice — once on the way in, once before it reaches the DOM — because an icon is markup and a pack is a file from the internet.

13CSS themes — a stylesheet you author

The theme table edits values Crea knows about. A CSS theme is the other half of that idea: a stylesheet, written by hand, that re-points the app's tokens. One folder per theme, one file inside it.

.genesis/themes/retroma/theme.css

/* @name Retroma */
:root,
[data-theme="dark"] {
  --bg: #241c22;
  --surface: #32272f;
  --surface-elevated: #402f3b;
  --border: #54404d;
  --text-primary: #f2e2ea;
  --accent: #f08bb5;
}

[data-theme="light"] {
  --bg: #f0dae5;   /* the same theme answers both halves */
  --surface: #fdfafc;
  --text-primary: #3a2a31;
  --accent: #d55c8c;
}

A theme folder id may only use a–z, A–Z, 0–9, space, _ and -. Anything else is not listed, because the id is used as a folder name and a name is a promise. A folder with no theme.css is skipped rather than listed as a broken entry: the list is what can be applied.

Installing one

1. Settings › Project › Theme, then Open CSS themes folder.
2. Drop the theme's folder in — <id>/theme.css, one level down.
3. Press Rescan. It appears under CSS themes in the same dropdown as Genesis and your saved looks.
4. Pick it. To go back, pick Genesis — deleting the folder is not required.

🔴 Nothing in the interface prints that path except this button. .genesis is hidden from the file tree, refused by the generic filesystem bridge, and .genesis/themes/ is dot-prefixed inside a dot-prefixed folder — so without one door the writer would have no way to install a theme at all. The button creates the folder if it is missing, so the first press opens an empty one rather than failing.

14The three layers

Every colour in Crea resolves through three layers, lowest first. Each is a place a value can come from, and knowing the order is the whole of authoring one.

1. Base tokens — src/index.css, :root and [data-theme="dark|light"]. What an untouched project wears.
2. Your theme's CSS — the file above, injected verbatim as one <style id="crea-theme-css"> element.
3. The writer's colour pickers — the --project-* variables the Theme table writes inline on <html>.

The utilities are what make this work without any component knowing: every Tailwind colour is mapped to var(--project-*, var(--token)) in one @theme inline block, so bg-surface reads all three layers and cannot be pointed anywhere else.

15What a theme may say

The authoring surface is the nine palette tokens from §2:

--bg  --surface  --surface-elevated  --border
--text-primary  --text-secondary
--accent  --electric  --danger

Everything else in the interface is a projection whose default already points at one of those nine:

So re-pointing the nine recolours the whole application — rail, header, footer, both sidebars, every field, every button, the scroll bar and every window frame — and it keeps doing so as the interface grows, because no utility name is involved.

A theme may also re-point a chrome name directly (--rail-bg, --btn-save-bg, …) when it wants, say, a rail that is not its --surface. Read the warning below first.

A theme may style anything else too — spacing, borders, type, states, even ::selection. Tokens are what survive a change to the interface; a rule aimed at a class is a rule that stops matching the day the class is renamed — with one deliberate exception: the rail's and the dock's hooks are published for this. .crea-rail-entry, the two slots, data-rail-code / data-rail-kind / data-rail-live and the --rail-*-display pair are a contract you may build on — and so are nav.crea-os-dock, .crea-os-dock-body, .crea-os-dock-entry, .crea-os-dock-dot, .crea-dock-slot, .crea-dock-aside with data-dock-side, and the --dock-* names — see §11 and §11.1. That is what makes a dock you can redesign rather than a dock you can only recolour: a taskbar, a launcher and a shelf are one skeleton under three stylesheets.

Both halves, in full

Declare every token you mean in each half. :root matches a light document as well, and :root and [data-theme="light"] tie on specificity, so a token set only in the dark block would leak into the light one.

16Rescan, reset, limits

Reset means "no override"

A CSS theme has no customisation block to be a reset baseline, and it does not need one. Each Reset to default in Customisation writes null, which removes the --project-* override — and the value underneath is your theme's colour. "Reset to this theme's value" and "stop overriding" are the same act, so the reset machinery had to learn nothing about CSS themes.

When a theme is read

A theme is read when it is picked, when the project opens, and when you press Rescan — not while you type. A half-written stylesheet repainting the interface on every save would show a look that never existed. Rescan re-lists the folder and re-reads the theme currently on screen, which is the whole authoring loop: edit theme.css, press it, look. It is also the only way to re-read a file that was deleted and restored behind the project's back.

Switching projects drops the stylesheet first

A window outlives the realm it is showing — that is what makes switching projects instant — so the injected element is removed before the new realm's preferences are read. Left behind, one project's theme would paint the next one until the read resolved, and for ever if it failed.

A missing theme is an error, not an empty stylesheet

If the folder is gone, reading it fails rather than answering "" — an empty stylesheet is indistinguishable from a theme that changes nothing, so the writer would see the previous theme still on screen with no reason why. The app removes the element and keeps its own look instead.

What is not permitted

A theme is not sanitised — it is a local file installed on purpose, and CSS is the point. What constrains it is the document's own policy: style-src 'self' 'unsafe-inline' with no remote origin, and img-src / font-src limited to self, data:, blob: and crea-media:. So a theme may be as opinionated as it likes about colour, spacing and type, and an @import from the internet, a remote url() or a web-font fetch simply will not load.

17Worked example: Retroma

A complete theme ships beside this guide, in the Crea folder itself — not inside a realm, so nothing is applied until you copy it in:

Crea/themes/retroma/theme.css

Copy the retroma/ folder into <realm>/.genesis/themes/ and pick Retroma under CSS themes. It is a pastel-retro look after the Retroma theme for Obsidian: a pink gingham desk, near-white paper panels with a mauve hairline, deep maroon ink, and buttons that look like they can be pressed. Daylight is bubblegum and cream; night is plum and rose.

It names the nine palette tokens plus --on-electric, --success and --warning — the tokens with no --project-* counterpart — and it names no projection at all, so every picker in Settings keeps working on top of it. The two exceptions to that caution are deliberate and safe: --dock-gap and --sidebar-gap at :root, which the app never writes inline, so there is no picker for them to win over (§11.1).

Two things in it are worth copying as habits. Its --on-electric is dark in the night half, because #8f97e8 is light enough that white text on it fails contrast — the button group is a pair, and a theme that sets a fill without its ink has a button nobody can read. And it paints ::selection from --accent, so selecting text is rose in both halves instead of the system's blue.

A third habit is the desk texture, and it is the one rule in the file that is shape rather than colour. .crea-window already carries bg-bg, so a background-image there is drawn over the token rather than replacing it: three radial-gradients — a 1.5px dot every 16px, a second dot offset half a cell, and one soft star every 180px at a few percent — make the gingham and its confetti with no image file and no request. The colour the writer picked still shows underneath, and the bg row in the theme table still moves. A backdrop-filter would have been the wrong channel here: the desk is the furthest thing back and there is nothing behind it to blur.

The rail and the dock are treated as surfaces. The codes are letterpressed (letter-spacing plus a 1px highlight text-shadow), the live entry wears the rose, the marks are drawn at stroke-width: 1.75 because two-pixel strokes read as bled ink on pale paper, and one entry is scaled from --icon-rail with a calc() multiple rather than pinned to a literal, so Dock icons still reaches it. It deliberately leaves the sizes on :root alone — those belong to the writer's pickers — and the commented-out display swap at the end of the rail section is the invitation: uncomment --rail-code-display / --rail-mark-display and the navrail becomes a dock in both layouts. That is §11's contract doing its job.

The dock is a shelf of pressable chips: a pale pink tray with an inset top highlight and an inset bottom shade, which is what makes it read as pressed tin rather than as a rectangle; a 4px corner on each entry; and a live entry held down — rose text on a rose wash with the highlight moved to the bottom edge. Its marker is a square pip, because a round dot beside letterpressed type would be the one shape in the theme that came from somewhere else. It is all §11.1's hooks, and it touches none of the writer's position, radius, float, width or icons position.

The floating sidebars get the paper, the app gets the geometry. The panels float in os unless the writer attached them, so the theme's sidebar rules are keyed on html[data-sidebar-float="on"]: a card with a soft inner rule and a shade along its bottom, and the heading strip painted in --surface-elevated — the pink title bar Retroma draws on every box. It never writes inset or left, because the inset is --sidebar-gap and the app adds --dock-edge on the left and --dock-edge-right on the right, so a panel clears a dock on either edge whether it floats or is attached.

Two further desks are written out at the end of the file and commented out — a Windows-style taskbar (set Dock width → Full width, untick Float the dock, then Dock icons position) and an Ubuntu-style left launcher — because a published contract is only worth publishing if the file that uses it shows how far it goes.

18Folder colours are not a theme

.genesis/folder-colors.json is { palette, folders }: a named palette the writer assigns to individual files and folders from Change color. That is content — "this folder is the red one" — and it is deliberately separate from the theme.

The separation is visible in the controls: a folder colour is chosen from a grid of named swatches, while every colour in the Theme table is a wheel with a hue/saturation disc, a value slider and a hex field. Interface customisation is not a palette pick, and a project with three folder colours must not be able to paint only three of its own tokens.

Absence is the flag: a folder with no entry existed before Crea and renders grey; a folder Crea created has an entry and renders white until recoloured. Removing a palette entry leaves the folders that used it falling back to grey, rather than uncolouring them.

19Files and channels

The renderer has no filesystem access. Everything here goes through the preload bridge, and .genesis is refused by the generic file channels on purpose — each kind of state has its own, so a malformed path cannot wander into one and a bad write cannot corrupt another.

Every JSON write is atomic: Crea writes a sibling temporary file and renames it over the target. A plain write truncates first and writes second, so a process that dies between the two leaves a zero-byte file — and an empty layout does not complain, it silently throws the writer's desk away and restores blank screens.

🔴 .genesis is not live-watched, on purpose. The app rewrites its own layout inside it on every change, so treating those events as the writer's work would be pure churn — and patching a file tree for a preference makes a sidebar redraw for a reason nobody can see. What follows is that a font or theme dropped in from a file manager appears the next time the picker opens (fonts) or when you press Rescan (themes), rather than instantly. Both lists are re-read at exactly those moments for this reason.

Crea · local-first · no server, no database, no network