# Spec: Tokens (Layer 01)

File: `src/layers/01-tokens.css`

## Purpose

Pure design token definitions. Aliases Open Props primitives to semantic names. Contains only `:root {}` variable declarations — no rules, no selectors, no styling.

## Open Props Dependency

ASW builds on Open Props as its primitive token source. Open Props provides:
- Color scales: `--color-0` through `--color-16`
- Size scale: `--size-1` through `--size-15`, `--size-px-1` through `--size-px-12`
- Font sizes: `--font-size-0` through `--font-size-8`
- Font weights: `--font-weight-1` through `--font-weight-9`
- Shadows: `--shadow-1` through `--shadow-6`
- Border sizes: `--border-size-1` through `--border-size-5`
- Animations, easings, gradients, and more

**Version:** tracked in `vendor/open-props/VERSION`

## Aliasing Contract

Every Open Props primitive used in the framework MUST be aliased through this file. Downstream layers (02+) MUST reference semantic aliases, never primitives.

```css
/* YES — downstream layers use this */
color: var(--text);
font-weight: var(--weight-bold);
padding: var(--space-4);

/* NO — never in layers 02+ */
color: var(--color-6);
font-weight: var(--font-weight-7);
padding: var(--size-3);
```

## Token Categories

### Colors
- `--surface`, `--surface-alt` — background colors
- `--text`, `--text-muted` — foreground colors
- `--accent`, `--accent-hover` — interactive/brand color
- `--border`, `--border-muted` — border colors
- `--code-bg`, `--code-text` — code block colors

### Spacing
- `--space-1` through `--space-7` — spacing scale
- Maps to Open Props `--size-N` scale

### Typography
- `--weight-normal`, `--weight-medium`, `--weight-semibold`, `--weight-bold`
- `--font-body`, `--font-mono` — font stacks
- `--line-height-body`, `--line-height-heading`
- `--width-prose` — max-width for readable text

### Shadows
- `--shadow-dropdown`, `--shadow-modal` — purpose-named shadows

### Focus / Interaction
- `--focus-ring-width` — keyboard focus ring width

## Scenarios

### Given a new primitive reference needed
- **When** a downstream layer needs an Open Props value
- **Then** add a semantic alias to this file first
- **And** reference only the alias in the downstream layer

### Given an unused token
- **When** auditing finds a token alias with zero references in layers 02+
- **Then** it may be removed from this file

### Given this file
- **When** inspected
- **Then** it contains only `:root {}` with `--custom-property: value;` declarations
- **And** no element selectors, no class selectors, no rules