# Tokens and roles

`tokens.json` (in `@enma-design/tokens`) is the source of truth. Product code reads the `--e-*` roles; the raw per-theme tokens (`--ember-accent`, `--paper-radius-lg`) exist only so the theme maps can point at them.

## Color roles

Every theme defines every role in light and dark.

| Role            | Variable            | Use                                                                                  |
| --------------- | ------------------- | ------------------------------------------------------------------------------------ |
| `bg`            | `--e-bg`            | The canvas behind everything.                                                        |
| `surface`       | `--e-surface`       | Cards, sheets, the phone frame, table wrappers.                                      |
| `raised`        | `--e-raised`        | Grouped content inside a surface: list groups, inner panels, hover rows.             |
| `field`         | `--e-field`         | Input and secondary-button fill.                                                     |
| `line`          | `--e-line`          | Hairlines between rows and table cells. Decorative, never a control's only boundary. |
| `line-strong`   | `--e-line-strong`   | Control borders: inputs, secondary buttons, unchecked boxes. 3:1 or more.            |
| `ink`           | `--e-ink`           | Primary text and icons on bg, surface, raised and field. 4.5:1 or more.              |
| `ink-2`         | `--e-ink-2`         | Secondary text, labels, meta and placeholders. 4.5:1 or more.                        |
| `primary`       | `--e-primary`       | The call to action fill. One per view.                                               |
| `on-primary`    | `--e-on-primary`    | Text and icons on primary.                                                           |
| `accent`        | `--e-accent`        | The spark: highlighted bar, status dot, active mark. Once or twice per view.         |
| `on-accent`     | `--e-on-accent`     | Text on an accent fill.                                                              |
| `accent-ink`    | `--e-accent-ink`    | Accent as text or icon (links, active tab) on surfaces or accent-soft.               |
| `accent-soft`   | `--e-accent-soft`   | Tinted background behind accent-ink (accent badges, avatar fallback).                |
| `positive`      | `--e-positive`      | Positive status text, on positive-soft or surface.                                   |
| `positive-soft` | `--e-positive-soft` | Background of positive badges and deltas.                                            |
| `negative`      | `--e-negative`      | Negative status and error text, on negative-soft or surface.                         |
| `negative-soft` | `--e-negative-soft` | Background of negative badges and danger buttons.                                    |
| `hero`          | `--e-hero`          | Fill of the one hero card per screen.                                                |
| `on-hero`       | `--e-on-hero`       | Text and the big number on the hero.                                                 |
| `on-hero-2`     | `--e-on-hero-2`     | Secondary text on the hero.                                                          |
| `track`         | `--e-track`         | Unfilled chart bars and progress tracks on the hero.                                 |
| `focus`         | `--e-focus`         | The keyboard ring: 2px with a 2px gap in the page color, 3:1 or more.                |

Never put `ink-2` on accent or hero fills. Status always carries a word too.

## Type scale

One scale for every theme; the theme picks the faces. Use the helper classes instead of setting families by hand.

| Style      | Size / line | Class                    | Face                     |
| ---------- | ----------- | ------------------------ | ------------------------ |
| display-xl | 48 / 52     | `e-display-xl`           | display, once per screen |
| display    | 34 / 40     | `e-display`              | display                  |
| title      | 22 / 28     | `e-title`                | display                  |
| heading    | 17 / 24     | `e-heading`              | body, 600                |
| body-lg    | 16 / 24     | `e-body-lg`              | body                     |
| body       | 14 / 20     | `e-body`                 | body                     |
| label      | 13 / 18     | `e-label`                | body, 500                |
| caption    | 12 / 16     | `e-caption`              | body, ink-2              |
| micro      | 11 / 14     | (axis and tab labels)    | body                     |
| num-hero   | 56          | `Stat size="hero"`       | number face, tabular     |
| num-kpi    | 30          | `Stat size="kpi"`        | number face, tabular     |
| num-inline | 13          | `e-meta`, table `is-num` | meta face, tabular       |

Also `e-eyebrow` (small label, uppercase in Paper) and `e-num` (number face on any element). Display sizes track tight; body text never does. Paper sets display sizes larger (56, 40, 27) and numbers 1.36 times larger.

## Spacing, sizes and radius

- Spacing is a 4px grid: `--space-1` 4, `--space-2` 8, `--space-3` 12, `--space-4` 16, `--space-5` 20, `--space-6` 24, `--space-8` 32, `--space-10` 40, `--space-12` 48, `--space-16` 64, plus `--space-half` 2.
- Controls: `--control-sm` 32, `--control-md` 40, `--control-lg` 48. Touch targets `--touch-min` 44. Icons 16, 20 and 24.
- Radius nests: `--e-r-xl` frame, `--e-r-lg` card, `--e-r-md` group, `--e-r-sm` input, `--e-r-control` buttons and segmented controls.

## Motion

- Durations: `--duration-instant` 90ms (hover color), `--duration-fast` 140ms (borders, focus), `--duration-base` 220ms (switches, menus), `--duration-slow` 360ms (sheets), `--duration-press` 450ms (spring return), `--duration-chart` 900ms (bars grow), `--duration-count` 1100ms (numbers count up).
- Curves: `--easing-out` (entering, settling), `--easing-spring` (press release, toggles), `--easing-snap` (quick B2B changes), `--easing-chart` (bars growing).
- Animate only `transform` and `opacity`. Everything collapses to instant under `prefers-reduced-motion`.

## Shadows

`--e-shadow-card` lifts surfaces and `--e-shadow-cta` sits under the primary button. Paper has none. Never invent shadows a theme does not define.