# Colour

> Foundations · Tetrifox Brand Book · https://design.tetrifox.com/foundations/colour

## Purpose

Disciplined raw material becomes meaning through semantic tokens. Dark-first, accessible, and precise enough that orange signals without becoming the field.

## Rules

### Must

- **Design dark-first. `:root` is the canonical dark field; `.light` is an opt-in inverse applied as a class on `<html>`.** The brand is built on a dark field. Light is proof that the tokens invert cleanly, not a second identity. Tokens: `--background`, `--foreground`. [Dark-first palette](https://design.tetrifox.com/foundations/colour#palette) · `colour.dark-first`
- **Reach for a semantic token first. Use a raw ramp step only when no semantic role fits.** Semantic tokens follow the active theme and carry intent; a ramp step is fixed raw material. [Ramps](https://design.tetrifox.com/foundations/colour#ramps) · `colour.semantic-first`
- **Use the fixed, theme-independent status colours for error, success and warning. The green ramp is brand-positive, not a status colour.** Status must read the same in both themes; brand green stays a ramp used sparingly. Tokens: `--color-error`, `--color-success`, `--color-warning`. [Ramps](https://design.tetrifox.com/foundations/colour#ramps) · `colour.status-colours`
- **Bind every interface colour to a semantic role — field, ink, layer, divider, state or signal — so it follows the active theme.** Roles are what invert between themes; the role name also tells the next reader why the colour is there. Tokens: `--background`, `--foreground`, `--surface`, `--border`, `--muted`, `--text-accent`. [Semantic tokens](https://design.tetrifox.com/foundations/colour#semantic-tokens) · `colour.bind-to-role`
- **Reserve orange for actions, focus, labels (the eyebrow) and text selection.** Orange is the signal; each use points at something. Tokens: `--text-accent`, `--color-brand-600`, `--color-brand-500`. [Accent restraint](https://design.tetrifox.com/foundations/colour#accent-restraint) · `colour.accent-uses`
- **Show one primary (orange) button per view; use secondary or link buttons for every other action.** Two orange actions cancel each other out. Tokens: `--color-brand-700`. [Accent restraint](https://design.tetrifox.com/foundations/colour#accent-restraint) · `colour.one-primary-action`
- **Text must clear WCAG AA against its ground: 4.5:1 for body text, 3:1 for large text (24px and up, or 18.66px bold).** Contrast is a measurable consequence of every colour choice. Tokens: `--foreground`, `--muted-foreground`, `--background`. [Contrast (AA)](https://design.tetrifox.com/foundations/colour#contrast) · `colour.text-aa`
- **Verify contrast in both themes. Each theme carries its own accent step, so a verdict in dark says nothing about light.** `--text-accent` resolves to a lighter step on the dark field and a darker step on white. Tokens: `--text-accent`. [Contrast (AA)](https://design.tetrifox.com/foundations/colour#contrast) · `colour.measure-per-theme`

### Must not

- **Hardcode hex values in components, or introduce colours outside the four ramps and the fixed status colours.** A literal cannot follow the theme or be traced back to a decision. [Ramps](https://design.tetrifox.com/foundations/colour#ramps) · `colour.no-hardcoded-hex`
- **Use brand orange as a field, a large fill, or body copy.** A flooded surface leaves nothing to point at, and white body text on `--color-brand-600` does not clear AA. Tokens: `--color-brand-600`. [Accent restraint](https://design.tetrifox.com/foundations/colour#accent-restraint) · `colour.accent-not-field`

### Prefer

- **Separate layers with semantic surfaces and borders before reaching for another hue.** _(Extension)_ Depth comes from the surface ladder; a new hue competes with the one accent that is allowed to signal. Tokens: `--surface`, `--surface-alt`, `--border`. [Dark-first palette](https://design.tetrifox.com/foundations/colour#palette) · `colour.depth-before-colour`
- **Use cyan sparingly, as a secondary signal. Its documented anchor is the motion bloom of the pattern background.** Cyan is the counterpoint to orange, not a second accent. Tokens: `--color-cyan-400`, `--field-bloom`. [Ramps](https://design.tetrifox.com/foundations/colour#ramps) · `colour.cyan-signal`
- **In Tailwind, use the aliased utilities — `bg-background`, `bg-surface`, `text-primary`, `text-secondary`, `text-tertiary`, `text-accent`, `border-border` — rather than ramp utilities.** The aliases resolve to the semantic layer through `@theme inline`, so components stay theme-aware without extra classes. Tokens: `--color-primary`, `--color-secondary`, `--color-tertiary`, `--color-accent`. [Semantic tokens](https://design.tetrifox.com/foundations/colour#semantic-tokens) · `colour.tailwind-aliases`
- **Judge accent restraint by role — one action, labels, focus — not by a coverage percentage. The book sets no numeric budget for orange.** _(Extension)_ A percentage would be an invented fact; the Images grade reports warm coverage as evidence, never as pass or fail. [Accent restraint](https://design.tetrifox.com/foundations/colour#accent-restraint) · `colour.no-accent-budget`
- **Keep accent text to short labels and links. Prose stays on the foreground and secondary inks.** _(Extension)_ The accent passes AA in both themes, so this is restraint, not contrast: a paragraph of orange stops signalling. Tokens: `--text-accent`, `--foreground`, `--muted-foreground`. [Incorrect usage](https://design.tetrifox.com/foundations/colour#incorrect-usage) · `colour.accent-short-labels`

## Tokens used

| Token | Dark (`:root`) | Light (`.light`) |
| --- | --- | --- |
| `--background` | `#0a0d12` | `#ffffff` |
| `--foreground` | `#f5f7fa` | `#12181f` |
| `--surface` | `#1f2933` | `#f5f7fa` |
| `--surface-alt` | `#323f4b` | `#e4e7eb` |
| `--border` | `#1f2933` | `#cbd2d9` |
| `--color-error` | `#dc2626` | `#dc2626` |
| `--color-success` | `#16a34a` | `#16a34a` |
| `--color-warning` | `#d97706` | `#d97706` |
| `--color-cyan-400` | `#2bc4f0` | `#2bc4f0` |
| `--field-bloom` | `#2bc4f0` | `#10add9` |
| `--muted` | `#a0abb7` | `#616e7c` |
| `--text-accent` | `#ff9163` | `#a63c09` |
| `--color-primary` | `#f5f7fa` | `#12181f` |
| `--color-secondary` | `#cbd2d9` | `#52606d` |
| `--color-tertiary` | `#a0abb7` | `#616e7c` |
| `--color-accent` | `#ff9163` | `#a63c09` |
| `--color-brand-600` | `#ea580c` | `#ea580c` |
| `--color-brand-500` | `#f97316` | `#f97316` |
| `--color-brand-700` | `#c94a0a` | `#c94a0a` |
| `--muted-foreground` | `#cbd2d9` | `#52606d` |

## Do / Don't

- **Signal, not surface.** Do: The field stays neutral; orange marks one deliberate action. Don't: The accent becomes the environment and body contrast collapses.
- **Meaning, not a literal.** Do: The semantic alias keeps the component tied to its role. Don't: A raw value cannot follow the active theme or communicate intent.
- **Readable, not merely branded.** Do: Foreground carries prose; accent remains a short label. Don't: Brand orange as body copy on white reaches AA-large at best.

## Related chapters

- [Typography](https://design.tetrifox.com/foundations/typography.md)
- [Iconography](https://design.tetrifox.com/foundations/iconography.md)
- [Components](https://design.tetrifox.com/expressions/components.md)
