# AdiaUI Token Surface

Consumable design-token reference for component authors.

> **Rule of thumb:** Components consume **L3 semantic aliases** (`--a-fg`, `--a-bg-hover`, `--a-accent`). They never reference L1 primitives (`--a-neutral-50`) directly. The L3 layer maps to L2 families (`--a-canvas-text`), which map to L1 primitives (`--a-neutral-50`).

---

## Token layers

Files are organized by **dimension × layer** (v0.6.48 reorg, [ADR-0035](../../../.brain/adrs/0035-foundation-by-dimension-and-layer.md)).
A file answers two questions: which dimension (color · type · space · size · radius · motion · elevation) and which layer (primitive → semantic → role → applied/element → attribute-API → context → reset).

| Layer | Files | When to use |
|-------|-------|-------------|
| **L1 — Color primitives** | `colors/parameters.css`, `colors/primitives-*.css` | Token system authors only. OKLCH base values, hue ramps, neutral scales. |
| **L2 — Color families** | `colors/semantics/core.css` | Component authors building *new* semantic aliases not yet exposed. Maps primitives to meaning (`--a-canvas-text`, `--a-danger-muted`). |
| **L3 — Color aliases** | `colors/semantics/core.css` + `colors/semantics/{features,buckets,data-viz}.css` | **All component CSS.** The stable public API: `--a-fg`, `--a-bg`, `--a-accent`, `--a-focus-ring`, `--a-data-0`. |
| **Dynamic / Theme** | `themes.css`, `colors/surfaces.css` | Theme authors. Per-theme hue shifts, density, radius overrides. |
| **Type primitives + roles** | `type/scale.css` (L1/L2), `type/roles.css` (L3) | Component authors for font-size, weight, leading, tracking. |
| **Element defaults** | `type/elements.css` | Native HTML element typographic baseline (table, code, h1–h6, links…). |
| **Spacing / Size** | `foundation/space.css`, `foundation/size.css` | Component authors for padding, margin, gap, component/chrome heights. |
| **Radius** | `foundation/radius.css` | `--a-radius-sm/md/lg`, the `--a-radius-k` knob. |
| **Shadows** | `foundation/elevation.css` | Elevation authors. `--a-shadow-sm/md/lg`. |
| **Timing** | `foundation/motion.css` | Motion authors. `--a-duration`, `--a-easing`. |
| **Attribute API** | `api/sizing.css`, `api/text.css`, `api/layout.css` | The consumer-facing `[size]`/`[gap]`/`[weight]`/`[color]`/`[grow]`… selectors. |

> `tokens.css`, `typography.css`, `colors/semantics.css` remain as **compat barrels** at their published paths — they `@import` the files above. Link them exactly as before; the reorg is behind the barrel.

---

## L3 Color API (the tokens components consume)

### Neutral surfaces (`--a-canvas-*` → `--a-bg-*` / `--a-fg-*`)

| Token | Purpose | Example use |
|-------|---------|-------------|
| `--a-bg` | Default surface (page bg, panel bg) | `body { background: var(--a-bg); }` |
| `--a-bg-subtle` | Alternating rows, card backgrounds | `.card { background: var(--a-bg-subtle); }` |
| `--a-bg-muted` | Disabled / inactive surfaces | `[disabled] { background: var(--a-bg-muted); }` |
| `--a-bg-strong` | Active track, selected chips | `.track-active { background: var(--a-bg-strong); }` |
| `--a-bg-hover` | Hover state backgrounds | `:hover { background: var(--a-bg-hover); }` |
| `--a-bg-active` | Pressed / active state | `:active { background: var(--a-bg-active); }` |
| `--a-bg-selected` | Selected item background | `[aria-selected="true"] { background: var(--a-bg-selected); }` |
| `--a-bg-disabled` | Disabled state background | `[disabled] { background: var(--a-bg-disabled); }` |
| `--a-bg-invalid` | Invalid / error state background | `[aria-invalid="true"] { background: var(--a-bg-invalid); }` |
| `--a-bg-scrim` | Modal overlay backdrop | `.modal-overlay { background: var(--a-bg-scrim); }` |
| `--a-fg` | Default text | `body { color: var(--a-fg); }` |
| `--a-fg-subtle` | Secondary text, descriptions | `.description { color: var(--a-fg-subtle); }` |
| `--a-fg-muted` | Placeholder text, timestamps | `.timestamp { color: var(--a-fg-muted); }` |
| `--a-fg-strong` | Headings, emphasized text | `h1 { color: var(--a-fg-strong); }` |
| `--a-fg-inverse` | Text on dark/brand buttons | `.button-primary { color: var(--a-fg-inverse); }` |

### Borders

| Token | Purpose |
|-------|---------|
| `--a-border-subtle` | Dividers, hairlines |
| `--a-border` | Default borders, input outlines |
| `--a-border-strong` | Focus rings, active borders |
| `--a-border-hover` | Hover state borders |
| `--a-border-active` | Active/pressed borders |
| `--a-border-selected` | Selected item borders |
| `--a-border-invalid` | Error state borders |
| `--a-border-disabled` | Disabled borders |

### Accent (interactive)

| Token | Purpose |
|-------|---------|
| `--a-accent` | Primary accent color (buttons, links, active states) |
| `--a-accent-hover` | Accent hover state |
| `--a-accent-active` | Accent pressed state |
| `--a-accent-muted` | Subtle accent (tinted backgrounds) |
| `--a-accent-bg` | Accent-filled surface |
| `--a-accent-bg-hover` | Accent-filled hover |
| `--a-accent-bg-active` | Accent-filled active |
| `--a-accent-fg` | Text on accent surfaces |
| `--a-accent-border` | Accent borders |

### Brand

Same matrix as accent (`--a-brand`, `--a-brand-hover`, `--a-brand-bg`, `--a-brand-fg`, etc.) for brand-color surfaces. Used in marketing contexts, headers, hero sections.

### Status colors

| Token family | Use case |
|--------------|----------|
| `--a-danger-*` | Errors, destructive actions, deletions |
| `--a-warning-*` | Warnings, caution states |
| `--a-success-*` | Success confirmations, completed states |
| `--a-info-*` | Informational highlights, tips |

Each status family mirrors the accent matrix: `-bg`, `-bg-hover`, `-bg-active`, `-fg`, `-border`, `-muted`, etc.

### Data visualization (`--a-data-0` … `--a-data-9`)

Chromatic data colors for charts, graphs, status indicators. Ten slots distinguishable by hue shift.

| Token | Default hue | Use |
|-------|-------------|-----|
| `--a-data-0` | 225° | Primary data series |
| `--a-data-1` | 247° | Secondary series |
| `--a-data-2` | 269° | Tertiary |
| … | … | … |
| `--a-data-9` | 335° | Tenth series |

Individual hue overrides: `--a-data-N-hue: 180;` to pin a specific slot.

---

## Typography API

### Scale tokens (use these directly)

| Token | Purpose |
|-------|---------|
| `--a-body-size` | Running text (paragraphs, descriptions) |
| `--a-heading-size` | Sub-headings |
| `--a-section-size` | Section headings |
| `--a-title-size` | Page titles |
| `--a-display-size` | Hero numbers, big stats |
| `--a-deck-size` | Lead paragraphs, hero copy |
| `--a-caption-size` | Captions, metadata, footnotes |
| `--a-code-size` | Monospace code blocks |
| `--a-label-size` | Form labels, badges |
| `--a-ui-size` | UI chrome text (buttons, tabs) |
| `--a-metric-size` | Dashboard metrics, KPIs |
| `--a-kicker-size` | Overlines, eyebrow text |

Each has `-sm`, `-md`, `-lg` variants (e.g., `--a-body-sm`, `--a-body-lg`).

### Font families

| Token | Purpose |
|-------|---------|
| `--a-font-family-body` | Prose blocks |
| `--a-font-family-heading` | Headings |
| `--a-font-family-display` | Hero / display |
| `--a-font-family-code` | Monospace |
| `--a-font-family-ui` | Buttons, inputs, chrome |
| `--a-font-family-control` | Form controls |
| `--a-font-family-editorial` | Marketing / long-form |
| `--a-font-family-text` | Fallback generic text |

### Weight & tracking

| Token | Value | Use |
|-------|-------|-----|
| `--a-weight-thin` | 300 | Hero numbers, elegant display |
| `--a-weight-light` | 400 | Body text |
| `--a-weight-normal` | 500 | Default UI |
| `--a-weight-medium` | 600 | Slightly emphasized |
| `--a-weight-semibold` | 700 | Headings |
| `--a-weight-bold` | 800 | Strong emphasis |
| `--a-tracking-tight` | -0.02em | Display / headlines |
| `--a-tracking-normal` | 0 | Body |
| `--a-tracking-wide` | 0.03em | Labels, uppercase |
| `--a-tracking-wider` | 0.06em | Kickers, overlines |

---

## Spacing API

### Base tokens (parametric: value = `base × --a-density`)

| Token | Base value | Use |
|-------|-----------|-----|
| `--a-space-0` | 0 | None |
| `--a-space-0-5` | 0.125rem (2px) | Hairline |
| `--a-space-1` | 0.25rem (4px) | Tight padding |
| `--a-space-2` | 0.5rem (8px) | Default gap |
| `--a-space-3` | 0.75rem (12px) | Comfortable gap |
| `--a-space-4` | 1rem (16px) | Card padding |
| `--a-space-5` | 1.25rem (20px) | Section padding |
| `--a-space-6` | 1.5rem (24px) | Large gap |
| `--a-space-7` | 1.75rem (28px) | Extra large |
| `--a-space-8` | 2rem (32px) | Section gutters |
| `--a-space-10` | 2.5rem (40px) | Page gutters |
| `--a-space-12` | 3rem (48px) | Major sections |
| `--a-space-16` | 4rem (64px) | Hero spacing |

### Composite gap tokens

| Token | Maps to | Use |
|-------|---------|-----|
| `--a-gap-sm` | `--a-space-3` | Tight component groups |
| `--a-gap-md` | `--a-space-4` | Default component groups |
| `--a-gap-lg` | `--a-space-6` | Loose component groups |

---

## Chrome dimensions

| Token | Value | Element |
|-------|-------|---------|
| `--a-chrome-app-header-height` | 48px | App-level header |
| `--a-chrome-app-toolbar-height` | 48px | App-level toolbar |
| `--a-chrome-app-footer-height` | 48px | App-level footer |
| `--a-chrome-pane-header-height` | 36px | Pane / panel header |
| `--a-chrome-pane-toolbar-height` | 36px | Pane / panel toolbar |
| `--a-chrome-pane-footer-height` | 36px | Pane / panel footer |

---

## Radius & density

| Token | Type | Default | Effect |
|-------|------|---------|--------|
| `--a-density` | `@property <number>` | 1 | Scales ALL spacing, padding, gaps, component heights |
| `--a-radius-k` | `@property <number>` | 1 | Scales ALL corner rounding |
| `--a-radius-sm` | length | 0.375rem | Small corners (inputs, buttons) |
| `--a-radius-md` | length | 0.5rem | Medium corners (cards, popovers) |
| `--a-radius-lg` | length | 0.75rem | Large corners (modals, drawers) |
| `--a-radius-full` | length | 9999px | Pills, chips, avatars |

Set `--a-density` and `--a-radius-k` on `:root` for global effect, or on `[density="tight"]` / `[density="comfortable"]` for scoped regions.

---

## Shadows

| Token | Default | Use |
|-------|---------|-----|
| `--a-shadow-sm` | `0 1px 2px` | Subtle lift (cards at rest) |
| `--a-shadow-md` | `0 4px 8px` | Elevated (dropdowns, popovers) |
| `--a-shadow-lg` | `0 8px 24px` | Highest elevation (modals, drawers) |
| `--a-shadow-intensity` | 1 | Multiplier for shadow opacity |

---

## Timing

| Token | Value | Use |
|-------|-------|-----|
| `--a-duration-fast` | 120ms | Hover states, micro-interactions |
| `--a-duration` | 250ms | Default transition |
| `--a-duration-slow` | 300ms | Page transitions, large movements |
| `--a-easing` | `cubic-bezier(0.25, 0.1, 0.25, 1)` | Default ease |
| `--a-easing-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | Exit / snap animations |

---

## How to add a new token

1. **Need a new semantic color?** Add it in `colors/semantics/core.css` (canvas/accent/brand/status), mapping to an L2 family — or the matching `colors/semantics/{features,buckets,data-viz}.css` for focus/field/highlight/chrome/bucket/data tokens. Example:
   ```css
   --a-bg-ghost: var(--a-canvas-0); /* new variant */
   ```
2. **Need a new primitive hue?** Extend `colors/parameters.css` hue ramp.
3. **Need a new spacing step?** Add to `foundation/space.css`. (radius → `foundation/radius.css`, motion → `foundation/motion.css`, shadow → `foundation/elevation.css`, type role → `type/roles.css`.)
4. **Need a new global attribute?** Add the `[attr]` selector to the matching `api/{sizing,text,layout}.css` — never scatter attribute selectors into primitive files.
5. **Never** add tokens directly in component CSS. Always add to the token system first, then consume.

---

## File inventory

```
styles/
├── index.css               # Real barrel: tokens → components → resets (re-exported by ../index.css)
│
├── tokens.css              # COMPAT BARREL → colors + typography + foundation + api/sizing
├── typography.css          # COMPAT BARREL → type/{scale,roles,elements} + api/{text,layout}
│
├── foundation/             # non-color, non-type PRIMITIVES (L1), one file per dimension
│   ├── index.css           #   barrel
│   ├── space.css           #   --a-space-* · inset · gap   (+ the --a-density knob)
│   ├── size.css            #   --a-size-* · chrome heights · toggle · icon/caret
│   ├── radius.css          #   --a-radius-*                (+ the --a-radius-k knob)
│   ├── motion.css          #   --a-duration-* · --a-easing-*
│   └── elevation.css       #   --a-shadow-*
│
├── type/                   # the TYPE system (content of the typography.css barrel)
│   ├── scale.css           #   L1/L2: families, weights, leading, tracking
│   ├── roles.css           #   L3: 13 roles + h1–h6 defaults + [variant]
│   └── elements.css        #   native element typographic defaults (table, code, h1–h6, links…)
│
├── colors/                 # the COLOR system (L1 → L3)
│   ├── index.css           #   barrel: parameters → primitives → surfaces → scrims → semantics
│   ├── parameters.css      #   L1: hue definitions, OKLCH ramp parameters
│   ├── primitives.css      #   L1 barrel → primitives-{shared,neutral,brand,accent,info,success,warning,danger}.css
│   ├── primitives-*.css    #   L1: per-family OKLCH ramps (8 files)
│   ├── surfaces.css        #   L2: canvas ramps (--a-canvas-0 … 6)
│   ├── scrims.css          #   L2: overlay transparency values
│   ├── semantics.css       #   COMPAT BARREL → semantics/*
│   └── semantics/
│       ├── core.css        #   L2+L3 canvas/accent/brand/status aliases (the consumable API)
│       ├── buckets.css     #   sequential data-vis ramps
│       ├── features.css    #   focus ring · field · highlight · chrome
│       ├── data-viz.css    #   --a-data-0..9 categorical palette + tuning knobs
│       └── aliases.css     #   scrim role aliases + legacy status-compat (loads LAST — order-bearing)
│
├── api/                    # the global ATTRIBUTE API (consumer-facing [attr] selectors)
│   ├── sizing.css          #   [density] [radius] [size] [gap] [padding] [margin]
│   ├── text.css            #   [text-align] [weight] [color] [transform] [truncate]
│   └── layout.css          #   [hidden] [nomargin] [grow]
│
├── themes.css              # CONTEXT: 8 named themes + light/dark scheme overrides ([data-theme])
├── prose.css               # CONTEXT: opt-in article typography ([prose])
├── resets.css              # global RESET (box-sizing, scrollbar, focus, normalize)
├── fonts.css               # @font-face declarations + font-family primitives
├── components.css          # per-component @import barrel
└── design-tokens-export.js # tooling: Figma Variables Pro exporter (reads the live --a-* surface)
```

---

## Token count (approximate)

| Layer | File(s) | ~Tokens |
|-------|---------|---------|
| L1 Primitives | `colors/parameters.css`, `colors/primitives-*.css` | ~80 |
| L2 Families | `colors/semantics/core.css` (family section) | ~60 |
| L3 Semantic aliases | `colors/semantics/{core,features,buckets,data-viz}.css` | ~150 |
| Typography | `type/{scale,roles}.css` | ~80 |
| Spacing / Size | `foundation/{space,size}.css` | ~25 |
| Chrome | `foundation/size.css` | ~10 |
| Shadows | `foundation/elevation.css` | ~4 |
| Timing | `foundation/motion.css` | ~5 |
| **Total** | | **~410** |
