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