# Making a wayBetter for X theme
A theme is a small JSON file. It is data, not a stylesheet: wayBetter turns it into CSS, maps X's
own colors onto yours and keeps every text readable. Import it in **wayBetter → Appearance →
Import**, export any theme (built-in or yours) from the same place.
`npm create waybetter theme -- --name "My Theme" --accent "#3ddc97"` writes a starting file with
the `"$schema"` line and a full palette; **wayBetter → Make → Theme API** shows the active theme's
values and `--wb-*` variables live.
## The smallest theme
Three colors are enough. Every other role (surfaces, borders, muted text, the filled button) is
derived from them with the same proportions the built-in themes use.
```json
{
"$schema": "https://unpkg.com/waybetter/theme.schema.json",
"name": "Midnight Mint",
"author": "you",
"mode": "dark",
"colors": { "bg": "#0b1110", "text": "#e8f3ef", "accent": "#3ddc97" }
}
```
`$schema` is optional; it lets editors such as VS Code complete and check the file (see
[The schema](#the-schema)).
## Everything a theme can set
Every field except `name` is optional. Missing groups keep X's own geometry; values out of range
are clamped, unknown values fall back to the default.
| Field | What it is |
| --- | --- |
| `name`, `description`, `author` | Shown in the gallery (60 / 200 / 60 characters). |
| `id` | `a-z0-9-`, up to 40 characters. Derived from the name when missing. |
| `mode` | `light`, `dark` or `auto`: which way scrollbars and form controls lean. |
| `colors` | `bg`, `text`, `accent` (required when `colors` is present) and optionally `surface`, `elevated`, `border`, `muted`, `inverse` + `onInverse` (X's filled Post/Follow button), `page` (the canvas behind the columns). Six-digit hex only. |
| `font.roles` | Which font goes where (see [Font roles](#font-roles)). |
| `font.family` / `font.tweet` | Shorthand for the interface and post text stacks, kept for older theme files and older apps. They equal `roles.interface` / `roles.post`; when a role is present it wins. |
| `font.scale` | 0.85–1.2, multiplies X's font sizes. |
| `font.weight`, `font.bold` | 300–500 and 500–800, replace X's 400/700. |
| `font.tracking`, `font.leading` | Letter spacing (−0.03–0.06 em), post line height (1.2–1.8, 0 keeps X's). |
| `shape.radius`, `shape.button`, `shape.avatar` | Card radius (0–28), button radius (0–9999), `circle` / `rounded` / `square`. |
| `layout.column`, `layout.sidebar` | Main column (520–820 px) and right column (290–400 px) widths. |
| `layout.density` | `compact`, `default`, `comfortable`. |
| `layout.cards`, `layout.frame` | Posts as separate cards; a frame around the columns. |
| `background` | `{ "kind": "gradient", "from", "to", "angle", "glow"? }`, `{ "kind": "pattern", "pattern": "dots\|grid\|diagonal\|scanlines\|paper\|clouds", "ink", "opacity", "size" }` or `{ "kind": "image", "url": "data:image/…;base64,…", "fit": "cover\|tile", "dim" }` (images up to about 800 KB, embedded, never a remote URL). |
| `effects.motion` | Transition length in ms (0–400). |
| `effects.hover` | `none`, `tint`, `lift`, `glow`. |
| `effects.shadow` | `none`, `soft`, `deep`. |
| `effects.crt` | Scanline/CRT overlay. |
| `css` | Free-form CSS appended last. Edit it in **Appearance → Customize → Theme CSS**; it is exported and saved with the theme. Same trust level as your own Custom CSS; the import dialog says so. |
## Font roles
Every role is `"inherit"` (the default) or its own font. A role that inherits uses the interface
font; the interface itself inherits X's Chirp (and in wayBetter's own window, Geist). An inheriting
`mono` keeps a monospaced face, since code needs fixed-width letters.
| Role | Where |
| --- | --- |
| `interface` | All of X: navigation, buttons, menus. Takes only `family`/`source`; its size, weights and spacing are `font.scale`, `weight`, `bold` and `tracking`. |
| `post` | Post and reply text. |
| `heading` | Display names, profile names, page headings. |
| `numbers` | Like, repost and follower counts. |
| `mono` | Code blocks. |
| `chrome` | wayBetter's window: tabs, address bar, titlebar, the wayBetter panel. |
| `dialog` | Plugin dialogs and toasts (the UI kit). |
A role's own font is `{ "family": [...], "source"?: "google", "weight"?: 100–900, "size"?: 0.75–1.5,
"tracking"?: −0.05–0.1, "tabular"?: true }`. An empty `family` keeps the inherited font and only
changes the rest (e.g. tabular figures for counts):
```json
"font": { "roles": {
"interface": { "family": ["Inter", "system-ui", "sans-serif"], "source": "google" },
"heading": { "family": ["Fraunces", "Georgia", "serif"], "source": "google", "weight": 700 },
"numbers": { "family": [], "tabular": true },
"mono": { "family": ["Geist Mono"] }
} }
```
## Google Fonts
`"source": "google"` means the first family is a [Google Fonts](https://fonts.google.com) family.
X's page blocks web fonts, so wayBetter downloads the font files once (natively, from
`fonts.googleapis.com` and `fonts.gstatic.com` only, Latin and Latin Extended, into its app data)
and loads them into X from bytes; X never requests a font. Cached fonts work offline. Pick them in
any font role (**Appearance → Fonts**, or the **Theme Builder**): the font browser searches the
whole catalog, previews each family live (only the letters shown are fetched), and lets you choose
the weight range (variable fonts) or weights to download. Importing a theme that names Google fonts
asks before downloading anything; until then the rest of its stack is used. Google Fonts are open
source (SIL Open Font License 1.1 or Apache License 2.0; each family's page on fonts.google.com
names its license and designers). **Appearance → Downloaded fonts** lists and removes them.
## Account and pane themes
**Appearance → Where themes apply** gives an account its own theme (every pane of that account)
and any open pane its own theme (also from the pane's ⋯ menu next to Split, or the tab's right-click
menu). A pane's theme wins over its account's, which wins over the app theme. Pane and account
themes are the theme documents as they are; the app theme keeps its customizations. The same switch
decides whether **wayBetter's window** (tabs, address bar, titlebar, panel) takes the theme's colors
and window font, or keeps wayBetter's own Night Ink style; a pane with its own theme gets its own
tab strip and address bar colors.
## Theme Builder
**wayBetter → Theme Builder** edits a theme document with a live preview on your real X panes and
this window (not saved until you save; closing the builder gives every pane its own theme back):
three base colors derive the whole palette (any role can be set by hand), a contrast report shows
every pair X draws with its ratio and can fix them, font roles with the Google Fonts browser,
corners, density, layout, background, effects and theme CSS. Undo/redo (Ctrl+Z / Ctrl+Shift+Z),
**Start from** any theme, **Save as theme**, **Export** (a `.json` with `$schema`) and **Share**
(copies the JSON).
## Theme CSS vs Custom CSS
- **Theme CSS** (Appearance → Customize) belongs to the selected theme: it travels with Export and
"Save as theme". Like every customization, switching to another theme starts clean, so use
"Save as theme" to keep your edits.
- **Custom CSS** (bottom of Appearance) applies to every tab on top of whichever theme is selected.
## Readability is enforced
Whatever you pick, text is kept at 7:1 contrast and muted text, links and the accent at 4.5:1 on
every surface, and button labels stay readable on their buttons. If an imported theme needed
adjusting, the import dialog tells you.
## The schema
`theme.schema.json` in the [`waybetter`](https://www.npmjs.com/package/waybetter) package is the
JSON Schema of this format (draft 2020-12): every field, its type, range, enum and default, the
same limits the app applies on import (it is tested against them). Exports from **Appearance →
Export** carry the `"$schema"` line. Use the published URL above, or a local copy:
```json
{ "$schema": "./node_modules/waybetter/theme.schema.json", "name": "My theme" }
```
The schema is stricter than the importer: a value out of range is an error in your editor, while
the app clamps it (and a wrong color is ignored) when you import the file.
## Plugins follow the theme
Plugins read the active theme through `wayBetter.api.theme` and the `--wb-*` CSS variables, and
their dialogs and toasts (`wayBetter.api.ui`) use its colors, corners and font. See
[PLUGINS.md](./PLUGINS.md#matching-the-theme-apitheme).
## Sharing
A theme is one `.json` file. Share it however you like; whoever imports it sees its name, author
and, if it has any, a warning that it carries custom CSS. To publish it in the wayBetter Store
(), add one folder in a pull request: see
(the steps are also in `docs/STORE.md` in the source repository).