# 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).