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) — color weight pairs with spacing rhythm
• D2. Coupling & Compactness (cem-coupling) — normative for interactive operability
• D3. Shape & Bend (cem-shape) — bend/inset harmony rules
• D4. Layering (cem-layering) — prominent layers “earn” breathing room
• D5. Stroke & Separation (cem-stroke) — boundaries, dividers, focus indicators
• D6. Typography (cem-voice-fonts-typography) — reading rhythm validation
• D7. Time & Motion (cem-timing) — rhythm perception

Table of Contents

1. Scope
2. CEM alignment principles applied to spacing
   • 2.1 Semantic intent first
   • 2.2 Bounded variation
   • 2.3 Accessibility and operability by construction
3. Token model
4. Relation to Dimensional Tokens
   • 4.1 Dimensional Tokens: where spacing lives
   • 4.2 Governance rules (cross-category contracts)
5. Reference spacing scale (semantic)
   • 5.1 Primary dimension scale
   • 5.2 Mapping to M3 rhythm
6. Consumer-semantic spacing taxonomy
   • 6.1 Relationship gaps (between items)
   • 6.2 Insets (inside a surface)
   • 6.3 Coupling and interaction safety (D2 cross-reference)
   • 6.4 Reading rhythm (vertical cadence for prose)
   • 6.5 Data/scan rhythm (dense but legible)
7. Layout rhythm tokens (compositional semantics)
   • 7.1 Stack rhythm (vertical composition)
   • 7.2 Cluster rhythm (horizontal groups)
   • 7.3 Page gutters (responsive breathing room)
8. Spacing modes knob (dense / normal / sparse)
   • 8.1 Adjustment policy
   • 8.2 Concrete overrides
   • 8.3 Notes on component mapping
   • 8.4 Layout mapping checklist
9. Mapping notes: M3 ↔ CEM
10. Quick adoption checklist

Appendices

• Appendix A. D2 Coupling Mode Matrix (excerpt)
• 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

  • 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

  • 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

  • bend / corner radius roles
  • bend-inset harmony (see §4.2 rule 5)

• D4. Layering — see cem-layering

  • 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

  • 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

  • weight/mass roles that affect perceived density and hierarchy

• D7. Time & Motion Timing — see cem-timing

  • 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:

/* 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 §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 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

Cross-reference: These tokens are consumed by D3 Shape (cem-shape) 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

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

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

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

6.3 Coupling and interaction safety (D2 cross-reference)

These tokens are defined and governed in D2 (cem-coupling). 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.

: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

Cross-reference: Reading rhythm must be validated against typography tokens. See cem-voice-fonts-typography.

6.5 Data/scan rhythm (dense but legible)

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

cem-dim-rhythm-data

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

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.

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

8.1 Adjustment policy

Mode intent summary:

• 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

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 §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.
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 §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); visual geometry values live in D2c. Controls (cem-controls).

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:

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.

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 — interactive operability constraints
• D3. Shape & Bend — bend tokens, bend-inset harmony
• D5. Stroke & Separation — boundaries, dividers, focus/selection/target indicators
• D6. Typography — reading rhythm validation
• D7. Time & Motion — rhythm perception