# Theming A theme is a JSON file. It sets values called tokens, the app writes them to CSS custom properties on the document root, and the interface repaints. There is nothing to compile: themes are created and edited from the app, saved to disk, and shared as a single file. This document is the contract. It says what a theme file may contain, what happens to a file that is incomplete or written for an older version of the format, and what each token controls. ## Where themes live Built-in themes ship inside the app. Every theme you create or import is one `.json` file in the `themes` folder of the app config directory, next to the rest of the configuration. Deleting the file removes the theme, and the app falls back to Dark if the deleted theme was the active one. The theme folder is part of the backup manifest, so an app backup carries your themes with it. ## The file ```json { "schemaVersion": 3, "id": "nord", "name": "Nord", "author": "someone", "version": "1.0.0", "colorScheme": "dark", "extends": "dark", "glass": false, "tokens": { "accent": "#88c0d0", "bgCard": "#3b4252" } } ``` | Field | Required | Meaning | | --------------- | -------- | ------------------------------------------------------------------------------------- | | `schemaVersion` | no | Contract version the file was written for. Absent means 1. | | `id` | yes | Stable identifier and file name. Letters, digits, `-` and `_`, 64 characters at most. | | `name` | yes | What the theme is called in the picker. 64 characters at most. | | `author` | no | Free text, shown nowhere but carried through export and import. | | `version` | no | The theme author's own version string. Not the contract version. | | `colorScheme` | yes | `dark` or `light`. Decides the root values and the native form controls. | | `extends` | no | Id of the theme this one inherits from. | | `glass` | no | `true` puts the theme on the translucent surface scale. | | `tokens` | yes | Map of token name to value. Only the tokens the theme cares about. | | `css` | no | Raw CSS applied on top of the theme. See Custom CSS below. | Unknown fields are ignored. Unknown or malformed tokens are dropped, and the rest of the file still applies. ## Versioning and migration `schemaVersion` is the version of this contract, not of your theme. It is bumped when a token is added, removed, or changes meaning. - **1**: the eleven original colour tokens. - **2**: accent and status colours, radii, elevations, density, interface font. - **3**: structure. Surface gradients, border weight and style, avatar shape, focus ring, overlay blur, heading font, line height, letter spacing, label case, font smoothing, animation speed. Version 2 said what a theme was painted with; version 3 says what it is made of. A file with no `schemaVersion` is a version 1 file. It is migrated on load by being pointed at the built-in theme of its own colour scheme, so its eleven colours keep winning and the tokens added since are inherited rather than missing. Nothing is rewritten on disk until you save the theme from the editor. Every later version migrates by doing nothing, which is what the contract is built for: a token a file does not set is resolved from what it extends and finally from the root, and the version 3 roots hold exactly the values the interface used to hardcode. A version 2 theme therefore renders in a version 3 build pixel for pixel as it did before, and the editor does not call it incomplete for saying nothing about its border style. A file that declares a version this build does not know is refused whole, with a message saying it needs a newer accshift. Applying half of it would produce a theme its author never wrote. ## Inheritance `extends` names the theme to take every token this file does not set from. It is what makes a theme a handful of lines instead of a full palette: the two built-in themes loaded from JSON, `midnight` and `glass-dark`, each extend `dark` and override only colours. Resolution walks the chain nearest first, and the built-in root of the document's colour scheme is always the last word. That root is complete by construction, so resolution always produces a complete token set. The chain is capped at eight documents. A cycle, a missing base or a chain that runs past the cap stops the walk and lets the root fill the rest: the theme still paints, and the editor says which base it could not find. ## Custom CSS `css` holds raw CSS, applied after the app stylesheet when the theme is active and removed the moment another theme is selected. It is there for what the tokens cannot express, a spacing tweak or a rule on one specific element, and it is the part of a theme most likely to break: the class names it targets are internal and change between releases. Custom CSS is not inherited through `extends`. A rule written against one theme's markup has no reason to follow every theme that inherits from it. Duplicating a theme copies its CSS instead. Four constructs are refused, and a file carrying one applies with its CSS dropped rather than being rejected whole: | Refused | Why | | -------------- | -------------------------------------------------------------------- | | `@import` | Fetches a remote stylesheet, which tells its author the app started. | | `url()` | Same, through a background image or a font. | | `expression()` | Legacy Internet Explorer construct that evaluates script. | | `` label to every dictionary in `crates/accshift-app/i18n`, and its row to the token reference above. A token whose value is a CSS keyword the author also types into the file, like `ridge` or `uppercase`, keeps that keyword in the editor dropdown untranslated: translating it would name the same thing two ways. Choices that are words of ours, like `cozy` or `circle`, do get a translation. Older files keep working without a migration entry as long as the resolver can fill the new token from the root, which is exactly what version 1 files get. Removing or repurposing a token is what needs real migration work.