# Color

Use Arrow color **tokens** (`--tdds-color-*`) and **utility classes** (`tdds:color-*`, `tdds:background-color-*`) — never hardcoded hex. Tokens auto-flip in inverse (dark) mode; hex values do not.

## Philosophy

- **Semantic over literal.** Pick a token by intent (`status-critical`, `brand-primary-400`) — not by appearance ("magenta", "#e20074").
- **Inverse-aware by default.** Tokens like `fill-on`, `text-on`, `border-on` automatically flip when inside `<ArrowThemeProvider inverse>`. They are the safest choice for surfaces and inverse-aware UI.
- **Brand-primary 400** is T-Mobile Magenta — the brand's signature color.

## Token families

| Family | Tokens | Use for |
|--------|--------|---------|
| Grayscale | `--tdds-color-brand-grayscale-{white,100,200,300,400,500,600,700,800,900,1000,black}` | Neutral surfaces, text, borders |
| Brand primary (Magenta) | `--tdds-color-brand-primary-{100..600}` | Calls-to-action, brand accents (e.g., 400 = T-Mobile Magenta) |
| Brand secondary | `--tdds-color-brand-secondary-{100..600}` | Supporting brand color (token-only, no utility class) |
| Brand highlight | `--tdds-color-brand-highlight-{100,200,400,600}` | Promo / highlight emphasis (token-only) |
| Status — positive | `--tdds-color-brand-status-positive-{100..400}` | Success, confirmation |
| Status — caution | `--tdds-color-brand-status-caution-{100..400}` | Warnings |
| Status — critical | `--tdds-color-brand-status-critical-{100..400}` | Errors, destructive states |
| Status — info | `--tdds-color-brand-status-info-{100..400}` | Informational notices |
| Surface adaptive | `--tdds-color-fill-on`, `--tdds-color-text-on`, `--tdds-color-border-on` | Inverse-aware fill/text/border |

## Utility classes

| Class | Effect |
|-------|--------|
| `tdds:color-grayscale-{level}` | Sets text `color` to grayscale token |
| `tdds:background-color-grayscale-{level}` | Sets `background-color` to grayscale token |
| `tdds:color-primary-{100..600}` | Text in brand primary |
| `tdds:background-color-primary-{100..600}` | Background in brand primary |

Secondary, highlight, and status families are **token-only** (no utility class). Apply via `style={{ color: 'var(--tdds-color-brand-status-critical-300)' }}` only when no component prop or status-aware component (e.g., `NoticeBar variant="error"`) covers the case.

## Decision tree

| Need | Use |
|------|-----|
| Inverse-aware text on any surface | `var(--tdds-color-text-on)` |
| Inverse-aware background | `var(--tdds-color-fill-on)` |
| Inverse-aware border | `var(--tdds-color-border-on)` |
| Page background, neutral surface | `tdds:background-color-grayscale-100` (or 200) |
| Body text on light | `tdds:color-grayscale-1000` |
| Body text on dark | `tdds:color-grayscale-white` (or wrap in `<ArrowThemeProvider inverse>` and use `text-on`) |
| Primary CTA | Use `<Button variant="primary">` — do not paint manually |
| Brand magenta accent | `var(--tdds-color-brand-primary-400)` |
| Success / error / caution / info messaging | Use `NoticeBar` or `StatusLabel` with the matching `variant` |

## Common mistakes

- **DON'T** hardcode `#e20074` (magenta) — use `var(--tdds-color-brand-primary-400)`.
- **DON'T** add a `dark-mode` CSS file — set `inverse` on the provider or component instead.
- **DON'T** invent token names. Every token starts with `--tdds-color-brand-` or `--tdds-color-{fill|text|border}-on`.
- **DON'T** use status colors for decoration. Reserve them for actual status messaging.
- **DON'T** repaint a Button — use `variant="primary" | "secondary" | "tertiary"`.
