# Color

All colours in the design system are expressed as CSS custom properties defined on `:root`. Never use raw hex values in component code — reference semantic tokens instead.

## Semantic Text Colors

| Token | Usage |
|---|---|
| `--text-primary` | Body text, headings — default reading text |
| `--text-secondary` | Captions, helper text, less prominent labels |
| `--text-label` | Form field labels |
| `--text-error` | Error state text |
| `--text-info` | Informational text |
| `--text-success` | Success-state text |
| `--text-warning` | Warning-state text |
| `--text-revision` | Revision / draft state text |
| `--text-primary-disabled` | Disabled primary text |
| `--text-secondary-disabled` | Disabled secondary text |
| `--text-tooltip` | Text inside tooltips (white on dark) |
| `--text-hyperlink---active` | Active link colour |
| `--text-hyperlink---visited` | Visited link colour |

## Semantic Background Colors

| Token | Usage |
|---|---|
| `--container-fills-backgrounds-page` | Page-level background |
| `--container-fills-backgrounds-default-section` | Default section background |
| `--container-fills-backgrounds-nested` | Nested container background |
| `--container-fills-backgrounds-card` | Card background |
| `--container-fills-backgrounds-card-hover` | Card hover state |
| `--container-fills-backgrounds-popover` | Popover / dropdown background |
| `--container-fills-backgrounds-tooltip` | Tooltip background (dark) |
| `--container-fills-backgrounds-semantics-error` | Error-state container fill |
| `--container-fills-backgrounds-semantics-info` | Info-state container fill |
| `--container-fills-backgrounds-semantics-success` | Success-state container fill |
| `--container-fills-backgrounds-semantics-warning` | Warning-state container fill |
| `--container-fills-backgrounds-semantics-neutral` | Neutral-state container fill |
| `--container-fills-backgrounds-semantics-revision` | Revision-state container fill |

## Dividers

| Token | Usage |
|---|---|
| `--dividers-default` | Standard separator |
| `--dividers-dark` | Prominent separator |
| `--dividers-light-stroke` | Subtle separator |

## Glyph Colors

| Token | Usage |
|---|---|
| `--glyphs-default` | Default icon colour |
| `--glyphs-hover` | Icon on hover |
| `--glyphs-focused` | Icon on focus |
| `--glyphs-disabled` | Disabled icon |
| `--glyphs-error` | Error-state icon |
| `--glyphs-info` | Info-state icon |
| `--glyphs-success` | Success-state icon |
| `--glyphs-warning` | Warning-state icon |
| `--glyphs-revision` | Revision-state icon |

## Semantic Palette Scales

Each semantic colour has a full 50–1000 scale. Use specific steps only when building custom components; prefer the semantic tokens above in all other cases.

| Scale | Base Usage |
|---|---|
| `--error-*` | Error / danger states |
| `--warning-*` | Warning states |
| `--success-*` | Success / positive states |
| `--info-*` | Informational states |
| `--revision-*` | Draft / revision states |
| `--gray-*` | Neutral surfaces and text (`--gray-0` = white, `--gray-1000` = near black) |
| `--midnight-*` | Brand accent colour — varies per theme |

## Brand / Midnight Colors

The `midnight-*` scale is **theme-dependent**. Its actual hex values are injected by `ThemeProvider` based on `config.brand`. Use these tokens to express brand-coloured interactive elements.

Common steps:
- `--midnight-50` — very light brand tint (hover backgrounds, selected rows)
- `--midnight-500` — mid-tone brand accent
- `--midnight-650` — primary interactive / focused field stroke
- `--midnight-750` — field focused stroke
- `--midnight-950` — dark nav background

## Form Field Colors

| Token | Usage |
|---|---|
| `--fields-fill-default` | Default input background |
| `--fields-fill-applied` | Input background when value is set |
| `--fields-fill-disabled` | Disabled input background |
| `--fields-stroke-default` | Default input border |
| `--fields-stroke-hover` | Input border on hover |
| `--fields-stroke-focused` | Input border on focus |
| `--fields-stroke-applied` | Input border when value applied |
| `--fields-stroke-error` | Input border in error state |
| `--fields-stroke-disabled` | Disabled input border |

## Table Colors

| Token | Usage |
|---|---|
| `--tables-default` | Default table row background |
| `--tables-header` | Table header background |
| `--tables-hover` | Row hover background |
| `--tables-selected` | Selected row background |
| `--tables-header-selected` | Selected header cell background |

## Sidebar / Nav Colors

| Token | Usage |
|---|---|
| `--sidenav-background` | Navigation sidebar background |
| `--sidenav-hover` | Nav item hover |
| `--sidenav-selected` | Active nav item |
| `--sidenav-text` | Nav item text (white) |

## Decision Tree: Choosing a Color Token

```
Need to color text?
├── Reading text → --text-primary
├── Secondary / helper → --text-secondary
├── Form label → --text-label
└── Semantic state (error/warning/success/info) → --text-{state}

Need a background?
├── Page surface → --container-fills-backgrounds-page
├── Section / card → --container-fills-backgrounds-default-section or -card
├── Semantic state container → --container-fills-backgrounds-semantics-{state}
└── Popover / dropdown → --container-fills-backgrounds-popover

Need a form field border?
└── Use --fields-stroke-{state} tokens

Need a brand colour?
└── Use --midnight-{step} — step 500–750 for interactive elements
```

## Common Mistakes

- Do NOT use raw hex values like `#0070e0`. Always use a CSS token.
- Do NOT use `$gray-900` SCSS variables in new components — use `--text-primary` CSS custom property.
- Do NOT use `--midnight-*` directly for text — use `--text-*` semantic tokens.