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 Lab* (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).