# CEM D3 Shape — Bend (Edge Softness & Corner Roundedness)

**Status:** Proposed (canonical CEM spec)
**Last updated:** December 19, 2025

**Taxonomy placement:** D3. Shape & Bend (part of the 7-dimensional CEM token framework)

**Companion specs:**
- **D0. Color (Emotional Palette)** ([`cem-colors.md`](./cem-colors.md)) — color and shape work together for emotional impact
- **D1. Space & Rhythm** ([`cem-dimension.md`](./cem-dimension.md)) — provides dimension scale used by bend
- **D2. Coupling & Compactness** ([`cem-coupling.md`](./cem-coupling.md)) — provides control height for geometry-driven bend
- **D5. Stroke & Separation** ([`cem-stroke.md`](./cem-stroke.md)) — boundaries, dividers, and focus/selection/target indicators
- **D6. Typography** ([`cem-voice-fonts-typography.md`](./cem-voice-fonts-typography.md)) — related visual hierarchy
- **D7. Time & Motion** ([`cem-timing.md`](./cem-timing.md)) — animation timing for shape transitions

---

## Table of Contents

1. [Purpose and scope](#1-purpose-and-scope)
2. [Why "bend" (token naming rationale)](#2-why-bend-token-naming-rationale)
3. [CEM alignment principles applied to shape](#3-cem-alignment-principles-applied-to-shape)
   - [3.1 Semantic intent first](#31-semantic-intent-first)
   - [3.2 Bounded variation](#32-bounded-variation)
   - [3.3 Layering (basis → semantic endpoints → adapters)](#33-layering-basis--semantic-endpoints--adapters)
4. [Minimal bend basis (complexity-compliant)](#4-minimal-bend-basis-complexity-compliant)
5. [Semantic endpoints (product-facing contract)](#5-semantic-endpoints-product-facing-contract)
6. [Shape mode knob (brand expression)](#6-shape-mode-knob-brand-expression)
   - [6.1 Mode meanings](#61-mode-meanings)
   - [6.2 Mode implementation (recommended)](#62-mode-implementation-recommended)
   - [6.3 Helper classes (optional; scoped overrides)](#63-helper-classes-optional-scoped-overrides)
7. [Directional and asymmetric patterns](#7-directional-and-asymmetric-patterns)
   - [7.1 Attachment pattern](#71-attachment-pattern-one-pattern-not-many-tokens)
   - [7.2 When to use asymmetric corners](#72-when-to-use-asymmetric-corners)
   - [7.3 Implementation guidance](#73-implementation-guidance)
   - [7.4 Common recipes](#74-common-recipes)
8. [Accessibility and inclusive design requirements](#8-accessibility-and-inclusive-design-requirements)
   - [8.1 Shape must not be the only signal](#81-shape-must-not-be-the-only-signal)
   - [8.2 High-contrast and forced-colors resilience](#82-high-contrast-and-forced-colors-resilience)
   - [8.3 Focus indicators must respect the target](#83-focus-indicators-must-respect-the-target)
   - [8.4 Pointer target size and spacing](#84-pointer-target-size-and-spacing-bend--d2-size--d1-separation)
   - [8.5 Bend vs inset readability](#85-bend-vs-inset-readability-bend--d1-padding)
   - [8.6 Minimum test checklist](#86-minimum-test-checklist)
9. [Consumer vocabulary for "round ends" (capsules)](#9-consumer-vocabulary-for-round-ends-capsules)
10. [Component mapping](#10-component-mapping)
    - [10.1 Action binding (existing)](#101-action-binding-existing)
    - [10.2 Extended component mapping](#102-extended-component-mapping)
    - [10.3 Local alias pattern](#103-local-alias-pattern-preferred-for-variants)
11. [Notes on external systems (adapter-only)](#11-notes-on-external-systems-adapter-only)
12. [Quick adoption checklist](#12-quick-adoption-checklist)
13. [Governance and versioning](#13-governance-and-versioning)
    - [13.1 What counts as breaking (MAJOR)](#131-what-counts-as-breaking-major)
    - [13.2 What is non-breaking (MINOR / PATCH)](#132-what-is-non-breaking-minor--patch)
    - [13.3 Deprecation policy (recommended)](#133-deprecation-policy-recommended)
    - [13.4 Canonical token summary](#134-canonical-token-summary-contract-surface)

**Appendices**
- [Appendix A — Material 3 shape scale reference](#appendix-a--material-3-shape-scale-reference-adapter-mapping)
- [References](#references)

---

## 1. Purpose and scope

This spec defines **shape tokens beyond actions** — a consumer-semantic subsystem for **edge softness** and **corner roundedness**.

It:

- Describes **edge softness** and **corner roundedness** in terms of *perceived friendliness* rather than pixel values.
- Provides a **bounded reference basis** that can be adapter-mapped to Material 3 (and other) shape scales.
- Exposes **semantic endpoints** for surfaces and components based on their **role** in the UI.
- Supports an optional **shape mode knob** for brand expression: `sharp | smooth | round`.

Shape tokens communicate personality and help users understand **UI boundaries, groupings, and interactive affordances**.

**Out of scope:** layering/elevation (D4 — see [`cem-layering.md`](./cem-layering.md)), stroke thickness (D5), spacing/insets (D1), and operable/touch geometry (D2) — though shape must integrate with them (see §8 Accessibility section).

---

## 2. Why "bend" (token naming rationale)

In CEM terms, **bend** names the degree to which an edge curves away from a sharp corner. This framing:

- Avoids ambiguity with CSS `border-radius` (which can be a length, percentage, or elliptical).
- Emphasizes the *perceived* quality rather than the *implementation* detail.
- Supports consumer-semantic intent: "How friendly/formal does this surface feel?"

**Rule:** product code should use `--cem-bend-*` endpoints; implementation primitives (`border-radius`, elliptical radii,
corner pairs, etc.) remain an adapter/implementation detail.

---

## 3. CEM alignment principles applied to shape

### 3.1 Semantic intent first

Developers should apply tokens like:

- `--cem-bend-surface`, `--cem-bend-control`, `--cem-bend-overlay` (role semantics)
- `--cem-bend` (active bend value, mode-switchable)

…and not value-centric names like `radius-8` in component code.

This mirrors common design-token practice: values are "primitive/global," while **semantic/alias tokens** name where/how a
value is used. Keep product code semantic; keep value plumbing in the token layer.

### 3.2 Bounded variation

A small set of *distinct, recognizable* bend steps should cover most UI. The range goes from:

- `sharp` (none) → `smooth` (small bend) → `round-ends` (capsule) → `circle`

CEM applies a "bounded token budget" heuristic: avoid a long ladder of barely-distinguishable bend steps. If you need a new
step, justify it by a perceptual difference that survives dense mode, high zoom, and high-contrast overrides.

### 3.3 Layering (basis → semantic endpoints → adapters)

- **Basis tokens** define "what bend exists" (sharp / smooth / round-ends / circle).
- **Semantic endpoints** define "where bend is used" (surface / control / overlay / media).
- **Adapters** map external systems (Material / Fluent / etc.) into the basis and endpoints.

This keeps complexity low while still supporting multiple libraries.

---

## 4. Minimal bend basis (complexity-compliant)

This is the smallest stable basis that supports most UIs without overfitting.

```css
:root {
  /* Sharp = no bend */
  --cem-bend-sharp: 0;

  /* Smooth = small, friendly rounding; bind to D1 dimension scale */
  --cem-bend-smooth: var(--cem-dim-x-small); /* 0.5rem / 8px */

  /*
    Round ends (capsule / pill):
    Semicircle ends require bend = 0.5 * element height.
    Uses --cem-control-height from D2 (cem-coupling.md) as default.
    Provide --cem-shape-height where --cem-control-height is not appropriate.
  */
  --cem-bend-round: calc(var(--cem-shape-height, var(--cem-control-height)) / 2);

  /* True circle (avatars): percentage is defined relative to the element box. */
  --cem-bend-circle: 50%;

  /* Active bend used by endpoints that want the "default feel" (mode-switchable). */
  --cem-bend: var(--cem-bend-smooth);
}
```

**Cross-references:**
- `--cem-dim-x-small` is defined in [`cem-dimension.md`](./cem-dimension.md) §5
- `--cem-control-height` is defined in [`cem-coupling.md`](./cem-coupling.md) §4.2

---

## 5. Semantic endpoints (product-facing contract)

These are the tokens components should consume.

```css
:root {
  /* Core roles */
  --cem-bend-control: var(--cem-bend);
  --cem-bend-surface: var(--cem-dim-small);       /* 0.75rem / 12px — perceptual container geometry */
  --cem-bend-overlay: var(--cem-bend);            /* menus, tooltips, small popovers */

  /* Common specializations (keep minimal) */
  --cem-bend-field:              var(--cem-bend-control);
  --cem-bend-control-round-ends: var(--cem-bend-round);  /* optional capsule control variant */
  --cem-bend-modal:              calc(var(--cem-dim-large) + var(--cem-dim-xx-small)); /* ~28px — larger overlays */

  /* Media */
  --cem-bend-media:  var(--cem-bend);
  --cem-bend-avatar: var(--cem-bend-circle);
}
```

**Cross-references:**
- `--cem-dim-small`, `--cem-dim-large`, `--cem-dim-xx-small` are defined in [`cem-dimension.md`](./cem-dimension.md) §5

---

## 6. Shape mode knob (brand expression)

A shape mode knob is an **optional** product-level control that shifts bend across the UI to express a consistent brand
personality. It is intentionally coarse-grained: three modes are usually enough.

### 6.1 Mode meanings

| Mode      | Product intent                    | Typical bend policy (what changes)                                                                                                           | Perceived feel         |
|-----------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|------------------------|
| `sharp`   | Technical, precise, enterprise    | Default bend moves toward `--cem-bend-sharp`; surfaces/overlays may remain slightly bent to preserve grouping and layer separation           | Formal, authoritative  |
| `smooth`  | Balanced, modern (default)        | Canonical defaults (base `--cem-bend-smooth`, surfaces at D1 "small")                                                                        | Friendly, professional |
| `round`   | Consumer, welcoming, approachable | Surfaces step up (e.g., D1 "medium"); optional capsule controls via `--cem-bend-control-round-ends` where the product uses them consistently | Warm, inviting         |

**Critical constraint:** shape modes must not change meaning. A user should not need to infer state or priority from
roundness alone (see §8 Accessibility section).

### 6.2 Mode implementation (recommended)

Implement modes via a theme selector (attribute or class) and override **only** the base and/or semantic endpoints.
Avoid an in-CSS "mode selector variable" (e.g., `--cem-shape-mode: round`) because CSS cannot branch on it without a
preprocessor; it also obscures where the mode is applied.

```css
/* Default / smooth */
:root,
:root[data-cem-shape="smooth"] {
  --cem-bend: var(--cem-bend-smooth);
  --cem-bend-control: var(--cem-bend);
  --cem-bend-overlay: var(--cem-bend);
  --cem-bend-surface: var(--cem-dim-small);
}

/* Sharp */
:root[data-cem-shape="sharp"] {
  --cem-bend: var(--cem-bend-sharp);

  /* Minimum resilience policy (recommended): keep containers slightly bent unless the brand explicitly wants boxy UI */
  --cem-bend-surface: var(--cem-bend-smooth);
  --cem-bend-overlay: var(--cem-bend-smooth);
  --cem-bend-control: var(--cem-bend); /* sharp controls */
}

/* Round */
:root[data-cem-shape="round"] {
  /* Keep the default control bend unless capsules are a deliberate product-wide choice */
  --cem-bend: var(--cem-bend-smooth);

  --cem-bend-surface: var(--cem-dim-medium);
  --cem-bend-overlay: var(--cem-bend-smooth);

  /* Optional: enable capsules consistently (brand decision) */
  /* --cem-bend-control: var(--cem-bend-round); */
  /* --cem-bend-field:   var(--cem-bend-round); */
}
```

**If you introduce more granular local aliases** (e.g., card vs page surface), they may also be overridden by the mode
selector, but only as pointers to existing endpoints. Do not mint a parallel "mode-specific" token family.

### 6.3 Helper classes (optional; scoped overrides)

If you need one-off local overrides (e.g., a demo page or controlled experiment), helper classes are acceptable, but should
not replace theme-level mode selectors.

```css
.cem-bend-smooth { --cem-bend: var(--cem-bend-smooth); }
.cem-bend-round  { --cem-bend: var(--cem-bend-round);  }
.cem-bend-sharp  { --cem-bend: var(--cem-bend-sharp);  }
```

Prefer overriding **semantic endpoints** (`--cem-bend-control`, `--cem-bend-surface`) rather than the global `--cem-bend`
when working inside components.

---

## 7. Directional and asymmetric patterns

### 7.1 Attachment pattern (one pattern, not many tokens)

When a surface is **attached** (sheet, drawer), do not round the attached edge.

```css
:root {
  --cem-bend-attached-edge: var(--cem-bend-sharp);
  --cem-bend-free-edge:     var(--cem-bend-modal);
}

/* Example: bottom sheet */
.cem-bottom-sheet {
  border-radius:
    var(--cem-bend-free-edge)
    var(--cem-bend-free-edge)
    var(--cem-bend-attached-edge)
    var(--cem-bend-attached-edge);
}
```

### 7.2 When to use asymmetric corners

Use asymmetric bend only when it communicates **composition**:

- **Attached elements:** popovers, sheets, or dropdowns visually "connected" to a trigger or viewport edge
- **Grouped controls:** segmented buttons / grouped toggles where only the outer corners are rounded
- **Sectioned containers:** card headers/footers that inherit top/bottom corners from the parent surface

Do **not** use asymmetric corners as the sole carrier of meaning or state (see §8 Accessibility section).

### 7.3 Implementation guidance

- Prefer **logical corner properties** so behavior is correct in RTL and other writing modes:
  `border-start-start-radius`, `border-start-end-radius`, `border-end-start-radius`, `border-end-end-radius`.
- Reuse existing semantic/basis tokens (`--cem-bend-control`, `--cem-bend-overlay`, `--cem-bend-attached-edge`,
  `--cem-bend-free-edge`) rather than minting new global "top/start/end" tokens.

### 7.4 Common recipes

**1) Popover attached to a trigger (attached on top, free on bottom)**

```css
.cem-popover--attached-top {
  border-start-start-radius: var(--cem-bend-attached-edge);
  border-start-end-radius:   var(--cem-bend-attached-edge);
  border-end-start-radius:   var(--cem-bend-overlay);
  border-end-end-radius:     var(--cem-bend-overlay);
}
```

**2) Segmented / grouped controls (outer corners only)**

```css
.cem-segment {
  border-radius: 0; /* inner corners remain sharp */
}

.cem-segment:first-child {
  border-start-start-radius: var(--cem-bend-control);
  border-end-start-radius:   var(--cem-bend-control);
}

.cem-segment:last-child {
  border-start-end-radius: var(--cem-bend-control);
  border-end-end-radius:   var(--cem-bend-control);
}
```

**3) Card header inherits top corners, body stays rectangular**

```css
.cem-card {
  border-radius: var(--cem-bend-surface);
  overflow: clip; /* ensure header background respects corners */
}

.cem-card__header {
  border-start-start-radius: var(--cem-bend-surface);
  border-start-end-radius:   var(--cem-bend-surface);
  border-end-start-radius:   0;
  border-end-end-radius:     0;
}
```

**Optional local shorthand (avoid globals):** If you need `border-radius` shorthand, keep it component-scoped and do not
encode LTR assumptions into global `--cem-bend-start/end` variables.

---

## 8. Accessibility and inclusive design requirements

Bend is a *secondary* visual cue. It must never be the only carrier of state, meaning, or instructions.

### 8.1 Shape must not be the only signal

Do not encode meaning using bend alone (e.g., "rounded = primary" / "square = secondary") unless there is a redundant cue
(color, text, icon, pattern, or stroke).

### 8.2 High-contrast and forced-colors resilience

High-contrast modes can override fills/shadows and reduce the perceptibility of subtle shape differences. Treat bend deltas
smaller than "sharp vs smooth" as **non-essential**. For critical distinctions:

- rely on **D5 stroke/outline** ([`cem-stroke.md`](./cem-stroke.md)) and **D0 color semantics**
- provide non-color redundancy (icon/text) for state/meaning

### 8.3 Focus indicators must respect the target

Focus rings and outlines must align with the target's bend, and must remain visible at high zoom and in forced-colors.

Practical guidance (cross-dimension):

- **D1:** reserve ring space via offset/inset so the ring does not collide with corners or get clipped (see [`cem-dimension.md`](./cem-dimension.md)).
- **D5:** define focus stroke width and style via `--cem-stroke-focus`; do not rely on bend to indicate focus (see [`cem-stroke.md`](./cem-stroke.md) §5).
- **D2:** ensure focus ring does not reduce effective hit size; hit targets remain compliant (see [`cem-coupling.md`](./cem-coupling.md)).

Recommended robust pattern (shape-aligned ring in normal mode, resilient in forced-colors):

```css
.cem-focusable:focus-visible {
  /* Baseline indicator that survives forced-colors */
  outline: var(--cem-stroke-focus, 2px) solid transparent;
  outline-offset: var(--cem-stroke-indicator-offset, 2px); /* D5 indicator placement */

  /* Primary ring for normal mode (shape-aligned) */
  box-shadow: 0 0 0 var(--cem-stroke-focus, 2px) currentColor;

  border-radius: var(--cem-bend-control);
}
```


### 8.4 Pointer target size and spacing (bend × D2 size × D1 separation)

Round controls can *look* smaller even when they meet minimum targets. Ensure:

- D2 control height/width targets are met (especially icon buttons and small chips) — see [`cem-coupling.md`](./cem-coupling.md)
- D1 spacing provides separation between adjacent targets — see [`cem-dimension.md`](./cem-dimension.md)

### 8.5 Bend vs inset readability (bend × D1 padding)

High bend on compact surfaces increases corner curvature and can visually crowd content. When bend increases, step D1 inset
up rather than pushing content into the curve.

### 8.6 Minimum test checklist

Validate under:

- keyboard navigation with `:focus-visible`
- forced-colors / high-contrast modes
- zoom 200–400% and text scaling (no clipping; adequate spacing)
- dense vs normal modes (D2 height changes keep round-ends correct)
- small-target components (icon buttons, chips) for hit area and separation

---

## 9. Consumer vocabulary for "round ends" (capsules)

Recommended consumer-perspective terms (descending literalness):

- **round-ends**
- **capsule**
- **pill**
- **bubble button** (marketing-leaning)
- **stadium** (designer-leaning)

**Canonical endpoint name in this spec:** `--cem-bend-control-round-ends`

If you want an alias, make it a pointer:

```css
--cem-bend-control-capsule: var(--cem-bend-control-round-ends);
```

---

## 10. Component mapping

This section provides a practical "where to bind bend" reference. It is intentionally **role-first** and maps components to
existing CEM endpoints. If a component needs an internal override, implement it as a **local alias** (component scope),
not as new global tokens.

### 10.1 Action binding (existing)

The existing implementation binds actions to the bend system:

```css
.action, button {
  --cem-action-border-radius: var(--cem-bend);
  border-radius: var(--cem-action-border-radius);
}
```

### 10.2 Extended component mapping

The mapping below is consistent with common practices across modern systems:

- Material 3 applies the corner radius scale broadly to rectangular components (e.g., cards, dialogs, menus) and uses larger
  radii for prominent overlays (dialogs are specified with 28dp container corners).
- Fluent groups shape usage into rectangular elements, flyout elements (popovers), and pill/round elements (personas), and
  recommends "none" for structural bars.
- Radix Themes treats radius as a theme-level property inherited by panels like Card/Dialog/Popover.
- Polaris documents concrete radii for cards (e.g., default 8px).
- Carbon specifies radii for certain control families (e.g., content switcher corners).

**Table: map components to CEM endpoints**

| Component family                     | Recommended token / basis                                                            | Rationale (consumer + system)                                                                                |
|--------------------------------------|--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| **Buttons**                          | `--cem-bend-control`                                                                 | Standard interactive affordance (default feel)                                                               |
| **Icon buttons (circular variants)** | Local alias → `border-radius: var(--cem-bend-circle)`                                | Icon buttons often present as circles; use basis circle via local alias (do not mint a global "icon radius") |
| **FAB**                              | Circle variant → `--cem-bend-circle`; Extended FAB → `--cem-bend-control-round-ends` | Prominent control; circular (classic FAB) or capsule (extended FAB)                                          |
| **Chips / Tags**                     | `--cem-bend-control-round-ends`                                                      | "Capsule" shape signals lightweight, removable, filter-like affordance                                       |
| **Badges / Counters**                | `--cem-bend-smooth` (or `--cem-bend-control`)                                        | Small rounding prevents harsh micro-shapes; keep subtle                                                      |
| **Text fields / Select**             | `--cem-bend-field`                                                                   | Field geometry should match the product's primary control feel                                               |
| **Switches / Toggles**               | Track: `--cem-bend-round`; Thumb: `--cem-bend-circle`                                | Track is a pill; thumb is a circle (distinct affordance)                                                     |
| **Cards / Panels**                   | `--cem-bend-surface`                                                                 | Container grouping and boundaries                                                                            |
| **Tables / Dense list rows**         | `--cem-bend-sharp` (or none)                                                         | Grid-aligned surfaces should remain formal/structural; avoid decorative rounding                             |
| **Dialogs / Sheets**                 | `--cem-bend-modal` (+ attachment pattern for sheets)                                 | High salience overlays; larger bend supports "layered" reading and separation                                |
| **Menus / Dropdowns / Popovers**     | `--cem-bend-overlay`                                                                 | Transient overlays; match default bend feel                                                                  |
| **Tooltips**                         | `--cem-bend-overlay`                                                                 | Small transient overlay; keep consistent with menus                                                          |
| **Snackbars / Toasts**               | `--cem-bend-overlay` (policy may choose sharper)                                     | Notification surfaces should not demand attention via shape alone                                            |
| **Navigation rail / App bar**        | `--cem-bend-sharp`                                                                   | Structural navigation regions read more stable with sharp edges                                              |
| **Tabs**                             | Underline tabs: `--cem-bend-sharp`; Pill tabs: `--cem-bend-control-round-ends`       | Keep minimal unless the design intentionally uses pill tabs                                                  |
| **Avatars / Personas**               | `--cem-bend-avatar` (`50%`)                                                          | Circular identity affordance                                                                                 |
| **Media thumbnails**                 | `--cem-bend-media`                                                                   | Gentle rounding to match overall feel without obscuring content edges                                        |

### 10.3 Local alias pattern (preferred for variants)

```css
.cem-icon-button {
  /* local alias: do not mint a global "icon radius" */
  border-radius: var(--cem-bend-circle);
}

.cem-chip {
  border-radius: var(--cem-bend-control-round-ends);
}
```

---

## 11. Notes on external systems (adapter-only)

Many systems use a **bounded corner scale** and recommend applying it by role:

- Material 3: "corner radius scale" across rectangular components; larger corners on prominent overlays.
- Fluent 2: "None…Circle" tokens and guidance by component area (structural bars vs flyouts vs personas).
- Radix Themes: theme-level radius inherited by panel-like components.
- Polaris and Carbon: documented radii for common container/control families.

CEM consumes these patterns at the adapter layer but keeps product code consumer-semantic.

---

## 12. Quick adoption checklist

Use this checklist to adopt the bend system with minimal churn and predictable outcomes.

1. **Confirm prerequisites (D1 + D2 are present)**
   - D1 provides the physical scale used by bend (`--cem-dim-xx-small`, `--cem-dim-x-small`, `--cem-dim-small`, etc.) — see [`cem-dimension.md`](./cem-dimension.md).
   - D2 provides height for geometry-driven bend (`--cem-control-height`), so round-ends remain correct across density/size modes — see [`cem-coupling.md`](./cem-coupling.md).

2. **Adopt the bend basis (`--cem-bend-*`)**
   - Keep the basis small: `sharp`, `smooth`, `round` (endcaps), `circle`, and the active `--cem-bend`.
   - Decide product policy for "capsule controls" (where `--cem-bend-round` is used): occasional variant vs product-wide style.

3. **Map semantic endpoints to the basis (role-first)**
   - Set `--cem-bend-control`, `--cem-bend-surface`, `--cem-bend-overlay`, and the minimal specializations already defined in this spec.
   - Avoid mapping components directly to "scale aliases" (`xs/sm/md/...`) in product code. Those are adapter-only.

4. **Bind components to semantic endpoints (no raw values)**
   - Bind `border-radius` to endpoints (e.g., `--cem-bend-control`, `--cem-bend-surface`) or to basis geometry tokens (`--cem-bend-round`, `--cem-bend-circle`) via **local aliases** for variants.
   - For asymmetric corners (groups/attachments), use the patterns in this spec and prefer **logical corner properties** to remain RTL-safe.

5. **If needed, introduce a shape mode knob (`sharp | smooth | round`)**
   - Add `data-cem-shape="..."` only if brand expression requires it.
   - Modes should override **only** `--cem-bend` and/or semantic endpoints (never introduce mode-specific component tokens).

6. **Validate in accessibility and "hard mode" rendering**
   - **Focus ring follows target shape** and is not clipped (avoid `overflow: hidden` trapping focus; validate `outline-offset` / ring space).
   - **Forced-colors / high-contrast**: affordances remain clear when shadows/fills are overridden; outline-based focus remains visible.
   - **Grouped controls**: only outer corners rounded; inner corners sharp; RTL behavior correct.
   - **Overlays** (tooltips/menus/popovers) are consistent with `--cem-bend-overlay`; **modals** use `--cem-bend-modal` (M3 dialogs are typically 28dp).
   - **Chips and badges** maintain pill/circular intent across density modes (round ends use ½-height rule).
   - **Target size & spacing** remain compliant when shapes look visually smaller (particularly icon buttons and chips). Coordinate with D2 sizing and D1 separation.
   - **Focus not obscured** by sticky headers/overlays during keyboard navigation.

7. **Lock in governance**
   - Add a code convention (or lint rule) that forbids raw `border-radius` values in components except inside adapter layers.
   - Document which endpoints are allowed for each component family (use the Component mapping table as the baseline).

---

## 13. Governance and versioning

This spec is intended to be adopted as a **stable contract** between design, engineering, and component libraries. Treat
changes using **semantic versioning** (MAJOR.MINOR.PATCH) with explicit deprecation when feasible.

### 13.1 What counts as breaking (MAJOR)

Treat as major (breaking) if you:

- Rename or remove any **canonical** bend basis token (`--cem-bend-*`) or any **canonical semantic endpoint**.
- Change the **semantic meaning** of an endpoint (e.g., what "overlay" covers; whether "round" means endcaps vs fixed value).
- Change the **geometry definition** of round-ends (`½ height`) or circle (`50%`) in a way that alters component behavior.
- Change mode names, add/remove supported modes, or change the meaning of an existing mode selector
  (e.g., `data-cem-shape="sharp|smooth|round"`).

**Business rationale:** these changes can silently alter UI boundaries, focus geometry, and density-mode behavior across many
components at once.

### 13.2 What is non-breaking (MINOR / PATCH)

Treat as minor/patch if you:

- Adjust underlying numeric values (via D1 tokens) while preserving semantics and perceptual intent.
- Add new semantic endpoints that are **optional**, clearly scoped, and do not change existing endpoint meaning.
- Add mapping guidance, adapter notes, examples, or clarify documentation.
- Expand component mapping tables without changing existing bindings.

### 13.3 Deprecation policy (recommended)

- When replacing an endpoint, keep the old name as an **alias** for at least one minor release cycle.
- Provide a migration note: "old → new," and a rationale tied to consumer semantics and accessibility.

### 13.4 Canonical token summary (contract surface)

The table below distinguishes **required CEM contract tokens** from **optional adapter aliases**.

| Token                           | Category                    |   Required     | Notes                                                 |
|---------------------------------|-----------------------------|:--------------:|-------------------------------------------------------|
| `--cem-bend-sharp`              | Bend basis                  |      Yes       | No bend (sharp corners)                               |
| `--cem-bend-smooth`             | Bend basis                  |      Yes       | Small bend; binds to D1 `--cem-dim-x-small`           |
| `--cem-bend-round`              | Bend basis (geometry)       |      Yes       | Round-ends (capsule): `½ height`                      |
| `--cem-bend-circle`             | Bend basis (geometry)       |      Yes       | Circle: `50%`                                         |
| `--cem-bend`                    | Active alias                |      Yes       | Mode-switchable default bend                          |
| `--cem-bend-control`            | Semantic endpoint           |      Yes       | Primary control bend                                  |
| `--cem-bend-surface`            | Semantic endpoint           |      Yes       | Primary container/surface bend                        |
| `--cem-bend-overlay`            | Semantic endpoint           |      Yes       | Small overlays (menus/tooltips/popovers)              |
| `--cem-bend-field`              | Semantic endpoint           |  Recommended   | Usually equals control bend                           |
| `--cem-bend-modal`              | Semantic endpoint           |  Recommended   | Prominent overlays (dialogs/sheets)                   |
| `--cem-bend-control-round-ends` | Semantic endpoint (variant) |    Optional    | Use only if capsules are a consistent product pattern |
| `--cem-bend-media`              | Semantic endpoint           |  Recommended   | Media thumbnails/previews                             |
| `--cem-bend-avatar`             | Semantic endpoint           |  Recommended   | Avatar/persona geometry (circle)                      |
| `--cem-bend-attached-edge`      | Pattern token               |  Recommended   | For asymmetric attachment patterns                    |
| `--cem-bend-free-edge`          | Pattern token               |  Recommended   | For asymmetric attachment patterns                    |
| `--cem-action-border-radius`    | Component binding           | Yes (existing) | Existing action binding contract                      |

**Adapter-only (optional) aliases**

The following "M3-parity" aliases may be exposed for compatibility, but must not be required by product component code:

- `--cem-bend-none`, `--cem-bend-xs`, `--cem-bend-sm`, `--cem-bend-md`, `--cem-bend-lg`, `--cem-bend-xl`, `--cem-bend-full`

If these aliases exist, treat them as adapter surface: renames/removals are breaking for adapter consumers, but should not
affect product components if semantic endpoints are followed.

---

## Appendix A — Material 3 shape scale reference (adapter mapping)

This appendix is **non-normative**: it exists to help adapters map Material 3 shape scales into the CEM bend basis and
semantic endpoints.

Material Design 3 defines a corner-radius scale with canonical steps (0/4/8/12/16/28 + "full"), and also introduces
additional "increased" steps for larger containers in newer guidance.

### A.1 Canonical M3 `--md-sys-shape-corner-*` steps → CEM

| M3 token                            | Typical value  | CEM mapping (adapter-only)                                       | Prefer applying via CEM endpoints                    | Perceived quality        |
|-------------------------------------|----------------|------------------------------------------------------------------|------------------------------------------------------|--------------------------|
| `--md-sys-shape-corner-none`        | 0              | `--cem-bend-sharp`                                               | attached edges, structural bars (`--cem-bend-sharp`) | Sharp, formal, technical |
| `--md-sys-shape-corner-extra-small` | 4dp            | `var(--cem-dim-xx-small)`                                        | rare micro-bend (badges, subtle containers)          | Barely rounded, subtle   |
| `--md-sys-shape-corner-small`       | 8dp            | `--cem-bend-smooth`                                              | `--cem-bend-control`, `--cem-bend-overlay`           | Slightly soft            |
| `--md-sys-shape-corner-medium`      | 12dp           | `var(--cem-dim-small)`                                           | `--cem-bend-surface`                                 | Balanced friendliness    |
| `--md-sys-shape-corner-large`       | 16dp           | `var(--cem-dim-medium)`                                          | `--cem-bend-surface-strong` (if you expose it)       | Noticeably rounded       |
| `--md-sys-shape-corner-extra-large` | 28dp           | `--cem-bend-modal`                                               | `--cem-bend-modal`                                   | Very soft, approachable  |
| `--md-sys-shape-corner-full`        | pill / 50%     | `--cem-bend-round` (capsule) and/or `--cem-bend-circle` (circle) | chips, capsule controls, avatars                     | Playful, highly rounded  |

### A.2 Optional M3-parity aliases (adapter-only)

If you want to expose M3-like short aliases for compatibility, define them as **aliases** to CEM basis and D1 tokens.
These are **not** intended for product component code.

```css
:root {
  --cem-bend-none: var(--cem-bend-sharp);
  --cem-bend-xs:   var(--cem-dim-xx-small); /* ~4dp */
  --cem-bend-sm:   var(--cem-dim-x-small);  /* ~8dp */
  --cem-bend-md:   var(--cem-dim-small);    /* ~12dp */
  --cem-bend-lg:   var(--cem-dim-medium);   /* ~16dp */
  --cem-bend-xl:   var(--cem-bend-modal);   /* ~28dp */

  /* "full" depends on geometry: capsule vs circle */
  --cem-bend-full: var(--cem-bend-round);
}
```

### A.3 Notes on validation vs "current" libraries

- Material Web uses `--md-sys-shape-corner-*` tokens in theming and leaves exact numeric assignments to the system theme.
- Angular Material may publish/ship a scale whose *numeric* values differ from the M3 "typical" table; treat Angular's
  scale as its **own source scale** and map to CEM by intent, not by exact dp numbers.
- CEM's contract is semantic endpoints. Adapters own external token mapping.

---

## References

**Primary sources**
- [Material Design 3: Shape (shape scale tokens)](https://m3.material.io/styles/shape/shape-scale-tokens)
- [Material Design 3: Corner radius scale](https://m3.material.io/styles/shape/corner-radius-scale)
- [Material Web: Theming](https://material-web.dev/theming/material-theming/)
- [Angular Material: Design Tokens](https://deepwiki.com/angular/components/5.2-material-design-tokens)
- [Google Developers: Building the Shape System](https://developers.googleblog.com/building-the-shape-system-for-material-design/)

**Additional ecosystem references (non-normative)**
- [Fluent 2: Shapes](https://fluent2.microsoft.design/shapes)
- [Radix Themes: Radius](https://www.radix-ui.com/themes/docs/theme/radius)
- [Shopify Polaris: Card](https://polaris-react.shopify.com/components/layout-and-structure/card)
- [Carbon: Content switcher style](https://carbondesignsystem.com/components/content-switcher/style/)

**Local CEM documentation**
- [D1. Space & Rhythm](./cem-dimension.md) — dimension scale tokens
- [D2. Coupling & Compactness](./cem-coupling.md) — control height and operability
- [D6. Typography](./cem-voice-fonts-typography.md) — voice and typography tokens
- [D7. Time & Motion](./cem-timing.md) — timing and easing tokens