Themes: pick a look, or bring your own.

A theme is one small JSON file. It carries colours, type, shape, look and a terminal palette. ColliePWA ships four of them, and you can import more from a file on your phone.

01/What it is

A theme is a file of looks.

A theme names the colours of the app, once for a light half and once for a dark half. It can also name a typeface, a face for titles, a shape, a look and the colours of the terminal mirror. Shape and look are ten words, such as radius, shadow and density. The layout, the tap sizes and the meaning of a status stay as they are, so blocked is still blocked in every theme.

Every value in a file is a closed word or a checked colour. The file cannot run code, and it cannot load a file, a font or an image.

A theme and Appearance are two settings. The theme says which colours to use. Appearance says which half to show: System, Light or Dark.

02/Pick

Pick a theme in Settings.

Open Settings, then Appearance, and tap a theme. It applies at once, with no reload, and the next time you open ColliePWA the first frame is already in that theme. One tap on Collie brings the default back.

A theme that names a typeface sets your typeface once. You can still change it afterwards in the Typeface card.

Collie

Typeface: Aldrich

The look you know: neutral greys, with Aldrich for the type.

Nightwatch

Typeface: IBM Plex Sans

flat · bold · strong · band · heavy

For the phone on call at night. A true black dark half, flat and square, with heavy lines, a dim amber accent and a dim amber band behind the header and the bars.

Terminal palette

Daylight

Typeface: Geist

Titles: Atkinson Hyperlegible Next

round · lifted · roomy · gradient · cards · sentence

For bright sun and low vision. Body text at AAA contrast, round roomy cards, a page that shifts toward the foot, and status colours that run from blue to orange, not from red to green.

Terminal palette

Harbour

Typeface: Atkinson Hyperlegible Next

Titles: Space Grotesk

soft · lifted · grain · thin

For people who come from the terminal. Cool blue-grey with one teal accent, soft corners, a fine grain and thin icons, and a Solarized-based terminal palette on a near-black blue.

Terminal palette

03/Import

Import a theme from a file.

1Put a theme file on your phone. It ends in .json and is smaller than 64 KiB.
2In Settings, open the Theme card under Appearance, tap Import and choose the file.
3Read the preview. It shows the colours of both halves, the shape, the terminal colours and a contrast report. A weak contrast shows a warning, and you can still apply the theme. A file that breaks the rules is refused, and nothing changes.

A theme changes how the app looks and nothing else. It cannot run code, load files or reach a server.

A device keeps up to eight imported themes. There is no import from a link, and themes do not sync between devices.

04/Write

Write your own.

The quickest start is a shipped theme. Export it, change id and name, edit the colours, the shape words or the terminal palette, and import it again. An imported theme cannot use the id of a shipped theme.

This is a shortened harbour.json, a version 2 file. The ... lines stand for the parts left out.

{
  "version": 2,
  "id": "harbour",
  "name": "Harbour",
  "author": "Collie",
  "light": {
    "background": "oklch(0.95 0.01 235)",
    "foreground": "oklch(0.26 0.025 250)",
    "card": "oklch(0.985 0.004 235)",
    "...": "..."
  },
  "dark": {
    "background": "oklch(0.21 0.018 250)",
    "foreground": "oklch(0.93 0.012 240)",
    "card": "oklch(0.255 0.02 252)",
    "...": "..."
  },
  "fonts": { "ui": "atkinson", "display": "grotesk" },
  "surface": {
    "radius": "soft",
    "shadow": "lifted",
    "density": "default",
    "weight": "default",
    "border": "default",
    "ground": "grain",
    "chrome": "page",
    "rows": "rules",
    "icons": "thin",
    "labels": "caps"
  },
  "ansi": {
    "0": "#073642",
    "1": "#f0504a",
    "2": "#859900",
    "...": "..."
  }
}

The 43 tokens

A theme file may name only these tokens, in four groups. A file with any other key is refused.

Group	What it paints	Tokens
Surfaces and inks21	The page, cards, chrome, text, buttons, borders and the focus ring.	`background` `foreground` `card` `card-foreground` `chrome` `primary` `primary-foreground` `secondary` `secondary-foreground` `muted` `muted-foreground` `accent` `accent-foreground` `control-on` `control-on-foreground` `destructive` `destructive-foreground` `border` `input` `rule` `ring`
Status6	The agent states and the info colour.	`status-blocked` `status-working` `status-done` `status-idle` `status-unknown` `status-info`
Syntax6	The inks in diffs and code.	`syntax-keyword` `syntax-string` `syntax-constant` `syntax-property` `syntax-entity` `syntax-comment`
Host identity10	The colours that tell your machines apart.	`host-0` `host-1` `host-2` `host-3` `host-4` `host-5` `host-6` `host-7` `host-8` `host-9`

Shape and look

The surface block holds ten words. Each one comes from a closed list, and a token you leave out keeps its default, the first word of its list. A free number is never accepted, so a theme cannot break a tap size.

radius: The corner of a card, a row, a field and a button.
sharp
soft
round
shadow: The shadow under raised panels.
default
flat
lifted
density: How much room sits inside and between controls.
default
roomy
weight: How heavy medium and semibold text draws.
default
bold
border: The width of a hairline.
default
strong
ground: The page behind everything: flat, a soft gradient or a fine grain.
flat
gradient
grain
chrome: The header and the bars: on the page colour, or on a band of their own.
page
band
rows: A list as one framed group with rules, or as a card for each row.
rules
cards
icons: The stroke width of every icon.
default
thin
heavy
labels: Small section labels, in capitals or in sentence case.
caps
sentence

Terminal palette

The ansi block holds 18 colours or none: the 16 terminal colours, ink and ground. Each is #rrggbb or oklch(L C H), and each passes a gate.

Values: A value is a colour: #rrggbb, #rrggbbaa or oklch(L C H), with / A for opacity. L runs from 0 to 1, C from 0 to 0.5 and H from 0 to 360, all as plain numbers.
Halves: Give light, dark or both. A half you leave out is filled from Collie, token by token.
Typefaces: The optional fonts.ui names one of the typefaces that ColliePWA bundles. The optional fonts.display names one for titles. No other font is accepted.
What is refused: A key outside the list, a version other than 1 or 2, a value that is not a colour or a shape word, var(), url() or any other function, the id of a shipped theme, and a file over 64 KiB. The message names the cause, and nothing is applied.
Version: version is 1 or 2. A file with a surface block, a fonts.display face or an ansi block says 2. A version 2 file needs ColliePWA 1.22.0 or newer.

05/Share

Export and share.

Export writes the active theme as a .collie-theme.json file. Send it to someone, or keep it in a repository, and they import it the same way you did.

Details in Themes