# Semantic Timing and Motion Tokens (CEM) — Canonical Spec

Status: Canonical (v1.0)

Last updated: December 21, 2025

Audience: Design Systems, Product Design, Front-End Engineering

Applies to: UI animation timing (durations and easing curves)

Companion specs:

- D0. Color (Emotional Palette) (`cem-colors`) — color transition timing
- D1. Space & Rhythm (`cem-dimension`) — spacing animation timing
- D2. Coupling & Compactness (`cem-coupling`) — density transition timing
- D3. Shape — Bend (`cem-shape`) — bend/morph animation timing
- D4. Layering (`cem-layering`) — lift/drop transitions, reduced-motion behavior
- D5. Stroke & Separation (`cem-stroke`) — focus/selection transition timing

## 1. Purpose and scope

This spec defines the CEM contract surface for motion timing:

- Duration tokens (how long a change takes)
- Easing tokens (how the motion accelerates/decelerates) The goal is to make motion choices intent-driven (what the user experiences), while allowing implementations/adapters (e.g., Material, custom, platform-native) to supply exact numeric curves/physics.

## 2. Taxonomy placement

- D7. Timing & Motion (this spec)
  - time durations
  - easing curves

Related dimensions:

- D4. Layering & Elevation: overlays/dialogs often use longer durations
- D2. Coupling & Compactness: compact density should not force overly fast or illegible motion
- D5. Stroke & Separation: focus/selection indicators may animate; duration must not impede operability

## 3. Consumer vocabulary

CEM duration names reflect how users perceive timing:

- instant — “blink; do not interrupt”
- noticeable — “registerable, but not slow”
- lingering — “large change; allow the user to track it”

Easing names reflect intent:

- smooth — everyday, unobtrusive
- highlighted — draws attention (more pronounced)
- uniform — neutral/mechanical (constant speed)
- classic — legacy compatibility

## 4. Canonical token surface

### 4.1 Duration tokens (required)

###### cem-timing-durations

Token | Value | Description | tier
--- | --- | --- | ---
`--cem-duration-instant` | `50ms` | Blink; do not interrupt flow | required
`--cem-duration-noticeable` | `250ms` | Registerable but not slow | required
`--cem-duration-lingering` | `300ms` | Large change; allow user to track | required
`--cem-duration-action` | `var(--cem-duration-noticeable)` | Default for interactive state changes | recommended
`--cem-duration-overlay` | `var(--cem-duration-lingering)` | Default for overlay entry/exit | recommended

Normative rules:

- Ordering MUST remain: `instant < noticeable < lingering`.
- Reduced-motion modes may shorten durations (including to `0ms`), but MUST preserve relative ordering.

### 4.2 Easing tokens (required)

Easing tokens are expressed as CSS timing functions. R-D7-1 resolved: `highlighted` curves now use Material 3 “Emphasized” cubic-beziers — visibly more deliberate than `smooth`. Adapters SHOULD replace these with platform-appropriate emphasized curves.

###### cem-timing-easings

Token | Value | Description | tier
--- | --- | --- | ---
`--cem-easing-smooth` | `ease-in-out` | Default; everyday unobtrusive motion | required
`--cem-easing-start-smooth` | `ease-in` | Entrance motion | required
`--cem-easing-end-smooth` | `ease-out` | Dismissal motion | required
`--cem-easing-highlighted` | `cubic-bezier(0.2, 0, 0, 1)` | Attention-drawing motion (M3 Emphasized) | required
`--cem-easing-highlighted-start` | `cubic-bezier(0.3, 0, 0.8, 0.15)` | Highlighted entrance (M3 Emphasized Accelerate) | required
`--cem-easing-highlighted-end` | `cubic-bezier(0.05, 0.7, 0.1, 1)` | Highlighted dismissal (M3 Emphasized Decelerate) | required
`--cem-easing-uniform` | `linear` | Neutral/mechanical (e.g. indeterminate progress) | required
`--cem-easing-classic` | `ease` | Legacy compatibility | required

Normative rules:

- `smooth` MUST be suitable as the default.
- `highlighted*` MUST be visibly more pronounced than the corresponding `smooth*` curves in the same implementation. The defaults use M3 Emphasized curves; adapters SHOULD provide platform-appropriate equivalents.

### 4.3 Spring motion (adapter-local, not canonical tokens)

R-D7-2 is resolved by not defining or reserving canonical `--cem-spring-*` custom properties in v1.

Reason:

- Spring rendering is implementation-specific across WAAPI polyfills, native toolkits, and framework animation engines.
- CSS custom properties do not provide a portable spring value syntax equivalent to `stiffness`, `damping`, and `mass`.
- Reserved names with placeholder values create false API surface and would violate the manifest rule that emitted tokens must have concrete values.

Adapter guidance:

- Products may define adapter-local spring presets in their platform layer.
- Adapter-local springs SHOULD map back to CEM timing intent (`instant | noticeable | lingering`) and easing intent (`smooth | highlighted`) in their documentation.
- If a future CEM version adds canonical spring tokens, it must introduce a concrete value encoding and manifest table.

Normative rules (if springs are implemented):

- `instant | noticeable | lingering` MUST preserve perceived ordering from fastest to slowest.
- `delight` MAY overshoot/bounce; `functional` SHOULD minimize overshoot.

### 4.4 Reduced-motion overrides

When `prefers-reduced-motion: reduce` is active, duration tokens are overridden to dramatically shorter values while preserving their relative ordering (`instant < noticeable < lingering`). Alias tokens (`--cem-duration-action`, `--cem-duration-overlay`) inherit automatically via `var()` and need no explicit override. Easing tokens are unaffected.

###### cem-timing-reduced-motion

Token | reduced-motion value | Description
--- | --- | ---
`--cem-duration-instant` | `0ms` | Off entirely — motion is imperceptible
`--cem-duration-noticeable` | `50ms` | Dramatically shortened; signals “something happened”
`--cem-duration-lingering` | `100ms` | Dramatically shortened; ordering preserved

## 5. Usage guidance

- Use instant for micro-interactions that must not interrupt flow (e.g., tiny state toggles).
- Use noticeable for most component transitions (expand/collapse, standard page UI changes).
- Use lingering for overlays and large spatial changes where users must track context.

Easing selection:

- Use smooth for default transitions.
- Use start-smooth for entrances; end-smooth for dismissals.
- Use highlighted variants when motion’s purpose is to direct attention.
- Use uniform for mechanical/neutral motion (e.g., indeterminate progress).
- Use classic only for legacy compatibility.

## 6. Governance and versioning

Treat D7 tokens as contract-level once canonical.

Breaking (MAJOR):

- Renaming/removing a required token
- Changing the semantic meaning of a token
- Violating the ordering rule (`instant < noticeable < lingering`)

Non-breaking (MINOR/PATCH):

- Adjusting numeric values while preserving semantics and ordering
- Adding optional aliases or a future concrete spring token family with a real value encoding
- Documentation clarifications

## 7. Token manifest index

Token tier is encoded in the `tier` column of each source table. The manifest validator derives expected token names from these tables using the same XPath pattern as `cem-timing.html`.

Source table h6 id | Tokens covered | Validator derivation
--- | --- | ---
`cem-timing-durations` | `--cem-duration-*` (5 tokens: 3 required + 2 recommended aliases) | one token per row
`cem-timing-easings` | `--cem-easing-*` (8 tokens: all required) | one token per row

Reduced-motion overrides (`cem-timing-reduced-motion`) produce no new token names — they override core duration tokens within `@media (prefers-reduced-motion: reduce)`. Spring tokens (`--cem-spring-*`) are intentionally absent from the v1 manifest and default CSS output; spring motion is adapter-local until CEM defines a portable concrete encoding.