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

# Material Design 3 — Foundations reference (supplement)

Covers 27 sitemap URLs under `foundations/*` that `reference-foundations.md` did not fetch under their exact
path (per-tab sub-pages the earlier pass reached only via a parent tab, plus a few pages the earlier pass
never visited at all). Only content **not already in `reference-foundations.md`** is written out in full;
pages that turned out to duplicate material already in the reference say so in one line instead of repeating
it. Same structure as the reference: Principles / Rules / Values tables / M3 vs M3 Expressive /
Accessibility / Source URLs, grouped by topic.

---

## Accessibility — assistive technology, designing, writing

### Duplicates (no new content)
- `foundations/designing/overview` — restates the reference's "Do use native elements / Don't use
  non-standard elements" dialog example verbatim. One new framing sentence: the designing tabs
  (Accessibility markup, Implementing accessibility, ...) exist to **"translate a visual UI into a
  text-based, linear user experience that maps to code."** The page only fully rendered two of its stage
  tabs (Accessibility markup, Implementing accessibility); a third stage implied by "three stages" was not
  captured in this fetch.

### New — Assistive technology (foundations/overview/assistive-technology)
Three assistive-technology categories, quoted:
- **Keyboard**: "Hardware or software directional controllers such as keyboards, a D-pad, or trackball allow
  users to jump from selection to selection in a linear fashion."
- **Screen readers**: "A screen reader is a software program that uses either a braille display or reads
  text aloud, such as Google's screen reader, TalkBack." Verbalizes visible content (paragraph/button text)
  **and** hidden content (alt text for icons, headings). Used by people with vision impairments, reading
  difficulty, or temporary reading limitations.
- **Switch input**: "Switches scan the items on your screen, highlighting each item in turn, until you make
  a selection. Switch Access lets you interact with your Android device using one or more switches instead
  of the touchscreen."

### New — Writing best practices, beyond alt text (foundations/writing/best-practices)
The reference already covers alt text length/rules; this page adds three more image-text mechanisms:
- **Adjacent text**: text in/around an image should present key information about the image (distinct from
  alt text and captions).
- **Captions**: text that appears below an image, explaining how it relates to the content; benefits both
  sighted and screen-reader users (screen readers **do** read captions, unlike embedded image text).
- **Embedded text in images**: "Screen readers are unable to read text that is embedded in imagery." Any
  essential information embedded as image text must be duplicated into the alt text instead. Caution flagged
  explicitly for this case.
- Alt text is also framed as an SEO benefit ("Keywords can also improve search engine optimization").

### New — Text resizing (foundations/writing/text-resizing)
**Requirement**: UIs must support a minimum text increase of **200%**.

**Scaling rules** — most components:
- Text and line height scale up proportionally, multiplied by the scale value.
- Padding remains constant at **1x** the default size (e.g., a button keeps 8dp top/bottom and 24dp
  left/right padding at 1x, 1.3x, and 2x text scale).
- Spacing between elements in a component remains constant at 1x.
- Components with no text (progress indicators, checkboxes, radio buttons) are **not** affected by text
  resizing — don't resize them.

**Multiplier calculation** (when the OS doesn't drive resizing): offer multipliers (e.g. 1.5x, 2x);
`font size = default font size (density 0) × scale value`. Example: 14pt at 1x → 28pt at 2x scale.

**Methods to handle large type** (avoids clipping, overlap, unwanted truncation):
| Method | Rule |
| --- | --- |
| Increase container size | Let containers grow so text doesn't overlap/clip/truncate; design for line-to-line eye tracking |
| Reflow the layout | Stack components (e.g. buttons) that were side-by-side, rather than keeping them fixed-width |
| Enable content to scroll | Prefer vertical scrolling only — never ask users to scroll both vertically and horizontally |
| Touch & hold tooltips | For space-constrained components — **top app bar, navigation bar, navigation rail, and fixed (non-scrolling) tabs** — keep the component's own text at 1x and show the full scaled-up label in a tooltip on touch & hold |

### New — Text truncation (foundations/writing/text-truncation)
**Requirement**: "Content, understandability, and functionality must not be lost when users modify their
type settings." (Exceptions may apply for non-Latin-alphabet languages.)

- **Text wrapping**: wrap text when it's critical, needed for understandability, or space allows. **Don't**
  cut off wrapped text without a way to see the rest (e.g., an expand affordance).
- **Height/width of components**: prefer flexible containers that grow to fit content over fixed text-size
  limits that don't fit the available space.
- **Ellipsis + hover/link**: truncating to an ellipsis is acceptable **only** if the full text is reachable
  via a tooltip or a link that reveals what was truncated. An ellipsis with no reveal mechanism "is not
  accessible." Note: this pattern still adds difficulty for some users, so use it deliberately.

### Source URLs
https://m3.material.io/foundations/overview/assistive-technology
https://m3.material.io/foundations/designing/overview
https://m3.material.io/foundations/writing/best-practices
https://m3.material.io/foundations/writing/text-resizing
https://m3.material.io/foundations/writing/text-truncation

---

## Content design — global writing, style guide

### Duplicates (no new content)
- `foundations/content-design/global-writing/overview` — same definition of global writing already quoted
  in the reference. One new line: **"This guidance is for all American English that is localized."**
- `foundations/content-design/style-guide/ux-writing-best-practices` — this is the exact content the earlier
  pass already captured at `foundations/content-design/style-guide` (explain consequences, scannable
  words/formats, sentence case, abbreviations sparingly) — fully identical, word for word.

### New — Grammar and punctuation (foundations/content-design/style-guide/grammar-and-punctuation)
Not covered anywhere in the reference. Rules, quoted/paraphrased:
- **Skip periods on single sentences** — omit in labels, tooltip text, bulleted lists, dialog body text,
  hyperlinked text. Use periods for multiple sentences, or long/complex sentences.
- **Use contractions** — easier to scan; exception: spelled-out "do not" can read as more emphatic than
  "don't" when caution is needed.
- **Serial (Oxford) comma** — always use it, except before an ampersand. Commas always go inside quotation
  marks.
- **Commas in numbers**: use commas for numbers **1,000–1,000,000**. Don't use commas when identifying
  something (street address, radio frequency, year). Above 1 million, comma use depends on context;
  "million" can be abbreviated "M" with rounding when giving a sense of volume rather than an exact count
  (e.g. "23M views").
- **Skip colons in headings** — no colon on a heading introducing a list; do use a colon for a list
  introduced within body text.
- **Exclamation points sparingly** — fine for greetings/congratulatory moments; avoid for empty states and
  routine tasks ("save it for bigger accomplishments").
- **Ellipses sparingly** — indicate an in-progress action or incomplete text (check with engineering, since
  truncation ellipses are often automatic). No space before an ellipsis. Omit ellipses from menu items or
  buttons that open a dialog or start a process.
- **Parentheses** — only to define acronyms/jargon or cite a source; never for an aside/afterthought (fold
  the info into the sentence instead).
- **Ampersands**: "&" is acceptable in headlines, column headers, table headers, navigation labels, and
  buttons (space-constrained contexts) — but spelling out "and" improves readability where there's room.
  Always spell out "and" in sentences/paragraphs, before the final item in a 3+ item list, and in email
  subject lines.
- **Dashes** — three kinds: em dash (—), en dash (–), hyphen (-). Avoid em dashes in UX writing (replace with
  a comma, period, or new sentence). Use an en dash with no surrounding spaces for a range (e.g. "9 AM–Noon").
- **Hyphens** — bind closely related words; also represent negative numbers (e.g. "-100"); never surrounded
  by spaces. Defer to AP style when unsure whether a phrase needs one. Hyphenation table:
  | Rule | Examples | Why |
  | --- | --- | --- |
  | Hyphenate adjective phrases | case-by-case basis, best-in-class performance, once-in-a-lifetime opportunity | Multiple words used together as one adjective are hyphenated — but not proper nouns or common phrases ("cell phone number", "chocolate chip cookie") |
  | Hyphenate noun phrases | sign-off, drive-through, go-ahead (verb+adverb); higher-up, most-read (adjective-as-noun); jack-of-all-trades, stick-in-the-mud (fixed idioms) | Certain multi-word nouns are always hyphenated |
  | Don't hyphenate verb phrases | "look out for falling rocks," "drop off your car," "check in to the room" | A verb+adverb/preposition acting as a verb isn't hyphenated (contrast the noun "check-in"); note "check into" ≠ "check in to" |
- **Italics sparingly** — hard to read; use bold for emphasis instead. Italics are acceptable for a single
  word/phrase (a name or title), never a full sentence.
- **No caps blocks** — "Avoid using caps blocks altogether; they're not accessible." Use sentence case for
  all product text.

### New — Word choice: pronouns (foundations/content-design/style-guide/word-choice)
Note: this is a **different** page from the already-covered `global-writing/word-choice` (which is about
localization word choice). This one is about person/pronoun choice:
- **Use second person ("you"/"your")** — makes the UI feel like it's speaking to the user about their own
  actions; avoid impersonal/robotic phrasing.
- **Don't mix first and second person** in the same context (e.g. "My photos" title next to "Your photos"
  description) — pick one address form, or drop the pronoun.
- **Use caution with "I"/"we"** — for a large company like Google, first person can read as robotic or
  disconcerting; prefer the user's point of view or remove the pronoun. **Exception**: legal text may use
  "I"/"my" to emphasize ownership in an agreement (e.g. "I agree to the terms of service").

### Source URLs
https://m3.material.io/foundations/content-design/global-writing/overview
https://m3.material.io/foundations/content-design/style-guide/grammar-and-punctuation
https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices
https://m3.material.io/foundations/content-design/style-guide/word-choice

---

## Design tokens — usage workflow

### Duplicates (no new content)
- `foundations/design-tokens/overview` — restates the reference's token definition, naming scheme,
  three-class model (ref/sys/comp), and contexts verbatim (this is the site's single `design-tokens` page,
  now also reachable at `/overview`).

### New — Reading a component's token spec table (foundations/design-tokens/overview)
Not in the reference: a documented procedure for finding a token in a component's Specs tab. Tokens there
are grouped first by **state** (enabled, disabled, hover, etc.), then by **element** (the part the token
applies to, e.g. container or label text). Table columns:
| Column | Meaning |
| --- | --- |
| Name | The style aspect the token applies to (e.g. color, font) |
| Token ID | The token defining that style aspect |
| Description | Optional extra info |
| Context/value | The value stored for a given context |

Worked example given on the page: to verify a filled button's label-text color, go to *Common buttons* →
*Specs*, find the filled-button token module, locate the "label text" row under elements, and copy the color
token into code (or compare it to the Figma color role).

### New — How to use tokens, a Figma workflow (foundations/design-tokens/how-to-use-tokens)
Entirely new — a step-by-step production workflow, not covered anywhere in the reference:
1. **Install** the Material Theme Builder Figma plugin.
2. **Generate tokens**: Plugins → Material Theme Builder → Open Plugin → Get started. Creates a
   `material-theme` artboard with baseline tonal palettes (light/dark) and a default type scale, populated
   as Figma styles.
3. **Update token values** — two ways:
   - Via the plugin (color only): re-open the plugin, choose new colors; color/text styles update in place.
   - Via Figma styles directly: right-click a style → "Go to style definition," hover the style → the
     adjust icon (or right-click → Edit style) to change name/description/properties.
4. **Use tokens in mockups**: apply the generated Figma styles to layout elements instead of hand-setting
   color/typography, so engineers can trust the design intent transfers.
5. **Use tokens with the Material Design Kit**: duplicate the kit, open the plugin with kit components
   selected, and choose **Swap** to replace baseline token values with the custom generated ones.
6. **Export tokens**: plugin's Export tab → choose a target format (Android, Jetpack Compose) → save as a
   named `.zip`.

### Source URLs
https://m3.material.io/foundations/design-tokens/overview
https://m3.material.io/foundations/design-tokens/how-to-use-tokens

---

## Interaction: states (per-state one-line definitions)

### Duplicate, with one addition
`foundations/interaction/states/overview` restates the "two visual indicators," "states can combine," and
six-state list already in the reference. New here: the site's own one-line definition for each state
(not quoted in the reference), verbatim:
| State | Definition |
| --- | --- |
| Enabled | "communicates an interactive component or element" |
| Disabled | "communicates an inoperable component or element" |
| Hover | "communicates when a user has placed a cursor above an interactive element" |
| Focused | "communicates when a user has highlighted an element, using an input method such as a keyboard or voice" |
| Pressed | "communicates a user tap" |
| Dragged | "communicates when a user presses and moves an element" |

### Source URL
https://m3.material.io/foundations/interaction/states/overview

---

## Layout — adaptive design, breakpoints per class, canonical layouts

### Duplicates (no new content)
- `foundations/layout/layout-overview/overview` — same 7-parts-of-layout figure and Layout terms glossary
  already quoted in the reference (this is the site's `layout-overview` tab, now also at `/overview`).
- `foundations/layout/scaffold/overview` — same Bars/Rails/Panes summary already in the reference.
- `foundations/layout/grids-spacing/overview` — same "grids adapt across breakpoints / spacing groups &
  directs attention / density for data-heavy views" summary already in the reference.
- `foundations/layout/breakpoints/overview` — same breakpoint width table, pane/navigation/communication/
  action table, five adaptation questions, and common-swappable-components table already fully quoted in
  the reference.
- `foundations/usability/overview` and `foundations/usability/applying-m3-expressive` — **both render the
  same content** as the reference's Usability section (five NN/g usability aspects, usability-vs-
  accessibility distinction, the M3-Expressive design-tactics list — color/contrast, containment, motion,
  shape & shape morph, size, typography — and "design based on primary goals"). No new facts on either page.

### New — Adaptive design, defined (foundations/layout/layout-overview/adaptive-design)
Not covered in the reference at all — this is the site's actual definition of the "adaptive design" term
the reference only flagged as a May-2026 rename target:
- **Adaptive vs. responsive**: "While responsive design scales a single layout to fit any screen, adaptive
  design customizes a product to optimize the experience on each device." Adapts to **People** (preferences/
  settings), **Devices** (watch, phone, foldable, tablet, desktop, XR), and **Usage** (window resize,
  orientation, device switch).
- **Three primary experience types** — design starts at mobile and scales up to spatial; all three should
  account for touch, pointer, and physical-keyboard input regardless of the device's default input:
  | Experience | Notes |
  | --- | --- |
  | Mobile | Phones, foldables, tablets. Window modes: **full-screen** (default), **split-screen** (2+ apps sharing the screen), **bubbles** (floating multitask windows) |
  | Desktop | Free-form windows adapting across breakpoints; split-screen/floating/free-form multitasking. A tablet becomes a desktop experience once a keyboard+mouse connect; an Android phone can become desktop-like via an external monitor |
  | Spatial (XR) | Multiple free-form windows in a "virtually limitless" screen. Android XR's immersive **"full space"** mode positions components freely in 3D. A navigation rail can become an **Orbiter**, floating beside the main pane (ties to the glossary's XR "Orbiter" term already in the reference, now with a concrete use case) |
- **Adaptive strategies** (named mechanism, not in the reference): as a pane/window resizes or someone
  navigates, panes may change size, enter/exit, or reorganize via three strategies: **show and hide**,
  **levitate**, and **reflow**. Panes are "the primary segments of a layout" and can change based on context.
- **Pane display styles**, with sharper definitions/examples than the reference's terse list:
  - **Co-planar**: panes displayed side by side.
  - **Floating**: a pane displayed above other panes/content, "like a dialog."
  - **Docked**: a pane displayed above other content where one edge extends beyond a screen edge, "like a
    bottom sheet."
- Compose's **Navigation 3** library lets multiple destinations show on screen simultaneously and adapts
  layouts across window sizes/screens automatically.
- **Adapting components** — three component-level adaptation strategies:
  | Strategy | Example given |
  | --- | --- |
  | Resizing | A button may scale with its parent container, or "hug" its content and stay left/right-aligned |
  | Showing & hiding | A list item can reveal a description/extra info as its container scales up |
  | Presentation changes | A FAB can become an extended FAB; a navigation rail can auto-expand as the window grows |

### New — Breakpoints, per window-size class (foundations/layout/breakpoints/{compact,medium,expanded,large-extra-large})
The reference only has the aggregate breakpoint table; these per-class pages add concrete margins, pane
widths, and navigation placement the reference doesn't state:

| Breakpoint | Width | Margins/spacer | Panes | Navigation | Notes |
| --- | --- | --- | --- | --- | --- |
| Compact | <600dp | **16dp** margins | 1 (always) | Navigation bar or modal expanded navigation rail, placed close to the screen edge for reach | Must transition dynamically on: foldable unfold, portrait→landscape rotation, exiting split-screen, multi-window resize larger, free-form resize |
| Medium | 600–839dp | **24dp** margins and spacer | 1 recommended; 2 only for low-density content (e.g. settings) — each pane defaults to 50% width, don't set custom widths; a drag handle can expand either pane to 100% | Single-pane: navigation rail (can hide on secondary destinations if a back button still reaches the primary destination); two-pane: navigation bar (to keep panes at full width) | Reachability: top 25% of screen is hard to reach on horizontal tablets/unfolded foldables — limit interactions there; page defines 3 ergonomic regions (inconvenient reach / comfortable / challenging near bottom edge). Transition triggers: foldable fold, landscape→portrait rotation, full-screen→split-screen, multi-window start, free-form resize |
| Expanded | 840–1199dp | **24dp** margins and spacer | 1 (only for dense content like video) or 2 (recommended); fixed-and-flexible layout's fixed pane defaults to **360dp**; a split-pane layout's two flexible panes visually center the spacer, with nav rail + first pane totaling 50% | Navigation rail (collapsed or expanded); hideable on secondary destinations with a back button; use tabs/other in-pane components for secondary/sort/filter nav | Transition triggers: foldable fold, landscape→portrait rotation, full-screen→split-screen, multi-window start, free-form resize |
| Large (1200–1599dp) & Extra-large (1600dp+) | — | **24dp** margins and spacer | 2 recommended (1 only for dense/media content); fixed-and-flexible fixed pane defaults to **412dp**; extra-large only can add a **standard side sheet as a 3rd pane** (side sheet max width 400dp even though 412dp is the general fixed-pane recommendation) — never exceed 3 panes | Navigation rail, collapsed or expanded depending on content volume; expanded rail suits extra-large best, collapse when space is needed or deep in the hierarchy | Large/extra-large are "most useful for...laptop and desktop devices"; some products may skip them entirely. Watch line length/typography at this size. Transition triggers: full-screen→split-screen, multi-window start, free-form resize |

### New — Canonical layout examples, in detail (foundations/layout/canonical-examples/{overview,feed,list-detail,supporting-pane})
The reference only had a stub (three names + "not fetched, outside foundations/*"); these are the real
`foundations/layout/canonical-examples/*` pages (distinct from the `m3/pages/canonical-examples/*` URLs the
reference declined to follow), each with compact/medium/expanded configurations:

**Overview**
- Three canonical layouts exist: **feed, list-detail, supporting pane** — each with compact/medium/expanded
  configurations, meant as a starting point rather than a fixed template.
- Supporting-pane split defined precisely: primary/focus area "typically about two-thirds" of the window;
  secondary/supporting area takes the remaining third.
- **Advanced custom layouts**: build on a canonical example or layer scaffold elements directly. The
  **"layering"** technique uses the **levitate** adaptive strategy — a pane floats above other content for a
  focused, task-oriented moment (examples given: reviewing a shopping basket, responding to comments,
  creating a calendar event).
- Availability: Figma M3 Design Kit, Jetpack Compose canonical-layouts sample, Android Views (MDC-Android)
  canonical-layouts sample.

**Feed**
- Use case: grid of cards/lists for quick browsing/discovery of large content volumes (news, photos, social
  media); grids adapt from single- to multi-column at any size.
- Dividing space: flexible enough to mix proportions/sizes (e.g. small + large cards together) to signal
  relationships between items; items reflow on rotation/unfold/multi-window, and item **order is determined
  by position**.
- Across breakpoints: **Compact** — stack vertically, one card per row, full pane width. **Medium** — split
  into multiple equal-width columns (example shown: 4 columns). **Expanded/large/extra-large** — more
  columns than medium, and column width should usually increase as the breakpoint grows.

**List-detail**
- Use case: parent-child content pairings — text message + conversation, file browser + open folder, artist
  + album, settings + category detail, inbox + selected email.
- Visible-panes table (breakpoint dp ranges as stated on this page):
  | Breakpoint (dp) | Visible panes |
  | --- | --- |
  | Compact (0–599) | 1 pane |
  | Medium (600–839) | 1 (recommended) or 2 |
  | Expanded (840+) | 2 |
  | Large (1200–1599) | 2 |
  | Extra-large (1600+) | 2 |
- **Compact**: single pane only, either list or detail view at a time.
- **Medium**: single pane for information-dense content/deep focus, **or** two-pane to browse and switch
  quickly — use a bottom navigation bar or modal navigation rail in two-pane mode to maximize horizontal
  space.
- **Expanded/large/extra-large**: two-pane.
- **Behavior**: a **Back button appears in the detail view only for single-pane layouts**; a **selected
  state appears in the list view only for two-pane layouts**; use explicit/implicit grouping to direct
  visual focus in two-pane layouts. Layouts transition dynamically as available space changes (e.g. rotating
  from expanded to medium collapses two panes back to one).

**Supporting pane**
- Use case: secondary content that is "only meaningful in relation to" the primary content (contrast with
  list-detail's parent-child relationship — use list-detail instead if that's the actual relationship).
  Examples: productivity, document editing + commenting, content/media browsing.
- Placement/width table:
  | Supporting-pane placement | Pane width | Breakpoint |
  | --- | --- | --- |
  | Below the focus pane | Flexible | Compact or Medium |
  | Leading or trailing side of the focus pane | Fixed, **360dp** | Expanded |
- **Compact**: supporting pane appears below the focus pane; a bottom sheet is a good way to keep focus on
  the primary pane while still giving access to supporting info.
- **Medium**: supporting pane appears below the focus pane (same as compact).
- **Expanded**: supporting pane moves to the leading or trailing side of the focus pane.

### Source URLs
https://m3.material.io/foundations/layout/layout-overview/overview
https://m3.material.io/foundations/layout/layout-overview/adaptive-design
https://m3.material.io/foundations/layout/scaffold/overview
https://m3.material.io/foundations/layout/grids-spacing/overview
https://m3.material.io/foundations/layout/breakpoints/overview
https://m3.material.io/foundations/layout/breakpoints/compact
https://m3.material.io/foundations/layout/breakpoints/medium
https://m3.material.io/foundations/layout/breakpoints/expanded
https://m3.material.io/foundations/layout/breakpoints/large-extra-large
https://m3.material.io/foundations/layout/canonical-examples/overview
https://m3.material.io/foundations/layout/canonical-examples/feed
https://m3.material.io/foundations/layout/canonical-examples/list-detail
https://m3.material.io/foundations/layout/canonical-examples/supporting-pane
https://m3.material.io/foundations/usability/overview
https://m3.material.io/foundations/usability/applying-m3-expressive