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

4.2 Height ranges (semantic)

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

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

cem-bp-height

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

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

cem-bp-height-ranges

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.

6.2 Material UI (MUI) default breakpoints

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

Strategy B mapping (CEM keys as MUI keys):

Strategy C mapping (mixed keyspace, transitional):

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

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.

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

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.

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.md) — spacing scale and layout gaps
• D2. Coupling & Compactness (cem-coupling.md) — density invariants across ranges
• D5. Stroke & Separation (cem-stroke.md) — separability reinforcement under density pressure
• D6. Typography (Voice & Reading) (cem-voice-fonts-typography.md) — reading constraints and scanning patterns
• D1y. Responsiveness Strategy (cem-responsive.md) — 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.