livewire-material/docs/reference/m3/foundations.md

# Material Design 3 — Foundations reference

Extracted verbatim (with light reformatting) from m3.material.io/foundations for auditing an M3 Expressive
component library. Facts not present on the fetched pages are marked "(not on the site; from ...)".
Where the site's own text is ambiguous or inconsistent, both readings are quoted rather than resolved.

---

## Accessibility (foundations/overview, /overview/principles, /designing*, /writing, /building-for-all*)

### Principles
- "Accessibility by default is a core design value for Material." Accessibility requirements and goals are
  documented across component pages and guidelines.
- Three principles for accessible design:
  - **Honor individuals** — universal defaults rarely meet everyone's needs; build in customizable features
    since a person's needs change over time.
  - **Learn before, not after** — invest in research across a wide range of abilities before defining
    solutions, rather than reacting to problems after launch.
  - **Requirements as a starting point** — treat WCAG minimums as a floor for creative solutions, not a
    ceiling (dark mode, text-to-speech, speech-to-text all originated as accommodations).
- "Usability focuses on making products intuitive and easy to understand for everyone" while "Accessibility
  focuses on making products accessible for people with disabilities. Accessible experiences are
  perceivable, operable, understandable and robust, and support people who use assistive technology."
  (from foundations/usability)

### Rules (do / don't)
- **Do** use native platform elements/semantic HTML so components automatically carry the right
  accessibility markup (e.g., a native `dialog`).
- **Don't** use non-standard elements to fake a standard pattern (e.g., a custom div styled as a dialog) —
  it requires extra testing to work with assistive tech.
- Disabled states **do not** need to meet contrast requirements.
- **Landmarks (web only)** — classify page regions with ARIA landmark roles so visual structure is also
  conveyed in code. The eight landmark roles: **navigation, search, main, banner, complementary,
  contentinfo, region, form**.
  - Only one **main**, one **banner**, one **contentinfo** per page.
  - Label any landmark role that repeats (e.g., multiple `navigation` regions) with a unique, specific
    label; **all regions** should be labeled.
  - **Don't repeat the landmark role inside its own label** (e.g., a nav labeled "Navigation").
- **Headings (web only)**:
  - Identify headings by content hierarchy, not visual styling.
  - "Headings should not skip a level, for example, don't go from H2 to H4 without using an H3."
  - Map content to H1–H6 in sequential order.
  - "A single H1 for the page title is recommended."
  - Heading level and visual prominence don't have to match.
- **Focus order / keyboard**:
  - Default tab order should follow the DOM and "generally flows from left to right; top to bottom." Use
    this default unless a custom pattern requires otherwise.
  - Define **initial focus** for a screen and for multi-element components (dialogs, complex cards).
  - When a dialog opens, focus moves into it (to a specific interactive element); on close/cancel, focus
    returns to the element that triggered it.
  - Tab / Shift+Tab move between interactive elements (Shift+Tab reverses); arrow keys navigate within a
    component (menu items, grid cells); Enter activates a link/button or submits a focused form.
  - Grouped sub-elements can be one tab stop, navigated internally with arrow keys.
  - **Keyboard shortcuts**: use two-or-more-key combinations by default. Document all shortcuts (help page
    or tutorial). If a shortcut uses a single key, provide at least one of, in preference order:
    1. (most preferred) remap to include a non-printable key,
    2. (preferred) only activate when the relevant component is focused,
    3. (temporary only) allow turning the shortcut off.
- **Labeling elements**:
  - Needs a label: interactive icons/buttons with no/insufficient visible text, interactive images,
    meaningful visual cues (progress bars, error states), meaningful icons/images, generic links
    ("Learn more"), buttons with ambiguous/duplicate text ("Save").
  - Doesn't need a label: non-interactive UI text (read automatically), buttons with sufficient text
    ("Download image").
  - **Don't include the element's role (button, menu, etc.) in the label text** — the role is added
    automatically when the proper role is assigned.
  - Decorative icons/images that add nothing for a screen-reader user should be marked decorative/hidden
    (e.g., `alt=""`).

### Values
| Item | Value | Source |
| --- | --- | --- |
| Large text/graphics contrast (≥14pt bold / ≥18pt regular) | ≥ 3:1 against background | designing/color-contrast, writing |
| Small text contrast | ≥ 4.5:1 against background | designing/color-contrast, writing |
| Clustered non-text elements (e.g. a group of buttons) vs. background | ≥ 3:1 recommended | designing/color-contrast |
| Standalone elements (e.g. a single FAB) vs. background | not required to meet 3:1 (prominence already differentiates them) | designing/color-contrast |
| Disabled-state contrast | not required to meet contrast requirements | designing/color-contrast, applying-states |
| Touch target minimum | **48 × 48dp** (≈9mm physical; recommended range 7–10mm) | designing/structure |
| iOS touch target note | iOS recommends 44 × 44dp | designing/structure |
| Pointer (mouse/stylus) target minimum | **44 × 44dp** | designing/structure |
| Target spacing | ≥ 8dp between adjacent targets | designing/structure |
| Web default target size | at least 48 × 48 **CSS pixels** | grids-spacing/density |
| Alt text length | "up to 125 characters" (foundations/writing) **vs.** "recommended length ... is 140 characters" (content-design/alt-text) — site is internally inconsistent; both figures are quoted verbatim | writing, content-design/alt-text |

### Alt text rules (content-design/alt-text, foundations/writing)
- Alt text is read in place of an image by screen readers and shown if an image fails to load.
- **Do** write alt text that conveys context/meaning; **don't** leave the auto-generated filename as alt
  text.
- Mark an image `alt=""` (decorative) if removing it loses no information.
- Focus on the meaning/purpose of the image, not exhaustive visual detail.
- **Don't start alt text with "image of"** — screen readers already announce "image".
- Essential vs. non-essential image content: essential info must meet the 3:1 (large) / 4.5:1 (small) contrast
  above; decorative/non-essential elements are exempt.

### M3 vs M3 Expressive differences
- No explicit M3-vs-Expressive distinction is drawn on the Accessibility pages themselves; the WCAG-based
  contrast and target-size rules are presented as constant across both.

### Accessibility requirements (recap)
- Two-indicator principle for states is asserted only as a bullet: **"States have two visual indicators to
  ensure accessibility"** (foundations/interaction/states) — the page does not elaborate further on this
  Foundations tier (see Interaction States section below for the gap this leaves).

### Source URLs
https://m3.material.io/foundations/overview
https://m3.material.io/foundations/overview/principles
https://m3.material.io/foundations/designing (tabs: Overview, Color contrast, Structure, Flow, Elements)
https://m3.material.io/foundations/designing/color-contrast
https://m3.material.io/foundations/designing/structure
https://m3.material.io/foundations/designing/flow
https://m3.material.io/foundations/designing/elements
https://m3.material.io/foundations/writing
https://m3.material.io/foundations/building-for-all
https://m3.material.io/foundations/building-for-all/user-needs (identical rendered content to /building-for-all)
https://m3.material.io/foundations/building-for-all/co-design

---

## Content design (foundations/content-design/*)

### Principles
- "UI text should be clear to anyone." Follow **Associated Press (AP) Style** unless Material notes
  otherwise.

### Rules (do / don't) — Style guide (content-design/style-guide)
- **Explain consequences** in neutral, direct language; avoid alarming/condescending warnings. Do tell
  users what will happen and how to undo it; don't misrepresent consequences to influence a decision.
- **Use scannable words and formats** — specific titles/headings people can skim.
- **Use sentence case.** "Unless otherwise specified, use sentence-style capitalization... All text,
  including titles, headings, labels, menu items, navigation components, app bars, and buttons should use
  sentence-style capitalization." Products/branded terms may still be capitalized. **Don't use title case.**
- **Use abbreviations sparingly.** Spell out words where possible; avoid Latin abbreviations ("e.g.",
  "etc.") — use "for example," "and more" instead.

### Rules — Alt text (see also Accessibility above)
- Recommended alt text length: 140 characters (content-design/alt-text); don't start with "image of".

### Rules — Global writing (content-design/global-writing, /global-writing/word-choice)
- Global writing = writing inclusively for many cultures and optimized for localization/translation.
- **Use global examples; explain local references** — call out (in a message description for translators)
  locations, names/nicknames, currencies, temperatures, date formats, and providers (internet/cable) that
  don't translate globally.
- Use short, simple sentences; break into bullets/sections with headings.
- Avoid abbreviations; clarify ambiguous pronouns and "this"/"that" references.
- Avoid idiomatic, colloquial, or overly polite expressions (translation risk).
- Reduce technical jargon; clarify ambiguities.

### Rules — Notifications (content-design/notifications)
- Notifications should: be about the user (not the product); be precise, timely, actionable, contextual,
  relevant; give easy opt-out controls; never be unsolicited ads.
- Put the most important info first (people skim in an F-shape).
- CTAs should be concise, specific, actionable.
- Make notifications relevant/personal — don't broadcast generically.
- **Avoid dynamic text**, especially in headlines (breaks character limits when translated, doesn't
  expand if truncated). If used, pair with no more than one additional word, and prepare a fallback
  notification that fits the character budget.
- **Don't use relative day words** ("today"/"tomorrow"/"tonight") — about 20% of users don't see a
  notification the day it's sent; use the specific day of the week instead (exception: auto-dismissing
  notifications tied to a timestamp).
- Use emoji sparingly; never to accentuate bad news (negative emoji tested poorly); don't replace words
  with emoji.
- Don't repeat the app name/logo (already shown by the OS).
- Don't interrupt onboarding with unrelated notifications/emails.
- Give users in-context, clear opt-in/opt-out controls.

### Values
| Element | Character limit |
| --- | --- |
| Notification title | < 29 characters |
| Notification collapsed body | < 40 characters |
| Notification expanded body | < 80 characters (start with the collapsed body and extend it) |
| Notification buttons | 1–2 buttons, 1–2 words each |
| SMS, Latin-script languages | < 160 characters |
| SMS, non-Latin-script languages | < 134 characters |
| Alt text | 140 characters recommended (content-design/alt-text) / "up to 125 characters" (foundations/writing) |

### M3 vs M3 Expressive differences
- Not called out on these pages; content-design guidance is presented as version-agnostic.

### Accessibility requirements
- Alt text and captions are the accessibility mechanism this section owns (see Accessibility section for
  full alt-text rules); captions benefit both sighted and screen-reader users.

### Source URLs
https://m3.material.io/foundations/content-design/overview
https://m3.material.io/foundations/content-design/alt-text
https://m3.material.io/foundations/content-design/global-writing
https://m3.material.io/foundations/content-design/global-writing/word-choice
https://m3.material.io/foundations/content-design/notifications
https://m3.material.io/foundations/content-design/style-guide

---

## Customization (foundations/customization)

### Principles
- "M3 opens up new possibilities for both brand colors and individual color preferences to converge in
  one-of-a-kind experiences."
- Dynamic color lets an app retain brand-defining colors while also honoring a user's device/personal color
  preference; works for custom (non-Material) components too.

### Rules
- Build a **custom color scheme** with the M3 color system so the app can respect device/app-level dynamic
  color settings; always keep a fallback (non-dynamic) color scheme for users who don't enable dynamic
  color.
- Apply dynamic color selectively if desired (e.g., only on a profile screen) rather than app-wide.

### Values
- **Five essential color groups / roles**: Primary, Secondary, Tertiary, Neutral, Neutral Variant. An input
  (source) color generates a tonal palette that fills roles such as primary / on-primary / primary
  container.
- The Material Theme Builder (Figma plugin) generates **color and type tokens**, exportable to multiple
  code formats, including Design System Package (DSP) format.

### M3 vs M3 Expressive differences
- Not explicitly distinguished on this page; dynamic color and the 5-role model are presented as the
  current (M3) system without an Expressive-specific callout.

### Accessibility requirements
- "The color system automatically handles critical adjustments that provide accessible color contrast,
  legibility, interaction states, and component structure."

### Source URLs
https://m3.material.io/foundations/customization

---

## Design tokens (foundations/design-tokens)

Note: the task brief anticipated separate `/overview`, `/how-to-read-tokens`, `/how-to-use-tokens`
sub-pages; the live site has a **single page** at `foundations/design-tokens` covering all of this content
(confirmed via the site's own top-nav, which links only to `foundations/design-tokens`).

### Principles
- "Design tokens are small, reusable design decisions that make up a design system's visual style. Tokens
  replace static values with self-explanatory names."
- A token = a code-like name (e.g. `md.ref.palette.secondary90`) + an associated value (e.g. `#E8DEF8`);
  the value can be a color, typeface, measurement, or another token.
- Tokens let design and code stay in sync: "if a designer's mock-ups and an engineer's implementation both
  reference the same token... they can be confident that the same [value] is being used in both places,"
  even after the underlying value changes.
- Tokens should be used instead of hardcoded values whenever a design choice recurs across components.

### Rules
- **Do** use design tokens instead of hardcoded values.
- Name each token for how/where it's used (e.g. `md.comp.fab.primary.container.color` sets an FAB's
  container color).
- **System tokens should point to reference tokens**, not static values, whenever possible.
- **Component tokens should point to a system or reference token**, not hardcoded values, whenever
  possible.
- Tokens are recommended when: building a design system from scratch or updating one broadly, applying a
  system across a suite of products, wanting to maintain/update styles easily, or wanting dynamic color.
  Tokens are **less** helpful for an existing app with values unlikely to change and no design system.

### Values — naming scheme
| Part | Meaning | Example |
| --- | --- | --- |
| System prefix | Always starts with the system name | `md` (Material Design) |
| Class | `ref` = reference, `sys` = system, `comp` = component | `md.ref…`, `md.sys…`, `md.comp…` |
| Role/descriptor | Descriptive words for the token's purpose | `…palette.secondary90`, `…color.secondary-container`, `…fab.primary.container.color` |

### Values — the three token classes
| Class | Prefix | Definition | Example |
| --- | --- | --- | --- |
| Reference tokens | `ref` | "All available tokens with associated values." Point to static values (or other reference tokens); don't change based on context. | `md.ref.palette.secondary90` → `#E8DEF8`; `md.ref.typeface.plain-medium` → Roboto Medium |
| System tokens | `sys` | "Decisions and roles that give the design system its character" — theming happens here; can point to different ref tokens by context (e.g. light/dark theme). | `md.sys.color.secondary-container` → `md.ref.palette.secondary90`; `md.sys.typescale.label-medium.font` |
| Component tokens | `comp` | "(in development)" — the design properties assigned to a specific component's elements (container, label, icon, state, size, shape, color, elevation). | Extended FAB container color / label text tokens |

- **Contexts**: conditions under which a token points to a non-default value — "device form factors, dark
  theme, dense layouts, and right-to-left writing systems" are the examples given. A context acts like a
  tag overriding the default token value.
- Glossary cross-references (foundations/glossary): **Design tokens: Role** = "short nickname describing
  the purpose of a design token... Also known as slots" (e.g. "On surface", "Body 1"); **Design tokens:
  Value** = "the information defining a design attribute, either stored in a token or hard-coded."

### M3 vs M3 Expressive differences
- Component tokens are explicitly flagged as **"(in development)"** — i.e., not every component's tokens
  are finalized/complete as of this fetch.

### Accessibility requirements
- Not directly addressed on this page; contexts (e.g. dark theme, dense layout) are the token mechanism
  used elsewhere to satisfy accessibility/adaptation requirements.

### Source URLs
https://m3.material.io/foundations/design-tokens

---

## Interaction: gestures, inputs, selection, states

### Gestures (foundations/interaction/gestures)

**Principles**
- "Gestures help people navigate, take action, or transform content." UI elements should respond to
  gestures in real time. Tap, scroll, and swipe are the most common.

**Types (do/don't-style catalogue, no numeric specs given)**
- Tap (navigate/interact), Double tap (zoom in/out), Long press (extra functionality / selection), Scroll
  and pan, Swipe (switch peer views like tabs, complete actions, or reveal actions on a list item), Drag,
  Pick up and move (long-press + drag to reorder), Pinch (scale), Compound gestures (e.g. pan + pinch on a
  map).
- **Predictive back** (Android): swipe left/right to preview going back before committing. Compatible
  components: **bottom sheet, navigation bar, navigation rail, search bar, side sheet**.

**Source**: https://m3.material.io/foundations/interaction/gestures

### Inputs (foundations/interaction/inputs)

**Principles**
- "Design for touch, keyboard, and mouse interactions." Embrace multiple input methods within one app.

**Rules / values**
- External input devices: mouse (left/right click, wheel, extra buttons), trackpad (click, gestures,
  haptics), physical keyboard (replaces virtual keyboard; media keys; modifier keys), stylus.
- **Hover**: rest a cursor on an interactive element to trigger its hover state (see States below) and, if
  applicable, a tooltip.
- **Cursor shapes**: Pointer (default), Hand (links/linked images), Resize arrows (resizable element
  edges), I-beam (editable/selectable text). Text-selection click semantics: single click places cursor /
  deselects & repositions; double click selects a word; triple click selects a paragraph.
- **Physical keyboard**: show/hide the on-screen (virtual) keyboard based on whether a physical keyboard is
  attached (do hide it when a physical keyboard connects; do show it again when disconnected). Enter
  typically sends/submits; Spacebar (or media keys) typically play/pause media.

**Source**: https://m3.material.io/foundations/interaction/inputs

### Selection (foundations/interaction/selection)

**Principles**
- Selection can be shown via a check icon, a checkbox, or a surface-color change (or a combination).
- An entire component, or only certain parts of it, can be selected. Selection can be performed by tap,
  cursor, keyboard, or voice.

**Values**
- Components that **inherit selection styling**: cards, checkboxes, chips, data tables, icon buttons, list
  items, menu items, pickers, radio buttons, segmented buttons, sliders, switch.
- Components that use an **active indicator** instead (only one selected at a time): navigation bar,
  navigation drawer, navigation rail, tabs.

**Rules**
- Touch: long-press or two-finger touch (or a shortcut, e.g. tapping an avatar) enters selection mode; tap
  additional items to add them; tap each selected item (or a toolbar action) to exit selection mode.
- Long-press + drag can batch-select — **don't** reuse this gesture combo for selection if it's already
  used to pick up/move items (e.g. reordering cards).
- Desktop/click: when selection is the primary activity, checkboxes stay visible; when secondary, show a
  checkbox on hover for a single item, and for all items once one is selected.

**Source**: https://m3.material.io/foundations/interaction/selection

### States (foundations/interaction/states, /states/state-layers, /states/applying-states)

**Principles**
- "States are visual indicators used to communicate the status of a component or interactive element."
- **"States have two visual indicators to ensure accessibility"** — stated as a bullet on the States
  overview page; the site does **not** elaborate on this rule anywhere in Foundations (no page defines
  what the two indicators must be, e.g. color + shape/outline). This is a documentation gap to flag when
  auditing — Foundations only asserts the principle, not the mechanism.
- States can combine (e.g. selected + hover); apply states consistently across components.
- Six states: **Enabled, Disabled, Hover, Focused, Pressed, Dragged.**

**State layer mechanics (states/state-layers)**
- "A state layer is a semi-transparent covering on an element that indicates its state," providing "a
  systematic approach to visualizing states by using opacity." Only one state layer can be applied at a
  given time; it can cover the whole element or a circular sub-region.
- The state layer's color equals the **content's "on" color** (e.g. if the container uses **secondary
  container** and content uses **on secondary container**, the state layer uses **on secondary
  container**).
- **"The size of state layers is 40dp while the interactive target size is 48dp."**

**Values — state layer / disabled opacities** (from the states/state-layers interactive module, exact
figures)
| State | Opacity |
| --- | --- |
| Hover | 0.08 (+8%) |
| Focus | 0.10 (+10%) |
| Pressed | 0.10 (+10%) |
| Dragged | 0.16 (+16%) |
| Disabled | 0.38 |

**Rules — per-state inheritance (applying-states)**
| State | Inherited by | NOT inherited by |
| --- | --- | --- |
| Disabled | Buttons, Cards, Checkboxes, Chips, List items, Radio buttons, Switches, Text fields | App bars, Badges, Dialogs, FABs, Menus, Navigation bar/drawer/rail, Sheets, Tabs, Tooltips |
| Hover | Buttons, Cards, Checkbox, Chips, Date/time pickers, List items, Slider, Switch, Text fields | App bars, Badges, Dialogs, Menus, Navigation bar/drawer/rail, Sheets, Tabs |
| Focused | Buttons, Cards, Checkbox, Chips, Date/time pickers, List items, Selection controls, Text fields | App bars, Badges, Banner, Card, Dialogs, Navigation bar/drawer/rail, Sheets |
| Pressed | Buttons, Cards, Checkbox, Chips, List items, Text fields | App bars, Badges, Bottom navigation, Dialogs, Menus, Sheets, Tabs |
| Dragged | Cards, Chips, List items, Sliders | App bars, Badges, Buttons, Dialogs, Menus, Navigation bar/drawer/rail |

- **Disabled**: communicated via color change + reduced elevation; not focusable, draggable, or pressable;
  no hover/other state layer; exempt from contrast requirements; "if the action... is unavailable, the FAB
  shouldn't appear" (don't just disable it) — a Don't example specifically about FABs.
- **Hover**: lower-emphasis overlay; appears/disappears with a "low-emphasis animated fade"; only one hover
  state active in a layout at a time; can combine with focused/activated/selected/pressed.
- **Focused / keyboard focus indicator**: "When an element is tabbed to, it appears in its focused state
  with a ring-like keyboard focus indicator." **No thickness, offset, or color token is specified anywhere
  in Foundations** — this page only calls it "ring-like." (Exact focus-ring specs, if they exist, live in
  per-component spec pages outside the Foundations section — flag as out-of-scope-for-this-file / a gap
  for the audit.) Only one focus state active at a time; initiated by Tab (or equivalent).
- **Pressed**: higher-emphasis than hover; a **ripple overlay** signifies press (can also/alternatively use
  an elevation change); only one pressed state active at a time; initiated by tap/click/keyboard/voice
  activation.
- **Dragged**: lower-emphasis overlay than pressed, "to avoid distracting users from their task"; can also
  use elevation; only one dragged state active at a time; initiated by touch-and-hold + move.

### M3 vs M3 Expressive differences
- Not explicitly called out for interaction/states; the state-layer opacity table and inheritance lists are
  presented as the current, single spec (this appears to be the M3 Expressive-era rewrite of the classic M2
  state-layer table, but the site does not itself label old vs. new values here).

### Accessibility requirements
- The "two visual indicators" principle (see above) is the accessibility hook for state changes but is left
  unelaborated in Foundations.
- Disabled components are fully exempted from contrast requirements.
- Keyboard operability requirements live in Accessibility → Flow (focus order, keyboard shortcuts) above,
  and cross-reference into States for the focus indicator.

### Source URLs
https://m3.material.io/foundations/interaction/gestures
https://m3.material.io/foundations/interaction/inputs
https://m3.material.io/foundations/interaction/selection
https://m3.material.io/foundations/interaction/states/overview
https://m3.material.io/foundations/interaction/states/state-layers
https://m3.material.io/foundations/interaction/states/applying-states

---

## Layout (foundations/layout/*)

Note on the task brief's guessed slugs: the live IA does **not** use `/understanding-layout/*` or
`/applying-layout/*`. Real structure discovered via the site's own nav/tab links:
- `layout/layout-overview` (tabs: Overview, **Overview: Parts of layout** → `/layout-overview/parts-of-layout`)
- `layout/scaffold` (tabs: Overview, Bars, Rails, Panes)
- `layout/grids-spacing` (tabs: Overview, Grids, Spacing, Density)
- `layout/breakpoints`
- `layout/bidirectionality-rtl`
- `layout/canonical-examples`

### Principles
- "Layout is the visual and strategic arrangement of elements on a screen," used to organize elements,
  signal hierarchy, and draw attention to key actions.
- Adapt layouts to the five breakpoints; build from an established canonical layout example; design for
  bidirectionality (LTR + RTL); apply consistent arrangement/sizing/spacing.
- Material's components are built with **"leading"/"trailing"** (not left/right) naming so they support RTL
  by construction — "extra configuration may be needed to achieve specific RTL situations," though.
- **May-2026 renames** (explicitly called out on the site as new terminology): **"Window size classes
  renamed to breakpoints"**; **"Responsive layout renamed to adaptive design."**

### Values — Layout terms glossary (layout-overview)
- **Adaptive design**: techniques letting an interface dynamically respond to user preference, device
  type, state, and breakpoints.
- **Bars**: frame the page (app bar, bottom navigation bar).
- **Bidirectionality**: a writing system displaying content RTL.
- **Breakpoints**: "opinionated window sizes where a layout changes to match available space, device
  conventions, and ergonomics (previously window size classes)."
- **Column**: one or more vertical blocks of content within a pane.
- **Drag handle**: resizes panes.
- **Fold**: the flexible/hinge area separating two displays on a foldable.
- **Gap**: space between components/elements within a container.
- **Margin**: space between the screen edge and elements inside it.
- **Multi-window mode**: multiple apps sharing one screen simultaneously.
- **Pane**: "a layout container that houses other components and elements within a single app... fixed,
  flexible, floating, or semi-permanent."
- **Rails**: perimeter space around panes holding navigation rails, toolbars, pane controls.
- **RTL language**: e.g. Arabic, Hebrew, Farsi — used by "over 2 billion people."
- **Rulers**: opinionated global alignment lines.
- **Safety region**: zones reserved for system UI (status bar, gesture bar) — "shouldn't contain primary
  content."
- **Scaffold**: "a fundamental UI design structure that provides a standard platform for assembling key
  screen components."
- **Spacer**: space between two panes on a foldable.
- **7 parts of layout** (numbered figure caption): Column, Fold, Margin, Bar, Drag handle, Pane, Rail.

### Values — Breakpoints (layout/breakpoints)
| Breakpoint | Width (dp) | Common devices |
| --- | --- | --- |
| Compact | Under 600dp | Phone in portrait |
| Medium | 600–839dp | Tablet in portrait; foldable in portrait (unfolded) |
| Expanded | 840–1199dp | Phone/tablet in landscape; foldable in landscape (unfolded); desktop |
| Large | 1200–1599dp | Desktop |
| Extra-large | 1600dp+ | Desktop; ultra-wide monitors |

- Height breakpoints (compact/medium/expanded) also exist on Android but are rarely needed since most
  layouts scroll vertically.

**Breakpoint → recommended panes / navigation / communication / action** (layout/breakpoints)
| Breakpoint | Panes | Navigation | Communication | Action |
| --- | --- | --- | --- | --- |
| Compact | 1 | Navigation bar, modal expanded navigation rail | Simple dialog, full-screen dialog | Bottom sheet |
| Medium | 1 (recommended) or 2 | Navigation bar, modal expanded navigation rail | Simple dialog | Menu |
| Expanded | 1 or 2 (recommended) | Modal or standard expanded navigation rail | Simple dialog | Menu |
| Large | 1 or 2 (recommended) | Modal or standard expanded navigation rail | Simple dialog | Menu |
| Extra-large | 1 to 3 (recommended) | Modal or standard expanded navigation rail | Simple dialog | Menu |

**Common swappable components by breakpoint** (layout/breakpoints)
| Component type | Compact | Medium | Expanded |
| --- | --- | --- | --- |
| Navigation | Navigation bar | Collapsed navigation rail | Collapsed navigation rail |
| Navigation (secondary row) | Modal expanded navigation rail | Modal expanded navigation rail | Standard expanded navigation rail |
| Communication | Basic or full-screen dialog | Basic dialog | Basic dialog |
| Supplemental selection | Bottom sheet | Menu | Menu |

- Pane-count guidance restated: **compact/medium → 1 pane; expanded/large → 2 panes recommended;
  extra-large → consider 3 panes.**
- Five questions to ask moving up a breakpoint: what should be **revealed, divided (paned), resized,
  repositioned, swapped**. Across breakpoints, keep text to **40–60 characters per line**.
- Component-swap example: compact navigation bar → medium/expanded navigation rail; collapsed rail
  (medium/expanded) → expanded rail (large/extra-large). **Don't** swap functionally non-equivalent
  components (e.g. a button for a menu).

### Values — Scaffold (layout/scaffold, /bars, /rails, /panes)
- Scaffold = **Bars + Rails + Panes**, arranged around a **safety region** that must stay clear of primary
  content.
- **Bars**: frame the page; contain app bar (top) or navigation bar (bottom). App bars: title + 1–2
  essential actions (search, back). "**Navigation bars let people switch between 3–5 primary UI views**"
  at compact/medium breakpoints.
- **Rails**: the perimeter layer after bars; hold navigation rails, toolbars, chat inputs, FABs, other
  primary controls; on desktop, a leading/trailing rail; on mobile, a toolbar can float in the rail region.
- **Panes**: all content must live in a pane; a layout has **1–3 panes**, adapting to breakpoint and
  language direction (RTL flips navigation to the right).
  - **Single-pane** layouts: any breakpoint, recommended at compact/medium.
  - **Two-pane** layouts: common at expanded/large/extra-large; fixed-and-flexible panes can appear in
    either order.
  - **Three-pane** layouts: "Fixed panes at this breakpoint are recommended to be **412dp**, but side
    sheets have a default maximum width of **400dp**."
  - **Snap widths** when resizing a two-pane layout at expanded/large/extra-large: **360dp**, **412dp**, or
    a centered split-pane with spacer.
  - **Persistent resizing** (remembers width across sessions/breakpoint changes) is the default
    recommendation for most resizable layouts; **temporary resizing** (reverts to default on
    close/reopen) is for supporting-pane layouts where resizing is uncommon.
  - Multi-pane display styles: **co-planar** (side by side — used for persistent utilities so they stay
    accessible), **floating**, **docked**.
  - **Accessibility**: coplanar-pane focus order must match visual arrangement; modal floating panes trap
    focus (move focus in on open, return it to the trigger on close) and close on outside interaction;
    non-modal floating panes let focus move freely in/out and must sit in logical reading order; docked
    panes follow the same focus rules as floating panes, plus the coplanar focus-order requirement.

### Values — Grids & spacing (layout/grids-spacing, /grids, /spacing, /density)
- Grids: column count/width/spacing scale with breakpoint (compact fewer columns → expanded/foldable more
  columns); **no explicit numeric column-count or gutter table is given on the current site** (this is a
  gap versus the classic M2 12-column grid spec — flag if the component library assumes fixed column
  counts).
- **Rulers**: Bar & safety rulers (reserve system-UI space), Title ruler (aligns app-bar title), Content
  rulers (first ruler = major blocks like hero/headline; secondary rulers = supplementary text/actions).
  Margin rulers can be widened/narrowed for expressive effect (e.g., full-bleed photo grid vs. a
  wide-margin search bar).
- Spacing is used to **group** (explicit grouping = outlines/dividers/shadows; implicit grouping =
  proximity/whitespace only), to **direct attention** (rhythm, similarity, proximity, continuity), and as
  **expression** (generous spacing + bright surfaces on the most important content; negative space for
  emphasis). No fixed numeric spacing scale (e.g. 4/8/16dp increments) is stated on this page beyond the
  8dp target-spacing rule already listed under Accessibility.
- **Density** (component scaling):
  - Density scale is numbered starting at **0** (default) and moves negative (**-1, -2, -3**) as space
    decreases.
  - "Higher density is typically applied by decreasing the top and bottom padding or overall height by
    **4dp**" per step.
  - Text size should not change as a container scales with density.
  - Example figures from the page: 20dp gap between a text field's label and input; a "don't" example shows
    a dropdown item shrunk to 38dp of selectable height (too dense — reduces usability).
  - **Density must be opt-in, never default**: "People should be able to **opt in** to dense layouts and
    components." Settings interactions themselves must keep default target sizes (**48×48 CSS pixels**).
    "Don't scale layouts below 48×48dp by default."
  - **Interaction targets must stay ≥48×48dp even when the visible element is scaled down** — e.g. a
    settings icon can be 24×24dp visually but must keep a 48×48dp target; a 36dp-tall button can keep a
    48dp target.
  - Don't increase density in focused/high-stakes UI (menus, snackbars, dialogs).
  - Pixel density formula: `pixel density = screen width (or height) in px / screen width (or height) in
    inches`.
  - **Density-independent pixel (dp)**: "A dp is equal to one physical pixel on a screen with a density of
    160." Formula: `dp = (width in pixels × 160) / screen density`.

### Values — Bidirectionality / RTL (layout/bidirectionality-rtl)
- Over 2 billion people read/write RTL languages (Arabic, Hebrew, Farsi, Urdu).
- **Mirroring**: LTR ⇄ RTL flips element alignment/order; reading starts top-right in RTL. **Exception**:
  graphs/charts stay LTR even in Persian and Urdu.
- **Text rendering** has two parts: alignment (box placement) and directionality (text/element flow).
  Common RTL bugs: text entry, cursor position, punctuation, phone numbers, URLs. **Don't** reverse an
  email's username/domain order (domain always stays to the right of the username, even though the
  username itself can render RTL). **Don't** apply LTR directionality to RTL content (scrambles word
  order) — content needs both RTL alignment *and* RTL directionality.
- **Icons**: directional icons (back/forward, send) mirror in RTL. **Exception**: in Hebrew, timelines and
  media controls keep LTR directionality; help icons mirror only in some RTL languages (e.g. Urdu,
  Persian).
- **Time / progress**: linear progress indicators fill right-to-left in most RTL languages, **except
  Hebrew, which stays LTR**. Circular progress indicators always move clockwise regardless of direction.
  Media player controls (video/audio) are **always LTR**. Clocks always turn clockwise; on a 12-hour clock
  in RTL, the AM/PM symbol moves to the left; the 24-hour clock is common outside English-primary
  locales.
- **Canonical layouts in RTL**: list-detail, feed, and supporting-pane layouts are all explicitly "mirrored
  in RTL."
- **Component specifics**: badges reposition; toolbars mirror tool order; app bars mirror layout and flip
  directional icons; **navigation rail sits on the leading edge — right side in RTL, left in LTR**
  (expanded nav rail too); text field leading/trailing icons swap sides; a chip's trailing icon "is always
  aligned to the end side of the container" (right for LTR, left for RTL).
- **Gestures**: swipe-to-reveal actions and Android predictive back must mirror their LTR counterparts
  (e.g. a delete action revealed by a right-swipe in LTR should be revealed by a left-swipe in RTL).

### Values — Canonical layout examples (layout/canonical-examples)
- Named canonical layouts referenced: **feed**, **list-detail**, **supporting-pane** (each links out to a
  dedicated `m3.material.io/m3/pages/canonical-examples/...` page — a legacy/alternate URL namespace not
  fetched here since it falls outside `foundations/*`). An "Advanced custom layouts" section exists on the
  page but only points onward, with no further numeric content on this page itself.

### M3 vs M3 Expressive differences
- The May-2026 rename ("window size class" → "breakpoint"; "responsive layout" → "adaptive design") is the
  only explicit terminology-version marker found in Layout.
- Density (opt-in component scaling) and the layout scaffold (bars/rails/panes model) are presented as the
  current single system, introduced/updated as part of the same May-2026 refresh per layout-overview's
  "What's new" log ("Introduced layout scaffold... Updated canonical layout examples... Spacing system").

### Accessibility requirements
- Safety regions must stay clear of primary content (keeps content from being obscured by system UI).
- Pane focus-order/trap rules above (coplanar order must match visual order; modal panes trap and restore
  focus).
- RTL is treated as an accessibility/global-reach requirement throughout, not an optional locale nicety.
- Minimum 48×48dp interaction targets carry through from Accessibility into density/scaling rules here.

### Source URLs
https://m3.material.io/foundations/layout/layout-overview
https://m3.material.io/foundations/layout/layout-overview/parts-of-layout
https://m3.material.io/foundations/layout/scaffold/overview
https://m3.material.io/foundations/layout/scaffold/bars
https://m3.material.io/foundations/layout/scaffold/rails
https://m3.material.io/foundations/layout/scaffold/panes
https://m3.material.io/foundations/layout/grids-spacing/overview
https://m3.material.io/foundations/layout/grids-spacing/grids
https://m3.material.io/foundations/layout/grids-spacing/spacing
https://m3.material.io/foundations/layout/grids-spacing/density
https://m3.material.io/foundations/layout/breakpoints
https://m3.material.io/foundations/layout/bidirectionality-rtl
https://m3.material.io/foundations/layout/canonical-examples

---

## Usability (foundations/usability)

### Principles
- "Usability focuses on making products intuitive and easy to understand for everyone" — distinct from
  Accessibility (see Accessibility section for the exact wording of the distinction).
- Key takeaways: emphasize key actions for visual hierarchy; leverage M3 Expressive design tactics; don't
  overwhelm users with visual information; test and iterate.

### Values — Nielsen Norman Group's five usability aspects (quoted directly)
| Aspect | Definition |
| --- | --- |
| Efficiency | Users can efficiently complete tasks and goals |
| Errors | Proper design reduces the likelihood of mistakes, and users can easily correct any errors that do occur |
| Learnability | New users learn to use the product and complete tasks easily, even the first time |
| Memorability | Returning users remember how to use the product |
| Satisfaction | Users are satisfied with the designed experience |

### Rules — Usability design tactics (explicitly framed as **M3 Expressive** tactics)
- **Color & contrast**: use eye-catching primary/secondary colors and contrasting pairs (e.g. purple +
  green) for hierarchy; always follow the accessibility contrast rules above.
- **Containment & grouping**: group related elements in subtle containers; break content into sections with
  containment/spacing/headings.
- **Motion**: use sparingly to emphasize key moments — "motion can be distracting" if overused.
- **Shape & shape morph**: "The Material shape library has **35 shapes**." Shape adds emphasis/delight,
  guides focus, differentiates containers/buttons/animations, signals interaction, sets emotional tone.
  Every shape can morph into any other in the set; shape morph communicates interaction states (selected,
  tap, swipe, scroll, release, long press) and emphasizes in-progress actions.
- **Size**: the most important action/CTA should be the largest element; larger key actions measurably
  improve efficiency, error rate, satisfaction, learnability (per the doc's own claim, no citation given).
- **Typography**: use type scale/weight to separate information hierarchies (largest/most legible text =
  primary action; smaller text = secondary/tertiary); group similar content with the same font style.
- Design around **primary / secondary / tertiary goals**: give primary goals the strongest emphasis;
  simplify to one primary task per page; make core actions large/reachable; don't stack too many expressive
  tactics at once (distracting).
- **Iterate**: test and gather feedback early/often from a range of users/contexts.

### M3 vs M3 Expressive differences
- This entire page's "design tactics" section is explicitly attributed to **M3 Expressive** ("Leverage
  [expressive design tactics]... containment, size, shape, color, and typography"), including the 35-shape
  library and shape-morph mechanic, which are Expressive-era additions.

### Accessibility requirements
- "Accessibility focuses on making products accessible for people with disabilities... perceivable,
  operable, understandable and robust... support people who use assistive technology" (contrasted directly
  with usability's broader "intuitive for everyone" framing).

### Source URLs
https://m3.material.io/foundations/usability

---

## Glossary terms that matter for a web component library (foundations/glossary)

Only terms relevant to auditing a component library are excerpted; the full glossary runs A–Z (~20KB) and
also defines many component names already covered under Components (out of scope here). Quoted verbatim.

| Term | Definition (verbatim) |
| --- | --- |
| Adaptive design | "A design approach in which the interface changes based on known user, device, or environmental conditions. Adaptive design in Material includes layout and component adaptations." |
| Condition | "A signal that determines when and how an adaptive layout or component should adapt." |
| Contrast | "Difference between colors. For accessibility, contrast refers strictly to the difference in tone. **A difference of 40 in tone guarantees a WCAG contrast ratio ≥ 3.0; a difference of 50 in tone guarantees a contrast ratio ≥ 4.5.**" |
| Customization | "A modification made to a UI reflecting an app, OEM, or individual user's visual preferences and brand." Can be per-element or global (a theme). |
| Dark theme | "A dark theme is a low-light UI that displays mostly dark surfaces." |
| Design tokens | "A design token represents a small, reusable design decision that's part of a design system's visual style. Tokens replace static values with self-explanatory names." |
| Design tokens: Context | "The set of conditions in which tokens can point to non-default values (for example, dark theme, dense layout)." |
| Design tokens: Role | "A shortened version of the system token name (for example, Secondary container color; Headline 1)." |
| Design tokens: Types | Reference tokens (e.g. `md.ref.palette.secondary200`); Component tokens (define a component element's design attributes); System tokens (e.g. `md.sys.color.secondary-container`) |
| Design tokens: Value | "The information defining a design attribute, either stored in a token or hard-coded." |
| Element | (page continues past excerpt boundary — not fully captured; component name only) |
| HCT | "HCT is an abbreviation of hue, chroma, tone. It's the name of the color space that enables dynamic color. HCT is based on CAM16 hue and chroma; the L* construct for luminance from L*a*b* (CIELAB, 1976) is denoted as T for tone." |
| Mode | (component/theming term; not fully excerpted) |
| Orbiter | "Floating UI elements that control the content within spatial panels." (XR-adjacent; likely out of scope) |
| Pane | "The building blocks of a layout. Content and actions are grouped into panes, which adapt the content to best fit the screen." |
| Role | "Short nickname describing the purpose of a design token within a design system. Also known as slots. Examples: On surface; Body 1." |
| Spatial | (XR-adjacent term; out of scope per task instructions) |
| Style | (design-spec term; not fully excerpted) |
| Theme | (not fully excerpted — see "Note: A light scheme is not the same as a light theme" under Color: Scheme) |

### Color-system glossary terms (used throughout Customization/Design tokens)
| Term | Definition (verbatim) |
| --- | --- |
| Color: Baseline scheme | "the group of selected tones that make up the default colors values used for light and dark themes." |
| Color: Dynamic color | "A customization feature in which a user-generated color scheme is mapped to an app's color scheme." Not simply Theme-Builder output or an algorithmic scheme — it's the *presence of a changeable color role*. |
| Color: Extended color | "A color specified (in addition to key colors) in order to fill color roles for custom schemes... brand expression or conventional (semantic) meanings." |
| Color: Key color | "not an extracted color — it's a derivation of the source color... the basis for a tonal palette." |
| Color: Scheme | "Any mapping of color roles to specific tones from a tonal palette." A **dark scheme** ≠ a **dark theme** (scheme vs. theme distinction explicitly noted). |
| Color: Source color | "The single color that's extracted to define all five key colors." |
| Color: Tonal palette | "a 13-tone range that serves as the basis for mapping tones to specific roles." |
| Color: Tone | "colors with the same hue and chroma... degrees of lightness." Code: `Tone.of(hex).get(tone)` or `Tone.of(hue, chroma).get(tone)`. |
| Color: User-generated schemes | colors derived from a user's wallpaper selection or Android preset colors. |

### Source URLs
https://m3.material.io/foundations/glossary

---

## Cross-cutting gaps found (for the auditing agents to be aware of)

1. **Focus indicator specifics** (thickness / offset / color token) are **not defined anywhere in
   Foundations** — only "ring-like keyboard focus indicator" is stated (states/applying-states). If the
   component library asserts a specific focus-ring spec, that spec's source is not this section of the
   site.
2. **The "two visual indicators" accessibility rule for states** is asserted once, as a bullet, with zero
   elaboration anywhere in Foundations on what the two indicators must be.
3. **Alt text length is inconsistent across the site itself**: 125 characters (foundations/writing) vs. 140
   characters (foundations/content-design/alt-text).
4. **No explicit numeric grid/column/gutter table** exists on the current (M3 Expressive-era) Layout pages,
   unlike the classic Material 2 12-column-grid spec; grids/spacing guidance here is qualitative except for
   the 8dp target-spacing and pane-width (360/400/412dp) numbers captured above.
5. **Component tokens are explicitly flagged "(in development)"** on the design-tokens page — treat
   component-token completeness claims cautiously.
6. Two task-provided sub-page slugs did not exist as separate URLs: `design-tokens/overview`,
   `/how-to-read-tokens`, `/how-to-use-tokens` all collapse into the single `foundations/design-tokens`
   page; `layout/understanding-layout/*` and `layout/applying-layout/*` do not exist — the real nesting is
   `layout/layout-overview/parts-of-layout`, `layout/scaffold/{bars,rails,panes}`, and
   `layout/grids-spacing/{grids,spacing,density}` (all fetched and covered above).