@epa-wg/custom-element-dist 0.0.33 → 0.0.35

package/src/material/theme/tokens/cem-timing.md

@@ -0,0 +1,198 @@
+# 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, easing curves, and optional spring presets)
+
+**Companion specs:**
+- **D0. Color (Emotional Palette)** ([`cem-colors.md`](./cem-colors.md)) — color transition timing
+- **D1. Space & Rhythm** ([`cem-dimension.md`](./cem-dimension.md)) — spacing animation timing
+- **D2. Coupling & Compactness** ([`cem-coupling.md`](./cem-coupling.md)) — density transition timing
+- **D3. Shape — Bend** ([`cem-shape.md`](./cem-shape.md)) — bend/morph animation timing
+- **D4. Layering** ([`cem-layering.md`](./cem-layering.md)) — lift/drop transitions, reduced-motion behavior
+- **D5. Stroke & Separation** ([`cem-stroke.md`](./cem-stroke.md)) — 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)
+- **Spring** presets (optional; for platforms that support spring physics)
+
+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
+  - spring presets (optional)
+
+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)
+
+```css
+:root {
+  /* Core buckets (contract-level) */
+  --cem-duration-instant:    50ms;
+  --cem-duration-noticeable: 250ms;
+  --cem-duration-lingering:  300ms;
+
+  /* Optional semantic aliases (adapter may override) */
+  --cem-duration-action: var(--cem-duration-noticeable);
+  --cem-duration-overlay: var(--cem-duration-lingering);
+}
+```
+
+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.
+
+```css
+:root {
+  /* Everyday motion */
+  --cem-easing-smooth:        ease-in-out;
+  --cem-easing-start-smooth:  ease-in;
+  --cem-easing-end-smooth:    ease-out;
+
+  /* Attention-drawing motion (adapter SHOULD provide a more pronounced curve) */
+  --cem-easing-highlighted:        var(--cem-easing-smooth);
+  --cem-easing-highlighted-start:  var(--cem-easing-start-smooth);
+  --cem-easing-highlighted-end:    var(--cem-easing-end-smooth);
+
+  /* Neutral/legacy */
+  --cem-easing-uniform: linear;
+  --cem-easing-classic: ease;
+}
+```
+
+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 above defaults provide placeholders; adapters are expected to supply real emphasized curves.)
+
+### 4.3 Spring tokens (optional extension)
+
+Spring tokens are **optional** because spring rendering is implementation-specific (WAAPI polyfills, native toolkits,
+framework animation engines, etc.).
+
+If springs are supported, reserve the following semantic naming grid:
+
+- **Focus**: `reposition | highlight`
+- **Feel**: `functional | delight`
+- **Speed**: `instant | noticeable | lingering`
+
+Recommended token shape (implementation-defined value encoding):
+
+```css
+:root {
+  /* Example encoding as a string. Implementations may choose a different encoding. */
+  --cem-spring-reposition-functional-instant:  "stiffness=… damping=…";
+  --cem-spring-reposition-functional-noticeable: "stiffness=… damping=…";
+  --cem-spring-reposition-functional-lingering:  "stiffness=… damping=…";
+
+  --cem-spring-highlight-delight-lingering: "stiffness=… damping=…";
+}
+```
+
+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.
+
+---
+
+## 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 additional optional spring presets
+- Documentation clarifications
+
+---
+
+## 7. Canonical token summary (contract surface)
+
+| Token | Category | Required |
+|---|---|---|
+| `--cem-duration-instant` | Duration | Yes |
+| `--cem-duration-noticeable` | Duration | Yes |
+| `--cem-duration-lingering` | Duration | Yes |
+| `--cem-easing-smooth` | Easing | Yes |
+| `--cem-easing-start-smooth` | Easing | Yes |
+| `--cem-easing-end-smooth` | Easing | Yes |
+| `--cem-easing-highlighted` | Easing | Yes |
+| `--cem-easing-highlighted-start` | Easing | Yes |
+| `--cem-easing-highlighted-end` | Easing | Yes |
+| `--cem-easing-uniform` | Easing | Yes |
+| `--cem-easing-classic` | Easing | Yes |
+| `--cem-duration-action` | Duration alias | No |
+| `--cem-duration-overlay` | Duration alias | No |
+| `--cem-spring-*` | Spring presets | No |

package/src/material/theme/tokens/cem-typography-model-stack.svg

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="700" viewBox="0 0 1200 700" role="img" aria-label="CEM typography model: Fontography, Typography, and Voice with Ink and Speech projections">
+  <defs>
+    <style>
+      :root {
+        --cem-ink: #111;
+        --cem-surface: #fff;
+        --cem-outline: #c7c7c7;
+        --cem-muted: #666;
+        --cem-accent: #005a9c;
+      }
+      .frame { fill: var(--cem-surface); stroke: var(--cem-outline); stroke-width: 2; rx: 18; }
+      .card  { fill: var(--cem-surface); stroke: var(--cem-outline); stroke-width: 2; rx: 22; }
+      .card-accent { fill: var(--cem-surface); stroke: var(--cem-accent); stroke-width: 2.5; rx: 22; }
+      .title { font: 700 34px system-ui, -apple-system, "Segoe UI", Arial, sans-serif; fill: var(--cem-ink); }
+      .h2    { font: 650 26px system-ui, -apple-system, "Segoe UI", Arial, sans-serif; fill: var(--cem-ink); }
+      .text  { font: 400 18px system-ui, -apple-system, "Segoe UI", Arial, sans-serif; fill: var(--cem-ink); }
+      .muted { font: 400 16px system-ui, -apple-system, "Segoe UI", Arial, sans-serif; fill: var(--cem-muted); }
+      .mono  { font: 500 16px ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; fill: var(--cem-muted); }
+      .arrow-strong { stroke: var(--cem-accent); stroke-width: 3; fill: none; marker-end: url(#arrowheadAccent); }
+    </style>
+    <marker id="arrowheadAccent" markerWidth="10" markerHeight="8" refX="8" refY="4" orient="auto">
+      <path d="M0,0 L10,4 L0,8 Z" fill="var(--cem-accent)"/>
+    </marker>
+  </defs>
+
+  <rect x="30" y="30" width="1140" height="640" class="frame"/>
+  <text x="70" y="95" class="title">CEM Typography Model: Fontography, Typography, Voice</text>
+  <text x="70" y="128" class="muted">Voice is modality-independent prominence. It projects into Ink (visual) and Speech (read-aloud prosody).</text>
+
+  <rect x="90" y="170" width="520" height="135" class="card"/>
+  <text x="125" y="218" class="h2">Fontography</text>
+  <text x="125" y="248" class="text">Fonts as assets + feature policy</text>
+  <text x="125" y="276" class="mono">--cem-fontography-&lt;role&gt;-family</text>
+
+  <rect x="90" y="325" width="520" height="155" class="card"/>
+  <text x="125" y="372" class="h2">Typography</text>
+  <text x="125" y="402" class="text">Layout perception: size, rhythm, spacing</text>
+  <text x="125" y="430" class="mono">--cem-typography-&lt;role&gt;-font-size</text>
+  <text x="125" y="455" class="mono">--cem-typography-&lt;role&gt;-line-height</text>
+
+  <rect x="90" y="505" width="520" height="140" class="card-accent"/>
+  <text x="125" y="552" class="h2">Voice</text>
+  <text x="125" y="582" class="text">Prominence semantics (cross‑modal)</text>
+  <text x="125" y="610" class="mono">--cem-voice-&lt;level&gt;-…</text>
+
+  <path d="M610,575 C700,575 710,345 800,345" class="arrow-strong"/>
+  <path d="M610,595 C700,595 710,515 800,515" class="arrow-strong"/>
+
+  <rect x="800" y="255" width="330" height="170" class="card"/>
+  <text x="835" y="302" class="h2">Ink projection</text>
+  <text x="835" y="332" class="text">Visual strength for text + icons</text>
+  <text x="835" y="362" class="mono">--cem-voice-*-ink-thickness</text>
+  <text x="835" y="388" class="mono">--cem-voice-*-icon-stroke-multiplier</text>
+
+  <rect x="800" y="445" width="330" height="190" class="card"/>
+  <text x="835" y="492" class="h2">Speech projection</text>
+  <text x="835" y="522" class="text">Product read‑aloud prosody</text>
+  <text x="835" y="552" class="mono">--cem-voice-*-speech-rate</text>
+  <text x="835" y="578" class="mono">--cem-voice-*-speech-pitch</text>
+  <text x="835" y="604" class="mono">--cem-voice-*-speech-volume</text>
+
+  <text x="70" y="665" class="muted">Note: Screen readers primarily follow HTML/ARIA semantics; voice tokens are intended for product read‑aloud features.</text>
+</svg>