# Colour

## Purpose

Palette, roles, states and how colour is applied.

## Decisions

- **Dark mode is the default**, with a toggle available for light mode. The first visit **matches the person's system setting**, and falls back to dark when the system setting cannot be read. Light mode values are on [Theming](theming.md).
- **Neutral backgrounds use exactly three tiers**, to avoid many shades of grey or blue-grey:
  1. **background** — the default page background
  2. **above-background** — a slightly lighter grey for cards, bars, anything above the background
  3. **background-accent** — an even lighter grey for 1px borders and separator lines on those

**Background palette:** a deep, slightly warm neutral.

| Tier | Hex |
|---|---|
| background | `#0e0d0c` |
| above-background | `#171615` |
| background-accent | `#272523` |

**Primary text colour: soft white `#f2f2f2`.** Contrast: 17.3 on background, 16.1 on above-background, 13.6 on background-accent.

**Secondary (grey) text colour: `#8c8c8c`.** Contrast: 5.8 on background, 5.4 on above-background, 4.5 on background-accent. Contrast between primary and secondary text is 3.0.

**Active tab fill: above-background `#171615`**, so the highlighted tab matches the surface it joins. Inactive tabs use background `#0e0d0c`.

### Interaction states

Neutral surfaces and controls move through the tiers. **A fourth fill tier, `#322f2c` is used for the pressed state**.

| State | Neutral surface (menu item, row, tab) | Violet primary button | Outlined Warn / Delete |
|---|---|---|---|
| Rest | tier of its container | `#7520ff` | above-background `#171615` fill, coloured border and label |
| Hover | background-accent `#272523` | `violet-600` `#5f03d5` | fill `#272523`, border and label unchanged |
| Pressed | fourth tier `#322f2c` | `violet-700` `#4801a5` | fill `#322f2c`, border and label unchanged |
| Disabled | | fill `#37156d`, text `#757473` | border and label `#6e0827` (red-pink) darkened toward the background |

- **Selected:** a violet `#7520ff` fill with soft white text (contrast 5.5).
- **Disabled:** each control keeps its own colour but darkened toward the background (60% for fills and borders, 55% for text). Disabled field text is `#4d4c4c`.
- **Focus ring:** concentric, 2px gap then a 2px ring in lighter violet `#a169fa` (contrast 5.5 on the background).
- **Text field:** hover border `#322f2c`, focus border violet `#7520ff`, error border red-pink `#ff0050` with a red-pink icon (not text), disabled border unchanged with dark text.
- **Off / unchecked:** switch off is a background-accent `#272523` track with a grey `#8c8c8c` thumb; an unchecked checkbox has a 1px `#272523` border on the background fill.

### More states, semantic colours, links and gradient uses

- **Selected item hover and pressed:** the same as the primary button: hover `violet-600` (`#5f03d5`), pressed `violet-700` (`#4801a5`).
- **Trackpad card bottom buttons:** neutral segments use smaller steps, hover `#171615` and pressed `#272523`; the violet segment uses the standard violet hover and pressed.
- **Tabs:** inactive tabs have short `|` separators. A hovered inactive tab fills with background-accent `#272523`, with rounded top corners (8px) and a square bottom.
- **Success colour:** emerald `#34d399` (contrast 10.1 on the background). A new colour outside the signature three.
- **Info colour:** blue `#3b9eff` (contrast 7.0 on the background). A new colour outside the signature three.
- Success and info follow the same rule as danger and warning: the colour is on the icon and the border, and the text stays soft white and grey.
- **Links:** lighter violet `#a169fa`, underlined. Visited links stay orange `#ff8000` after being clicked.
- **Gradient uses:** progress bar fills, card borders, avatar/logo rings and the spinner. Linear gradients are at **135°**. The card border, avatar ring, and similar highlight treatments are for premium or highlighted things only, not everywhere: a featured card (linear 135°), a highlighted button outline and a highlighted tag (linear 135°), and an avatar ring using the **conic** gradient. The gradient is not used for dividers, heading text, button fills or glow.
- **Spinner:** the full ring in the conic gradient with the order reversed so it spins clockwise, the solid red at the head with a rounded (semicircular) cap, and the faded tail behind it: `conic-gradient(#ff005000 0%,#7520ff 23.333%,#ff8000 56.666%,#ff0050 90%,#ff0050 100%)`, with a red `#ff0050` cap the width of the ring at the head. Rotates clockwise (positive rotation).

### Signature colours

Three important colours are included in the language. **Violet is the primary colour.** Red-pink is the danger colour and orange is the warning colour.

| Role | Name | Hex |
|---|---|---|
| **Primary** | Violet | `#7520ff` |
| Danger | Red-pink | `#ff0050` |
| Warning | Orange | `#ff8000` |

Primary text on the primary colour (soft white `#f2f2f2`) has contrast 5.5. The primary colour against the backgrounds is 3.2 (background) and 2.9 (above-background).

**Applying danger and warning colours:** the colour goes on the **icon and the border**, not on running text. Text may also be coloured for emphasis (see [Principles](../philosophy/principles.md)); running text stays soft white or grey. The exception is a **button**: because its label is a single word, the text may also take the colour (e.g. a Delete button with a red-pink border, icon and "Delete"). Supporting text stays primary or secondary text colour.

Contrast: red-pink is 5.0 on background, 4.6 on above-background and 3.9 on background-accent; orange is 7.7, 7.2 and 6.1. Icons and borders need 3.0 and coloured text 4.5, so coloured button text in red-pink is fine on the background and above-background tiers but not on background-accent.

### Signature gradient

Cycles through the three colours and returns to the start:

```css
repeating-conic-gradient(#ff0050 0%, #ff8000 33.333%, #7520ff 66.666%, #ff0050 100%)
```

**Linear variant:** a non-looping linear version is also part of the language:

```css
linear-gradient(90deg, #ff0050 0%, #ff8000 50%, #7520ff 100%)
```

### Palette extension

The colour system has a full palette of twelve hues with nine steps each; see [Colour Palette](colour-palette.md). Violet hover and pressed use **`violet-600` and `violet-700`** from the palette. White text on them is 7.6:1 and 10.3:1.