@epa-wg/custom-element-dist 0.0.32 → 0.0.34

package/src/material/theme/tokens/cem-stroke-density-illustration-4to1-v3.svg

@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="3200" height="800" viewBox="0 0 3200 800">
+
+  <defs>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
+      <feOffset dx="0" dy="10" result="off"/>
+      <feGaussianBlur in="off" stdDeviation="10" result="blur"/>
+      <feColorMatrix in="blur" type="matrix"
+        values="0 0 0 0 0
+                0 0 0 0 0
+                0 0 0 0 0
+                0 0 0 0.22 0" result="shadow"/>
+      <feBlend in="shadow" in2="SourceGraphic" mode="normal"/>
+    </filter>
+    <style>
+      .title { font: 700 54px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: black; }
+      .banner { font: 400 30px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: #13539b; }
+      .label { font: 700 30px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: #141416; }
+      .sub { font: 400 24px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: #4b4b52; }
+      .ui { font: 400 30px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: #141416; }
+      .ui-bold { font: 700 30px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: #141416; }
+      .small { font: 400 24px system-ui, -apple-system, Segoe UI, Arial, sans-serif; fill: #4b4b52; }
+    </style>
+  </defs>
+
+<rect x="0" y="0" width="3200" height="800" fill="#ffffff"/>
+<rect x="60" y="28" width="3080" height="78" rx="24" fill="#e8f1fc"/>
+<text x="95" y="80" class="banner">Dense UI may need stronger strokes; Comfort UI can rely on whitespace for separation.</text>
+<text x="1600.0" y="164" text-anchor="middle" class="title">Stroke thickness varies by density mode (semantics unchanged)</text>
+<g filter="url(#shadow)"><rect x="90" y="216" width="1475" height="494" rx="32" fill="#ffffff"/></g>
+<g filter="url(#shadow)"><rect x="1635" y="216" width="1475" height="494" rx="32" fill="#ffffff"/></g>
+<text x="130" y="278" class="label">DENSE</text>
+<text x="160" y="316" class="sub">Ink carries more of the separation load</text>
+<text x="1675" y="278" class="label">COMFORT</text>
+<text x="1698" y="316" class="sub">Space carries more of the separation load</text>
+<rect x="130" y="336" width="1395" height="360" rx="28" fill="#f5f6f8" stroke="#37373c" stroke-width="5"/>
+<rect x="135" y="341" width="1385" height="86" rx="22" fill="#ffffff"/>
+<circle cx="173" cy="384.0" r="16" fill="#d2d4da" stroke="#5f5f66" stroke-width="1"/>
+<text x="203" y="385" class="ui-bold">Settings</text>
+<rect x="1388" y="366.0" width="110" height="36" rx="18" fill="#ebecf0" stroke="#8c8e94" stroke-width="1"/>
+<circle cx="1480.0" cy="384.0" r="18.0" fill="#ffffff" stroke="#8c8e94" stroke-width="1"/>
+<rect x="135" y="443" width="1385" height="78" fill="#ffffff"/>
+<rect x="157" y="464.0" width="36" height="36" rx="6" fill="#ffffff" stroke="#787a80" stroke-width="2"/>
+<text x="211" y="481" class="ui-bold">Option 1</text>
+<text x="211" y="515" class="small">Supporting detail</text>
+<line x1="1470" y1="474.0" x2="1478" y2="482.0" stroke="#787a80" stroke-width="3" stroke-linecap="round"/>
+<line x1="1470" y1="490.0" x2="1478" y2="482.0" stroke="#787a80" stroke-width="3" stroke-linecap="round"/>
+<line x1="135" y1="521" x2="1520" y2="521" stroke="#46484e" stroke-width="4" stroke-linecap="round"/>
+<rect x="135" y="521" width="1385" height="78" fill="#fafbfd"/>
+<rect x="157" y="542.0" width="36" height="36" rx="6" fill="#ffffff" stroke="#787a80" stroke-width="2"/>
+<line x1="165" y1="560.0" x2="173" y2="570.0" stroke="#46484e" stroke-width="3" stroke-linecap="round"/>
+<line x1="173" y1="570.0" x2="187" y2="550.0" stroke="#46484e" stroke-width="3" stroke-linecap="round"/>
+<text x="211" y="559" class="ui">Option 2</text>
+<text x="211" y="593" class="small">Supporting detail</text>
+<line x1="1470" y1="552.0" x2="1478" y2="560.0" stroke="#787a80" stroke-width="3" stroke-linecap="round"/>
+<line x1="1470" y1="568.0" x2="1478" y2="560.0" stroke="#787a80" stroke-width="3" stroke-linecap="round"/>
+<line x1="135" y1="599" x2="1520" y2="599" stroke="#46484e" stroke-width="4" stroke-linecap="round"/>
+<rect x="135" y="599" width="1385" height="78" fill="#ffffff"/>
+<rect x="157" y="620.0" width="36" height="36" rx="6" fill="#ffffff" stroke="#787a80" stroke-width="2"/>
+<text x="211" y="637" class="ui">Option 3</text>
+<text x="211" y="671" class="small">Supporting detail</text>
+<line x1="1470" y1="630.0" x2="1478" y2="638.0" stroke="#787a80" stroke-width="3" stroke-linecap="round"/>
+<line x1="1470" y1="646.0" x2="1478" y2="638.0" stroke="#787a80" stroke-width="3" stroke-linecap="round"/>
+<line x1="135" y1="677" x2="1520" y2="677" stroke="#46484e" stroke-width="2" stroke-linecap="round"/>
+
+<line x1="152" y1="596" x2="392" y2="596" stroke="#28282d" stroke-width="4" stroke-linecap="round"/>
+<text x="412" y="596" class="small" style="fill:#141416;">4px separator</text>
+<rect x="1675" y="336" width="1395" height="360" rx="28" fill="#f5f6f8" stroke="#37373c" stroke-width="2"/>
+<rect x="1677" y="338" width="1391" height="104" rx="22" fill="#ffffff"/>
+<circle cx="1725" cy="390.0" r="18" fill="#d2d4da" stroke="#5f5f66" stroke-width="1"/>
+<text x="1757" y="392" class="ui-bold">Settings</text>
+<rect x="2928" y="372.0" width="110" height="36" rx="18" fill="#ebecf0" stroke="#8c8e94" stroke-width="1"/>
+<circle cx="3020.0" cy="390.0" r="18.0" fill="#ffffff" stroke="#8c8e94" stroke-width="1"/>
+<rect x="1677" y="464" width="1391" height="105" fill="#ffffff"/>
+<rect x="1707" y="496.5" width="40" height="40" rx="6" fill="#ffffff" stroke="#787a80" stroke-width="1"/>
+<text x="1765" y="512" class="ui-bold">Option 1</text>
+<text x="1765" y="546" class="small">Supporting detail</text>
+<line x1="3010" y1="508.5" x2="3018" y2="516.5" stroke="#787a80" stroke-width="2" stroke-linecap="round"/>
+<line x1="3010" y1="524.5" x2="3018" y2="516.5" stroke="#787a80" stroke-width="2" stroke-linecap="round"/>
+<line x1="1677" y1="569" x2="3068" y2="569" stroke="#96989e" stroke-width="1" stroke-linecap="round"/>
+<rect x="1677" y="569" width="1391" height="105" fill="#fafbfd"/>
+<rect x="1707" y="601.5" width="40" height="40" rx="6" fill="#ffffff" stroke="#787a80" stroke-width="1"/>
+<line x1="1715" y1="621.5" x2="1725" y2="633.5" stroke="#46484e" stroke-width="2" stroke-linecap="round"/>
+<line x1="1725" y1="633.5" x2="1741" y2="609.5" stroke="#46484e" stroke-width="2" stroke-linecap="round"/>
+<text x="1765" y="617" class="ui">Option 2</text>
+<text x="1765" y="651" class="small">Supporting detail</text>
+<line x1="3010" y1="613.5" x2="3018" y2="621.5" stroke="#787a80" stroke-width="2" stroke-linecap="round"/>
+<line x1="3010" y1="629.5" x2="3018" y2="621.5" stroke="#787a80" stroke-width="2" stroke-linecap="round"/>
+<line x1="1677" y1="674" x2="3068" y2="674" stroke="#96989e" stroke-width="1" stroke-linecap="round"/>
+<rect x="1707" y="811.5" width="40" height="40" rx="6" fill="#ffffff" stroke="#787a80" stroke-width="1"/>
+<line x1="1705" y1="570" x2="1945" y2="570" stroke="#28282d" stroke-width="1" stroke-linecap="round"/>
+<text x="1965" y="572" class="small" style="fill:#141416;">1px separator</text>
+<text  x="760.0" y="240" class="small" >Density mode</text>
+<line x1="680.0" y1="278" x2="920.0" y2="278" stroke="#a0a2a8" stroke-width="6" stroke-linecap="round"/>
+<line x1="680.0" y1="266" x2="680.0" y2="290" stroke="#a0a2a8" stroke-width="4" stroke-linecap="round"/>
+<line x1="800.0" y1="266" x2="800.0" y2="290" stroke="#a0a2a8" stroke-width="4" stroke-linecap="round"/>
+<line x1="920.0" y1="266" x2="920.0" y2="290" stroke="#a0a2a8" stroke-width="4" stroke-linecap="round"/>
+<circle cx="730.0" cy="278" r="20" fill="#ffffff" stroke="#46484e" stroke-width="4"/>
+<text x="674.0" y="328" class="small">Dense</text>
+<text x="834.0" y="328" class="small">Comfort</text>
+<text x="1600.0" y="770" text-anchor="middle" class="small">Non-breaking adjustment: tune stroke thickness per density mode; preserve semantic meaning of boundaries.</text>
+</svg>

package/src/material/theme/tokens/cem-stroke.md

@@ -0,0 +1,480 @@
+# CEM D5 Stroke & Separation — Boundaries, Dividers, and Focus Indicators
+
+**Status:** Proposed (canonical CEM spec)  
+**Last updated:** December 19, 2025
+
+**Taxonomy placement:** D5. Stroke & Separation (part of the 7-dimensional CEM token framework)
+
+**Companion specs:**
+- **D0. Color (Emotional Palette & System Color Mapping)** ([`cem-colors.md`](./cem-colors.md)) — defines separator/focus colors; D5 defines *thickness and geometry*
+- **D1. Space & Rhythm** ([`cem-dimension.md`](./cem-dimension.md)) — inset/spacing rules that keep strokes readable without crowding
+- **D2. Coupling & Compactness** ([`cem-coupling.md`](./cem-coupling.md)) — density modes that affect when thin strokes must become stronger
+- **D3. Shape — Bend** ([`cem-shape.md`](./cem-shape.md)) — corner radii and rounding rules that strokes must follow
+- **D4. Layering** ([`cem-layering.md`](./cem-layering.md)) — when to prefer shadow separation vs stroke separation
+- **D7. Time & Motion** ([`cem-timing.md`](./cem-timing.md)) — animation timing for focus/selection transitions
+
+---
+
+## Contents
+
+1. [What D5 controls](#1-what-d5-controls)
+2. [Design goals](#2-design-goals)
+3. [Minimal stroke basis](#3-minimal-stroke-basis)
+4. [Semantic endpoints (product-facing contract)](#4-semantic-endpoints-product-facing-contract)
+5. [Focus, selected, and target indicators](#5-focus-selected-and-target-indicators)
+6. [Dividers and separators](#6-dividers-and-separators)
+7. [Inter-dimension coupling](#7-inter-dimension-coupling)
+8. [Accessibility and forced-colors requirements](#8-accessibility-and-forced-colors-requirements)
+9. [Implementation guidance (CSS recipes)](#9-implementation-guidance-css-recipes)
+10. [Framework mapping guidance (Angular Material, MUI)](#10-framework-mapping-guidance-angular-material-mui)
+11. [Canonical token summary](#11-canonical-token-summary)
+12. [Governance and versioning](#12-governance-and-versioning)
+13. [References](#13-references)
+
+---
+
+## 1. What D5 controls
+
+D5 defines the **geometry of separation**:
+
+- **Stroke thickness**: borders, hairlines, dividers, gridlines, outlines.
+- **Indicator geometry**: focus rings, selection rings, target indicators (including patterned outlines such as zebra).
+- **Stroke placement**: whether an indicator is *inside* the component, *on the edge*, or *outside* the component.
+
+D5 **does not** define:
+- **Colors** (D0 defines `Canvas`, `CanvasText`, `SelectedItem`, emotional palettes, etc.).
+- **Spacing and inset** (D1).
+- **Component height or density rules** (D2).
+- **Corner rounding** (D3).
+- **Motion curves and timing** (D7).
+
+---
+
+## 2. Design goals
+
+### 2.1 Consumer semantics first
+
+Tokens must express *what the stroke means to the consumer*, not how it is implemented:
+
+- “boundary” vs “divider” vs “focus indicator” vs “selection indicator”
+- not “mdc notched-outline width” or “outlined input border width”
+
+### 2.2 Bounded complexity
+
+Stroke systems can explode into per-component and per-state width tokens. CEM avoids that by defining:
+
+- a **small width basis** (few values)
+- a **small set of semantic endpoints**
+- and **mapping guidance** for frameworks that expose many internal variables.
+
+### 2.3 No layout shift on interaction
+
+Changing border width on focus is a common source of **layout shift** (e.g., label jumps in outlined text fields). Focus and selection indicators should be drawn using **outline** or **box-shadow**, or on a pseudo-element, rather than changing border-box geometry.
+
+### 2.4 Accessibility as a hard constraint
+
+D5 must support modern focus-indicator requirements (including minimum visible area/thickness and sufficient contrast in high-contrast themes). See §8.
+
+---
+
+## 3. Minimal stroke basis
+
+CEM D5 uses a **4-step stroke basis** that covers almost all UI needs without a large token surface.
+
+### 3.1 Stroke basis tokens
+
+> These tokens are *foundational*. Semantic endpoints map to them.
+
+```css
+:root {
+  /* Basis: keep small and stable */
+  --cem-stroke-none:     0px;  /* no stroke */
+  --cem-stroke-hair:     1px;  /* hairline separators, subtle boundaries */
+  --cem-stroke-standard: 2px;  /* focus/selection indicators; high legibility */
+  --cem-stroke-strong:   3px;  /* high-emphasis boundaries; contrast themes */
+}
+```
+
+**Notes**
+- `1px` remains device-independent (CSS px), and is appropriate for dividers and subtle component boundaries.
+- `2px` is the default for **focus visibility** and state distinction.
+- `3px` exists primarily for **high contrast** and “hard separation” contexts.
+
+- Material Design component specs frequently use 1–2dp stroke thickness for outlines and focus indicators; in web CEM this maps cleanly onto `1px` hairlines and `2px` indicators (see References for representative component spec links and issue discussions).
+
+
+### 3.2 Density coupling (D2 interaction)
+
+Stroke thickness is allowed to vary *by density mode* as a **non-breaking** adjustment, as long as semantics stay intact:
+
+- Dense UI may need **stronger strokes** because small targets and reduced whitespace reduce separability.
+- Comfort UI can remain at hairline boundaries in more places because whitespace carries part of the separation work.
+![cem-stroke-density-illustration-4to1-v3.svg](./cem-stroke-density-illustration-4to1-v3.svg)
+---
+
+## 4. Semantic endpoints (product-facing contract)
+
+These are the **canonical semantic endpoints** that components consume.
+
+### 4.1 Endpoints
+
+```css
+:root {
+  /* Canonical boundaries */
+  --cem-stroke-boundary:          var(--cem-stroke-hair);
+
+  /* Canonical separators */
+  --cem-stroke-divider:           var(--cem-stroke-hair);
+
+  /* Canonical indicators */
+  --cem-stroke-focus:             var(--cem-stroke-standard);
+  --cem-stroke-selected:          var(--cem-stroke-standard);
+  --cem-stroke-target:            var(--cem-stroke-standard);
+
+  /* Placement */
+  --cem-stroke-indicator-offset:  2px; /* distance outside the edge, not thickness */
+
+  /* Optional convenience endpoints (aliases, not required by contract) */
+  --cem-stroke-grid:              var(--cem-stroke-divider);        /* tables / data grids */
+  --cem-stroke-boundary-strong:   var(--cem-stroke-standard);       /* dialogs / sheets when needed */
+}
+```
+
+### 4.2 Semantics (normative)
+
+- `--cem-stroke-boundary` is the default edge for **control containers** (text fields, chips, cards, tiles).
+- `--cem-stroke-divider` separates **siblings** (list rows, table rows, sections).
+- `--cem-stroke-focus` is for **keyboard focus** (and must meet §8).
+- `--cem-stroke-selected` marks **selection** where background does not carry the whole burden of state (CEM preference).
+- `--cem-stroke-target` marks a **deep-linked / navigated-to** target (e.g., URL fragment target, “jump to result”).
+- `--cem-stroke-indicator-offset` prevents rings/indicators from visually merging with the component edge.
+
+Optional convenience endpoints (aliases):
+
+- `--cem-stroke-grid` is a readability alias for “divider inside structured content” (tables / data grids).
+- `--cem-stroke-boundary-strong` is a stronger boundary used only when elevation/shadow is unavailable or insufficient.
+
+---
+
+### 4.3 Component mapping matrix (informative)
+
+The D5 contract intentionally avoids per-component thickness tokens (e.g., `--cem-input-outline`). Instead:
+
+- Components bind to one of the **semantic endpoints** (boundary/divider/focus/selected/target).
+- Component libraries may expose **adapter variables** with component-friendly names, but those adapter names are *not* part of the canonical CEM contract.
+
+> Rule of thumb: **color is D0**, **thickness is D5**, **corner curvature is D3**, **spacing/insets is D1**, **density-mode overrides are D2**.
+
+| Component family                         | Primary D5 endpoint(s)                                 | Typical stroke usage           | Notes                                                                                                                      |
+|------------------------------------------|--------------------------------------------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| Dividers (horizontal/vertical)           | `--cem-stroke-divider`                                 | 1px hairline between siblings  | Prefer inset patterns for lists; increase strength in dense or low-contrast contexts.                                      |
+| List item separators                     | `--cem-stroke-divider` (or `--cem-stroke-grid`)        | Row separators                 | Treat dense “data-list” layouts as a grid for readability.                                                                 |
+| Table borders / grid lines               | `--cem-stroke-grid`                                    | Cell/row separators            | Use `grid` to distinguish “structured separators” from generic dividers; same thickness by default.                        |
+| Text field outline (outlined pattern)    | `--cem-stroke-boundary`                                | Control container edge         | Focus indication should be a ring (`--cem-stroke-focus`) rather than mutating border width.                                |
+| Text field underline (filled pattern)    | `--cem-stroke-boundary` or `--cem-stroke-divider`      | Baseline boundary              | Underline is a boundary of the control, not a sibling divider; map to divider only when visually used as “row separation”. |
+| Outlined button border                   | `--cem-stroke-boundary`                                | Variant boundary               | Use `boundary-strong` only for “hard separation” themes (e.g., low-elevation UIs).                                         |
+| Card / tile border                       | `--cem-stroke-boundary` (often `--cem-stroke-none`)    | Optional edge                  | Prefer D4 elevation or D0 surface contrast; use boundary only when needed for scannability.                                |
+| Checkbox / radio container border        | `--cem-stroke-boundary`                                | Control boundary               | The checkmark/dot is not a stroke token concern; it is icon geometry (D3) + color (D0).                                    |
+| Switch track outline (if any)            | `--cem-stroke-boundary`                                | Track boundary                 | Track *height* is D2/D1, not D5; D5 only provides line weight if outlined.                                                 |
+| Chip / badge border (bordered variant)   | `--cem-stroke-boundary`                                | Subtle outline                 | In dense chips, consider mapping `boundary` → `standard` via D2 coupling if needed for separation.                         |
+| Tabs / segmented control indicator       | `--cem-stroke-selected`                                | Active underline/bar thickness | Avoid using `divider` for active indicators; indicators communicate state, not separation.                                 |
+| Focus ring (all controls)                | `--cem-stroke-focus` + `--cem-stroke-indicator-offset` | External ring/outline          | Must satisfy WCAG 2.2 focus appearance (§8.1).                                                                             |
+| Target highlight (deep link / “jump to”) | `--cem-stroke-target`                                  | Temporary outline/ring         | Distinct from focus: target is navigational, focus is interactive.                                                         |
+| Menus / dropdowns / popovers (edge)      | `--cem-stroke-boundary` (often none)                   | Optional border                | Prefer D4 shadow separation; use boundary/boundary-strong in forced-colors or shadow-suppressed contexts.                  |
+| Progress/slider tracks                   | (usually none) / `--cem-stroke-boundary`               | Outline only if required       | Track *thickness* (e.g., 8px) is a **dimension**; treat that as D2/D1, not D5.                                             |
+
+
+## 5. Focus, selected, and target indicators
+
+CEM uses an **outline-driven indicator** model for states that must remain visible across backgrounds:
+- focus (keyboard / focus-visible)
+- selected
+- target (e.g., anchor `:target`)
+
+### 5.1 Zebra outline system (existing in `theme-data.xhtml`)
+
+The current theme implementation uses a **zebra ring** composed of stacked outside strokes using `box-shadow` and zebra color variables:
+
+- `--cem-zebra-strip-size`
+- `--cem-zebra-color-0` … `--cem-zebra-color-3`
+- `--cem-action-box-shadow` (used by `.action` components)
+
+In normal themes, a 3-stripe ring is used; in contrast themes, a 4-stripe ring is used (intent + focus + selected + target).
+
+### 5.2 Canonical zebra tokens (D5 contract)
+
+D5 treats these as canonical *indicator-pattern tokens*:
+
+```css
+:root {
+  --cem-zebra-strip-size: 2px;      /* thickness per stripe */
+  --cem-zebra-angle:      45deg;    /* if stripes are rendered as gradients */
+  --cem-zebra-color-0:    Canvas;       /* intent / base stripe (contrast themes) */
+  --cem-zebra-color-1:    CanvasText;   /* focus stripe */
+  --cem-zebra-color-2:    SelectedItem; /* selected stripe */
+  --cem-zebra-color-3:    SelectedItem; /* target stripe (or themed alternative) */
+}
+```
+
+### 5.3 Recommended indicator composition (box-shadow ring)
+
+```css
+/* 3-stripe ring: focus/selected/target (normal themes) */
+--cem-ring-zebra-3:
+  0 0 0 calc(1 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-1),
+  0 0 0 calc(2 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-2),
+  0 0 0 calc(3 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-3);
+
+/* 4-stripe ring: intent + focus + selected + target (contrast themes) */
+--cem-ring-zebra-4:
+  0 0 0 calc(1 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-0),
+  0 0 0 calc(2 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-1),
+  0 0 0 calc(3 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-2),
+  0 0 0 calc(4 * var(--cem-zebra-strip-size)) var(--cem-zebra-color-3);
+```
+
+**Why `box-shadow`?**
+- Avoids layout shift (unlike border-width changes).
+- Works with rounded corners (D3) and can visually sit outside the component.
+- Can be swapped to `outline` in forced-colors contexts (§8.2).
+
+### 5.4 Focus heuristics
+
+Prefer `:focus-visible` semantics. If the platform needs a polyfilled focus-ring behavior, align with heuristics similar to Material Web’s focus ring utilities (see references).
+
+---
+
+## 6. Dividers and separators
+
+### 6.1 Divider role types
+
+CEM recognizes three common divider roles (same thickness basis, different usage):
+
+1. **Section divider**: separates groups (higher salience)
+2. **Row divider**: list/table row hairlines
+3. **Gridline**: dense tabular separation
+
+All three should normally map to `--cem-stroke-divider` (hairline). Promote to `--cem-stroke-boundary-strong` when:
+- the UI is dense (D2)
+- the background is textured/animated
+- or the consumer must not miss the separation (e.g., critical comparison tables).
+
+### 6.2 Inset patterns (non-token guidance)
+
+Avoid creating many inset tokens. Use a single **inset rule**:
+- “Full-bleed dividers for full-bleed lists”
+- “Inset dividers under leading avatar/icon to preserve grouping”
+
+Spacing and inset should use D1 tokens.
+
+---
+
+## 7. Inter-dimension coupling
+
+### 7.1 D3 shape coupling
+
+Indicator rings should follow component rounding:
+
+```css
+border-radius: var(--cem-bend-control);
+box-shadow: var(--cem-ring-zebra-3);
+```
+
+If the ring is outside, it may require a slightly larger radius:
+
+```css
+border-radius: calc(var(--cem-bend-control) + var(--cem-stroke-indicator-offset));
+```
+
+### 7.2 D1 spacing coupling
+
+Where indicators sit outside the edge, ensure surrounding layout provides enough breathing room. Prefer:
+- container padding (D1)
+- or internal “guard rails” around interactive controls (D2), including `--cem-coupling-guard-min`
+  and `--cem-coupling-halo`
+
+Treat `--cem-coupling-guard-min` as the default clearance budget between adjacent operable zones.
+If you increase any of the following, you must also increase surrounding D1 spacing and/or D2 guard/halo
+(or accept overlap):
+
+- zebra ring outset: `3 * --cem-zebra-strip-size` (normal) / `4 * --cem-zebra-strip-size` (contrast)
+- outline outset: `--cem-stroke-indicator-offset + --cem-stroke-focus`
+
+See the D2 compatibility rule in [`cem-coupling.md`](./cem-coupling.md) §4.1.1.
+
+### 7.3 D4 elevation coupling
+
+Elevation and stroke are substitutes:
+- Use elevation for depth separation in normal themes where shadows are viable.
+- Use stroke (including zebra) in contrast themes, where shadows can be insufficient.
+
+---
+
+## 8. Accessibility and forced-colors requirements
+
+### 8.1 Focus appearance (WCAG 2.2)
+
+The focus indicator must be large/visible enough to be reliably perceived. A robust default is a **2px** perimeter (or equivalent area) around the focused component, which D5’s `--cem-stroke-focus` supports.
+
+### 8.2 Forced colors / high contrast
+
+In `forced-colors: active` contexts:
+- prefer `outline` (system colors) and avoid relying on subtle shadows
+- avoid gradients that may be flattened
+- ensure indicator uses `CanvasText` / `Highlight` as appropriate in D0 mapping
+
+Suggested baseline:
+
+```css
+@media (forced-colors: active) {
+  .cem-focusable:focus-visible {
+    outline: var(--cem-stroke-focus) solid CanvasText;
+    outline-offset: var(--cem-stroke-indicator-offset);
+    box-shadow: none;
+  }
+}
+```
+
+---
+
+## 9. Implementation guidance (CSS recipes)
+
+### 9.1 Prefer rings over border-width mutation
+
+**Avoid**
+```css
+/* Causes layout shift */
+.control:focus { border-width: 2px; }
+```
+
+**Prefer**
+```css
+.control:focus-visible {
+  outline: var(--cem-stroke-focus) solid currentColor;
+  outline-offset: var(--cem-stroke-indicator-offset);
+}
+```
+
+or (for rounded geometry / zebra):
+```css
+.control:focus-visible {
+  box-shadow: var(--cem-ring-zebra-3);
+}
+```
+
+### 9.2 Layering order for multiple indicators
+
+If multiple indicators can apply, compose in a stable order:
+1. focus
+2. selected
+3. target
+
+In zebra, this is naturally expressed as concentric stripes.
+
+### 9.3 Action components (existing pattern)
+
+Current implementation uses:
+
+```css
+.action { box-shadow: var(--cem-action-box-shadow); }
+.action:hover { --cem-action-box-shadow: var(--cem-action-box-shadow-hover); }
+.action:active { --cem-action-box-shadow: var(--cem-action-box-shadow-active); }
+```
+
+In contrast themes, `--cem-action-box-shadow` becomes the zebra ring.
+
+---
+
+## 10. Framework mapping guidance (Angular Material, MUI)
+
+This section is **non-normative**. It documents how to map framework tokens/variables into the CEM D5 semantic endpoints.
+
+### 10.1 Angular Material (MDC-based) mapping
+
+Common MDC variables (examples seen in Angular Material customization workflows):
+
+- `--mdc-outlined-text-field-outline-width` → `--cem-stroke-boundary`
+- `--mdc-outlined-text-field-focus-outline-width` → `--cem-stroke-focus` (or `--cem-stroke-boundary-strong`)
+- `--mdc-filled-text-field-active-indicator-height` → `--cem-stroke-divider`
+- `--mdc-filled-text-field-focus-active-indicator-height` → `--cem-stroke-focus`
+- `--mdc-outlined-card-outline-width` → `--cem-stroke-boundary`
+
+Angular Material also exposes higher-level variables in some setups, e.g.:
+- `--mat-form-field-outlined-focus-outline-width` → `--cem-stroke-focus`
+
+**Guidance:** map these variables *from* CEM tokens; do not treat them as canonical tokens in CEM.
+
+### 10.2 MUI mapping
+
+**MUI System**
+- `sx={{ border: 1 }}` expresses a border thickness via the theme’s `borders` scale.
+- Map `border: 1` (typical) to `--cem-stroke-boundary` (hairline).
+
+**MUI Joy UI**
+Joy exposes per-component CSS variables for focus ring geometry (examples):
+- `--Input-focusedThickness` → `--cem-stroke-focus`
+- `--Input-focusedInset` → whether focus is inset or outset (maps to indicator placement policy)
+- `--Input-focusedOffset` → `--cem-stroke-indicator-offset`
+
+---
+
+## 11. Canonical token summary
+
+| Token | Category | Required | Meaning |
+|------|----------|----------|---------|
+| `--cem-stroke-none` | Basis | ✓ | No stroke |
+| `--cem-stroke-hair` | Basis | ✓ | 1px hairline |
+| `--cem-stroke-standard` | Basis | ✓ | 2px standard indicator |
+| `--cem-stroke-strong` | Basis | ✓ | 3px strong separation |
+| `--cem-stroke-boundary` | Semantic | ✓ | Default component boundary |
+| `--cem-stroke-boundary-strong` | Semantic | Optional | Strong boundary for cases where elevation/shadow cannot carry separation |
+| `--cem-stroke-divider` | Semantic | ✓ | Default separator/divider |
+| `--cem-stroke-grid` | Semantic | Optional | Divider alias for structured content (tables/grids) |
+| `--cem-stroke-focus` | Semantic | ✓ | Focus-visible indicator width |
+| `--cem-stroke-selected` | Semantic | ✓ | Selection indicator width |
+| `--cem-stroke-target` | Semantic | ✓ | Target indicator width |
+| `--cem-stroke-indicator-offset` | Placement | ✓ | Ring/outline offset distance |
+| `--cem-zebra-strip-size` | Pattern | Optional | Stripe thickness for zebra indicators |
+| `--cem-zebra-angle` | Pattern | Optional | Stripe angle for gradient zebra |
+| `--cem-zebra-color-0..3` | Pattern | Optional | Concentric zebra stripe colors (intent/focus/selected/target) |
+| `--cem-action-box-shadow` | Adapter hook | Optional | Existing action indicator/shadow hook (implementation detail) |
+
+---
+
+## 12. Governance and versioning
+
+### 12.1 What counts as breaking
+
+Treat as **major** (breaking) if you:
+
+- Rename or remove any **Required (✓)** D5 endpoint listed in §11.
+- Change the semantic meaning of an endpoint (e.g., `--cem-stroke-focus` no longer representing focus thickness).
+- Remove zebra token meanings that consumers rely on (e.g., swapping which stripe denotes focus).
+
+### 12.2 What is non-breaking
+
+Treat as **minor/patch** if you:
+
+- Adjust numeric values within a theme while preserving semantics (e.g., `2px` → `3px` in contrast theme only).
+- Add new optional endpoints that are clearly scoped.
+- Clarify documentation, examples, or mapping guidance.
+
+---
+
+## 13. References
+
+- W3C WCAG 2.2 Understanding: Focus Appearance (Minimum) — https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
+- MDN: `:focus-visible` — https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible
+- Material Web focus ring documentation — https://github.com/material-components/material-web/blob/main/docs/components/focus-ring.md
+- Material Design 3 component specs (stroke/focus indicator values are listed per component):
+  - Menus (specs) — https://m3.material.io/components/menus/specs
+  - Checkbox (specs) — https://m3.material.io/components/checkbox/specs
+- Google issue tracker example referencing OutlinedTextField outline thickness in specs — https://issuetracker.google.com/issues/191543915
+
+- Angular Material customization guidance — https://v12.material.angular.io/guide/customizing-component-styles
+- Angular Material outlined form-field focus border width discussion (example) — https://github.com/angular/components/issues/28023
+- Angular Material customization examples showing outline width variables (examples):
+  - https://www.fusonic.net/en/blog/angular-material-customization
+  - https://dev.to/dhutaryan/how-to-make-angular-material-inputs-look-like-simple-fields-3oe5
+- MUI System borders utilities — https://mui.com/system/borders/
+- MUI Joy UI Input variables (focus thickness/offset) — https://mui.com/joy-ui/react-input/