# Semantic Spacing and Layout Rhythm Tokens (CEM × M3)

**Status:** Canonical (D1 v1.0)

**Last updated:** December 19, 2025

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

**Taxonomy placement:** D1. Space & Rhythm (part of the 7-dimensional CEM token framework)

**Companion specs:**

- **D0. Color (Emotional Palette)** ([`cem-colors.md`](./cem-colors.md)) — color weight pairs with spacing rhythm
- **D2. Coupling & Compactness** ([`cem-coupling.md`](./cem-coupling.md)) — normative for interactive operability
- **D3. Shape & Bend** ([`cem-shape.md`](./cem-shape.md)) — bend/inset harmony rules
- **D4. Layering** ([`cem-layering.md`](./cem-layering.md)) — prominent layers "earn" breathing room
- **D5. Stroke & Separation** ([`cem-stroke.md`](./cem-stroke.md)) — boundaries, dividers, focus indicators
- **D6. Typography** ([`cem-voice-fonts-typography.md`](./cem-voice-fonts-typography.md)) — reading rhythm validation
- **D7. Time & Motion** ([`cem-timing.md`](./cem-timing.md)) — rhythm perception

---

## Table of Contents

1. [Scope](#1-scope)
2. [CEM alignment principles applied to spacing](#2-cem-alignment-principles-applied-to-spacing)
    - [2.1 Semantic intent first](#21-semantic-intent-first)
    - [2.2 Bounded variation](#22-bounded-variation)
    - [2.3 Accessibility and operability by construction](#23-accessibility-and-operability-by-construction)
3. [Token model](#3-token-model)
4. [Relation to Dimensional Tokens](#4-relation-to-dimensional-tokens)
    - [4.1 Dimensional Tokens: where spacing lives](#41-dimensional-tokens-where-spacing-lives)
    - [4.2 Governance rules (cross-category contracts)](#42-governance-rules-cross-category-contracts)
5. [Reference spacing scale (semantic)](#5-reference-spacing-scale-semantic)
    - [5.1 Primary dimension scale](#51-primary-dimension-scale-semanticcss)
    - [5.2 Mapping to M3 rhythm](#52-mapping-to-m3-rhythm)
6. [Consumer-semantic spacing taxonomy](#6-consumer-semantic-spacing-taxonomy)
    - [6.1 Relationship gaps (between items)](#61-relationship-gaps-between-items)
    - [6.2 Insets (inside a surface)](#62-insets-inside-a-surface)
    - [6.3 Coupling and interaction safety (D2 cross-reference)](#63-coupling-and-interaction-safety-d2-cross-reference)
    - [6.4 Reading rhythm (vertical cadence for prose)](#64-reading-rhythm-vertical-cadence-for-prose)
    - [6.5 Data/scan rhythm (dense but legible)](#65-datascan-rhythm-dense-but-legible)
7. [Layout rhythm tokens (compositional semantics)](#7-layout-rhythm-tokens-compositional-semantics)
    - [7.1 Stack rhythm (vertical composition)](#71-stack-rhythm-vertical-composition)
    - [7.2 Cluster rhythm (horizontal groups)](#72-cluster-rhythm-horizontal-groups)
    - [7.3 Page gutters (responsive breathing room)](#73-page-gutters-responsive-breathing-room)
8. [Spacing modes knob (dense / normal / sparse)](#8-spacing-modes-knob-dense--normal--sparse)
    - [8.1 Adjustment policy](#81-adjustment-policy)
    - [8.2 Concrete overrides](#82-concrete-overrides-recommended-default-mapping)
    - [8.3 Notes on component mapping](#83-notes-on-component-mapping)
    - [8.4 Layout mapping checklist](#84-layout-mapping-checklist-how-to-apply)
9. [Mapping notes: M3 ↔ CEM](#9-mapping-notes-m3--cem)
10. [Quick adoption checklist](#10-quick-adoption-checklist)

**Appendices**

- [Appendix A. D2 Coupling Mode Matrix (excerpt)](#appendix-a-d2-coupling-mode-matrix-excerpt)
- [Appendix B. Governance and versioning](#appendix-b-governance-and-versioning)

---

## 1. Scope

This document defines a **consumer-semantic** spacing and layout rhythm token set that:

- Preserves the **Material 3 rhythm** (4dp increments, common 8dp cadence) as a *reference lattice*.
- Exposes **semantic endpoints** that describe *intent* (relationship, grouping, task flow) rather than
  *implementation* (e.g., `margin: 16px`).
- Supports an optional D1 knob for **spacing modes** (`dense | normal | sparse`) **without** conflating it with D2
  operability.

This document is **D1 (Space & Rhythm)**. It intentionally does *not* define interactive minimums; it **consumes** D2
coupling minimums as hard constraints.

---

## 2. CEM alignment principles applied to spacing

### 2.1 Semantic intent first

Developers should apply tokens like:

- `gap-related`, `gap-group`, `gap-section` (relationship semantics)
- `inset-control`, `inset-container` (surface semantics)
- `coupling-guard-min` (interaction safety contract; defined in D2)

…and not value-centric names like `space-16` in component code.

### 2.2 Bounded variation

A small set of *distinct, repeatable* space steps should cover most UI. Extended values exist but are intentionally
"rare".

### 2.3 Accessibility and operability by construction

Spacing must preserve:

- **Modality-neutral operability** (pointer, touch, stylus, gaze, switch, remote) via D2 coupling minimums
- **Readability** (line/paragraph rhythm)
- **User scaling** (prefer `rem` / `em` and allow platform scaling)

---

## 3. Token model

We use three layers:

1. **Reference scale tokens** (M3-aligned numeric steps; safe to map to dp/px)
2. **System/semantic tokens** (consumer-intent endpoints; what teams apply)
3. **Component mapping** (component-specific tokens map to semantic tokens; typically owned in component adapters)

---

## 4. Relation to Dimensional Tokens

### 4.1 Dimensional Tokens: where spacing lives

In CEM, spacing/rhythm is not "just layout." It is a primary subset of **Dimensional Tokens** (the physical layer: size,
distance, bend, stroke, depth).

Use this **legend-level** dimensional taxonomy to keep token categories coherent:

- **D1. Space & Rhythm** (this document)
    - gaps, insets, gutters, composition cadence, reading cadence, scan cadence

- **D2. Coupling & Compactness** (adjacent; constrains D1) — see [`cem-coupling.md`](./cem-coupling.md)
    - operable zone minimums
    - interference/isolation minimums
    - halo/expansion policy (visual size vs operable size)

- **D2c. Controls** (adjacent; visual geometry constrained by D2) — see [`cem-controls.md`](./cem-controls.md)
    - generic control geometry (height, padding)
    - icon-button size
    - list/menu/table row heights
    - per-coupling-mode visual geometry overrides

- **D3. Shape & Bend** — see [`cem-shape.md`](./cem-shape.md)
    - bend / corner radius roles
    - bend-inset harmony (see §4.2 rule 5)

- **D4. Layering** — see [`cem-layering.md`](./cem-layering.md)
    - signed 7-tier ladder (recess → base → raised → floating → overlay → command)
    - tonal shift, shadow, contour, scrim as depth channels
    - state-driven lift (hover, drag)

- **D5. Stroke & Separation** — see [`cem-stroke.md`](./cem-stroke.md)
    - boundaries (control container edges), dividers (sibling separation)
    - focus/selection/target indicators (including zebra pattern)
    - stroke basis (`--cem-stroke-none`, `--cem-stroke-hair`, `--cem-stroke-standard`, `--cem-stroke-strong`)

- **D6. Typography Thickness** — see [`cem-voice-fonts-typography.md`](./cem-voice-fonts-typography.md)
    - weight/mass roles that affect perceived density and hierarchy

- **D7. Time & Motion Timing** — see [`cem-timing.md`](./cem-timing.md)
    - durations/easing groups (not geometry, but participates in "rhythm" perception)

### 4.2 Governance rules (cross-category contracts)

These rules prevent spacing changes from degrading operability, accessibility, or visual hierarchy:

1. **Spacing modes are a D1 adjustment; never a D2 coupling regression**

- `dense | normal | sparse` may adjust *gaps/insets/gutters* (D1) selectively.
- D1 changes must not reduce the D2 safety minimums (**zone**, **guard**) and must not cause halo overlap.

2. **Normative layout contract for interactive adjacency**

When spacing occurs **between two interactive affordances**, layout must respect D2 guard:

```css
/* If the gap separates adjacent interactive affordances: */
.cem-gap-interactive {
    gap: max(var(--cem-gap-related), var(--cem-coupling-guard-min));
}
```

3. **When D1 can't grow, D5 may need to compensate**

- In tight layouts or contrast themes, increase stroke/separation to maintain scannability.

4. **Elevated/prominent surfaces "earn" breathing room**

- Higher layer prominence (D4) should generally correlate with more surrounding space (D1).

5. **Bend and inset should harmonize** (D1 × D3)

- Larger bend (D3) with very tight inset (D1) reads crowded; prefer stepping inset up.
- See [`cem-shape.md`](./cem-shape.md) §8.5 for detailed guidance on bend vs inset readability.

6. **Reading cadence is jointly governed by typography + spacing**

- Reading rhythm tokens (D1) must be validated against typescale/line-height policy (D6).
- See [`cem-voice-fonts-typography.md`](./cem-voice-fonts-typography.md) for typography tokens.

---

## 5. Reference spacing scale (semantic)

The spacing scale uses semantic size names rather than pixel values, making intent clear while preserving M3 rhythm (4dp
increments).

### 5.1 Primary dimension scale (semantic.css)

Eight steps covering common UI needs:

###### cem-dim-scale

| Token                 | Value   | Description                             | tier     |
|-----------------------|---------|-----------------------------------------|----------|
| `--cem-dim-xx-small`  | 0.25rem | 4px — micro gaps, icon padding          | required |
| `--cem-dim-x-small`   | 0.5rem  | 8px — related item gaps, control insets | required |
| `--cem-dim-small`     | 0.75rem | 12px — group gaps, inline rhythm        | required |
| `--cem-dim-medium`    | 1rem    | 16px — block gaps, container insets     | required |
| `--cem-dim-large`     | 1.5rem  | 24px — section gaps, surface insets     | required |
| `--cem-dim-x-large`   | 2rem    | 32px — page gaps, wide gutters          | required |
| `--cem-dim-xx-large`  | 4rem    | 64px — extended layout, hero spacing    | required |
| `--cem-dim-xxx-large` | 8rem    | 128px — maximum breathing room          | required |

**Cross-reference:** These tokens are consumed by D3 Shape ([`cem-shape.md`](./cem-shape.md)) for bend values:

- `--cem-bend-smooth` uses `--cem-dim-x-small` (8px)
- `--cem-bend-surface` uses `--cem-dim-small` (12px)
- `--cem-bend-modal` uses `--cem-dim-large` + `--cem-dim-xx-small` (~28px)

### 5.2 Mapping to M3 rhythm

| Semantic token        | Value   | M3 dp equivalent | Typical use                   |
|-----------------------|---------|------------------|-------------------------------|
| `--cem-dim-xx-small`  | 0.25rem | 4dp              | Micro gaps, tight padding     |
| `--cem-dim-x-small`   | 0.5rem  | 8dp              | Related items, control insets |
| `--cem-dim-small`     | 0.75rem | 12dp             | Group gaps, inline spacing    |
| `--cem-dim-medium`    | 1rem    | 16dp             | Block gaps, container insets  |
| `--cem-dim-large`     | 1.5rem  | 24dp             | Section gaps, surface padding |
| `--cem-dim-x-large`   | 2rem    | 32dp             | Page gaps, wide gutters       |
| `--cem-dim-xx-large`  | 4rem    | 64dp             | Extended layout spacing       |
| `--cem-dim-xxx-large` | 8rem    | 128dp            | Maximum layout spacing        |

---

## 6. Consumer-semantic spacing taxonomy

The taxonomy is organized by what the space *means to the user*.

### 6.1 Relationship gaps (between items)

Use when arranging siblings.

###### cem-dim-gaps

| Token               | Value                    | Description                                     | tier        |
|---------------------|--------------------------|-------------------------------------------------|-------------|
| `--cem-gap-related` | `var(--cem-dim-x-small)` | Siblings in the same unit (8px)                 | recommended |
| `--cem-gap-group`   | `var(--cem-dim-small)`   | Items in the same group, distinct (12px)        | recommended |
| `--cem-gap-block`   | `var(--cem-dim-medium)`  | Between groups/blocks inside one surface (16px) | recommended |
| `--cem-gap-section` | `var(--cem-dim-large)`   | Between major sections (24px)                   | recommended |
| `--cem-gap-page`    | `var(--cem-dim-x-large)` | Between page-level regions (32px)               | recommended |

**Guideline:** if users perceive two things as "one unit," use `gap-related`. If they perceive "these are separate
things," move up to `gap-group` or `gap-block`.

> Important: for interactive adjacency, apply the D2 guard contract (`gap = max(D1 gap, D2 guard)`).

### 6.2 Insets (inside a surface)

Use when padding content within a container.

###### cem-dim-insets

| Token                   | Value                    | Description                                                       | tier        |
|-------------------------|--------------------------|-------------------------------------------------------------------|-------------|
| `--cem-inset-control`   | `var(--cem-dim-x-small)` | Smallest safe inset for tight controls (8px)                      | recommended |
| `--cem-inset-container` | `var(--cem-dim-medium)`  | Default inset for common containers (16px)                        | recommended |
| `--cem-inset-surface`   | `var(--cem-dim-large)`   | Comfortable inset for reading surfaces and prominent cards (24px) | recommended |

**Cross-reference:** When combining insets with bend (D3), ensure inset is large enough to prevent content crowding in
rounded corners. See [`cem-shape.md`](./cem-shape.md) §8.5 for guidance.

### 6.3 Coupling and interaction safety (D2 cross-reference)

These tokens are **defined and governed in D2** ([`cem-coupling.md`](./cem-coupling.md)). They are listed here as a *
*normative constraint**
because they bound how far D1 spacing modes can compress interactive adjacency. **Do not set or tune these in D1**;
treat them as sourced from the D2 theme.

```css
:root {
    /* Minimum distancing between adjacent operable zones (prevents interference). */
    --cem-coupling-guard-min: 0.5rem; /* nominally 8px */

    /* Minimum operable zone (layout-level). Keep invariant across modes. */
    --cem-coupling-zone-min: 3rem; /* nominally 48px @ 16px root */

    /* Invisible expansion beyond visuals (halo). */
    --cem-coupling-halo: 0.25rem; /* nominally 4px */

    /* Legacy aliases (deprecated): keep only while migrating older code */
    --cem-touch-separation-min: var(--cem-coupling-guard-min);
    --cem-touch-target-min: var(--cem-coupling-zone-min);
}
```

Interpretation (summary):

- **Zone**: can the user reliably couple intent to the control?
- **Guard**: will adjacent controls accidentally steal intent?
- **Halo**: can we keep visuals compact while preserving operability?

### 6.4 Reading rhythm (vertical cadence for prose)

This is distinct from UI rhythm.

###### cem-dim-rhythm-reading

| Token                            | Value                  | Description                                              | tier        |
|----------------------------------|------------------------|----------------------------------------------------------|-------------|
| `--cem-rhythm-reading-paragraph` | 0.75em                 | Default paragraph spacing for prose                      | recommended |
| `--cem-rhythm-reading-section`   | `var(--cem-dim-large)` | Space between reading sections within one surface (24px) | recommended |

**Cross-reference:** Reading rhythm must be validated against typography tokens. See [
`cem-voice-fonts-typography.md`](./cem-voice-fonts-typography.md).

### 6.5 Data/scan rhythm (dense but legible)

Optimized for scan/compare flows (tables, metrics).

###### cem-dim-rhythm-data

| Token                     | Value                    | Description                                                   | tier        |
|---------------------------|--------------------------|---------------------------------------------------------------|-------------|
| `--cem-rhythm-data-row`   | `var(--cem-dim-x-small)` | Table-like, scan-first row padding (8px)                      | recommended |
| `--cem-rhythm-data-group` | `var(--cem-dim-medium)`  | Scan grouping — subtotals, row groups, metric clusters (16px) | recommended |

---

## 7. Layout rhythm tokens (compositional semantics)

These describe **layout structures** without baking in specific components.

### 7.1 Stack rhythm (vertical composition)

Default vertical stack gap for general UI stacks. Optional tight/loose variants for systems that need explicit range.

### 7.2 Cluster rhythm (horizontal groups)

Default cluster gap for inline groups (icons + text, toolbars, button clusters). The legacy `--cem-layout-inline-*`
aliases are deprecated — use `--cem-gap-*` instead.

### 7.3 Page gutters (responsive breathing room)

These are *responsive* and should be treated as semantics, not fixed numbers.

### 7.4 Layout token table

###### cem-dim-layout

| Token                       | Value                     | Description                                                               | tier        |
|-----------------------------|---------------------------|---------------------------------------------------------------------------|-------------|
| `--cem-layout-stack-gap`    | `var(--cem-gap-block)`    | Default vertical stack gap for general UI stacks                          | required    |
| `--cem-layout-cluster-gap`  | `var(--cem-gap-related)`  | Default cluster gap for inline groups                                     | required    |
| `--cem-layout-gutter`       | `var(--cem-dim-medium)`   | Default content gutter (16px)                                             | required    |
| `--cem-layout-gutter-wide`  | `var(--cem-dim-x-large)`  | Wide-screen gutter (32px)                                                 | recommended |
| `--cem-layout-gutter-max`   | `var(--cem-dim-xx-large)` | Maximum gutter (64px)                                                     | recommended |
| `--cem-layout-stack-tight`  | `var(--cem-gap-related)`  | Tight stack variant — rare, use only when explicitly tighter than default | optional    |
| `--cem-layout-stack-loose`  | `var(--cem-gap-section)`  | Loose stack variant — rare, use only when explicitly looser than default  | optional    |
| `--cem-layout-inline-tight` | `var(--cem-dim-x-small)`  | Deprecated — use `--cem-gap-related`                                      | deprecated  |
| `--cem-layout-inline`       | `var(--cem-dim-small)`    | Deprecated — use `--cem-gap-group`                                        | deprecated  |
| `--cem-layout-inline-loose` | `var(--cem-dim-medium)`   | Deprecated — use `--cem-gap-block`                                        | deprecated  |

---

## 8. Spacing modes knob (dense / normal / sparse)

Material often frames this as "density." In CEM, treat this explicitly as a **D1 spacing mode** that shifts Space &
Rhythm while preserving D2 coupling invariants.

```css
:root {
    /* dense | normal | sparse */
    --cem-layout-spacing: normal;
}
```

### 8.1 Adjustment policy

Mode intent summary:

| D1 spacing mode | Primary goal                 | What changes                                     | What must not change                                                                                                                     |
|-----------------|------------------------------|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| `dense`         | Increase information density | Step down gaps/insets/gutters ~1 step where safe | D2 coupling invariants (zone/guard), and any gap that separates interactive affordances must still satisfy `gap = max(D1 gap, D2 guard)` |
| `normal`        | Baseline                     | Use canonical endpoints as defined               | Same invariants                                                                                                                          |
| `sparse`        | Increase calm/readability    | Step up gaps/insets/gutters ~1 step              | Same invariants                                                                                                                          |

- **normal**: baseline values as defined in Sections 6–7.
- **dense**: reduce gaps/insets by ~1 step where it does not harm reading cadence or interactive coupling.
- **sparse**: increase gaps/insets by ~1 step to improve readability and perceived calm.

Hard constraints (never override):

- `--cem-coupling-zone-min`
- `--cem-coupling-guard-min` (may force some "gaps" to stay at or above the minimum)
- `--cem-coupling-halo` (must be considered when validating dense clusters)

### 8.2 Concrete overrides (recommended default mapping)

`normal` mode uses the baseline values defined in §6–7. `dense` steps gaps down ~1 scale step; `sparse` steps them up ~1
step. Tokens not in this table are unaffected by spacing mode.

###### cem-dim-spacing-overrides

| Token                            | dense                     | sparse                     |
|----------------------------------|---------------------------|----------------------------|
| `--cem-gap-related`              | `var(--cem-dim-x-small)`  | `var(--cem-dim-small)`     |
| `--cem-gap-group`                | `var(--cem-dim-x-small)`  | `var(--cem-dim-medium)`    |
| `--cem-gap-block`                | `var(--cem-dim-small)`    | `var(--cem-dim-large)`     |
| `--cem-gap-section`              | `var(--cem-dim-medium)`   | `var(--cem-dim-x-large)`   |
| `--cem-gap-page`                 | `var(--cem-dim-large)`    | `var(--cem-dim-xx-large)`  |
| `--cem-inset-control`            | `var(--cem-dim-x-small)`  | `var(--cem-dim-small)`     |
| `--cem-inset-container`          | `var(--cem-dim-small)`    | `var(--cem-dim-large)`     |
| `--cem-inset-surface`            | `var(--cem-dim-medium)`   | `var(--cem-dim-x-large)`   |
| `--cem-layout-gutter`            | `var(--cem-dim-small)`    | `var(--cem-dim-large)`     |
| `--cem-layout-gutter-wide`       | `var(--cem-dim-large)`    | `var(--cem-dim-xx-large)`  |
| `--cem-layout-gutter-max`        | `var(--cem-dim-x-large)`  | `var(--cem-dim-xxx-large)` |
| `--cem-rhythm-reading-paragraph` | 0.6em                     | 1em                        |
| `--cem-rhythm-reading-section`   | `var(--cem-dim-medium)`   | `var(--cem-dim-x-large)`   |
| `--cem-rhythm-data-row`          | `var(--cem-dim-xx-small)` | `var(--cem-dim-small)`     |
| `--cem-rhythm-data-group`        | `var(--cem-dim-small)`    | `var(--cem-dim-large)`     |

### 8.3 Notes on component mapping

* Components should bind to semantic endpoints (`gap-*`, `inset-*`, `rhythm-*`) and inherit spacing mode automatically.

* If a component is interactive and uses layout gaps between peer affordances, resolve its gap as:
  `gap = max(D1 semantic gap, D2 coupling guard)`.
* If a component must remain stable across spacing modes (rare), bind it to reference steps explicitly and document why.

### 8.4 Layout mapping checklist (how to apply)

Use these patterns so teams can implement screens without inventing spacing semantics.

**Stacks (vertical composition)**

- Default: use `--cem-layout-stack-gap` (maps to `--cem-gap-block`).
- Within a group of tightly related elements (e.g., label + control + helper): use `--cem-gap-related`.

**Clusters (horizontal composition)**

- Default: use `--cem-layout-cluster-gap` (maps to `--cem-gap-related`).
- If cluster members are independently interactive (e.g., icon button groups), resolve as:
    - `gap: max(var(--cem-layout-cluster-gap), var(--cem-coupling-guard-min))`.

**Cards / panels / surfaces**

- Container padding: `--cem-inset-container`.
- Reading- or emphasis-first surfaces: `--cem-inset-surface`.
- Tight control trays: `--cem-inset-control` (only when content remains legible).
- **Note:** When using rounded surfaces, ensure inset accommodates bend. See [`cem-shape.md`](./cem-shape.md) §8.5.

**Sections and page regions**

- Between blocks: `--cem-gap-block`.
- Between major sections: `--cem-gap-section`.
- Between page regions: `--cem-gap-page`.

**Gutters (responsive framing)**

- Default: `--cem-layout-gutter`.
- Wide screens: `--cem-layout-gutter-wide`.
- Maximum breathing room: `--cem-layout-gutter-max`.

**Reading and data cadence**

- Prose: use `--cem-rhythm-reading-paragraph` and `--cem-rhythm-reading-section`.
- Scan-heavy: use `--cem-rhythm-data-row` and `--cem-rhythm-data-group`.

---

## 9. Mapping notes: M3 ↔ CEM

### 9.1 Where this matches Material 3

- 4dp-based reference steps provide the same rhythmic lattice.
- "Micro/standard/macro/extended" groupings align with common M3 guidance.

### 9.2 Where this differs (intentionally)

- CEM exposes **consumer-intent** tokens as the *primary interface*.
- Value-centric tokens are kept as **reference** only.
- Component tokens should map to semantic tokens, not to raw numbers.

---

## 10. Quick adoption checklist

1. Use the dimension scale (`--cem-dim-*`) as the foundation.
2. Map semantic endpoints (`gap-*`, `inset-*`, `rhythm-*`) to dimension tokens.
3. Treat D2 coupling (`zone/guard/halo`) as **hard constraints** for interactive adjacency — see [
   `cem-coupling.md`](./cem-coupling.md).
4. Update component tokens to use semantic endpoints.
5. Add optional `data-cem-spacing="dense|normal|sparse"` only if product needs spacing modes.
6. Validate on representative surfaces:
    - interactive clusters: guard is respected and no halo overlap occurs
    - reading rhythm (articles/help)
    - scan rhythm (tables/metric panels)
    - responsive gutters
7. Validate bend-inset harmony on rounded surfaces — see [`cem-shape.md`](./cem-shape.md) §8.5.

---

## Appendix A. D2 Coupling Mode Matrix (excerpt)

This excerpt is provided for convenience when working in D1. The canonical safety definitions and governance live in
**D2. Coupling & Compactness** ([`cem-coupling.md`](./cem-coupling.md)); visual geometry values live in **D2c.
Controls** ([`cem-controls.md`](./cem-controls.md)).

| Coupling mode | Product intent                                            | D2c Controls visual geometry trend          | D2 halo (`--cem-coupling-halo`) trend | Typical surfaces                                      |
|---------------|-----------------------------------------------------------|---------------------------------------------|--------------------------------------|-------------------------------------------------------|
| `forgiving`   | Minimize mis-coupling for imprecise input                 | Larger controls/rows; more internal padding | Smaller (visuals already meet zone)  | mobile-first, kiosks, accessibility-first, gaze/dwell |
| `balanced`    | Default across modalities                                 | Baseline control heights/rows               | Baseline                             | mixed pointer + touch, general app UI                 |
| `compact`     | Increase information density without breaking operability | Smaller visuals; reduced chrome             | Larger (use halo to preserve zone)   | data grids, admin tools, scan-heavy panels            |

Normative invariants (do not override in D1):

- `--cem-coupling-zone-min` is mode-invariant.
- `--cem-coupling-guard-min` is mode-invariant.
- D1 gaps between interactive affordances must resolve as: `gap = max(D1 semantic gap, D2 coupling guard)`.

---

## Appendix B. Governance and versioning

This D1 spec is a **contract**. Changes must be intentional, reviewable, and versioned.

### B.1 What counts as breaking

Treat as **major** (breaking) if you:

- Rename or remove any canonical D1 semantic endpoint (`gap-*`, `inset-*`, `layout-*`, `rhythm-*`).
- Change the semantic meaning of an endpoint (e.g., `gap-group` stops meaning "within a group").
- Change mode names or add/remove spacing modes.
- Weaken the D1↔D2 constraint model (anything that could permit violating D2 coupling guard/zone).

### B.2 What is non-breaking

Treat as **minor/patch** if you:

- Adjust numeric values within a mode while preserving semantics and invariants.
- Add new semantic endpoints that are clearly scoped, optional, and do not redefine existing meaning.
- Clarify documentation, examples, or mapping guidance.

### B.3 Versioning guidance

- **PATCH**: documentation clarifications; no token/value changes.
- **MINOR**: additive tokens or additive examples; safe value tuning.
- **MAJOR**: renames, removals, meaning shifts, or mode changes.

### B.4 Canonical cross-spec invariants

D1 is subordinate to D2 for operability. The following must hold in every release:

- D2 coupling invariants remain enforceable from D1.
- Any D1 spacing used between interactive affordances must resolve as `gap = max(D1 semantic gap, D2 coupling guard)`.

---

## 11. Acceptance criteria

**Interactive-adjacency contract (non-normative for generator):** any consumer using D1 gaps between interactive
affordances must resolve the effective gap as:

```css
gap:

max
(
var
(
--cem-gap-related

)
,
var
(
--cem-coupling-guard-min

)
)
;
```

The generator does not enforce this — it is component-author responsibility, documented in the manifest notes above.

**Reading-rhythm validation** is deferred to D6 cross-check (Phase 12 in the implementation plan). D1 cannot validate
rhythm in isolation.

## 12. 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-dimension.html`.

| Source table h6 id       | Tokens covered                                                            | Validator derivation |
|--------------------------|---------------------------------------------------------------------------|----------------------|
| `cem-dim-scale`          | `--cem-dim-*` (8 tokens)                                                  | one token per row    |
| `cem-dim-gaps`           | `--cem-gap-*` (5 tokens)                                                  | one token per row    |
| `cem-dim-insets`         | `--cem-inset-*` (3 tokens)                                                | one token per row    |
| `cem-dim-rhythm-reading` | `--cem-rhythm-reading-*` (2 tokens)                                       | one token per row    |
| `cem-dim-rhythm-data`    | `--cem-rhythm-data-*` (2 tokens)                                          | one token per row    |
| `cem-dim-layout`         | `--cem-layout-*` (10 tokens; deprecated tier omitted from default output) | one token per row    |

Spacing mode overrides (`cem-dim-spacing-overrides`) produce no new token names — they override existing tokens within
`:root[data-cem-spacing="dense"]` and `:root[data-cem-spacing="sparse"]` selectors.

---

## References

**Local CEM documentation**

- [D2. Coupling & Compactness](./cem-coupling.md) — interactive operability constraints
- [D3. Shape & Bend](./cem-shape.md) — bend tokens, bend-inset harmony
- [D5. Stroke & Separation](./cem-stroke.md) — boundaries, dividers, focus/selection/target indicators
- [D6. Typography](./cem-voice-fonts-typography.md) — reading rhythm validation
- [D7. Time & Motion](./cem-timing.md) — rhythm perception
