Semantic Spacing and Layout Rhythm Tokens (CEM × M3)

Status: Canonical (D1 v1.0)

Last updated: August 10, 2026

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

  • 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

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

• D4. Layering — see 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

  • 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

  • weight/mass roles that affect perceived density and hierarchy

• D7. Time & Motion Timing — see 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:

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

• Space is the primary proximity/grouping signal. In tight layouts or contrast themes, D5 may reinforce that signal by increasing stroke/separation, but the visible line does not take ownership of the D1 relationship meaning.
• A divider component may package its D5 line with cross-axis margins. Select those margins from a D1 relationship endpoint and apply the D2 guard as a minimum when the separated siblings are interactive.

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 §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 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.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

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.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). 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.md.

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

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

Decision: optional component dimensions and compact hit areas

Control size belongs to D2c Controls, while D2 Coupling owns operability and D1 owns layout spacing. Do not map control size="large" to the D1 spacing token --cem-dim-large.

• Omitted size keeps inherited control geometry (currently a 2.5rem visual minimum); content and container flex/grid allocation determine the final box.
• Optional small / medium / large / x-large / xx-large profiles use minimum visible heights of 2.5rem / 3rem / 4rem / 6rem / 8rem. Large profiles support vertical rhythm when actions participate in layouts. They do not fix width or cap growth.
• Containers select data-cem-size; action exposes size as a local override. Removing it restores inheritance. Other controls can adopt this shared pattern.
• The native control owns at least --cem-coupling-zone-min in both axes (currently 3rem). Small requested geometry reserves a transparent hit border inside that box; profiles meeting the minimum need no expansion. This includes the omitted/default and compact-coupling cases, not just explicit small.
• Paint retains the compact surface and theme curvature; zebra encloses the operable bounds. The expanded region is clickable, participates in layout, and respects guard spacing. There is no overlapping absolute hit halo or extra interactive element.
• Typography, icons and padding retain their existing theme values in this increment. Size, spacing and coupling remain separate choices.

The 3rem target is CEM policy, not a claim of automatic ADA conformance. At a 16px root it is 48 CSS pixels; consumers must assess actual computed dimensions.

Size roles and composition

Size expresses available space and prominence. Content type suggests useful examples, but does not select size automatically. Keep medium as the API spelling for an ordinary standalone action; normal is not an additional value.

An icon-only action can use any profile. Glyph size, content layout, intent, coupling and control height remain independent. The xx-large baseline continues the 4/6/8rem progression for large controls; it is a starting minimum, not a fixed hero height or a reuse of the D1 --cem-dim-xx-large spacing token. Images, wrapping text and responsive container layout determine the final size. Only requested geometry below the coupling minimum adds the transparent hit border. Medium and larger default profiles add none, including tiles and heroes. An overridden profile below that minimum still receives the safety inset.

Compose image/title content through the default slot using noninteractive phrasing content, such as spans, images and strong text. The action permits label wrapping; the author owns stacked or responsive layouts inside the projected content. Size never silently changes row/column layout, font scale or image size. Keep content readable under zoom and narrow containers rather than clipping it to a preset height. A small profile stretched by layout retains its reserved compact inset; this policy follows requested geometry, not DOM measurement.

Semantics follow behavior at every size: a command uses a native button and a destination uses a native link. The current cem-action owns a native button; the image and hero playground samples therefore choose content, not navigate. Adding native-link support is a separate component contract change. A card with an interactive preview or several actions keeps those controls separate; do not nest them inside one action. The legacy material demo-list-card follows this composition: the preview is a sibling of a title/description link with a 6rem minimum height.

This decision draws on Angular Material buttons, Material 3 Expressive button sizes, icon button sizes, and Angular Material card composition. Material offers size choices for both text and icon buttons; CEM retains its own theme scale and coupling minimum.