# CEM D1x Breakpoints & Responsive Ranges — Window Size Classes (CEM × M3 × MUI)

Status: Canonical (v1.0) Last updated: 2025-12-23 Taxonomy placement: D1x. Layout Framing (Space & Rhythm extension) Audience: Design Systems, Product Design, Front-End Engineering

CEM first rule: If an adapter’s breakpoint names or defaults conflict with CEM semantics, CEM semantics win. Adapters translate to their own keyspaces; the consumer-facing vocabulary remains `compact/medium/expanded/large/xlarge`.

CEM uses breakpoints as a layout framing primitive that selects canonical layout archetypes (single-pane, two-pane, multi-pane) based on available space. Breakpoints express semantic meaning about available UI space, not device categories.

Companion specs:

- D0. Color (`cem-colors`) — emotional palette and action states
- D1. Space & Rhythm (`cem-dimension`) — spacing scale, density modes, layout gaps
- D1y. Responsiveness Strategy (`cem-responsive`) — intrinsic vs container vs breakpoint adaptation
- D2. Coupling & Compactness (`cem-coupling`) — zone/guard/halo invariants preserved across ranges
- D4. Layering (`cem-layering`) — depth/surface hierarchy
- D5. Stroke & Separation (`cem-stroke`) — separability may need reinforcement in dense layouts
- D6. Typography (`cem-voice-fonts-typography`) — reading constraints validated in large widths
- D7. Time & Motion (`cem-timing`) — layout transition timing

## Table of contents

1. Scope
2. Design principles
3. Token taxonomy
4. Window size classes
5. Token surface (CSS)
6. Adapter mapping
7. Usage guidance
8. Container queries extension
9. Governance and versioning
10. Canonical token summary
11. References

## 1. Scope

### 1.1 What D1x controls

D1x (Breakpoints) defines:

- Semantic range vocabulary: `compact`, `medium`, `expanded`, `large`, `xlarge` — stable names for layout bands.
- Numeric basis bounds: CSS custom properties for range boundaries.
- Adapter guidance: mapping to Material UI, Material Design 3, and other framework breakpoints.

### 1.2 What D1x does not define

D1x does not define:

- Column counts, grid systems, or gutter sizes (see D1 Space & Rhythm).
- Component-level responsive props (Grid, Stack, etc.).
- Container query values (optional extension in §8).

## 2. Design principles

### 2.0 CEM first rule: semantics before adapters

CEM breakpoint semantics are defined by available layout space and consumer intent (one-pane vs two-pane vs multi-pane), not by framework defaults (for example, `md` meaning “900px” in MUI). Treat framework breakpoints as an adapter layer.

### 2.1 Semantics express available space, not devices

A breakpoint expresses available UI space (window/container), not “tablet vs desktop”. Do not implement `isTablet`-style logic based on breakpoint names.

### 2.2 Bounded variation

Breakpoints are a small, stable vocabulary. Prefer 3–5 ranges, not dozens of product-specific micro-breakpoints.

### 2.3 Breakpoints select layouts; details are separate

Breakpoints choose canonical layout archetypes (one-pane → two-pane → multi-pane). Spacing, coupling, and stroke rules stay governed by their own dimensions (D1/D2/D5).

### 2.4 Cross-dimension invariants

- D2 coupling invariants (zone/guard/halo) must remain enforceable in every size class.
- D6 reading constraints should be validated in large widths (line length, paragraph rhythm).
- D5 separability may need reinforcement in dense layouts regardless of width.

## 3. Token taxonomy

### 3.1 Two-layer model

CEM breakpoints use a two-layer model:

    Basis bounds (numeric boundaries)
      --cem-bp-{axis}-{range}-{min|max}
            │
            ▼
    Semantic ranges (consumer vocabulary)
      compact | medium | expanded | large | xlarge

### 3.2 Why two layers?

- Adapter flexibility: numeric values can be tuned without changing semantic contracts.
- Consumer stability: product code depends on range names, not pixel values.
- Cross-framework mapping: different frameworks can adjust bounds while preserving intent.

## 4. Window size classes

CEM adopts the Material Design 3 window size class vocabulary as the primary reference because it is intentionally device-agnostic and defined on available width/height.

### 4.1 Width ranges (semantic)

CEM range | Meaning (consumer) | Width — reference
--- | --- | ---
`compact` | single-pane default; tight navigation | `< 600dp`
`medium` | two-pane possible; avoid over-wide lines | `600dp ≤ w < 840dp`
`expanded` | two-pane comfortable; navigation rail viable | `840dp ≤ w < 1200dp`
`large` | multi-pane viable; guard against sparse “stretch” | `1200dp ≤ w < 1600dp`
`xlarge` | desktop-class; constrain reading width, increase density | `≥ 1600dp`

### 4.2 Height ranges (semantic)

Height is usually secondary due to vertical scrolling, but matters for landscape phones and split-screen.

CEM range | Height — reference | Device representation (informative)
--- | --- | ---
`compact` | `< 480dp` | 99.78% of phones in landscape
`medium` | `480dp ≤ h < 900dp` | 96.56% of tablets in landscape, 97.59% of phones in portrait
`expanded` | `≥ 900dp` | 94.25% of tablets in portrait

> Note: Most apps adapt based on width alone. Consider height when width is `medium` while height is `compact` (e.g., phones in landscape), where two-pane layouts are often impractical.

## 5. Token surface (CSS)

### 5.1 Basis tokens (bounds)

These tokens are numeric bounds for ranges, consumed by build-time systems (PostCSS/@custom-media), JS breakpoints, and runtime CSS systems. Epsilon is used when expressing half-open intervals `[min, nextMin)` as exclusive `max-width`/`max-height` values.

###### cem-bp-basis

Token | Value | Description | tier
--- | --- | --- | ---
`--cem-bp-epsilon` | `0.01px` | Default epsilon for exclusive upper bounds | required
`--cem-bp-epsilon-css` | `0.01px` | Explicit CSS adapter epsilon (same as default) | recommended
`--cem-bp-epsilon-mui` | `0.05px` | MUI adapter epsilon (`theme.breakpoints.step = 5` parity) | recommended
`--cem-bp-width-compact-min` | `0px` | Compact width lower bound | required
`--cem-bp-width-compact-max` | `calc(var(--cem-bp-width-medium-min) - var(--cem-bp-epsilon))` | Compact width upper bound (exclusive) | required
`--cem-bp-width-medium-min` | `600px` | Medium width lower bound (M3 reference) | required
`--cem-bp-width-medium-max` | `calc(var(--cem-bp-width-expanded-min) - var(--cem-bp-epsilon))` | Medium width upper bound (exclusive) | required
`--cem-bp-width-expanded-min` | `840px` | Expanded width lower bound (M3 reference) | required
`--cem-bp-width-expanded-max` | `calc(var(--cem-bp-width-large-min) - var(--cem-bp-epsilon))` | Expanded width upper bound (exclusive) | recommended
`--cem-bp-width-large-min` | `1200px` | Large width lower bound (M3 reference) | recommended
`--cem-bp-width-large-max` | `calc(var(--cem-bp-width-xlarge-min) - var(--cem-bp-epsilon))` | Large width upper bound (exclusive) | recommended
`--cem-bp-width-xlarge-min` | `1600px` | Xlarge width lower bound (no max; unbounded) | recommended

###### cem-bp-height

Token | Value | Description | tier
--- | --- | --- | ---
`--cem-bp-height-compact-min` | `0px` | Compact height lower bound | recommended
`--cem-bp-height-compact-max` | `calc(var(--cem-bp-height-medium-min) - var(--cem-bp-epsilon))` | Compact height upper bound (exclusive) | recommended
`--cem-bp-height-medium-min` | `480px` | Medium height lower bound | recommended
`--cem-bp-height-medium-max` | `calc(var(--cem-bp-height-expanded-min) - var(--cem-bp-epsilon))` | Medium height upper bound (exclusive) | recommended
`--cem-bp-height-expanded-min` | `900px` | Expanded height lower bound (no max; unbounded) | recommended

### 5.2 Active width tracker

The `@media` helpers in Block B set this token so that JS can read the current breakpoint class via `getComputedStyle(document.documentElement).getPropertyValue('--cem-bp-active-width').trim()`. There is no `:root` default; the value is always resolved from `@media` context.

###### cem-bp-active

Token | Description | tier
--- | --- | ---
`--cem-bp-active-width` | Current active width class (compact/medium/expanded/large/xlarge); read via JS | recommended
`--cem-bp-active-height` | Current active height class (short/medium/tall); read via JS | recommended

### 5.3 Generator helper: @media range data

These tables drive the `@media` and height helper blocks in the generator. They are not token sources — rows do not begin with `--cem-*` and are excluded from the manifest automatically.

###### cem-bp-media-ranges

range | min-width | max-width | description
--- | --- | --- | ---
compact | 0px | 599.99px | max-only rule; M3 compact width
medium | 600px | 839.99px | M3 medium width
expanded | 840px | 1199.99px | M3 expanded width
large | 1200px | 1599.99px | M3 large width
xlarge | 1600px | — | min-only rule; M3 xlarge width

###### cem-bp-height-ranges

range | min-height | max-height | description
--- | --- | --- | ---
compact | 0px | 479.99px | max-only rule; compact height
medium | 480px | 899.99px | medium height
expanded | 900px | — | min-only rule; expanded height

### 5.4 Normative rules

- Bounds MUST be strictly increasing.
- Range names MUST remain stable (`compact`, `medium`, `expanded`, optionally `large`, `xlarge`).
- Ranges MUST be interpreted as half-open intervals: `[min, nextMin)` (lower bound inclusive, upper bound exclusive).
- If you must express an exclusive upper bound as a CSS `max-width`/`max-height`, subtract a small epsilon.
  - The epsilon value is adapter/toolchain-specific, but MUST be applied consistently to avoid overlap.
  - In Material UI, prefer the built-in mechanism: `theme.breakpoints.step` (default `5`, i.e., `0.05px`) which is used to implement exclusive `down()`/`between()` upper bounds.

### 5.5 @custom-media (where supported; NOT emitted in production output)

    @custom-media --cem-compact  (max-width: calc(600px - 0.01px));
    @custom-media --cem-medium   (min-width: 600px) and (max-width: calc(840px - 0.01px));
    @custom-media --cem-expanded (min-width: 840px) and (max-width: calc(1200px - 0.01px));
    @custom-media --cem-large    (min-width: 1200px) and (max-width: calc(1600px - 0.01px));
    @custom-media --cem-xlarge   (min-width: 1600px);

    /* Height classes */
    @custom-media --cem-height-compact  (max-height: calc(480px - 0.01px));
    @custom-media --cem-height-medium   (min-height: 480px) and (max-height: calc(900px - 0.01px));
    @custom-media --cem-height-expanded (min-height: 900px);

    /*
     * NOTE:
     * The `0.01px` epsilon is illustrative. Align epsilon to your toolchain:
     * - If you use MUI default step=5, prefer 0.05px for exclusive upper bounds.
     */

## 6. Adapter mapping

### 6.1 Material Design 3 (reference)

M3 window size classes provide the reference lattice for this spec. CEM directly adopts M3’s width/height boundaries.

M3 class | Width boundary
--- | ---
Compact | < 600dp
Medium | 600–839dp
Expanded | 840–1199dp
Large | 1200–1599dp
Extra-large | ≥ 1600dp

### 6.2 Material UI (MUI) default breakpoints

MUI key | Default value
--- | ---
`xs` | 0px
`sm` | 600px
`md` | 900px
`lg` | 1200px
`xl` | 1536px

Gap analysis: MUI lacks the 840px boundary (M3 `expanded`) and uses 1536px instead of 1600px for `xl`.

### 6.3 Recommended MUI → CEM strategies

CEM semantics are stable; your MUI integration chooses an adapter strategy.

Strategy A (recommended for most MUI codebases): keep MUI keys, align values to the CEM lattice.
This avoids custom keys and minimizes TypeScript/module-augmentation friction while matching CEM/M3 boundaries.

    const theme = createTheme({
      breakpoints: {
        values: {
          xs: 0,
          sm: 600,   // medium lower bound
          md: 840,   // expanded lower bound (repurposes MUI `md`)
          lg: 1200,  // large lower bound
          xl: 1600,  // xlarge lower bound (repurposes MUI `xl`)
        },
      },
    });

Strategy B (semantic purity): replace MUI keys with CEM keys (`compact/medium/expanded/large/xlarge`).
This yields the cleanest vocabulary, but requires TypeScript module augmentation and a broader migration.

Strategy C (bridge / mixed keyspace): add `expanded`/`xlarge` alongside the defaults.
Use only for incremental migration. This introduces two “large-ish” keys (`xl` vs `xlarge`)—treat the mixed period as transitional.

### 6.4 Mapping tables

Strategy A mapping (aligned values, default keys):

CEM range | MUI binding
--- | ---
`compact` | `down('sm')`
`medium` | `between('sm', 'md')`
`expanded` | `between('md', 'lg')`
`large` | `between('lg', 'xl')`
`xlarge` | `up('xl')`

Strategy B mapping (CEM keys as MUI keys):

CEM range | MUI binding
--- | ---
`compact` | `down('medium')` (or `only('compact')` if you define it explicitly)
`medium` | `between('medium', 'expanded')`
`expanded` | `between('expanded', 'large')`
`large` | `between('large', 'xlarge')`
`xlarge` | `up('xlarge')`

Strategy C mapping (mixed keyspace, transitional):

CEM range | MUI binding
--- | ---
`compact` | `down('sm')`
`medium` | `between('sm', 'expanded')`
`expanded` | `between('expanded', 'lg')`
`large` | `between('lg', 'xlarge')`
`xlarge` | `up('xlarge')`

## 7. Usage guidance

### 7.1 What SHOULD change at a breakpoint

Breakpoints trigger layout archetype changes:

- Navigation: bottom bar → rail → drawer
- Content: one-pane → two-pane → three-pane
- Density strategy: introduce secondary panes rather than shrinking controls below D2 invariants

### 7.2 What SHOULD NOT change at a breakpoint

- Do not reduce D2 coupling minimums.
- Do not rely on breakpoints to “fix” separability; use D5 stroke reinforcement where needed.
- Avoid large typography scale jumps; prefer continuous scaling and validate reading metrics (D6).

### 7.3 Responsive design principles

1. Mobile-first: start with `compact` layout, progressively enhance.
2. Content-driven: let content needs determine when to introduce panes.
3. Density-aware: larger screens can support higher information density (D2).
4. Line-length conscious: constrain reading width in `xlarge` to preserve D6 readability (45–75 characters optimal).

### 7.4 Orthogonal responsiveness strategy

Breakpoints (D1x) classify available space. Responsiveness strategy (D1y) classifies how layout adapts. Treat these as orthogonal axes:

- `intrinsic` — continuous adaptation via Flex wrap / intrinsic Grid / fluid constraints.
- `container` — adaptation based on container size (`@container`), for portable components.
- `breakpoint` — adaptation based on viewport/window size classes, for top-level IA shifts.
- `hybrid` — intrinsic-first, with breakpoint/container steps only where meaningfully needed.

In CEM, the default posture is intrinsic-first; introduce breakpoint-driven behavior primarily when the meaning of layout changes (e.g., one-pane → two-pane), not to compensate for rigid mechanics. See `cem-responsive`.

### 7.5 Component mapping checklist

Use this table to choose where D1x breakpoints apply and which D1y strategy to prefer. The “Responsiveness strategy” column is normative for component recipes; other columns are guidance.

Component family | Breakpoint role (D1x) | Preferred query context | Responsiveness strategy (D1y) | Notes
--- | --- | --- | --- | ---
App shell navigation (bottom bar / rail / drawer) | Yes (archetype switch) | Viewport/window | `breakpoint` / `hybrid` | Breakpoints change navigation meaning; keep D2 invariants.
Master–detail / list–detail panes | Yes (introduce second pane) | Viewport/window, sometimes container | `hybrid` | Use intrinsic sizing within panes; breakpoint decides when the second pane exists.
Card listings / galleries | Usually No | Container first | `intrinsic` / `container` | Prefer wrap or `auto-fit/minmax()`; avoid fixed column counts.
Forms (field groups) | Rare | Container first | `intrinsic` | Prefer flowing groups and `min()`/`max()` widths; breakpoint only for major reflow.
Data tables / dense comparison grids | Sometimes | Container first | `container` / `hybrid` | Container size often determines column visibility / stacking.
Side panels, filters, inspector panes | Sometimes | Container first | `container` / `hybrid` | The panel width (not viewport) is the driver in split UI.
Overlays (dialogs, popovers, tooltips) | No (typically) | Container/anchor | `intrinsic` | Size to content and coupling; do not key to viewport breakpoints.

### 7.6 Intrinsic layouts disclaimer (flex/grid, wrapping, and container-first responsiveness)

CEM breakpoints define semantic ranges of available space. They do not mandate a fixed grid, fixed column count, or device-class assumptions.

- Avoid fixed-column contracts on wide screens: ultra-wide and uncommon aspect ratios (including very wide displays such as ~8K×1K) can invalidate “N columns” assumptions even when total pixels are high.
- Prefer intrinsic, continuously-adaptive layouts first: use Flexbox with `flex-wrap`, and/or Grid patterns like `repeat(auto-fit, minmax(...))` so layout adapts smoothly to the actual space available.
- Prefer container width over viewport width for components: in split panes, sidebars, cards, and embedded widgets, container queries produce more reliable behavior than viewport media queries.

A well-designed intrinsic layout can span small mobile → large desktop → ultra-wide without introducing additional breakpoint classes. Use breakpoints primarily when the meaning of layout changes (e.g., introducing a second pane), not to compensate for rigid layout mechanics.

### 7.7 Content-first, component-first responsiveness patterns (informative)

- Content-driven breakpoints: introduce a breakpoint only when content “breaks” (wrapping, truncation, unusable density), not to match a device list.
- Component breakpoints via container queries: make components portable; they should adapt to the size of the region they are placed into.
- Continuous scaling where possible: use modern CSS constraints (e.g., `clamp()`) to avoid hard jumps in spacing/typography.

### 7.8 Should CEM introduce a token value like `responsive`?

Generally no: “responsive” is an implementation property (intrinsic vs breakpoint-driven), not a breakpoint range.

If you need to mark that a layout is intended to be intrinsic-responsive (wrapping/container-first), prefer a documentation tag in component mapping (e.g., `strategy: intrinsic`) or an adapter/build-time flag. Avoid encoding “responsive” as an extra breakpoint value because it conflates method with available space semantics.

## 8. Container queries extension

Some UIs (split panes, sidebars, embedded widgets) need size classes based on container width, not viewport.

### 8.1 Container bounds (optional)

These reference values reuse the same semantic lattice as the viewport breakpoints. Consumers place them in their own `@container` rules; CEM does not emit `@container` selectors directly. Uses `--cem-bp-epsilon` directly — no separate `--cem-cq-epsilon` needed.

R-D1x-WRAP resolved: CEM v1 documents the containment requirement but does not ship a wrapper component. Component libraries and products must opt each queryable host into containment with `container-type` (and optionally `container-name`). This keeps the token package framework-neutral and avoids adding layout side effects to consumers’ DOM. A wrapper may still be built by an adapter library, but it is not part of the canonical D1x token output.

###### cem-bp-cq

Token | Value | Description | tier
--- | --- | --- | ---
`--cem-cq-width-compact-max` | `calc(var(--cem-cq-width-medium-min) - var(--cem-bp-epsilon))` | Compact container upper bound (exclusive) | recommended
`--cem-cq-width-medium-min` | `600px` | Medium container lower bound | recommended
`--cem-cq-width-medium-max` | `calc(var(--cem-cq-width-expanded-min) - var(--cem-bp-epsilon))` | Medium container upper bound (exclusive) | recommended
`--cem-cq-width-expanded-min` | `840px` | Expanded container lower bound | recommended
`--cem-cq-width-expanded-max` | `calc(var(--cem-cq-width-large-min) - var(--cem-bp-epsilon))` | Expanded container upper bound (exclusive) | recommended
`--cem-cq-width-large-min` | `1200px` | Large container lower bound | recommended

### 8.2 Container query usage

    .container {
      container-type: inline-size;
      container-name: card;
    }

    @container card (max-width: 599.98px) {
      /* compact container layout */
    }

    @container card (min-width: 600px) and (max-width: 839.98px) {
      /* medium container layout */
    }

Implementation requirements:

- The element being queried MUST establish containment, usually with `container-type: inline-size`.
- Name containers (`container-name`) when more than one query context can be present or when component recipes need a stable target.
- Do not expect `--cem-cq-width-*` values to activate behavior by themselves; CSS custom properties cannot be used inside `@container` conditions.
- If a product provides a wrapper component, it should be adapter-owned and should do no more than establish the appropriate containment contract.

Material UI (optional): container query adapter and shorthand

Material UI exposes `theme.containerQueries` and an `sx` shorthand using `@<size>` / `@<size>/<name>`.

    // Theme API (breakpoint keys or unitless widths)
    theme.containerQueries.up('sm');        // => '@container (min-width: 600px)'
    theme.containerQueries('card').up(600); // => '@container card (min-width: 600px)'

    // sx shorthand (unitless sizes render as px; `@500px` is invalid syntax)
    <Box
      sx={{
        '@': { p: 1 },       // 0px
        '@600': { p: 2 },    // 600px
        '@840': { p: 3 },    // 840px
      }}
    />

### 8.3 Normative requirements

- Container bounds MUST map to the same semantic vocabulary (`compact/medium/expanded/...`).
- Consumer meaning MUST remain consistent between viewport and container contexts.

## 9. Governance and versioning

### 9.1 Breaking (major)

Treat as breaking if you:

- Rename/remove any canonical range name (`compact`, `medium`, `expanded`, `large`, `xlarge`).
- Reorder ranges or violate monotonic bounds.
- Change the meaning of a range (e.g., `medium` stops being the “two-pane possible” band).

### 9.2 Non-breaking (minor/patch)

Treat as non-breaking if you:

- Tune numeric bounds while preserving semantics and ordering.
- Add optional container-query bounds that map to the same range vocabulary.
- Clarify mapping guidance and examples.

## 10. 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-breakpoints.html`.

Source table h6 id | Tokens covered | Validator derivation
--- | --- | ---
`cem-bp-basis` | `--cem-bp-epsilon*` (3) + `--cem-bp-width-*` (9) = 12 tokens | one token per row
`cem-bp-height` | `--cem-bp-height-*` (5 tokens) | one token per row
`cem-bp-active` | `--cem-bp-active-width` + `--cem-bp-active-height` (2 tokens; set by @media, no `:root` default) | one token per row
`cem-bp-cq` | `--cem-cq-width-*` (6 tokens) | one token per row

Generator helper tables `cem-bp-media-ranges` and `cem-bp-height-ranges` are NOT token sources — their rows start with range names (not `--cem-*`), so they are automatically excluded from the manifest.

Note: `@custom-media` is NOT emitted in production output per Principle P5. The `@media` helper block (Block B) sets `--cem-bp-active-width` for JS consumption. The `@container` helper block (Block C) is intentionally not emitted after R-D1x-WRAP resolution; `--cem-cq-*` reference values are available in `:root` for consumers or adapter-owned wrappers to use in their own `@container` rules.

## 11. References

### Internal

- D1. Space & Rhythm (`cem-dimension`) — spacing scale and layout gaps
- D2. Coupling & Compactness (`cem-coupling`) — density invariants across ranges
- D5. Stroke & Separation (`cem-stroke`) — separability reinforcement under density pressure
- D6. Typography (Voice & Reading) (`cem-voice-fonts-typography`) — reading constraints and scanning patterns
- D1y. Responsiveness Strategy (`cem-responsive`) — intrinsic/container/breakpoint strategy vocabulary

### External

- Material Design 3 — Window size classes
- Android Developers — Use window size classes
- Material UI — Breakpoints
- Material UI — Container queries
- MDN — CSS container queries
- web.dev — Responsive web design basics (content-driven breakpoints)
- Jen Simmons — Designing Intrinsic Layouts (intrinsic design patterns)
- ModernCSS — Contextual Spacing for Intrinsic Web Design (`clamp()`)

This spec is the canonical D1x contract for CEM responsive breakpoints and adapter mapping.