Plan the Material 3 alignment, with the audits and Google's references
Every foundations, styles and components page of m3.material.io (238, from the sitemap) extracted into docs/reference/m3, five audit reports with 142 findings in docs/audits/m3-alignment, and the 2.0.0 plan in docs/plans/material-3-alignment.md. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9
This commit is contained in:
Andreas Reinhold / reini
co-authored by
Claude Fable 5.1
Claude Fable 5.1
parent
b1fc0c9cfa
commit
651a513d1e
@@ -0,0 +1,37 @@
|
||||
# Material Design 3 reference (extracted 2026-09-13)
|
||||
|
||||
What Google's documentation says, condensed for auditing this library against it. Every file
|
||||
keeps the wording of the site where a rule is stated, the tables verbatim, and a source URL per
|
||||
section. Numbers the site only draws in pictures were taken from androidx Compose Material 3's
|
||||
token files (`compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/`)
|
||||
and the Material Components Android component docs, and are marked with their source.
|
||||
|
||||
| File | Covers |
|
||||
|---|---|
|
||||
| `foundations.md`, `foundations-supplement.md` | accessibility, content design, customisation, design tokens, interaction (gestures, inputs, selection, states), layout (window size classes, scaffold, grids and spacing, canonical layouts, RTL), usability, glossary |
|
||||
| `styles.md`, `styles-supplement.md` | colour (roles, system, dynamic, custom colours, contrast), elevation, icons, motion (Expressive springs, easing and duration, transitions), shape (corner scale, shapes, morph), spacing, typography |
|
||||
| `components-actions-communication-containment.md` | buttons, icon buttons, button groups, split button, segmented buttons, FAB, extended FAB, FAB menu, badges, progress indicators, loading indicator, snackbar, tooltips, bottom sheets, cards, carousel, dialogs, divider, lists, side sheets, menus |
|
||||
| `components-navigation-selection-inputs.md` | app bars, navigation bar, navigation rail, navigation drawer, tabs, toolbars, search, checkbox, chips, radio button, sliders, switch, text fields, date pickers, time pickers, data tables |
|
||||
| `pages.txt` | the 238 pages under `/foundations`, `/styles` and `/components` in the site's sitemap (watches and XR left out) — the coverage checklist; every one was fetched |
|
||||
|
||||
## Refreshing
|
||||
|
||||
m3.material.io renders only in a browser. Read it through a reader proxy, one page at a time
|
||||
(it rate-limits with HTTP 429; retry after a few seconds; add `-H "x-no-cache: true"` for a
|
||||
stale snapshot):
|
||||
|
||||
```bash
|
||||
curl -sL "https://m3.material.io/sitemap.xml" | grep -o '<loc>[^<]*' | sed 's/<loc>//' # the page list
|
||||
curl -sL "https://r.jina.ai/https://m3.material.io/components/buttons/specs" # one page
|
||||
```
|
||||
|
||||
The audits that used these files are in `docs/audits/m3-alignment/`.
|
||||
|
||||
## Attribution
|
||||
|
||||
The text is Google's, from https://m3.material.io, reproduced here so the library can be
|
||||
checked against it; the token values are from the Android Open Source Project (Apache-2.0, see
|
||||
`NOTICE`). Google publishes its design documentation under the Creative Commons Attribution 4.0
|
||||
licence "except as otherwise noted"; confirm the statement in the site's footer before
|
||||
reproducing these files anywhere else. `docs/` is export-ignored, so they are not part of the
|
||||
Composer distribution.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,355 @@
|
||||
# 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
|
||||
@@ -0,0 +1,748 @@
|
||||
# Material Design 3 — Foundations reference
|
||||
|
||||
Extracted verbatim (with light reformatting) from m3.material.io/foundations for auditing an M3 Expressive
|
||||
component library. Facts not present on the fetched pages are marked "(not on the site; from ...)".
|
||||
Where the site's own text is ambiguous or inconsistent, both readings are quoted rather than resolved.
|
||||
|
||||
---
|
||||
|
||||
## Accessibility (foundations/overview, /overview/principles, /designing*, /writing, /building-for-all*)
|
||||
|
||||
### Principles
|
||||
- "Accessibility by default is a core design value for Material." Accessibility requirements and goals are
|
||||
documented across component pages and guidelines.
|
||||
- Three principles for accessible design:
|
||||
- **Honor individuals** — universal defaults rarely meet everyone's needs; build in customizable features
|
||||
since a person's needs change over time.
|
||||
- **Learn before, not after** — invest in research across a wide range of abilities before defining
|
||||
solutions, rather than reacting to problems after launch.
|
||||
- **Requirements as a starting point** — treat WCAG minimums as a floor for creative solutions, not a
|
||||
ceiling (dark mode, text-to-speech, speech-to-text all originated as accommodations).
|
||||
- "Usability focuses on making products intuitive and easy to understand for everyone" while "Accessibility
|
||||
focuses on making products accessible for people with disabilities. Accessible experiences are
|
||||
perceivable, operable, understandable and robust, and support people who use assistive technology."
|
||||
(from foundations/usability)
|
||||
|
||||
### Rules (do / don't)
|
||||
- **Do** use native platform elements/semantic HTML so components automatically carry the right
|
||||
accessibility markup (e.g., a native `dialog`).
|
||||
- **Don't** use non-standard elements to fake a standard pattern (e.g., a custom div styled as a dialog) —
|
||||
it requires extra testing to work with assistive tech.
|
||||
- Disabled states **do not** need to meet contrast requirements.
|
||||
- **Landmarks (web only)** — classify page regions with ARIA landmark roles so visual structure is also
|
||||
conveyed in code. The eight landmark roles: **navigation, search, main, banner, complementary,
|
||||
contentinfo, region, form**.
|
||||
- Only one **main**, one **banner**, one **contentinfo** per page.
|
||||
- Label any landmark role that repeats (e.g., multiple `navigation` regions) with a unique, specific
|
||||
label; **all regions** should be labeled.
|
||||
- **Don't repeat the landmark role inside its own label** (e.g., a nav labeled "Navigation").
|
||||
- **Headings (web only)**:
|
||||
- Identify headings by content hierarchy, not visual styling.
|
||||
- "Headings should not skip a level, for example, don't go from H2 to H4 without using an H3."
|
||||
- Map content to H1–H6 in sequential order.
|
||||
- "A single H1 for the page title is recommended."
|
||||
- Heading level and visual prominence don't have to match.
|
||||
- **Focus order / keyboard**:
|
||||
- Default tab order should follow the DOM and "generally flows from left to right; top to bottom." Use
|
||||
this default unless a custom pattern requires otherwise.
|
||||
- Define **initial focus** for a screen and for multi-element components (dialogs, complex cards).
|
||||
- When a dialog opens, focus moves into it (to a specific interactive element); on close/cancel, focus
|
||||
returns to the element that triggered it.
|
||||
- Tab / Shift+Tab move between interactive elements (Shift+Tab reverses); arrow keys navigate within a
|
||||
component (menu items, grid cells); Enter activates a link/button or submits a focused form.
|
||||
- Grouped sub-elements can be one tab stop, navigated internally with arrow keys.
|
||||
- **Keyboard shortcuts**: use two-or-more-key combinations by default. Document all shortcuts (help page
|
||||
or tutorial). If a shortcut uses a single key, provide at least one of, in preference order:
|
||||
1. (most preferred) remap to include a non-printable key,
|
||||
2. (preferred) only activate when the relevant component is focused,
|
||||
3. (temporary only) allow turning the shortcut off.
|
||||
- **Labeling elements**:
|
||||
- Needs a label: interactive icons/buttons with no/insufficient visible text, interactive images,
|
||||
meaningful visual cues (progress bars, error states), meaningful icons/images, generic links
|
||||
("Learn more"), buttons with ambiguous/duplicate text ("Save").
|
||||
- Doesn't need a label: non-interactive UI text (read automatically), buttons with sufficient text
|
||||
("Download image").
|
||||
- **Don't include the element's role (button, menu, etc.) in the label text** — the role is added
|
||||
automatically when the proper role is assigned.
|
||||
- Decorative icons/images that add nothing for a screen-reader user should be marked decorative/hidden
|
||||
(e.g., `alt=""`).
|
||||
|
||||
### Values
|
||||
| Item | Value | Source |
|
||||
| --- | --- | --- |
|
||||
| Large text/graphics contrast (≥14pt bold / ≥18pt regular) | ≥ 3:1 against background | designing/color-contrast, writing |
|
||||
| Small text contrast | ≥ 4.5:1 against background | designing/color-contrast, writing |
|
||||
| Clustered non-text elements (e.g. a group of buttons) vs. background | ≥ 3:1 recommended | designing/color-contrast |
|
||||
| Standalone elements (e.g. a single FAB) vs. background | not required to meet 3:1 (prominence already differentiates them) | designing/color-contrast |
|
||||
| Disabled-state contrast | not required to meet contrast requirements | designing/color-contrast, applying-states |
|
||||
| Touch target minimum | **48 × 48dp** (≈9mm physical; recommended range 7–10mm) | designing/structure |
|
||||
| iOS touch target note | iOS recommends 44 × 44dp | designing/structure |
|
||||
| Pointer (mouse/stylus) target minimum | **44 × 44dp** | designing/structure |
|
||||
| Target spacing | ≥ 8dp between adjacent targets | designing/structure |
|
||||
| Web default target size | at least 48 × 48 **CSS pixels** | grids-spacing/density |
|
||||
| Alt text length | "up to 125 characters" (foundations/writing) **vs.** "recommended length ... is 140 characters" (content-design/alt-text) — site is internally inconsistent; both figures are quoted verbatim | writing, content-design/alt-text |
|
||||
|
||||
### Alt text rules (content-design/alt-text, foundations/writing)
|
||||
- Alt text is read in place of an image by screen readers and shown if an image fails to load.
|
||||
- **Do** write alt text that conveys context/meaning; **don't** leave the auto-generated filename as alt
|
||||
text.
|
||||
- Mark an image `alt=""` (decorative) if removing it loses no information.
|
||||
- Focus on the meaning/purpose of the image, not exhaustive visual detail.
|
||||
- **Don't start alt text with "image of"** — screen readers already announce "image".
|
||||
- Essential vs. non-essential image content: essential info must meet the 3:1 (large) / 4.5:1 (small) contrast
|
||||
above; decorative/non-essential elements are exempt.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- No explicit M3-vs-Expressive distinction is drawn on the Accessibility pages themselves; the WCAG-based
|
||||
contrast and target-size rules are presented as constant across both.
|
||||
|
||||
### Accessibility requirements (recap)
|
||||
- Two-indicator principle for states is asserted only as a bullet: **"States have two visual indicators to
|
||||
ensure accessibility"** (foundations/interaction/states) — the page does not elaborate further on this
|
||||
Foundations tier (see Interaction States section below for the gap this leaves).
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/overview
|
||||
https://m3.material.io/foundations/overview/principles
|
||||
https://m3.material.io/foundations/designing (tabs: Overview, Color contrast, Structure, Flow, Elements)
|
||||
https://m3.material.io/foundations/designing/color-contrast
|
||||
https://m3.material.io/foundations/designing/structure
|
||||
https://m3.material.io/foundations/designing/flow
|
||||
https://m3.material.io/foundations/designing/elements
|
||||
https://m3.material.io/foundations/writing
|
||||
https://m3.material.io/foundations/building-for-all
|
||||
https://m3.material.io/foundations/building-for-all/user-needs (identical rendered content to /building-for-all)
|
||||
https://m3.material.io/foundations/building-for-all/co-design
|
||||
|
||||
---
|
||||
|
||||
## Content design (foundations/content-design/*)
|
||||
|
||||
### Principles
|
||||
- "UI text should be clear to anyone." Follow **Associated Press (AP) Style** unless Material notes
|
||||
otherwise.
|
||||
|
||||
### Rules (do / don't) — Style guide (content-design/style-guide)
|
||||
- **Explain consequences** in neutral, direct language; avoid alarming/condescending warnings. Do tell
|
||||
users what will happen and how to undo it; don't misrepresent consequences to influence a decision.
|
||||
- **Use scannable words and formats** — specific titles/headings people can skim.
|
||||
- **Use sentence case.** "Unless otherwise specified, use sentence-style capitalization... All text,
|
||||
including titles, headings, labels, menu items, navigation components, app bars, and buttons should use
|
||||
sentence-style capitalization." Products/branded terms may still be capitalized. **Don't use title case.**
|
||||
- **Use abbreviations sparingly.** Spell out words where possible; avoid Latin abbreviations ("e.g.",
|
||||
"etc.") — use "for example," "and more" instead.
|
||||
|
||||
### Rules — Alt text (see also Accessibility above)
|
||||
- Recommended alt text length: 140 characters (content-design/alt-text); don't start with "image of".
|
||||
|
||||
### Rules — Global writing (content-design/global-writing, /global-writing/word-choice)
|
||||
- Global writing = writing inclusively for many cultures and optimized for localization/translation.
|
||||
- **Use global examples; explain local references** — call out (in a message description for translators)
|
||||
locations, names/nicknames, currencies, temperatures, date formats, and providers (internet/cable) that
|
||||
don't translate globally.
|
||||
- Use short, simple sentences; break into bullets/sections with headings.
|
||||
- Avoid abbreviations; clarify ambiguous pronouns and "this"/"that" references.
|
||||
- Avoid idiomatic, colloquial, or overly polite expressions (translation risk).
|
||||
- Reduce technical jargon; clarify ambiguities.
|
||||
|
||||
### Rules — Notifications (content-design/notifications)
|
||||
- Notifications should: be about the user (not the product); be precise, timely, actionable, contextual,
|
||||
relevant; give easy opt-out controls; never be unsolicited ads.
|
||||
- Put the most important info first (people skim in an F-shape).
|
||||
- CTAs should be concise, specific, actionable.
|
||||
- Make notifications relevant/personal — don't broadcast generically.
|
||||
- **Avoid dynamic text**, especially in headlines (breaks character limits when translated, doesn't
|
||||
expand if truncated). If used, pair with no more than one additional word, and prepare a fallback
|
||||
notification that fits the character budget.
|
||||
- **Don't use relative day words** ("today"/"tomorrow"/"tonight") — about 20% of users don't see a
|
||||
notification the day it's sent; use the specific day of the week instead (exception: auto-dismissing
|
||||
notifications tied to a timestamp).
|
||||
- Use emoji sparingly; never to accentuate bad news (negative emoji tested poorly); don't replace words
|
||||
with emoji.
|
||||
- Don't repeat the app name/logo (already shown by the OS).
|
||||
- Don't interrupt onboarding with unrelated notifications/emails.
|
||||
- Give users in-context, clear opt-in/opt-out controls.
|
||||
|
||||
### Values
|
||||
| Element | Character limit |
|
||||
| --- | --- |
|
||||
| Notification title | < 29 characters |
|
||||
| Notification collapsed body | < 40 characters |
|
||||
| Notification expanded body | < 80 characters (start with the collapsed body and extend it) |
|
||||
| Notification buttons | 1–2 buttons, 1–2 words each |
|
||||
| SMS, Latin-script languages | < 160 characters |
|
||||
| SMS, non-Latin-script languages | < 134 characters |
|
||||
| Alt text | 140 characters recommended (content-design/alt-text) / "up to 125 characters" (foundations/writing) |
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- Not called out on these pages; content-design guidance is presented as version-agnostic.
|
||||
|
||||
### Accessibility requirements
|
||||
- Alt text and captions are the accessibility mechanism this section owns (see Accessibility section for
|
||||
full alt-text rules); captions benefit both sighted and screen-reader users.
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/content-design/overview
|
||||
https://m3.material.io/foundations/content-design/alt-text
|
||||
https://m3.material.io/foundations/content-design/global-writing
|
||||
https://m3.material.io/foundations/content-design/global-writing/word-choice
|
||||
https://m3.material.io/foundations/content-design/notifications
|
||||
https://m3.material.io/foundations/content-design/style-guide
|
||||
|
||||
---
|
||||
|
||||
## Customization (foundations/customization)
|
||||
|
||||
### Principles
|
||||
- "M3 opens up new possibilities for both brand colors and individual color preferences to converge in
|
||||
one-of-a-kind experiences."
|
||||
- Dynamic color lets an app retain brand-defining colors while also honoring a user's device/personal color
|
||||
preference; works for custom (non-Material) components too.
|
||||
|
||||
### Rules
|
||||
- Build a **custom color scheme** with the M3 color system so the app can respect device/app-level dynamic
|
||||
color settings; always keep a fallback (non-dynamic) color scheme for users who don't enable dynamic
|
||||
color.
|
||||
- Apply dynamic color selectively if desired (e.g., only on a profile screen) rather than app-wide.
|
||||
|
||||
### Values
|
||||
- **Five essential color groups / roles**: Primary, Secondary, Tertiary, Neutral, Neutral Variant. An input
|
||||
(source) color generates a tonal palette that fills roles such as primary / on-primary / primary
|
||||
container.
|
||||
- The Material Theme Builder (Figma plugin) generates **color and type tokens**, exportable to multiple
|
||||
code formats, including Design System Package (DSP) format.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- Not explicitly distinguished on this page; dynamic color and the 5-role model are presented as the
|
||||
current (M3) system without an Expressive-specific callout.
|
||||
|
||||
### Accessibility requirements
|
||||
- "The color system automatically handles critical adjustments that provide accessible color contrast,
|
||||
legibility, interaction states, and component structure."
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/customization
|
||||
|
||||
---
|
||||
|
||||
## Design tokens (foundations/design-tokens)
|
||||
|
||||
Note: the task brief anticipated separate `/overview`, `/how-to-read-tokens`, `/how-to-use-tokens`
|
||||
sub-pages; the live site has a **single page** at `foundations/design-tokens` covering all of this content
|
||||
(confirmed via the site's own top-nav, which links only to `foundations/design-tokens`).
|
||||
|
||||
### Principles
|
||||
- "Design tokens are small, reusable design decisions that make up a design system's visual style. Tokens
|
||||
replace static values with self-explanatory names."
|
||||
- A token = a code-like name (e.g. `md.ref.palette.secondary90`) + an associated value (e.g. `#E8DEF8`);
|
||||
the value can be a color, typeface, measurement, or another token.
|
||||
- Tokens let design and code stay in sync: "if a designer's mock-ups and an engineer's implementation both
|
||||
reference the same token... they can be confident that the same [value] is being used in both places,"
|
||||
even after the underlying value changes.
|
||||
- Tokens should be used instead of hardcoded values whenever a design choice recurs across components.
|
||||
|
||||
### Rules
|
||||
- **Do** use design tokens instead of hardcoded values.
|
||||
- Name each token for how/where it's used (e.g. `md.comp.fab.primary.container.color` sets an FAB's
|
||||
container color).
|
||||
- **System tokens should point to reference tokens**, not static values, whenever possible.
|
||||
- **Component tokens should point to a system or reference token**, not hardcoded values, whenever
|
||||
possible.
|
||||
- Tokens are recommended when: building a design system from scratch or updating one broadly, applying a
|
||||
system across a suite of products, wanting to maintain/update styles easily, or wanting dynamic color.
|
||||
Tokens are **less** helpful for an existing app with values unlikely to change and no design system.
|
||||
|
||||
### Values — naming scheme
|
||||
| Part | Meaning | Example |
|
||||
| --- | --- | --- |
|
||||
| System prefix | Always starts with the system name | `md` (Material Design) |
|
||||
| Class | `ref` = reference, `sys` = system, `comp` = component | `md.ref…`, `md.sys…`, `md.comp…` |
|
||||
| Role/descriptor | Descriptive words for the token's purpose | `…palette.secondary90`, `…color.secondary-container`, `…fab.primary.container.color` |
|
||||
|
||||
### Values — the three token classes
|
||||
| Class | Prefix | Definition | Example |
|
||||
| --- | --- | --- | --- |
|
||||
| Reference tokens | `ref` | "All available tokens with associated values." Point to static values (or other reference tokens); don't change based on context. | `md.ref.palette.secondary90` → `#E8DEF8`; `md.ref.typeface.plain-medium` → Roboto Medium |
|
||||
| System tokens | `sys` | "Decisions and roles that give the design system its character" — theming happens here; can point to different ref tokens by context (e.g. light/dark theme). | `md.sys.color.secondary-container` → `md.ref.palette.secondary90`; `md.sys.typescale.label-medium.font` |
|
||||
| Component tokens | `comp` | "(in development)" — the design properties assigned to a specific component's elements (container, label, icon, state, size, shape, color, elevation). | Extended FAB container color / label text tokens |
|
||||
|
||||
- **Contexts**: conditions under which a token points to a non-default value — "device form factors, dark
|
||||
theme, dense layouts, and right-to-left writing systems" are the examples given. A context acts like a
|
||||
tag overriding the default token value.
|
||||
- Glossary cross-references (foundations/glossary): **Design tokens: Role** = "short nickname describing
|
||||
the purpose of a design token... Also known as slots" (e.g. "On surface", "Body 1"); **Design tokens:
|
||||
Value** = "the information defining a design attribute, either stored in a token or hard-coded."
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- Component tokens are explicitly flagged as **"(in development)"** — i.e., not every component's tokens
|
||||
are finalized/complete as of this fetch.
|
||||
|
||||
### Accessibility requirements
|
||||
- Not directly addressed on this page; contexts (e.g. dark theme, dense layout) are the token mechanism
|
||||
used elsewhere to satisfy accessibility/adaptation requirements.
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/design-tokens
|
||||
|
||||
---
|
||||
|
||||
## Interaction: gestures, inputs, selection, states
|
||||
|
||||
### Gestures (foundations/interaction/gestures)
|
||||
|
||||
**Principles**
|
||||
- "Gestures help people navigate, take action, or transform content." UI elements should respond to
|
||||
gestures in real time. Tap, scroll, and swipe are the most common.
|
||||
|
||||
**Types (do/don't-style catalogue, no numeric specs given)**
|
||||
- Tap (navigate/interact), Double tap (zoom in/out), Long press (extra functionality / selection), Scroll
|
||||
and pan, Swipe (switch peer views like tabs, complete actions, or reveal actions on a list item), Drag,
|
||||
Pick up and move (long-press + drag to reorder), Pinch (scale), Compound gestures (e.g. pan + pinch on a
|
||||
map).
|
||||
- **Predictive back** (Android): swipe left/right to preview going back before committing. Compatible
|
||||
components: **bottom sheet, navigation bar, navigation rail, search bar, side sheet**.
|
||||
|
||||
**Source**: https://m3.material.io/foundations/interaction/gestures
|
||||
|
||||
### Inputs (foundations/interaction/inputs)
|
||||
|
||||
**Principles**
|
||||
- "Design for touch, keyboard, and mouse interactions." Embrace multiple input methods within one app.
|
||||
|
||||
**Rules / values**
|
||||
- External input devices: mouse (left/right click, wheel, extra buttons), trackpad (click, gestures,
|
||||
haptics), physical keyboard (replaces virtual keyboard; media keys; modifier keys), stylus.
|
||||
- **Hover**: rest a cursor on an interactive element to trigger its hover state (see States below) and, if
|
||||
applicable, a tooltip.
|
||||
- **Cursor shapes**: Pointer (default), Hand (links/linked images), Resize arrows (resizable element
|
||||
edges), I-beam (editable/selectable text). Text-selection click semantics: single click places cursor /
|
||||
deselects & repositions; double click selects a word; triple click selects a paragraph.
|
||||
- **Physical keyboard**: show/hide the on-screen (virtual) keyboard based on whether a physical keyboard is
|
||||
attached (do hide it when a physical keyboard connects; do show it again when disconnected). Enter
|
||||
typically sends/submits; Spacebar (or media keys) typically play/pause media.
|
||||
|
||||
**Source**: https://m3.material.io/foundations/interaction/inputs
|
||||
|
||||
### Selection (foundations/interaction/selection)
|
||||
|
||||
**Principles**
|
||||
- Selection can be shown via a check icon, a checkbox, or a surface-color change (or a combination).
|
||||
- An entire component, or only certain parts of it, can be selected. Selection can be performed by tap,
|
||||
cursor, keyboard, or voice.
|
||||
|
||||
**Values**
|
||||
- Components that **inherit selection styling**: cards, checkboxes, chips, data tables, icon buttons, list
|
||||
items, menu items, pickers, radio buttons, segmented buttons, sliders, switch.
|
||||
- Components that use an **active indicator** instead (only one selected at a time): navigation bar,
|
||||
navigation drawer, navigation rail, tabs.
|
||||
|
||||
**Rules**
|
||||
- Touch: long-press or two-finger touch (or a shortcut, e.g. tapping an avatar) enters selection mode; tap
|
||||
additional items to add them; tap each selected item (or a toolbar action) to exit selection mode.
|
||||
- Long-press + drag can batch-select — **don't** reuse this gesture combo for selection if it's already
|
||||
used to pick up/move items (e.g. reordering cards).
|
||||
- Desktop/click: when selection is the primary activity, checkboxes stay visible; when secondary, show a
|
||||
checkbox on hover for a single item, and for all items once one is selected.
|
||||
|
||||
**Source**: https://m3.material.io/foundations/interaction/selection
|
||||
|
||||
### States (foundations/interaction/states, /states/state-layers, /states/applying-states)
|
||||
|
||||
**Principles**
|
||||
- "States are visual indicators used to communicate the status of a component or interactive element."
|
||||
- **"States have two visual indicators to ensure accessibility"** — stated as a bullet on the States
|
||||
overview page; the site does **not** elaborate on this rule anywhere in Foundations (no page defines
|
||||
what the two indicators must be, e.g. color + shape/outline). This is a documentation gap to flag when
|
||||
auditing — Foundations only asserts the principle, not the mechanism.
|
||||
- States can combine (e.g. selected + hover); apply states consistently across components.
|
||||
- Six states: **Enabled, Disabled, Hover, Focused, Pressed, Dragged.**
|
||||
|
||||
**State layer mechanics (states/state-layers)**
|
||||
- "A state layer is a semi-transparent covering on an element that indicates its state," providing "a
|
||||
systematic approach to visualizing states by using opacity." Only one state layer can be applied at a
|
||||
given time; it can cover the whole element or a circular sub-region.
|
||||
- The state layer's color equals the **content's "on" color** (e.g. if the container uses **secondary
|
||||
container** and content uses **on secondary container**, the state layer uses **on secondary
|
||||
container**).
|
||||
- **"The size of state layers is 40dp while the interactive target size is 48dp."**
|
||||
|
||||
**Values — state layer / disabled opacities** (from the states/state-layers interactive module, exact
|
||||
figures)
|
||||
| State | Opacity |
|
||||
| --- | --- |
|
||||
| Hover | 0.08 (+8%) |
|
||||
| Focus | 0.10 (+10%) |
|
||||
| Pressed | 0.10 (+10%) |
|
||||
| Dragged | 0.16 (+16%) |
|
||||
| Disabled | 0.38 |
|
||||
|
||||
**Rules — per-state inheritance (applying-states)**
|
||||
| State | Inherited by | NOT inherited by |
|
||||
| --- | --- | --- |
|
||||
| Disabled | Buttons, Cards, Checkboxes, Chips, List items, Radio buttons, Switches, Text fields | App bars, Badges, Dialogs, FABs, Menus, Navigation bar/drawer/rail, Sheets, Tabs, Tooltips |
|
||||
| Hover | Buttons, Cards, Checkbox, Chips, Date/time pickers, List items, Slider, Switch, Text fields | App bars, Badges, Dialogs, Menus, Navigation bar/drawer/rail, Sheets, Tabs |
|
||||
| Focused | Buttons, Cards, Checkbox, Chips, Date/time pickers, List items, Selection controls, Text fields | App bars, Badges, Banner, Card, Dialogs, Navigation bar/drawer/rail, Sheets |
|
||||
| Pressed | Buttons, Cards, Checkbox, Chips, List items, Text fields | App bars, Badges, Bottom navigation, Dialogs, Menus, Sheets, Tabs |
|
||||
| Dragged | Cards, Chips, List items, Sliders | App bars, Badges, Buttons, Dialogs, Menus, Navigation bar/drawer/rail |
|
||||
|
||||
- **Disabled**: communicated via color change + reduced elevation; not focusable, draggable, or pressable;
|
||||
no hover/other state layer; exempt from contrast requirements; "if the action... is unavailable, the FAB
|
||||
shouldn't appear" (don't just disable it) — a Don't example specifically about FABs.
|
||||
- **Hover**: lower-emphasis overlay; appears/disappears with a "low-emphasis animated fade"; only one hover
|
||||
state active in a layout at a time; can combine with focused/activated/selected/pressed.
|
||||
- **Focused / keyboard focus indicator**: "When an element is tabbed to, it appears in its focused state
|
||||
with a ring-like keyboard focus indicator." **No thickness, offset, or color token is specified anywhere
|
||||
in Foundations** — this page only calls it "ring-like." (Exact focus-ring specs, if they exist, live in
|
||||
per-component spec pages outside the Foundations section — flag as out-of-scope-for-this-file / a gap
|
||||
for the audit.) Only one focus state active at a time; initiated by Tab (or equivalent).
|
||||
- **Pressed**: higher-emphasis than hover; a **ripple overlay** signifies press (can also/alternatively use
|
||||
an elevation change); only one pressed state active at a time; initiated by tap/click/keyboard/voice
|
||||
activation.
|
||||
- **Dragged**: lower-emphasis overlay than pressed, "to avoid distracting users from their task"; can also
|
||||
use elevation; only one dragged state active at a time; initiated by touch-and-hold + move.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- Not explicitly called out for interaction/states; the state-layer opacity table and inheritance lists are
|
||||
presented as the current, single spec (this appears to be the M3 Expressive-era rewrite of the classic M2
|
||||
state-layer table, but the site does not itself label old vs. new values here).
|
||||
|
||||
### Accessibility requirements
|
||||
- The "two visual indicators" principle (see above) is the accessibility hook for state changes but is left
|
||||
unelaborated in Foundations.
|
||||
- Disabled components are fully exempted from contrast requirements.
|
||||
- Keyboard operability requirements live in Accessibility → Flow (focus order, keyboard shortcuts) above,
|
||||
and cross-reference into States for the focus indicator.
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/interaction/gestures
|
||||
https://m3.material.io/foundations/interaction/inputs
|
||||
https://m3.material.io/foundations/interaction/selection
|
||||
https://m3.material.io/foundations/interaction/states/overview
|
||||
https://m3.material.io/foundations/interaction/states/state-layers
|
||||
https://m3.material.io/foundations/interaction/states/applying-states
|
||||
|
||||
---
|
||||
|
||||
## Layout (foundations/layout/*)
|
||||
|
||||
Note on the task brief's guessed slugs: the live IA does **not** use `/understanding-layout/*` or
|
||||
`/applying-layout/*`. Real structure discovered via the site's own nav/tab links:
|
||||
- `layout/layout-overview` (tabs: Overview, **Overview: Parts of layout** → `/layout-overview/parts-of-layout`)
|
||||
- `layout/scaffold` (tabs: Overview, Bars, Rails, Panes)
|
||||
- `layout/grids-spacing` (tabs: Overview, Grids, Spacing, Density)
|
||||
- `layout/breakpoints`
|
||||
- `layout/bidirectionality-rtl`
|
||||
- `layout/canonical-examples`
|
||||
|
||||
### Principles
|
||||
- "Layout is the visual and strategic arrangement of elements on a screen," used to organize elements,
|
||||
signal hierarchy, and draw attention to key actions.
|
||||
- Adapt layouts to the five breakpoints; build from an established canonical layout example; design for
|
||||
bidirectionality (LTR + RTL); apply consistent arrangement/sizing/spacing.
|
||||
- Material's components are built with **"leading"/"trailing"** (not left/right) naming so they support RTL
|
||||
by construction — "extra configuration may be needed to achieve specific RTL situations," though.
|
||||
- **May-2026 renames** (explicitly called out on the site as new terminology): **"Window size classes
|
||||
renamed to breakpoints"**; **"Responsive layout renamed to adaptive design."**
|
||||
|
||||
### Values — Layout terms glossary (layout-overview)
|
||||
- **Adaptive design**: techniques letting an interface dynamically respond to user preference, device
|
||||
type, state, and breakpoints.
|
||||
- **Bars**: frame the page (app bar, bottom navigation bar).
|
||||
- **Bidirectionality**: a writing system displaying content RTL.
|
||||
- **Breakpoints**: "opinionated window sizes where a layout changes to match available space, device
|
||||
conventions, and ergonomics (previously window size classes)."
|
||||
- **Column**: one or more vertical blocks of content within a pane.
|
||||
- **Drag handle**: resizes panes.
|
||||
- **Fold**: the flexible/hinge area separating two displays on a foldable.
|
||||
- **Gap**: space between components/elements within a container.
|
||||
- **Margin**: space between the screen edge and elements inside it.
|
||||
- **Multi-window mode**: multiple apps sharing one screen simultaneously.
|
||||
- **Pane**: "a layout container that houses other components and elements within a single app... fixed,
|
||||
flexible, floating, or semi-permanent."
|
||||
- **Rails**: perimeter space around panes holding navigation rails, toolbars, pane controls.
|
||||
- **RTL language**: e.g. Arabic, Hebrew, Farsi — used by "over 2 billion people."
|
||||
- **Rulers**: opinionated global alignment lines.
|
||||
- **Safety region**: zones reserved for system UI (status bar, gesture bar) — "shouldn't contain primary
|
||||
content."
|
||||
- **Scaffold**: "a fundamental UI design structure that provides a standard platform for assembling key
|
||||
screen components."
|
||||
- **Spacer**: space between two panes on a foldable.
|
||||
- **7 parts of layout** (numbered figure caption): Column, Fold, Margin, Bar, Drag handle, Pane, Rail.
|
||||
|
||||
### Values — Breakpoints (layout/breakpoints)
|
||||
| Breakpoint | Width (dp) | Common devices |
|
||||
| --- | --- | --- |
|
||||
| Compact | Under 600dp | Phone in portrait |
|
||||
| Medium | 600–839dp | Tablet in portrait; foldable in portrait (unfolded) |
|
||||
| Expanded | 840–1199dp | Phone/tablet in landscape; foldable in landscape (unfolded); desktop |
|
||||
| Large | 1200–1599dp | Desktop |
|
||||
| Extra-large | 1600dp+ | Desktop; ultra-wide monitors |
|
||||
|
||||
- Height breakpoints (compact/medium/expanded) also exist on Android but are rarely needed since most
|
||||
layouts scroll vertically.
|
||||
|
||||
**Breakpoint → recommended panes / navigation / communication / action** (layout/breakpoints)
|
||||
| Breakpoint | Panes | Navigation | Communication | Action |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Compact | 1 | Navigation bar, modal expanded navigation rail | Simple dialog, full-screen dialog | Bottom sheet |
|
||||
| Medium | 1 (recommended) or 2 | Navigation bar, modal expanded navigation rail | Simple dialog | Menu |
|
||||
| Expanded | 1 or 2 (recommended) | Modal or standard expanded navigation rail | Simple dialog | Menu |
|
||||
| Large | 1 or 2 (recommended) | Modal or standard expanded navigation rail | Simple dialog | Menu |
|
||||
| Extra-large | 1 to 3 (recommended) | Modal or standard expanded navigation rail | Simple dialog | Menu |
|
||||
|
||||
**Common swappable components by breakpoint** (layout/breakpoints)
|
||||
| Component type | Compact | Medium | Expanded |
|
||||
| --- | --- | --- | --- |
|
||||
| Navigation | Navigation bar | Collapsed navigation rail | Collapsed navigation rail |
|
||||
| Navigation (secondary row) | Modal expanded navigation rail | Modal expanded navigation rail | Standard expanded navigation rail |
|
||||
| Communication | Basic or full-screen dialog | Basic dialog | Basic dialog |
|
||||
| Supplemental selection | Bottom sheet | Menu | Menu |
|
||||
|
||||
- Pane-count guidance restated: **compact/medium → 1 pane; expanded/large → 2 panes recommended;
|
||||
extra-large → consider 3 panes.**
|
||||
- Five questions to ask moving up a breakpoint: what should be **revealed, divided (paned), resized,
|
||||
repositioned, swapped**. Across breakpoints, keep text to **40–60 characters per line**.
|
||||
- Component-swap example: compact navigation bar → medium/expanded navigation rail; collapsed rail
|
||||
(medium/expanded) → expanded rail (large/extra-large). **Don't** swap functionally non-equivalent
|
||||
components (e.g. a button for a menu).
|
||||
|
||||
### Values — Scaffold (layout/scaffold, /bars, /rails, /panes)
|
||||
- Scaffold = **Bars + Rails + Panes**, arranged around a **safety region** that must stay clear of primary
|
||||
content.
|
||||
- **Bars**: frame the page; contain app bar (top) or navigation bar (bottom). App bars: title + 1–2
|
||||
essential actions (search, back). "**Navigation bars let people switch between 3–5 primary UI views**"
|
||||
at compact/medium breakpoints.
|
||||
- **Rails**: the perimeter layer after bars; hold navigation rails, toolbars, chat inputs, FABs, other
|
||||
primary controls; on desktop, a leading/trailing rail; on mobile, a toolbar can float in the rail region.
|
||||
- **Panes**: all content must live in a pane; a layout has **1–3 panes**, adapting to breakpoint and
|
||||
language direction (RTL flips navigation to the right).
|
||||
- **Single-pane** layouts: any breakpoint, recommended at compact/medium.
|
||||
- **Two-pane** layouts: common at expanded/large/extra-large; fixed-and-flexible panes can appear in
|
||||
either order.
|
||||
- **Three-pane** layouts: "Fixed panes at this breakpoint are recommended to be **412dp**, but side
|
||||
sheets have a default maximum width of **400dp**."
|
||||
- **Snap widths** when resizing a two-pane layout at expanded/large/extra-large: **360dp**, **412dp**, or
|
||||
a centered split-pane with spacer.
|
||||
- **Persistent resizing** (remembers width across sessions/breakpoint changes) is the default
|
||||
recommendation for most resizable layouts; **temporary resizing** (reverts to default on
|
||||
close/reopen) is for supporting-pane layouts where resizing is uncommon.
|
||||
- Multi-pane display styles: **co-planar** (side by side — used for persistent utilities so they stay
|
||||
accessible), **floating**, **docked**.
|
||||
- **Accessibility**: coplanar-pane focus order must match visual arrangement; modal floating panes trap
|
||||
focus (move focus in on open, return it to the trigger on close) and close on outside interaction;
|
||||
non-modal floating panes let focus move freely in/out and must sit in logical reading order; docked
|
||||
panes follow the same focus rules as floating panes, plus the coplanar focus-order requirement.
|
||||
|
||||
### Values — Grids & spacing (layout/grids-spacing, /grids, /spacing, /density)
|
||||
- Grids: column count/width/spacing scale with breakpoint (compact fewer columns → expanded/foldable more
|
||||
columns); **no explicit numeric column-count or gutter table is given on the current site** (this is a
|
||||
gap versus the classic M2 12-column grid spec — flag if the component library assumes fixed column
|
||||
counts).
|
||||
- **Rulers**: Bar & safety rulers (reserve system-UI space), Title ruler (aligns app-bar title), Content
|
||||
rulers (first ruler = major blocks like hero/headline; secondary rulers = supplementary text/actions).
|
||||
Margin rulers can be widened/narrowed for expressive effect (e.g., full-bleed photo grid vs. a
|
||||
wide-margin search bar).
|
||||
- Spacing is used to **group** (explicit grouping = outlines/dividers/shadows; implicit grouping =
|
||||
proximity/whitespace only), to **direct attention** (rhythm, similarity, proximity, continuity), and as
|
||||
**expression** (generous spacing + bright surfaces on the most important content; negative space for
|
||||
emphasis). No fixed numeric spacing scale (e.g. 4/8/16dp increments) is stated on this page beyond the
|
||||
8dp target-spacing rule already listed under Accessibility.
|
||||
- **Density** (component scaling):
|
||||
- Density scale is numbered starting at **0** (default) and moves negative (**-1, -2, -3**) as space
|
||||
decreases.
|
||||
- "Higher density is typically applied by decreasing the top and bottom padding or overall height by
|
||||
**4dp**" per step.
|
||||
- Text size should not change as a container scales with density.
|
||||
- Example figures from the page: 20dp gap between a text field's label and input; a "don't" example shows
|
||||
a dropdown item shrunk to 38dp of selectable height (too dense — reduces usability).
|
||||
- **Density must be opt-in, never default**: "People should be able to **opt in** to dense layouts and
|
||||
components." Settings interactions themselves must keep default target sizes (**48×48 CSS pixels**).
|
||||
"Don't scale layouts below 48×48dp by default."
|
||||
- **Interaction targets must stay ≥48×48dp even when the visible element is scaled down** — e.g. a
|
||||
settings icon can be 24×24dp visually but must keep a 48×48dp target; a 36dp-tall button can keep a
|
||||
48dp target.
|
||||
- Don't increase density in focused/high-stakes UI (menus, snackbars, dialogs).
|
||||
- Pixel density formula: `pixel density = screen width (or height) in px / screen width (or height) in
|
||||
inches`.
|
||||
- **Density-independent pixel (dp)**: "A dp is equal to one physical pixel on a screen with a density of
|
||||
160." Formula: `dp = (width in pixels × 160) / screen density`.
|
||||
|
||||
### Values — Bidirectionality / RTL (layout/bidirectionality-rtl)
|
||||
- Over 2 billion people read/write RTL languages (Arabic, Hebrew, Farsi, Urdu).
|
||||
- **Mirroring**: LTR ⇄ RTL flips element alignment/order; reading starts top-right in RTL. **Exception**:
|
||||
graphs/charts stay LTR even in Persian and Urdu.
|
||||
- **Text rendering** has two parts: alignment (box placement) and directionality (text/element flow).
|
||||
Common RTL bugs: text entry, cursor position, punctuation, phone numbers, URLs. **Don't** reverse an
|
||||
email's username/domain order (domain always stays to the right of the username, even though the
|
||||
username itself can render RTL). **Don't** apply LTR directionality to RTL content (scrambles word
|
||||
order) — content needs both RTL alignment *and* RTL directionality.
|
||||
- **Icons**: directional icons (back/forward, send) mirror in RTL. **Exception**: in Hebrew, timelines and
|
||||
media controls keep LTR directionality; help icons mirror only in some RTL languages (e.g. Urdu,
|
||||
Persian).
|
||||
- **Time / progress**: linear progress indicators fill right-to-left in most RTL languages, **except
|
||||
Hebrew, which stays LTR**. Circular progress indicators always move clockwise regardless of direction.
|
||||
Media player controls (video/audio) are **always LTR**. Clocks always turn clockwise; on a 12-hour clock
|
||||
in RTL, the AM/PM symbol moves to the left; the 24-hour clock is common outside English-primary
|
||||
locales.
|
||||
- **Canonical layouts in RTL**: list-detail, feed, and supporting-pane layouts are all explicitly "mirrored
|
||||
in RTL."
|
||||
- **Component specifics**: badges reposition; toolbars mirror tool order; app bars mirror layout and flip
|
||||
directional icons; **navigation rail sits on the leading edge — right side in RTL, left in LTR**
|
||||
(expanded nav rail too); text field leading/trailing icons swap sides; a chip's trailing icon "is always
|
||||
aligned to the end side of the container" (right for LTR, left for RTL).
|
||||
- **Gestures**: swipe-to-reveal actions and Android predictive back must mirror their LTR counterparts
|
||||
(e.g. a delete action revealed by a right-swipe in LTR should be revealed by a left-swipe in RTL).
|
||||
|
||||
### Values — Canonical layout examples (layout/canonical-examples)
|
||||
- Named canonical layouts referenced: **feed**, **list-detail**, **supporting-pane** (each links out to a
|
||||
dedicated `m3.material.io/m3/pages/canonical-examples/...` page — a legacy/alternate URL namespace not
|
||||
fetched here since it falls outside `foundations/*`). An "Advanced custom layouts" section exists on the
|
||||
page but only points onward, with no further numeric content on this page itself.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- The May-2026 rename ("window size class" → "breakpoint"; "responsive layout" → "adaptive design") is the
|
||||
only explicit terminology-version marker found in Layout.
|
||||
- Density (opt-in component scaling) and the layout scaffold (bars/rails/panes model) are presented as the
|
||||
current single system, introduced/updated as part of the same May-2026 refresh per layout-overview's
|
||||
"What's new" log ("Introduced layout scaffold... Updated canonical layout examples... Spacing system").
|
||||
|
||||
### Accessibility requirements
|
||||
- Safety regions must stay clear of primary content (keeps content from being obscured by system UI).
|
||||
- Pane focus-order/trap rules above (coplanar order must match visual order; modal panes trap and restore
|
||||
focus).
|
||||
- RTL is treated as an accessibility/global-reach requirement throughout, not an optional locale nicety.
|
||||
- Minimum 48×48dp interaction targets carry through from Accessibility into density/scaling rules here.
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/layout/layout-overview
|
||||
https://m3.material.io/foundations/layout/layout-overview/parts-of-layout
|
||||
https://m3.material.io/foundations/layout/scaffold/overview
|
||||
https://m3.material.io/foundations/layout/scaffold/bars
|
||||
https://m3.material.io/foundations/layout/scaffold/rails
|
||||
https://m3.material.io/foundations/layout/scaffold/panes
|
||||
https://m3.material.io/foundations/layout/grids-spacing/overview
|
||||
https://m3.material.io/foundations/layout/grids-spacing/grids
|
||||
https://m3.material.io/foundations/layout/grids-spacing/spacing
|
||||
https://m3.material.io/foundations/layout/grids-spacing/density
|
||||
https://m3.material.io/foundations/layout/breakpoints
|
||||
https://m3.material.io/foundations/layout/bidirectionality-rtl
|
||||
https://m3.material.io/foundations/layout/canonical-examples
|
||||
|
||||
---
|
||||
|
||||
## Usability (foundations/usability)
|
||||
|
||||
### Principles
|
||||
- "Usability focuses on making products intuitive and easy to understand for everyone" — distinct from
|
||||
Accessibility (see Accessibility section for the exact wording of the distinction).
|
||||
- Key takeaways: emphasize key actions for visual hierarchy; leverage M3 Expressive design tactics; don't
|
||||
overwhelm users with visual information; test and iterate.
|
||||
|
||||
### Values — Nielsen Norman Group's five usability aspects (quoted directly)
|
||||
| Aspect | Definition |
|
||||
| --- | --- |
|
||||
| Efficiency | Users can efficiently complete tasks and goals |
|
||||
| Errors | Proper design reduces the likelihood of mistakes, and users can easily correct any errors that do occur |
|
||||
| Learnability | New users learn to use the product and complete tasks easily, even the first time |
|
||||
| Memorability | Returning users remember how to use the product |
|
||||
| Satisfaction | Users are satisfied with the designed experience |
|
||||
|
||||
### Rules — Usability design tactics (explicitly framed as **M3 Expressive** tactics)
|
||||
- **Color & contrast**: use eye-catching primary/secondary colors and contrasting pairs (e.g. purple +
|
||||
green) for hierarchy; always follow the accessibility contrast rules above.
|
||||
- **Containment & grouping**: group related elements in subtle containers; break content into sections with
|
||||
containment/spacing/headings.
|
||||
- **Motion**: use sparingly to emphasize key moments — "motion can be distracting" if overused.
|
||||
- **Shape & shape morph**: "The Material shape library has **35 shapes**." Shape adds emphasis/delight,
|
||||
guides focus, differentiates containers/buttons/animations, signals interaction, sets emotional tone.
|
||||
Every shape can morph into any other in the set; shape morph communicates interaction states (selected,
|
||||
tap, swipe, scroll, release, long press) and emphasizes in-progress actions.
|
||||
- **Size**: the most important action/CTA should be the largest element; larger key actions measurably
|
||||
improve efficiency, error rate, satisfaction, learnability (per the doc's own claim, no citation given).
|
||||
- **Typography**: use type scale/weight to separate information hierarchies (largest/most legible text =
|
||||
primary action; smaller text = secondary/tertiary); group similar content with the same font style.
|
||||
- Design around **primary / secondary / tertiary goals**: give primary goals the strongest emphasis;
|
||||
simplify to one primary task per page; make core actions large/reachable; don't stack too many expressive
|
||||
tactics at once (distracting).
|
||||
- **Iterate**: test and gather feedback early/often from a range of users/contexts.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
- This entire page's "design tactics" section is explicitly attributed to **M3 Expressive** ("Leverage
|
||||
[expressive design tactics]... containment, size, shape, color, and typography"), including the 35-shape
|
||||
library and shape-morph mechanic, which are Expressive-era additions.
|
||||
|
||||
### Accessibility requirements
|
||||
- "Accessibility focuses on making products accessible for people with disabilities... perceivable,
|
||||
operable, understandable and robust... support people who use assistive technology" (contrasted directly
|
||||
with usability's broader "intuitive for everyone" framing).
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/usability
|
||||
|
||||
---
|
||||
|
||||
## Glossary terms that matter for a web component library (foundations/glossary)
|
||||
|
||||
Only terms relevant to auditing a component library are excerpted; the full glossary runs A–Z (~20KB) and
|
||||
also defines many component names already covered under Components (out of scope here). Quoted verbatim.
|
||||
|
||||
| Term | Definition (verbatim) |
|
||||
| --- | --- |
|
||||
| Adaptive design | "A design approach in which the interface changes based on known user, device, or environmental conditions. Adaptive design in Material includes layout and component adaptations." |
|
||||
| Condition | "A signal that determines when and how an adaptive layout or component should adapt." |
|
||||
| Contrast | "Difference between colors. For accessibility, contrast refers strictly to the difference in tone. **A difference of 40 in tone guarantees a WCAG contrast ratio ≥ 3.0; a difference of 50 in tone guarantees a contrast ratio ≥ 4.5.**" |
|
||||
| Customization | "A modification made to a UI reflecting an app, OEM, or individual user's visual preferences and brand." Can be per-element or global (a theme). |
|
||||
| Dark theme | "A dark theme is a low-light UI that displays mostly dark surfaces." |
|
||||
| Design tokens | "A design token represents a small, reusable design decision that's part of a design system's visual style. Tokens replace static values with self-explanatory names." |
|
||||
| Design tokens: Context | "The set of conditions in which tokens can point to non-default values (for example, dark theme, dense layout)." |
|
||||
| Design tokens: Role | "A shortened version of the system token name (for example, Secondary container color; Headline 1)." |
|
||||
| Design tokens: Types | Reference tokens (e.g. `md.ref.palette.secondary200`); Component tokens (define a component element's design attributes); System tokens (e.g. `md.sys.color.secondary-container`) |
|
||||
| Design tokens: Value | "The information defining a design attribute, either stored in a token or hard-coded." |
|
||||
| Element | (page continues past excerpt boundary — not fully captured; component name only) |
|
||||
| HCT | "HCT is an abbreviation of hue, chroma, tone. It's the name of the color space that enables dynamic color. HCT is based on CAM16 hue and chroma; the L* construct for luminance from L*a*b* (CIELAB, 1976) is denoted as T for tone." |
|
||||
| Mode | (component/theming term; not fully excerpted) |
|
||||
| Orbiter | "Floating UI elements that control the content within spatial panels." (XR-adjacent; likely out of scope) |
|
||||
| Pane | "The building blocks of a layout. Content and actions are grouped into panes, which adapt the content to best fit the screen." |
|
||||
| Role | "Short nickname describing the purpose of a design token within a design system. Also known as slots. Examples: On surface; Body 1." |
|
||||
| Spatial | (XR-adjacent term; out of scope per task instructions) |
|
||||
| Style | (design-spec term; not fully excerpted) |
|
||||
| Theme | (not fully excerpted — see "Note: A light scheme is not the same as a light theme" under Color: Scheme) |
|
||||
|
||||
### Color-system glossary terms (used throughout Customization/Design tokens)
|
||||
| Term | Definition (verbatim) |
|
||||
| --- | --- |
|
||||
| Color: Baseline scheme | "the group of selected tones that make up the default colors values used for light and dark themes." |
|
||||
| Color: Dynamic color | "A customization feature in which a user-generated color scheme is mapped to an app's color scheme." Not simply Theme-Builder output or an algorithmic scheme — it's the *presence of a changeable color role*. |
|
||||
| Color: Extended color | "A color specified (in addition to key colors) in order to fill color roles for custom schemes... brand expression or conventional (semantic) meanings." |
|
||||
| Color: Key color | "not an extracted color — it's a derivation of the source color... the basis for a tonal palette." |
|
||||
| Color: Scheme | "Any mapping of color roles to specific tones from a tonal palette." A **dark scheme** ≠ a **dark theme** (scheme vs. theme distinction explicitly noted). |
|
||||
| Color: Source color | "The single color that's extracted to define all five key colors." |
|
||||
| Color: Tonal palette | "a 13-tone range that serves as the basis for mapping tones to specific roles." |
|
||||
| Color: Tone | "colors with the same hue and chroma... degrees of lightness." Code: `Tone.of(hex).get(tone)` or `Tone.of(hue, chroma).get(tone)`. |
|
||||
| Color: User-generated schemes | colors derived from a user's wallpaper selection or Android preset colors. |
|
||||
|
||||
### Source URLs
|
||||
https://m3.material.io/foundations/glossary
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting gaps found (for the auditing agents to be aware of)
|
||||
|
||||
1. **Focus indicator specifics** (thickness / offset / color token) are **not defined anywhere in
|
||||
Foundations** — only "ring-like keyboard focus indicator" is stated (states/applying-states). If the
|
||||
component library asserts a specific focus-ring spec, that spec's source is not this section of the
|
||||
site.
|
||||
2. **The "two visual indicators" accessibility rule for states** is asserted once, as a bullet, with zero
|
||||
elaboration anywhere in Foundations on what the two indicators must be.
|
||||
3. **Alt text length is inconsistent across the site itself**: 125 characters (foundations/writing) vs. 140
|
||||
characters (foundations/content-design/alt-text).
|
||||
4. **No explicit numeric grid/column/gutter table** exists on the current (M3 Expressive-era) Layout pages,
|
||||
unlike the classic Material 2 12-column-grid spec; grids/spacing guidance here is qualitative except for
|
||||
the 8dp target-spacing and pane-width (360/400/412dp) numbers captured above.
|
||||
5. **Component tokens are explicitly flagged "(in development)"** on the design-tokens page — treat
|
||||
component-token completeness claims cautiously.
|
||||
6. Two task-provided sub-page slugs did not exist as separate URLs: `design-tokens/overview`,
|
||||
`/how-to-read-tokens`, `/how-to-use-tokens` all collapse into the single `foundations/design-tokens`
|
||||
page; `layout/understanding-layout/*` and `layout/applying-layout/*` do not exist — the real nesting is
|
||||
`layout/layout-overview/parts-of-layout`, `layout/scaffold/{bars,rails,panes}`, and
|
||||
`layout/grids-spacing/{grids,spacing,density}` (all fetched and covered above).
|
||||
@@ -0,0 +1,238 @@
|
||||
https://m3.material.io/components
|
||||
https://m3.material.io/components/all-buttons
|
||||
https://m3.material.io/components/app-bars/accessibility
|
||||
https://m3.material.io/components/app-bars/guidelines
|
||||
https://m3.material.io/components/app-bars/overview
|
||||
https://m3.material.io/components/app-bars/specs
|
||||
https://m3.material.io/components/badges/accessibility
|
||||
https://m3.material.io/components/badges/guidelines
|
||||
https://m3.material.io/components/badges/overview
|
||||
https://m3.material.io/components/badges/specs
|
||||
https://m3.material.io/components/bottom-sheets/accessibility
|
||||
https://m3.material.io/components/bottom-sheets/guidelines
|
||||
https://m3.material.io/components/bottom-sheets/overview
|
||||
https://m3.material.io/components/bottom-sheets/specs
|
||||
https://m3.material.io/components/button-groups/accessibility
|
||||
https://m3.material.io/components/button-groups/guidelines
|
||||
https://m3.material.io/components/button-groups/overview
|
||||
https://m3.material.io/components/button-groups/specs
|
||||
https://m3.material.io/components/buttons/accessibility
|
||||
https://m3.material.io/components/buttons/guidelines
|
||||
https://m3.material.io/components/buttons/overview
|
||||
https://m3.material.io/components/buttons/specs
|
||||
https://m3.material.io/components/cards/accessibility
|
||||
https://m3.material.io/components/cards/guidelines
|
||||
https://m3.material.io/components/cards/overview
|
||||
https://m3.material.io/components/cards/specs
|
||||
https://m3.material.io/components/carousel/accessibility
|
||||
https://m3.material.io/components/carousel/guidelines
|
||||
https://m3.material.io/components/carousel/overview
|
||||
https://m3.material.io/components/carousel/specs
|
||||
https://m3.material.io/components/checkbox/accessibility
|
||||
https://m3.material.io/components/checkbox/guidelines
|
||||
https://m3.material.io/components/checkbox/overview
|
||||
https://m3.material.io/components/checkbox/specs
|
||||
https://m3.material.io/components/chips/accessibility
|
||||
https://m3.material.io/components/chips/guidelines
|
||||
https://m3.material.io/components/chips/overview
|
||||
https://m3.material.io/components/chips/specs
|
||||
https://m3.material.io/components/date-pickers/accessibility
|
||||
https://m3.material.io/components/date-pickers/guidelines
|
||||
https://m3.material.io/components/date-pickers/overview
|
||||
https://m3.material.io/components/date-pickers/specs
|
||||
https://m3.material.io/components/dialogs/accessibility
|
||||
https://m3.material.io/components/dialogs/guidelines
|
||||
https://m3.material.io/components/dialogs/overview
|
||||
https://m3.material.io/components/dialogs/specs
|
||||
https://m3.material.io/components/divider/accessibility
|
||||
https://m3.material.io/components/divider/guidelines
|
||||
https://m3.material.io/components/divider/overview
|
||||
https://m3.material.io/components/divider/specs
|
||||
https://m3.material.io/components/extended-fab/accessibility
|
||||
https://m3.material.io/components/extended-fab/guidelines
|
||||
https://m3.material.io/components/extended-fab/overview
|
||||
https://m3.material.io/components/extended-fab/specs
|
||||
https://m3.material.io/components/fab-menu/accessibility
|
||||
https://m3.material.io/components/fab-menu/guidelines
|
||||
https://m3.material.io/components/fab-menu/overview
|
||||
https://m3.material.io/components/fab-menu/specs
|
||||
https://m3.material.io/components/floating-action-button/accessibility
|
||||
https://m3.material.io/components/floating-action-button/guidelines
|
||||
https://m3.material.io/components/floating-action-button/overview
|
||||
https://m3.material.io/components/floating-action-button/specs
|
||||
https://m3.material.io/components/icon-buttons/accessibility
|
||||
https://m3.material.io/components/icon-buttons/guidelines
|
||||
https://m3.material.io/components/icon-buttons/overview
|
||||
https://m3.material.io/components/icon-buttons/specs
|
||||
https://m3.material.io/components/lists/accessibility
|
||||
https://m3.material.io/components/lists/guidelines
|
||||
https://m3.material.io/components/lists/overview
|
||||
https://m3.material.io/components/lists/specs
|
||||
https://m3.material.io/components/loading-indicator/accessibility
|
||||
https://m3.material.io/components/loading-indicator/guidelines
|
||||
https://m3.material.io/components/loading-indicator/overview
|
||||
https://m3.material.io/components/loading-indicator/specs
|
||||
https://m3.material.io/components/menus/accessibility
|
||||
https://m3.material.io/components/menus/guidelines
|
||||
https://m3.material.io/components/menus/overview
|
||||
https://m3.material.io/components/menus/specs
|
||||
https://m3.material.io/components/navigation-bar/accessibility
|
||||
https://m3.material.io/components/navigation-bar/guidelines
|
||||
https://m3.material.io/components/navigation-bar/overview
|
||||
https://m3.material.io/components/navigation-bar/specs
|
||||
https://m3.material.io/components/navigation-drawer/accessibility
|
||||
https://m3.material.io/components/navigation-drawer/guidelines
|
||||
https://m3.material.io/components/navigation-drawer/overview
|
||||
https://m3.material.io/components/navigation-drawer/specs
|
||||
https://m3.material.io/components/navigation-rail/accessibility
|
||||
https://m3.material.io/components/navigation-rail/guidelines
|
||||
https://m3.material.io/components/navigation-rail/overview
|
||||
https://m3.material.io/components/navigation-rail/specs
|
||||
https://m3.material.io/components/progress-indicators/accessibility
|
||||
https://m3.material.io/components/progress-indicators/guidelines
|
||||
https://m3.material.io/components/progress-indicators/overview
|
||||
https://m3.material.io/components/progress-indicators/specs
|
||||
https://m3.material.io/components/radio-button/accessibility
|
||||
https://m3.material.io/components/radio-button/guidelines
|
||||
https://m3.material.io/components/radio-button/overview
|
||||
https://m3.material.io/components/radio-button/specs
|
||||
https://m3.material.io/components/search/accessibility
|
||||
https://m3.material.io/components/search/guidelines
|
||||
https://m3.material.io/components/search/overview
|
||||
https://m3.material.io/components/search/specs
|
||||
https://m3.material.io/components/segmented-buttons/accessibility
|
||||
https://m3.material.io/components/segmented-buttons/guidelines
|
||||
https://m3.material.io/components/segmented-buttons/overview
|
||||
https://m3.material.io/components/segmented-buttons/specs
|
||||
https://m3.material.io/components/side-sheets/accessibility
|
||||
https://m3.material.io/components/side-sheets/guidelines
|
||||
https://m3.material.io/components/side-sheets/overview
|
||||
https://m3.material.io/components/side-sheets/specs
|
||||
https://m3.material.io/components/sliders/accessibility
|
||||
https://m3.material.io/components/sliders/guidelines
|
||||
https://m3.material.io/components/sliders/overview
|
||||
https://m3.material.io/components/sliders/specs
|
||||
https://m3.material.io/components/snackbar/accessibility
|
||||
https://m3.material.io/components/snackbar/guidelines
|
||||
https://m3.material.io/components/snackbar/overview
|
||||
https://m3.material.io/components/snackbar/specs
|
||||
https://m3.material.io/components/split-button/accessibility
|
||||
https://m3.material.io/components/split-button/guidelines
|
||||
https://m3.material.io/components/split-button/overview
|
||||
https://m3.material.io/components/split-button/specs
|
||||
https://m3.material.io/components/switch/accessibility
|
||||
https://m3.material.io/components/switch/guidelines
|
||||
https://m3.material.io/components/switch/overview
|
||||
https://m3.material.io/components/switch/specs
|
||||
https://m3.material.io/components/tabs/accessibility
|
||||
https://m3.material.io/components/tabs/guidelines
|
||||
https://m3.material.io/components/tabs/overview
|
||||
https://m3.material.io/components/tabs/specs
|
||||
https://m3.material.io/components/text-fields/accessibility
|
||||
https://m3.material.io/components/text-fields/guidelines
|
||||
https://m3.material.io/components/text-fields/overview
|
||||
https://m3.material.io/components/text-fields/specs
|
||||
https://m3.material.io/components/time-pickers/accessibility
|
||||
https://m3.material.io/components/time-pickers/guidelines
|
||||
https://m3.material.io/components/time-pickers/overview
|
||||
https://m3.material.io/components/time-pickers/specs
|
||||
https://m3.material.io/components/toolbars/accessibility
|
||||
https://m3.material.io/components/toolbars/guidelines
|
||||
https://m3.material.io/components/toolbars/overview
|
||||
https://m3.material.io/components/toolbars/specs
|
||||
https://m3.material.io/components/tooltips/accessibility
|
||||
https://m3.material.io/components/tooltips/guidelines
|
||||
https://m3.material.io/components/tooltips/overview
|
||||
https://m3.material.io/components/tooltips/specs
|
||||
https://m3.material.io/foundations
|
||||
https://m3.material.io/foundations/building-for-all/co-design
|
||||
https://m3.material.io/foundations/building-for-all/user-needs
|
||||
https://m3.material.io/foundations/content-design/alt-text
|
||||
https://m3.material.io/foundations/content-design/global-writing/overview
|
||||
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/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
|
||||
https://m3.material.io/foundations/customization
|
||||
https://m3.material.io/foundations/design-tokens/how-to-use-tokens
|
||||
https://m3.material.io/foundations/design-tokens/overview
|
||||
https://m3.material.io/foundations/designing/color-contrast
|
||||
https://m3.material.io/foundations/designing/elements
|
||||
https://m3.material.io/foundations/designing/flow
|
||||
https://m3.material.io/foundations/designing/overview
|
||||
https://m3.material.io/foundations/designing/structure
|
||||
https://m3.material.io/foundations/glossary
|
||||
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/applying-states
|
||||
https://m3.material.io/foundations/interaction/states/overview
|
||||
https://m3.material.io/foundations/interaction/states/state-layers
|
||||
https://m3.material.io/foundations/layout/bidirectionality-rtl
|
||||
https://m3.material.io/foundations/layout/breakpoints/compact
|
||||
https://m3.material.io/foundations/layout/breakpoints/expanded
|
||||
https://m3.material.io/foundations/layout/breakpoints/large-extra-large
|
||||
https://m3.material.io/foundations/layout/breakpoints/medium
|
||||
https://m3.material.io/foundations/layout/breakpoints/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/overview
|
||||
https://m3.material.io/foundations/layout/canonical-examples/supporting-pane
|
||||
https://m3.material.io/foundations/layout/grids-spacing/density
|
||||
https://m3.material.io/foundations/layout/grids-spacing/grids
|
||||
https://m3.material.io/foundations/layout/grids-spacing/overview
|
||||
https://m3.material.io/foundations/layout/grids-spacing/spacing
|
||||
https://m3.material.io/foundations/layout/layout-overview/adaptive-design
|
||||
https://m3.material.io/foundations/layout/layout-overview/overview
|
||||
https://m3.material.io/foundations/layout/layout-overview/parts-of-layout
|
||||
https://m3.material.io/foundations/layout/scaffold/bars
|
||||
https://m3.material.io/foundations/layout/scaffold/overview
|
||||
https://m3.material.io/foundations/layout/scaffold/panes
|
||||
https://m3.material.io/foundations/layout/scaffold/rails
|
||||
https://m3.material.io/foundations/overview/assistive-technology
|
||||
https://m3.material.io/foundations/overview/principles
|
||||
https://m3.material.io/foundations/usability/applying-m3-expressive
|
||||
https://m3.material.io/foundations/usability/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
|
||||
https://m3.material.io/styles
|
||||
https://m3.material.io/styles/color/advanced/adjust-existing-colors
|
||||
https://m3.material.io/styles/color/advanced/apply-colors
|
||||
https://m3.material.io/styles/color/advanced/define-new-colors
|
||||
https://m3.material.io/styles/color/advanced/overview
|
||||
https://m3.material.io/styles/color/choosing-a-scheme
|
||||
https://m3.material.io/styles/color/dynamic/choosing-a-source
|
||||
https://m3.material.io/styles/color/dynamic/content-based-source
|
||||
https://m3.material.io/styles/color/dynamic/user-generated-source
|
||||
https://m3.material.io/styles/color/resources
|
||||
https://m3.material.io/styles/color/roles
|
||||
https://m3.material.io/styles/color/static/baseline
|
||||
https://m3.material.io/styles/color/static/custom-brand
|
||||
https://m3.material.io/styles/color/system/how-the-system-works
|
||||
https://m3.material.io/styles/color/system/overview
|
||||
https://m3.material.io/styles/elevation/applying-elevation
|
||||
https://m3.material.io/styles/elevation/overview
|
||||
https://m3.material.io/styles/elevation/tokens
|
||||
https://m3.material.io/styles/icons/applying-icons
|
||||
https://m3.material.io/styles/icons/designing-icons
|
||||
https://m3.material.io/styles/icons/overview
|
||||
https://m3.material.io/styles/motion/easing-and-duration/applying-easing-and-duration
|
||||
https://m3.material.io/styles/motion/easing-and-duration/tokens-specs
|
||||
https://m3.material.io/styles/motion/overview/how-it-works
|
||||
https://m3.material.io/styles/motion/overview/specs
|
||||
https://m3.material.io/styles/motion/transitions/applying-transitions
|
||||
https://m3.material.io/styles/motion/transitions/transition-patterns
|
||||
https://m3.material.io/styles/shape/corner-radius-scale
|
||||
https://m3.material.io/styles/shape/overview-principles
|
||||
https://m3.material.io/styles/shape/shape-morph
|
||||
https://m3.material.io/styles/spacing/applying-spacing
|
||||
https://m3.material.io/styles/spacing/overview
|
||||
https://m3.material.io/styles/spacing/tokens
|
||||
https://m3.material.io/styles/typography/applying-type
|
||||
https://m3.material.io/styles/typography/editorial-treatments
|
||||
https://m3.material.io/styles/typography/fonts
|
||||
https://m3.material.io/styles/typography/overview
|
||||
https://m3.material.io/styles/typography/type-scale-tokens
|
||||
@@ -0,0 +1,318 @@
|
||||
# Material Design 3 — Styles Supplement (Spacing; Color additions; Motion transition patterns)
|
||||
|
||||
Extraction from sitemap pages `reference-styles.md` did not cover (fetched directly, not via in-site
|
||||
navigation). Same structure as the reference. Only material **not** already in `reference-styles.md` is
|
||||
included; where a fetched page turned out to be a duplicate of an already-covered page, that is noted
|
||||
instead of repeating it.
|
||||
|
||||
**Duplicate pages found (no new content beyond what's already in the reference):**
|
||||
- `styles/color/system/overview` — byte-identical to `styles/color/system` (already in the reference's
|
||||
Color section / Source URLs), *except* it also carries a Resources table not previously captured — see
|
||||
Color § Values below.
|
||||
- `styles/color/advanced/overview` — byte-identical to `styles/color/advanced` (already in the reference's
|
||||
Color § Source URLs; its linked sub-pages apply-colors/define-new-colors/adjust-existing-colors are
|
||||
already the basis of the reference's "Advanced customization best practices" rules).
|
||||
- `styles/color/dynamic/choosing-a-source` — byte-identical to `styles/color/dynamic` (already in the
|
||||
reference's Color § Source URLs), *except* it's the canonical location for the source-selection
|
||||
decision criteria — see Color § Dynamic sources below (the reference didn't extract these criteria).
|
||||
- `styles/motion/easing-and-duration/applying-easing-and-duration` — its "Suggested easing and duration
|
||||
pairs" table, "Choosing an easing set", "Choosing an easing type" (by transition direction), and
|
||||
"Choosing a duration" (by size / enter vs. exit) sections are already reproduced verbatim in the
|
||||
reference's Motion § Rules and § Values. The only new fact is an M2-vs-M3 style comparison — see
|
||||
Motion § Principles below.
|
||||
|
||||
---
|
||||
|
||||
## Spacing
|
||||
|
||||
Absent from `reference-styles.md` entirely — no Spacing section existed. This is a full addition.
|
||||
|
||||
### Principles
|
||||
|
||||
- Spacing is applied to the margins, padding, and gaps of a component, UI element, or layout.
|
||||
- Spacing adapts to different values based on context, like mobile vs. desktop, or density settings.
|
||||
- The spacing system is measured on an **8dp scale**, where **space100 = 8dp**.
|
||||
- Spacing is applied to the flow of elements (horizontal, vertical) or in relation to elements (leading,
|
||||
trailing, top, bottom, gap).
|
||||
- Unlike the color system (which adjusts light/dark theme logic across all components at once), spacing
|
||||
logic is tailored and built within each component individually — there's no single global spacing
|
||||
transform.
|
||||
- Components have padding/margin/gap tokens that map to system spacing tokens, which resolve to final dp
|
||||
values (component token → system token → value).
|
||||
|
||||
### Rules (Google's wording)
|
||||
|
||||
- Spacing has three categories: **padding** (space inside an element), **gap** (space between elements in
|
||||
a grid or container), and **margin** (space outside an element). Position can be vertical, top, bottom,
|
||||
horizontal, leading, or trailing. **Leading**/**trailing** swap sides in RTL languages.
|
||||
- **Do** define padding and gaps on the parent container to organize all elements inside.
|
||||
- **Don't** define margins on child elements — they usually aren't uniform and require more tokens.
|
||||
- **Use padding & gaps before using margins**: Material rarely uses margins in components; padding/gaps
|
||||
apply spacing more uniformly. Only use margins for spacing beyond the parent container's padding, or in
|
||||
layouts.
|
||||
- Use a horizontal/vertical gap for simple components where gaps are always the same size; complex
|
||||
components with many different gaps should name them by the elements on each side (e.g. "icon-label
|
||||
gap") rather than a single generic gap token.
|
||||
- When text is scaled up to 200%, the same spacing should be preserved by default (spacing does not scale
|
||||
with text).
|
||||
- What to use, in priority order:
|
||||
1. **Pre-tokenized components** — some Material components map to spacing system tokens out of the box
|
||||
(work is ongoing to hook up all components; this mapping can be customized for form factor/density).
|
||||
2. **System tokens** — apply these to custom components/layouts, replacing hardcoded values.
|
||||
3. If the right system token doesn't exist, **customize the system** (see below) and add your own.
|
||||
- Customizing the system (three approaches, by scope):
|
||||
- **Customize Material's existing component spacing** — remap a component attribute to a different
|
||||
system token product-wide (e.g. change "button top padding" from **space125** to **space200** for a
|
||||
taller default button).
|
||||
- **Add custom system spacing & patterns** — when you need units beyond what Material provides, or have
|
||||
a recurring adaptive pattern. Follow the multiplier convention for new tokens (e.g. **space225 = 18dp**
|
||||
= 8dp × 2.25). Product-specific recurring patterns can get their own pattern token (e.g. if cards and
|
||||
sheets always adapt horizontal content padding the same way, create a **surface-content padding
|
||||
horizontal** token for that pattern).
|
||||
- **Add adaptive layout & density** — map the same component to different system tokens per device type
|
||||
(mobile vs. desktop), and/or adapt vertical padding to different values per density setting, while
|
||||
keeping the same core component.
|
||||
- **Note:** system spacing tokens are currently only used on **Jetpack Compose** (see Availability below)
|
||||
— this is a stronger platform restriction than color/elevation/shape, which have broader (if uneven)
|
||||
support.
|
||||
|
||||
### Values
|
||||
|
||||
#### Availability
|
||||
|
||||
| Type | Resource | Status |
|
||||
| --- | --- | --- |
|
||||
| Implementation | Android Views (MDC-Android) | Unavailable |
|
||||
| Implementation | Jetpack Compose | Available |
|
||||
| Implementation | Web | Unavailable |
|
||||
|
||||
#### Spacing scale
|
||||
|
||||
The site does not render the token→dp table as text (it's an image diagram); the following is
|
||||
reconstructed from the images' alt-text and from dp values cited inline elsewhere on the page, and should
|
||||
be treated as inferred, not a verbatim site table:
|
||||
|
||||
| Token | Multiplier | Value |
|
||||
| --- | --- | --- |
|
||||
| space25 | 0.25× | 2dp |
|
||||
| space50 | 0.5× | 4dp |
|
||||
| space75 | 0.75× | 6dp |
|
||||
| **space100** | **1×** | **8dp (base unit, `md.sys.measurement.space100`)** |
|
||||
| space125 | 1.25× | 10dp |
|
||||
| space200 | 2× | 16dp |
|
||||
| space300 | 3× | 24dp |
|
||||
| space400 | 4× | 32dp |
|
||||
| space500 | 5× | 40dp |
|
||||
| space600 | 6× | 48dp |
|
||||
| space700 | 7× | 56dp |
|
||||
| space800 | 8× | 64dp |
|
||||
| space900 | 9× | 72dp |
|
||||
|
||||
Basis for this reconstruction: the overview page's scale diagram alt-text reads "a spacing scale shows 2,
|
||||
4, 6, and 8 at the bottom range and 48, 56, 64, and 72 at the top of the range"; the tokens page states the
|
||||
main range "covers 0x to 9x" of the 8dp base unit and separately defines nested sub-1x units at "0.25x,
|
||||
0.5x, 0.75x, 1.25x"; the overview page separately lists the same nested dp values ("2dp, 4dp, 6dp, and
|
||||
10dp"). Values beyond space900 (e.g. the 18dp/space225 example) are explicitly presented as **custom**,
|
||||
not part of the default set. Material only defines the nested/nonstandard units it actively uses — the
|
||||
scale is not a complete arithmetic progression at every step.
|
||||
|
||||
#### Component spacing — naming convention
|
||||
|
||||
| | Going forward | Legacy |
|
||||
| --- | --- | --- |
|
||||
| Prefix | `padding`, `margin`, `gap` | `space` |
|
||||
| Positional modifiers | horizontal, vertical, leading, trailing, top, bottom | leading-space, trailing-space, top-space, bottom-space, between-space |
|
||||
| Example | "Medium button: leading padding" | "Medium button: leading space" |
|
||||
|
||||
#### Parts of spacing — example (Search)
|
||||
|
||||
The search container: 8dp vertical padding, 8dp horizontal gaps, 24dp horizontal margins by default
|
||||
(narrows to 12dp when focused, while padding/gaps stay the same). The 24dp default margin exists
|
||||
specifically "to ensure accurate placement from the screen edge."
|
||||
|
||||
#### Spacing concepts diagrammed on the site (numbered image captions — anatomy, not values)
|
||||
|
||||
- Component layout: (1) vertical padding top & bottom, (2) vertical gap, (3) horizontal padding leading &
|
||||
trailing, (4) horizontal gap.
|
||||
- Page layout: (1) margin, (2) top padding, (3) horizontal padding leading & trailing, (4) spacer/gap,
|
||||
(5) vertical gap. Layouts additionally use **panes** (layout containers, which can be fixed, flexible,
|
||||
floating, or semi-permanent) and **spacers** (space between two panes; contains a drag handle if the
|
||||
panes are resizable).
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
|
||||
No Expressive-specific spacing changes are called out on these pages (unlike shape/motion/typography,
|
||||
spacing carries no "M3 Expressive" labelled update section). The system is presented as a single,
|
||||
version-agnostic linear scale.
|
||||
|
||||
### Accessibility
|
||||
|
||||
- Spacing must be preserved (not scaled) when text is scaled up to 200%, so layouts stay stable and
|
||||
legible as text grows — spacing is a support mechanism for text-resizing accessibility, not something
|
||||
that competes with it.
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/spacing/overview
|
||||
- https://m3.material.io/styles/spacing/applying-spacing
|
||||
- https://m3.material.io/styles/spacing/tokens
|
||||
|
||||
---
|
||||
|
||||
## Color — additions
|
||||
|
||||
### Static: Custom brand color scheme
|
||||
|
||||
Not previously fetched. Supplements the reference's Color section (which covers baseline/static generally
|
||||
but not the brand-specific workflow).
|
||||
|
||||
**Principles**
|
||||
- A **brand-based static scheme** is hand-picked by the product team to align with the product's brand
|
||||
color(s), as opposed to the **baseline** static scheme (Material's own default) or a **dynamic** scheme.
|
||||
It requires greater ongoing investment since the team creates and maintains it entirely.
|
||||
- End-users see: an accessible UI with static colors, and "a product that looks like its brand."
|
||||
|
||||
**Rules (Google's wording)**
|
||||
- Brand schemes are still generated through the same tonal-palette machinery as dynamic color: you can
|
||||
set a **custom source color independently for each of the 6 palette groups** — Primary, Secondary,
|
||||
Tertiary, Error, Neutral, and Neutral Variant — not just Primary. Setting only Primary and leaving the
|
||||
rest defaulted is also valid ("use the scheme as-is").
|
||||
- Workflow (Material Theme Builder Figma plugin): add a new theme, name it (the name becomes the color
|
||||
role prefix in Figma), set a custom Hex source color for Primary (and optionally Secondary/Tertiary/
|
||||
Error/Neutral/Neutral Variant) → generates a full custom color scheme with the same role set as baseline.
|
||||
- Enabling "Generate State Layers" in the plugin settings when creating the theme is called out as
|
||||
necessary groundwork for interaction-state design (cross-references state layers).
|
||||
- Point of escalation: "want to further adjust your brand color scheme?" and "need to make adjustments?"
|
||||
both route to **Advanced customizations** (apply/define/adjust colors) — i.e. custom-brand is the
|
||||
starting point, advanced customization is the refinement path.
|
||||
- Develop: export the branded scheme from Material Theme Builder for Jetpack Compose, Android Views,
|
||||
Flutter, Web, or as a JSON file.
|
||||
|
||||
**Source URLs**
|
||||
- https://m3.material.io/styles/color/static/custom-brand
|
||||
|
||||
### Dynamic: choosing and using a source
|
||||
|
||||
Two new sub-pages (content-based-source, user-generated-source) plus decision criteria from
|
||||
choosing-a-source that the reference's Color section states only as a single pipeline description, not as
|
||||
selection criteria.
|
||||
|
||||
**Principles**
|
||||
- Both user-generated and content-based color go through the same pipeline: the image is digitally
|
||||
analyzed through **quantization**, a single color is selected as the source color, and tones are chosen
|
||||
and assigned to each color role (this is the concrete mechanism behind the "dynamic color pipeline"
|
||||
already summarized in the reference).
|
||||
- **User-generated color**: sourced from the user's wallpaper.
|
||||
- **Content-based color**: sourced from in-app content — an album thumbnail, a logo, a video preview.
|
||||
|
||||
**Rules (Google's wording) — decision criteria (not previously captured)**
|
||||
|
||||
| Source type | Choose it if… |
|
||||
| --- | --- |
|
||||
| User-generated | Users would benefit from a personalized experience that's well-tested; you want to showcase the latest Material features |
|
||||
| Content-based | Content is front-and-center in the product; the team can do some advanced customization; it supports usability of content-centric features like media players; best applied to contained screen elements adjacent to the source image (the source image itself need not stay visible) |
|
||||
| Multiple sources | Product requirements meet more than one of the above criteria and the team doesn't mind extra customization work; get started with user-generated color first, then customize |
|
||||
|
||||
- Example of multiple sources coexisting: a photo app derives content-based color (green) for edit buttons
|
||||
from the in-app photo, while wallpaper-derived user-generated color (red) drives share buttons elsewhere
|
||||
in the same screen.
|
||||
- Content-based color guidance: apply it where it enhances brand identity and personalization (e.g. a
|
||||
music app deriving color from album artwork; a news app differentiating publications by their content
|
||||
color).
|
||||
- QA/testing step for user-generated color (Figma workflow): use the Material Theme Builder's "Dynamic"
|
||||
mode, add a real image or use the Shuffle icon for a random source color, swap it onto frames, and
|
||||
**repeat across a range of colors** to get a sense of how the product will appear across different
|
||||
users' devices/wallpapers — i.e. dynamic-color design review should be done across many source colors,
|
||||
not just one or two.
|
||||
- Android implementation reference specifically for content-based color: MDC-Android's
|
||||
"Content-based dynamic color" doc (separate from the general dynamic-color doc already cited).
|
||||
|
||||
**Source URLs**
|
||||
- https://m3.material.io/styles/color/dynamic/choosing-a-source
|
||||
- https://m3.material.io/styles/color/dynamic/content-based-source
|
||||
- https://m3.material.io/styles/color/dynamic/user-generated-source
|
||||
|
||||
---
|
||||
|
||||
## Motion — Transitions (supplement)
|
||||
|
||||
The reference's Motion section already reproduces the easing/duration Rules and Values from
|
||||
`applying-easing-and-duration` verbatim, and names the six transition patterns in one summary line without
|
||||
detail. This section supplies the missing detail: what each pattern is for, what it's commonly used with,
|
||||
platform (Android/iOS) differences, and the accessibility/consistency criteria for transitions overall —
|
||||
which also fills the gap the reference explicitly flagged ("No general reduced-motion policy was found
|
||||
stated on `styles/motion` itself").
|
||||
|
||||
**Naming note:** the current M3 site does **not** use the older M2 terms "shared axis / fade through /
|
||||
fade." The current (2026) taxonomy is: **Container transform**, **Forward and backward** (≈ old shared
|
||||
axis), **Lateral**, **Top level** (≈ old fade through), **Enter and exit** (subsumes old "fade" cases), and
|
||||
**Skeleton loaders** (new, not an M2 concept). Anyone looking for "shared axis"/"fade through"/"fade" by
|
||||
name should map to this table.
|
||||
|
||||
### Principles — what makes a good transition
|
||||
|
||||
- **Follows accessibility settings**: when a platform's reduced-motion setting is on, transitions should
|
||||
use subtle fades instead of intense sliding/scaling, and disable decorative effects like parallax or
|
||||
shape morphing. *(This is the missing general reduced-motion policy for `styles/motion` — previously
|
||||
only found at the component level, e.g. carousel/menus.)*
|
||||
- **Consistent**: applying the same transition type consistently for the same kind of navigation makes
|
||||
apps feel cohesive and predictable (e.g. multiple Android apps sharing one forward/backward transition).
|
||||
- **Stable layouts**: use skeleton loaders (subtle pulsing) so content doesn't shift position or pop in
|
||||
abruptly as it loads.
|
||||
- **No jarring jump cuts**: avoid instant, uncued transitions by default — they're disorienting. Exception:
|
||||
a jump cut may be preferred when pure efficiency is the top priority (e.g. opening a menu in a
|
||||
productivity app).
|
||||
- **Coherent spatial model**: transitions should help users understand an app's physical/spatial layout
|
||||
(e.g. keep a consistent axis when moving between collapsed/expanded carousel views; don't flip between
|
||||
horizontal and vertical layouts).
|
||||
- **Unified direction**: elements are grouped and move along one primary axis rather than independently;
|
||||
only genuinely persistent elements (e.g. a hero image) should remain visible throughout — animating many
|
||||
persistent elements independently is distracting.
|
||||
- **Clean fades**: fully fade out old content before fading in new content; avoid overlapping
|
||||
partially-transparent frames. If a cross-fade is unavoidable, keep it quick and hide it during the
|
||||
fastest part of the transition (e.g. a dialog entering mid-screen should not slowly fade on top of
|
||||
content — use a short fade to hide the overlap).
|
||||
- **Simple style**: transitions are frequent and utility-driven, not a showcase for stylized motion — avoid
|
||||
overt effects like bouncy springs on common transitions.
|
||||
|
||||
### Rules — per-pattern guidance (Google's wording)
|
||||
|
||||
| Pattern | Use for | Commonly used with | Do / Don't / Caution |
|
||||
| --- | --- | --- | --- |
|
||||
| **Container transform** | Seamlessly transforming an element to show more detail (e.g. a card expanding into a details page); hero moments that should be expressive; shallow hierarchies (expand for detail, then collapse); creating a seamless connection between elements. Most dramatic/expressive pattern — reserve for the right context. | Cards, lists, image galleries, search boxes, sheets, FABs, chips | **Do** use it for hero moments instead of a forward/backward transition. **Don't** use it in apps with deep hierarchies (motion becomes excessive) or in utility-focused navigation (style mismatch). |
|
||||
| **Forward and backward** | Navigating between screens at consecutive hierarchy levels (e.g. inbox → message thread) | Lists, cards, buttons, links | **Do** use platform defaults — easy to implement, stays current with platform updates. Android fades content as screens slide (reduces motion vs. a full-width slide); iOS uses parallax (background slides slower than foreground). **Caution**: container transform requires custom implementation and can feel excessive if overused for this role. |
|
||||
| **Lateral** | Navigating between peer content at the same hierarchy level (e.g. swiping tabs in a content library) | Tabs, carousels, image galleries | Elements are grouped and slide in unison with **no fade or parallax**, creating a strong peer relationship and hinting at swipe-ability. **Caution**: fading content while it slides weakens the peer/swipe cue and can be confused with forward/backward. **Don't** use for hierarchical navigation — full-width sliding is excessive and wrongly implies a peer (non-hierarchical) relationship. |
|
||||
| **Top level** | Navigating between top-level destinations (e.g. tapping a nav bar/rail/drawer item) | Navigation bar, navigation rail, navigation drawer | Exiting screen quickly fades out, then the entering screen fades in — intentionally **no** grouping or persistent elements, since top-level destinations aren't necessarily related. **Don't** use a lateral transition here — it wrongly implies you can swipe between top-level destinations, conflicting with carousel/list swipe gestures. |
|
||||
| **Enter and exit — within screen bounds** | Introducing/removing a component in the context of the main UI (modal, e.g. a dialog; or non-modal, e.g. a bottom sheet coexisting with content) | FABs, dialogs, menus, snackbars, time pickers, tooltips | Android: expand/collapse along x or y axis only (scale and z-axis motion are avoided — they'd imply an elevation change, which conflicts with M3's reduced-elevation model). iOS: uniform scale to enter, fade to exit. Enter direction is informed by on-screen location, expanding away from the device edge (e.g. a top menu expands downward; a bottom snackbar expands upward). **Don't** use this pattern for navigating hierarchical screens — full-height sliding is excessive and creates an unclear screen-to-screen relationship. |
|
||||
| **Enter and exit — beyond screen bounds** | Components that slide fully on/off screen | App bars, banners, navigation bar, navigation rail, navigation drawer, sheets | Android: expand/collapse along x or y axis while sliding on/off (adds shape emphasis). iOS: slides on/off without changing shape. Coplanar side sheets shrink the available content area rather than overlaying it. Can be scroll-driven (e.g. a top app bar or nav bar sliding off/on during scroll, to reclaim screen space). Entry/exit location establishes spatial memory: notifications enter from the top (matches the pull-down drawer), a nav drawer enters from the left (matches its off-screen position), a bottom sheet/keyboard enters from the bottom (easiest to reach). |
|
||||
| **Skeleton loaders** | Transitioning from a temporary loading state to the fully loaded UI | Used in combination with other transition patterns | Subtle pulsing animation indicates indeterminate progress, animating from top-left to bottom-right. Once content loads, it quickly fades in **on top of** the skeleton loader (not instantly popping in). |
|
||||
|
||||
### Values
|
||||
|
||||
Durations and easing for these patterns are governed by the already-referenced tables (Suggested
|
||||
easing/duration pairs; legacy duration tokens) — no separate duration table is given per pattern on these
|
||||
pages. The pattern choice itself is the "value" documented here; see the Rules table above for the
|
||||
authoritative per-pattern mapping (this *is* the durations/patterns cross-reference the task asked for —
|
||||
the site does not tie a specific numeric duration to "container transform" etc. beyond the general
|
||||
begin/end-on-screen vs. enter vs. exit rules already in the reference).
|
||||
|
||||
### M2 vs M3 easing note (from `applying-easing-and-duration`; not an M3-vs-Expressive distinction)
|
||||
|
||||
- Compared to M2's more utilitarian easing style, **M3 easing is more expressive**: transitions have
|
||||
"snappy take-offs and very soft landings."
|
||||
- **M3 durations are slightly longer than M2's**, deliberately, to give transitions time to come to a
|
||||
gentle rest without feeling abrupt.
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
- General reduced-motion policy for transitions (see Principles above): substitute subtle fades for
|
||||
intense sliding/scaling, and disable decorative effects (parallax, shape morphing) when a platform's
|
||||
reduced-motion setting is on. This generalizes — and predates in priority — the component-level
|
||||
reduced-motion notes already in the reference (carousel, menus).
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/motion/transitions/applying-transitions
|
||||
- https://m3.material.io/styles/motion/transitions/transition-patterns
|
||||
- https://m3.material.io/styles/motion/easing-and-duration/applying-easing-and-duration (mostly duplicate
|
||||
of already-referenced content; see M2-vs-M3 note above for the one new fact)
|
||||
@@ -0,0 +1,896 @@
|
||||
# Material Design 3 — Styles Reference (Color, Elevation, Icons, Motion, Shape, Typography)
|
||||
|
||||
Ground-truth extraction from m3.material.io/styles and its sub-pages, plus androidx Compose Material3
|
||||
token source files where the site only renders a value inside an unrendered interactive widget.
|
||||
Anything not from the live site text is explicitly marked "(not on the site; from <source>)".
|
||||
|
||||
---
|
||||
|
||||
## Color
|
||||
|
||||
### Principles
|
||||
|
||||
- Color is used to express style and communicate meaning. With dynamic color, Material puts personal
|
||||
color preferences and individual needs at the forefront of systematic color application.
|
||||
- The Material color system includes: a built-in set of accessible color relationships (e.g. a dark
|
||||
surface color is algorithmically paired with a light text-label color so the UI automatically meets
|
||||
contrast requirements); 26+ color roles mapped to components; a built-in dark theme; a static baseline
|
||||
color scheme; and dynamic color (user-generated from wallpaper, or content-based from in-app content).
|
||||
- Color roles are "like the numbers in a paint-by-number canvas" — the connective tissue between UI
|
||||
elements and what color goes where.
|
||||
- **Color roles are mapped to Material Components.** Custom components must be mapped to this same
|
||||
role set.
|
||||
- **Color roles ensure accessibility.** The system is built on accessible color pairings; color pairs
|
||||
provide an accessible minimum 3:1 contrast.
|
||||
- **Color roles are tokenized.**
|
||||
- General vocabulary used in role names:
|
||||
- **Surface** — backgrounds and large, low-emphasis areas.
|
||||
- **Primary / Secondary / Tertiary** — accent roles used to emphasize or de-emphasize foreground elements.
|
||||
- **Container** — fill color for foreground elements like buttons; not for text or icons.
|
||||
- **On** — a color for text/icons *on top of* its paired parent color (e.g. "on primary" on "primary").
|
||||
- **Variant** — a lower-emphasis alternative to its non-variant pair (e.g. "outline variant" vs "outline").
|
||||
- The system uses a color space called **HCT** (Hue, Chroma, Tone), not HSL/RGB. HCT lets you manipulate
|
||||
hue and chroma without affecting tone.
|
||||
- **Hue**: 0–360, circular (perception as red/orange/yellow/…).
|
||||
- **Chroma**: 0 (grey/black/white) up to roughly 120 in HCT (colorfulness); max chroma varies by hue/tone.
|
||||
- **Tone**: 0 (pure black) to 100 (pure white); determines contrast. HCT tone is not interchangeable
|
||||
with HSL lightness — two colors can share an HCT tone (perceived brightness) while having different
|
||||
HSL lightness values.
|
||||
- Dynamic color pipeline: (1) start with a source color (from wallpaper, in-app content, or hand-picked);
|
||||
(2) feed it into an algorithm; (3) the algorithm generates key colors; (4) it creates a **tonal palette**
|
||||
per key color (tones 0–100 in steps of 10, plus 95/98/99, some palettes have more); (5) it assigns tones
|
||||
to the ~26 standard color roles for both light and dark theme; (6) the new colors are applied to the UI.
|
||||
|
||||
### Rules (Google's wording)
|
||||
|
||||
- Pair and layer color roles only as intended (e.g. primary + on primary + secondary container + on
|
||||
secondary container) to keep them legible as contrast level changes. **Don't** mix roles improperly
|
||||
(e.g. primary + primary container + secondary container + on surface) — this can become illegible as
|
||||
contrast changes.
|
||||
- **Don't** use the **outline** color for dividers (different contrast requirements) — use **outline
|
||||
variant** instead.
|
||||
- **Don't** use **outline** for components containing multiple elements (e.g. cards) — use **outline
|
||||
variant**.
|
||||
- **Don't** use **outline variant** to create visual hierarchy or define a target's visual boundary —
|
||||
use **outline** or another color giving 3:1 contrast with the surface.
|
||||
- **Caution**: **outline variant** can border targets like chips/buttons only if elements inside them
|
||||
(icons/text) already meet 4.5:1 contrast.
|
||||
- Most products won't need the **add-on** color roles (fixed/fixed-dim, on-fixed/on-fixed-variant,
|
||||
surface-dim/surface-bright). "If you aren't sure whether your product should use the add-on roles, it
|
||||
probably shouldn't."
|
||||
- **Don't** use **fixed** colors where contrast is necessary — they don't adapt to light/dark theme and
|
||||
are likely to cause contrast issues (e.g. a button fill on a permissions screen). **Do** use primary/
|
||||
secondary/tertiary where contrast is needed.
|
||||
- All color mappings — especially surface colors — should remain the same for a given layout region
|
||||
across breakpoints (e.g. body always **surface**, navigation always **surface container**, on both
|
||||
mobile and tablet).
|
||||
- Error is a **static** color by default (doesn't change with dynamic color schemes) but still adapts to
|
||||
light/dark theme.
|
||||
- Advanced customization best practices:
|
||||
- Any role starting with "on-" is guaranteed sufficient contrast with its paired role; other role pairs
|
||||
may not meet the 4.5:1 (small text) / 3:1 (large text) Material contrast requirements — check before
|
||||
reusing a pairing.
|
||||
- Always apply **color roles**, never static hex values or raw tonal-palette values, for anything that
|
||||
should respond to theme, contrast level, or dynamic color.
|
||||
- Test a dynamic-color component under multiple source-color themes (light/dark; red/yellow/green/blue).
|
||||
- Limit a screen to two color schemes from different source types (e.g. baseline/user-generated combined
|
||||
with one content-based source) to avoid visual disarray.
|
||||
- Don't replace semantic colors (e.g. red error, green success) with content-based dynamic color.
|
||||
- Don't harmonize colors whose appearance should stay absolutely consistent (e.g. brand colors).
|
||||
- Defining custom color roles should be considered only if the existing Material roles can't achieve the
|
||||
desired result.
|
||||
- Choosing a scheme: use **static (baseline)** if not ready for dynamic color, migrating from M2, building
|
||||
for enterprise users, or building for iOS. Use **dynamic** if the product should personalize, react to
|
||||
wallpaper/content, or offer user-controlled contrast.
|
||||
|
||||
### Values
|
||||
|
||||
#### Color roles (Compose `ColorSchemeKeyTokens`, 47 tokens; tone source `ColorLightTokens.kt` / `ColorDarkTokens.kt`)
|
||||
|
||||
Each role resolves to a tone from one of 5 tonal palettes (Primary, Secondary, Tertiary, Neutral,
|
||||
Neutral Variant) or Error. Format: role — light theme tone — dark theme tone.
|
||||
|
||||
| Role | Light tone | Dark tone | Purpose (site wording) |
|
||||
| --- | --- | --- | --- |
|
||||
| Primary | Primary40 | Primary80 | High-emphasis fills, text, icons against surface |
|
||||
| On primary | Primary100 | Primary20 | Text/icons against primary |
|
||||
| Primary container | Primary90 | Primary30 | Standout fill against surface, key components like FAB |
|
||||
| On primary container | Primary10 | Primary90 | Text/icons against primary container |
|
||||
| Secondary | Secondary40 | Secondary80 | Less prominent fills/text/icons against surface |
|
||||
| On secondary | Secondary100 | Secondary20 | Text/icons against secondary |
|
||||
| Secondary container | Secondary90 | Secondary30 | Recessive fill, e.g. tonal buttons |
|
||||
| On secondary container | Secondary10 | Secondary90 | Text/icons against secondary container |
|
||||
| Tertiary | Tertiary40 | Tertiary80 | Complementary accent, e.g. input fields |
|
||||
| On tertiary | Tertiary100 | Tertiary20 | Text/icons against tertiary |
|
||||
| Tertiary container | Tertiary90 | Tertiary30 | Complementary container fill |
|
||||
| On tertiary container | Tertiary10 | Tertiary90 | Text/icons against tertiary container |
|
||||
| Error | Error40 | Error80 | Attention-grabbing color for urgency |
|
||||
| On error | Error100 | Error20 | Text/icons against error |
|
||||
| Error container | Error90 | Error30 | Attention-grabbing fill |
|
||||
| On error container | Error10 | Error90 | Text/icons against error container |
|
||||
| Surface | Neutral98 | Neutral6 | Default background |
|
||||
| On surface | Neutral10 | Neutral90 | Text/icons on surface / surface container |
|
||||
| On surface variant | NeutralVariant30 | NeutralVariant80 | Lower-emphasis text/icons on surface |
|
||||
| Surface variant | NeutralVariant90 | NeutralVariant30 | (legacy; superseded by surface container roles Feb 2023) |
|
||||
| Background / On background | Neutral98 / Neutral10 | Neutral6 / Neutral90 | Legacy roles, same values as surface/on surface |
|
||||
| Outline | NeutralVariant50 | NeutralVariant60 | Important boundaries, e.g. text-field outline |
|
||||
| Outline variant | NeutralVariant80 | NeutralVariant30 | Decorative elements, e.g. dividers |
|
||||
| Inverse surface | Neutral20 | Neutral90 | Background contrasting against surrounding surface |
|
||||
| Inverse on surface | Neutral95 | Neutral20 | Text/icons against inverse surface |
|
||||
| Inverse primary | Primary80 | Primary40 | Actionable elements (e.g. text buttons) against inverse surface |
|
||||
| Scrim | Neutral0 | Neutral0 | Scrim behind modals, at 32% opacity |
|
||||
| Surface tint | (=Primary) | (=Primary) | Deprecated — use elevation level tokens instead |
|
||||
|
||||
Surface container family (5 levels, named by emphasis — not tied to elevation, replaced "surface +1..+5"
|
||||
in Feb 2023):
|
||||
|
||||
| Role | Light tone | Dark tone |
|
||||
| --- | --- | --- |
|
||||
| Surface container lowest | Neutral100 | Neutral4 |
|
||||
| Surface container low | Neutral96 | Neutral10 |
|
||||
| Surface container | Neutral94 | Neutral12 |
|
||||
| Surface container high | Neutral92 | Neutral17 |
|
||||
| Surface container highest | Neutral90 | Neutral22 |
|
||||
|
||||
Bright/dim add-on surface roles (keep relative brightness across both themes, unlike default surface
|
||||
which inverts):
|
||||
|
||||
| Role | Light tone | Dark tone |
|
||||
| --- | --- | --- |
|
||||
| Surface dim | Neutral87 | Neutral6 |
|
||||
| Surface bright | Neutral98 | Neutral24 |
|
||||
|
||||
Fixed accent add-on roles (same tone in light **and** dark theme; added Feb 2023):
|
||||
|
||||
| Role | Tone (both themes) | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Primary fixed | Primary90 | Fill color that stays constant across themes |
|
||||
| Primary fixed dim | Primary80 | Stronger/more emphasized fixed tone |
|
||||
| On primary fixed | Primary10 | Text/icons on primary fixed |
|
||||
| On primary fixed variant | Primary30 | Lower-emphasis text/icons on primary fixed |
|
||||
| Secondary fixed | Secondary90 | ” |
|
||||
| Secondary fixed dim | Secondary80 | ” |
|
||||
| On secondary fixed | Secondary10 | ” |
|
||||
| On secondary fixed variant | Secondary30 | ” |
|
||||
| Tertiary fixed | Tertiary90 | ” |
|
||||
| Tertiary fixed dim | Tertiary80 | ” |
|
||||
| On tertiary fixed | Tertiary10 | ” |
|
||||
| On tertiary fixed variant | Tertiary30 | ” |
|
||||
|
||||
#### Baseline tonal palettes (hex; from androidx `PaletteTokens.kt`, since the site renders these only in
|
||||
an interactive, non-text widget)
|
||||
|
||||
| Tone | Primary | Secondary | Tertiary | Neutral | Neutral Variant | Error |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| 0 | #000000 | #000000 | #000000 | #000000 | #000000 | #000000 |
|
||||
| 4 | — | — | — | #0F0D13 | — | — |
|
||||
| 6 | — | — | — | #141218 | — | — |
|
||||
| 10 | #21005D | #1D192B | #31111D | #1D1B20 | #1D1A22 | #410E0B |
|
||||
| 12 | — | — | — | #211F26 | — | — |
|
||||
| 17 | — | — | — | #2B2930 | — | — |
|
||||
| 20 | #381E72 | #332D41 | #492532 | #322F35 | #322F37 | #601410 |
|
||||
| 22 | — | — | — | #36343B | — | — |
|
||||
| 24 | — | — | — | #3B383E | — | — |
|
||||
| 30 | #4F378B | #4A4458 | #633B48 | #48464C | #49454F | #8C1D18 |
|
||||
| 40 | #6750A4 | #625B71 | #7D5260 | #605D64 | #605D66 | #B3261E |
|
||||
| 50 | #7F67BE | #7A7289 | #986977 | #79767D | #79747E | #DC362E |
|
||||
| 60 | #9A82DB | #958DA5 | #B58392 | #938F96 | #938F99 | #E46962 |
|
||||
| 70 | #B69DF8 | #B0A7C0 | #D29DAC | #AEA9B1 | #AEA9B4 | #EC928E |
|
||||
| 80 | #D0BCFF | #CCC2DC | #EFB8C8 | #CAC5CD | #CAC4D0 | #F2B8B5 |
|
||||
| 87 | — | — | — | #DED8E1 | — | — |
|
||||
| 90 | #EADDFF | #E8DEF8 | #FFD8E4 | #E6E0E9 | #E7E0EC | #F9DEDC |
|
||||
| 92 | — | — | — | #ECE6F0 | — | — |
|
||||
| 94 | — | — | — | #F3EDF7 | — | — |
|
||||
| 95 | #F6EDFF | #F6EDFF | #FFECF1 | #F5EFF7 | #F5EEFA | #FCEEEE |
|
||||
| 96 | — | — | — | #F7F2FA | — | — |
|
||||
| 98 | — | — | — | #FEF7FF | — | — |
|
||||
| 99 | #FFFBFE | #FFFBFE | #FFFBFA | #FFFBFF | #FFFBFE | #FFFBF9 |
|
||||
| 100 | #FFFFFF | #FFFFFF | #FFFFFF | #FFFFFF | #FFFFFF | #FFFFFF |
|
||||
|
||||
(Source: androidx Compose Material3 `PaletteTokens.kt` — the purple/violet "baseline" scheme. Any product
|
||||
using a different source color will generate a different palette via the HCT algorithm, but role→tone
|
||||
assignments are the same.)
|
||||
|
||||
#### Contrast levels
|
||||
|
||||
| Level | Ratio (approx.) | Notes |
|
||||
| --- | --- | --- |
|
||||
| Standard (default) | mixed | Emphasizes hierarchy using high- and low-contrast elements together |
|
||||
| Medium | 3:1 minimum | For users needing more contrast without high-contrast side effects like halation |
|
||||
| High | 7:1 | Further emphasizes essential elements (e.g. card content, not the card container) |
|
||||
|
||||
Contrast settings apply automatically in both light and dark theme. Custom components support contrast
|
||||
levels simply by using Material color roles (e.g. primary container / on primary container) — the role's
|
||||
resolved value changes per contrast level automatically.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
|
||||
The color pages do not explicitly label any change "M3 Expressive" the way shape/motion/typography pages
|
||||
do, but the "What's new" timeline on `styles/color` lists (with the May 2025 entry coinciding with the
|
||||
Expressive launch):
|
||||
|
||||
- **May 2025 — Three levels of contrast.** Color roles now support standard/medium/high contrast, each
|
||||
tokenized (see Values above).
|
||||
- **Aug 2024 — More colorful text & icons.** On-primary-container, on-secondary-container,
|
||||
on-tertiary-container, on-error-container were updated in light theme to be more colorful while
|
||||
remaining accessible; affects badges, buttons (all variants), chips, lists, menus, navigation bar,
|
||||
navigation drawer, navigation rail, switches, toolbars.
|
||||
- **Feb 2023 — Tone-based surface colors.** Replaced the old "surface +1 to +5 elevation overlay" model
|
||||
with the surface/surface-container role family (not tied to elevation). Also: default light-theme
|
||||
surface moved from tone 99 to tone 98; neutral palette chroma increased 4→6; dark-theme surfaces
|
||||
slightly darkened (alignment with Android SysUI).
|
||||
- **Feb 2023 — Additional accent colors.** Added fixed / fixed-dim roles for primary, secondary, tertiary.
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
- Color pairs provide an accessible **minimum 3:1 contrast** by design (color-role pairing system).
|
||||
- Text contrast targets (also stated on `foundations/designing/color-contrast`, W3C-based):
|
||||
large text (≥14pt bold / ≥18pt regular) and graphics: **≥3:1** against background; small text: **≥4.5:1**.
|
||||
Disabled states do not need to meet contrast requirements.
|
||||
- Non-text clustered elements (e.g. a group of buttons) should meet **3:1** contrast between container
|
||||
color and background; a standalone prominent element (e.g. a FAB) does not need this because its
|
||||
prominence already distinguishes it.
|
||||
- High contrast mode targets **7:1**.
|
||||
- Default typography color is **on surface** (or **on surface variant** as a strong alternative).
|
||||
- **Color-alone rule**: hyperlinked text must use primary (or tertiary, for a less prominent link) *and*
|
||||
must be underlined — color alone must not be the only signal.
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles
|
||||
- https://m3.material.io/styles/color
|
||||
- https://m3.material.io/styles/color/system (identical render to /styles/color)
|
||||
- https://m3.material.io/styles/color/roles
|
||||
- https://m3.material.io/styles/color/system/how-the-system-works
|
||||
- https://m3.material.io/styles/color/choosing-a-scheme
|
||||
- https://m3.material.io/styles/color/static (= /styles/color/static/baseline)
|
||||
- https://m3.material.io/styles/color/dynamic
|
||||
- https://m3.material.io/styles/color/advanced
|
||||
- https://m3.material.io/styles/color/advanced/apply-colors
|
||||
- https://m3.material.io/styles/color/advanced/define-new-colors
|
||||
- https://m3.material.io/styles/color/advanced/adjust-existing-colors
|
||||
- https://m3.material.io/styles/color/resources
|
||||
- https://m3.material.io/foundations/designing/color-contrast (contrast-ratio table)
|
||||
- https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/ColorSchemeKeyTokens.kt
|
||||
- .../tokens/ColorLightTokens.kt
|
||||
- .../tokens/ColorDarkTokens.kt
|
||||
- .../tokens/PaletteTokens.kt
|
||||
|
||||
---
|
||||
|
||||
## Elevation
|
||||
|
||||
### Principles
|
||||
|
||||
- Elevation is applied to all surfaces and components.
|
||||
- Tokens codify the distance on the z-axis so components appear consistently relative to each other.
|
||||
- Tokens carry no shadow or color themselves — each platform determines the specific shadow/value used
|
||||
at each elevation level.
|
||||
- Elevation can be shown as tonal surface colors **or** shadows.
|
||||
- Avoid changing the default elevation of Material 3 components.
|
||||
- Stick to using a small number of elevation levels.
|
||||
- Elevation is measured as the distance between components along the z-axis in density-independent
|
||||
pixels (dp).
|
||||
- To successfully depict elevation, a surface must show: surface edges (contrast with surroundings),
|
||||
overlap with other surfaces (at rest or in motion), and distance from other surfaces.
|
||||
|
||||
### Rules (do/don't)
|
||||
|
||||
- **Do** ensure floating elements (e.g. a FAB) have sufficient contrast with the surface beneath them.
|
||||
**Don't** use colors with insufficient contrast — the relationship between surfaces must stay clear.
|
||||
- By default, Material 3 surfaces use **tonal difference** to indicate separation; shadows and scrims
|
||||
are alternative/additional methods.
|
||||
- Any overlapping containment areas or components should use **different surface/surface-container color
|
||||
roles** to communicate separation — these color roles are not tied to elevation.
|
||||
- Shadow size and softness both express distance: small, sharp shadows = close proximity; larger, softer
|
||||
shadows = more distance.
|
||||
- "When it comes to applying shadows, less is more. The fewer levels in your UI, the more power they have
|
||||
to direct attention and action."
|
||||
- Use **visible shadows** to: (1) protect elements against a patterned/busy background (cards, chips,
|
||||
buttons), or (2) encourage interaction (elements can temporarily lift on focus/selection/hover; a
|
||||
raised element can lower when a higher element appears).
|
||||
- Use a **scrim** to bring focus to elements over a large layered surface (e.g. modals, expanded
|
||||
navigation menus).
|
||||
|
||||
### Values
|
||||
|
||||
#### Elevation levels (`ElevationTokens.kt`; matches the site's dp values)
|
||||
|
||||
| Level | dp |
|
||||
| --- | --- |
|
||||
| 0 | 0dp |
|
||||
| 1 | 1dp |
|
||||
| 2 | 3dp |
|
||||
| 3 | 6dp |
|
||||
| 4 | 8dp |
|
||||
| 5 | 12dp |
|
||||
|
||||
An element's **resting state** is on levels 0–3; levels 4–5 are reserved for user-interacted states
|
||||
(hover, dragged) — e.g. hovering a FAB increases elevation by 1 level (level 3 → 4), consistently across
|
||||
all Material buttons.
|
||||
|
||||
#### Component resting elevation (from `styles/elevation/tokens`)
|
||||
|
||||
| Resting level | dp | Components |
|
||||
| --- | --- | --- |
|
||||
| 5 | 12dp | (not assigned as a resting level) |
|
||||
| 4 | 8dp | (not assigned as a resting level) |
|
||||
| 3 | 6dp | Date pickers, Dialogs (modal), Extended FAB, FAB, FAB menu (close button), Search, Time pickers |
|
||||
| 2 | 3dp | App bar (scrolled), Menu, Navigation bar, Rich tooltip, Toolbar |
|
||||
| 1 | 1dp | Banner, Bottom sheet (modal), Button (elevated), Card (elevated), Chips (elevated), Navigation drawer (modal), Side sheet (modal) |
|
||||
| 0 | 0dp | App bar (not scrolled), Buttons (filled/tonal/outlined), Button groups, Cards (filled/outlined), Carousel, Chips, Dialog (full-screen), Extended FAB (in nav rail), FAB (in nav rail), FAB menu (list items), Icon buttons, List, Navigation rail, Segmented button, Side sheet (docked), Slider, Split button, Tabs |
|
||||
|
||||
#### Scrim
|
||||
|
||||
Scrims use the **scrim** color role at **32% opacity**.
|
||||
|
||||
### Differences from M2
|
||||
|
||||
- **Shadows**: instead of applying shadows by default at all levels, use shadows only when needed for
|
||||
protection against a background or to encourage interaction.
|
||||
- **Color**: new color mappings and compatibility with dynamic color.
|
||||
- **Levels**: elevation is now described in terms of discrete levels (0–5) rather than continuous dp.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
|
||||
No "M3 Expressive" update is documented on the fetched elevation pages (`styles/elevation`,
|
||||
`/applying-elevation`, `/tokens`) — the elevation model appears unchanged by the Expressive update.
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
- Edges (surface separation) must create sufficient contrast between surfaces — meeting or exceeding
|
||||
accessible contrast ratios — to be perceived as separate. Elevation/shadow alone is treated as a visual
|
||||
cue that must be reinforced with adequate color/tonal contrast, not relied on in isolation.
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/elevation (= /styles/elevation/overview)
|
||||
- https://m3.material.io/styles/elevation/applying-elevation
|
||||
- https://m3.material.io/styles/elevation/tokens
|
||||
- https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/ElevationTokens.kt
|
||||
|
||||
---
|
||||
|
||||
## Icons
|
||||
|
||||
### Principles
|
||||
|
||||
- Icons are small symbols to easily identify actions and categories.
|
||||
- Material Symbols are the new default: a variable icon font set in three styles — **outlined, rounded,
|
||||
sharp** — across seven weights. (Legacy "Material Icons" remain available but lack the variable-font axes.)
|
||||
- Design principles (do/don't): simplify icons for clarity/legibility, don't be overly literal or complex;
|
||||
use geometric, consistent, bold shapes, don't use delicate/loose organic shapes; maintain one consistent
|
||||
visual style per icon set, don't mix styles within a set.
|
||||
|
||||
### Rules (do/don't)
|
||||
|
||||
- **Don't** use the lightest weight (100) for standard-size (24dp) icons — minimum weight for that size
|
||||
should be **200**. Use caution with excessive weight at 24dp too.
|
||||
- **Do** apply weight consistently across a group (e.g. a navigation rail); **don't** mix different weights.
|
||||
- **Do** use the same size for a Material Symbol and adjacent text; **don't** mix symbol/text sizes.
|
||||
- **Do** use the same optical weight for a symbol and adjacent text; **don't** mismatch optical weights.
|
||||
- **Do** shift a symbol's baseline down ~11.5% of the text size when pairing with text; **don't** use the
|
||||
same baseline for symbol and text.
|
||||
- **Do** position icons "on pixel" within the icon grid; **don't** place on non-integer (sub-pixel)
|
||||
coordinates.
|
||||
- Corners: default corner radius is **2dp**. For the **outlined** style, interior corners are square (not
|
||||
rounded); for shapes ≤2dp wide, stroke corners shouldn't be rounded. **Rounded** style: both exterior
|
||||
and interior corners are rounded. **Sharp** style: both exterior and interior corners reduce from 2dp
|
||||
to **0dp**. **Caution**: overly round corners reduce legibility. **Don't** use inconsistent corner radii.
|
||||
- Stroke: recommended stroke weight is **2dp** (regular weight, 400) with consistent weights and squared
|
||||
stroke terminals; **don't** use inconsistent stroke weights or rounded stroke terminals. Complex icons
|
||||
may use an optically-corrected **1.5dp** stroke to fit multiple curves in the 24×24dp space.
|
||||
- **Do** make icons face forward (flat); **don't** tilt, rotate, or render icons as dimensional/isometric.
|
||||
- Icon content must stay inside the **live area**; it may extend into padding toward the **trim area** if
|
||||
extra visual weight is needed, but **no part may extend past the trim area**.
|
||||
|
||||
### Values
|
||||
|
||||
#### Sizes
|
||||
|
||||
| Size | Use |
|
||||
| --- | --- |
|
||||
| 20dp | Desktop, dense layouts, small-scale visuals |
|
||||
| 24dp | Standard (baseline) size |
|
||||
| 40dp | Larger — pairs with display/headline type, larger screens |
|
||||
| 48dp | Larger — pairs with display/headline type, larger screens |
|
||||
|
||||
#### Layout (24dp standard icon)
|
||||
|
||||
| Region | Size |
|
||||
| --- | --- |
|
||||
| Trim area (total canvas) | 24dp × 24dp |
|
||||
| Live area | 20dp × 20dp |
|
||||
| Padding (live→trim) | 2dp around the perimeter |
|
||||
|
||||
#### Grid and keyline shapes (within the 24dp grid)
|
||||
|
||||
| Keyline | Dimensions |
|
||||
| --- | --- |
|
||||
| Square | 18dp × 18dp |
|
||||
| Circle | 20dp diameter |
|
||||
| Vertical rectangle | 20dp height × 16dp width |
|
||||
| Horizontal rectangle | 16dp height × 20dp width |
|
||||
|
||||
#### Corner radius by style
|
||||
|
||||
| Style | Exterior corner | Interior corner |
|
||||
| --- | --- | --- |
|
||||
| Outlined | 2dp rounded | Square (not rounded) |
|
||||
| Rounded | 2dp rounded | Rounded |
|
||||
| Sharp | 0dp | 0dp |
|
||||
|
||||
#### Material Symbols variable-font axes
|
||||
|
||||
| Axis | Range | Notes |
|
||||
| --- | --- | --- |
|
||||
| Weight | 100 (thin) – 700 (bold) | Also affects overall symbol size; min 200 recommended at 24dp |
|
||||
| Fill | 0 – 1 | 0 = unfilled/outlined, 1 = fully filled; communicates state transitions |
|
||||
| Grade | negative / 0 / positive (site examples: −25, 0) | Finer-grained than weight; doesn't change width or line breaks. Default grade is 0 for a dark icon on light background, **−25** for a light icon on dark background (compensates for visual bleed/halation). Positive grade for emphasis (e.g. active state). |
|
||||
| Optical size | 20dp – 48dp | Auto-adjusts stroke weight so the icon "looks the same" as size scales; use 20dp for dense desktop layouts, 40–48dp to highlight primary actions |
|
||||
|
||||
#### Icon styles (3): Outlined, Rounded, Sharp — see corner-radius table above.
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
|
||||
No "M3 Expressive" update is documented on the fetched icon pages (`styles/icons`,
|
||||
`/designing-icons`, `/applying-icons`). Material Symbols (three styles + four variable axes) predate the
|
||||
Expressive update; no Expressive-specific icon changes were found on the site.
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
- Icon meaning must always be unambiguous and accessible; use caution displaying icons without labels.
|
||||
Label text (short, meaningful) should be used especially for navigation.
|
||||
- Below **20dp**, symbols that are complex/highly-detailed, have multiple parts, or represent a key
|
||||
action essential to the product should have an accompanying text label. Simple symbols (e.g. a star for
|
||||
ratings) can be used alone at any size if they remain identifiable.
|
||||
- **Target size**: a 24dp symbol should have a default **target size of 48dp**.
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/icons (= /styles/icons/overview)
|
||||
- https://m3.material.io/styles/icons/designing-icons
|
||||
- https://m3.material.io/styles/icons/applying-icons
|
||||
|
||||
---
|
||||
|
||||
## Motion
|
||||
|
||||
### Principles
|
||||
|
||||
- May 2025: Material introduced the **motion physics system** with M3 Expressive — a spring-based system
|
||||
replacing the previous easing-and-duration system, intended to feel "more alive, fluid, and natural,"
|
||||
and to be easier to implement/customize.
|
||||
- Two preset **motion schemes**: **Expressive** (Material's opinionated default; overshoots final values
|
||||
to add bounce; use for most situations, hero moments, key interactions) and **Standard** (minimal
|
||||
bounce, eases into final values; for utilitarian products). Custom schemes can also be created.
|
||||
- A **spring** is defined by three attributes: **stiffness** (hardness — higher = faster resolve),
|
||||
**damping** (how fast bounce wears out — higher = faster stop; damping = 1 removes bounce entirely),
|
||||
and **initial velocity** (starting speed, combines with stiffness/damping to affect total duration).
|
||||
- Springs are versatile (one spring can drive transitions, button effects, gestures — consistent feel)
|
||||
and feel natural/predictable, handling gesture interruption and retargeting seamlessly.
|
||||
- Two spring **styles**: **Spatial** (movement — x/y position, rotation, size, rounded corners; overshoots
|
||||
and bounces into place) and **Effects** (color, opacity; no overshoot).
|
||||
- Three **speeds** per style: **default**, **fast**, **slow**. Most motion uses default; smaller elements
|
||||
may use fast; larger elements may use slow. The exact values differ by device class (wearable/phone/
|
||||
tablet) even though the *relative* speed ordering (fast < default < slow) is constant.
|
||||
- Token naming: e.g. `md.sys.motion.spring.fast.spatial` — the scheme (expressive/standard) is applied at
|
||||
the product level, not baked into the token name, so schemes can be swapped without re-tokenizing.
|
||||
- On Jetpack Compose, **21 Material components** use the motion physics system by default (Android Views/
|
||||
MDC-Android: available but not yet wired into components; Web: compatible via curve approximations).
|
||||
- Legacy **easing and duration** tokens remain available as a fallback and are still used for transition
|
||||
animation on platforms/paths not yet migrated to springs.
|
||||
|
||||
### Rules (do/don't; easing & duration choice)
|
||||
|
||||
- Choose the **Emphasized** easing set for most transitions (captures the M3 style); use **Standard**
|
||||
only for small, utility-focused, quick transitions, and as the fallback on platforms without Emphasized
|
||||
support (iOS, Web).
|
||||
- Easing by transition type:
|
||||
- **Begin and end on screen** → **Emphasized** (speeds up quickly, gentle rest, emphasizes the end).
|
||||
- **Enter the screen** → **Emphasized decelerate** (starts at peak velocity, gentle rest).
|
||||
- **Exit the screen permanently** → **Emphasized accelerate** (starts at rest, ends at peak velocity —
|
||||
implies it can't be retrieved).
|
||||
- **Exit the screen temporarily** → **Emphasized** (ends at rest just off-screen — implies it can be
|
||||
retrieved, e.g. a drawer).
|
||||
- Duration by transition size: small-area transitions get short durations; large-area transitions get
|
||||
long durations (consistent sense of speed).
|
||||
- Duration by direction: **exit/dismiss/collapse** → shorter durations (less attention needed); **enter/
|
||||
persist** → longer durations (focus attention on what's new).
|
||||
- Suggested easing+duration pairs (defaults good for most transitions):
|
||||
|
||||
| Easing | Duration | Transition type |
|
||||
| --- | --- | --- |
|
||||
| Emphasized | 500ms | Begin and end on screen |
|
||||
| Emphasized decelerate | 400ms | Enter the screen |
|
||||
| Emphasized accelerate | 200ms | Exit the screen |
|
||||
| Standard | 300ms | Begin and end on screen |
|
||||
| Standard decelerate | 250ms | Enter the screen |
|
||||
| Standard accelerate | 200ms | Exit the screen |
|
||||
|
||||
- Motion customization levels: **Level 1** — use a default scheme (expressive/standard) as-is; **Level 2**
|
||||
— create a custom `MotionScheme` (custom `AnimationSpec` per property) applied product-wide; **Level 3**
|
||||
— swap the scheme per element/screen (override the `CompositionLocal`) while most of the product uses
|
||||
the primary scheme.
|
||||
- Transition patterns documented: container transform (full-screen and within-screen), forward/backward,
|
||||
lateral, top-level, enter/exit (within screen bounds and beyond screen bounds), skeleton loaders.
|
||||
|
||||
### Values
|
||||
|
||||
#### Expressive motion scheme — spring tokens (`ExpressiveMotionTokens.kt`)
|
||||
|
||||
| Speed | Style | Damping | Stiffness |
|
||||
| --- | --- | --- | --- |
|
||||
| Fast | Spatial | 0.6 | 800.0 |
|
||||
| Fast | Effects | 1.0 | 3800.0 |
|
||||
| Default | Spatial | 0.8 | 380.0 |
|
||||
| Default | Effects | 1.0 | 1600.0 |
|
||||
| Slow | Spatial | 0.8 | 200.0 |
|
||||
| Slow | Effects | 1.0 | 800.0 |
|
||||
|
||||
#### Standard motion scheme — spring tokens (`StandardMotionTokens.kt`)
|
||||
|
||||
| Speed | Style | Damping | Stiffness |
|
||||
| --- | --- | --- | --- |
|
||||
| Fast | Spatial | 0.9 | 1400.0 |
|
||||
| Fast | Effects | 1.0 | 3800.0 |
|
||||
| Default | Spatial | 0.9 | 700.0 |
|
||||
| Default | Effects | 1.0 | 1600.0 |
|
||||
| Slow | Spatial | 0.9 | 300.0 |
|
||||
| Slow | Effects | 1.0 | 800.0 |
|
||||
|
||||
#### Web curve equivalents for springs (from `styles/motion/overview/specs`; springs aren't natively
|
||||
supported on the web, so Web should use these approximated cubic-bezier curves with matching duration)
|
||||
|
||||
| Spring | Cubic-bezier | Duration |
|
||||
| --- | --- | --- |
|
||||
| Expressive fast spatial | 0.42, 1.67, 0.21, 0.90 | 350ms |
|
||||
| Expressive default spatial | 0.38, 1.21, 0.22, 1.00 | 500ms |
|
||||
| Expressive slow spatial | 0.39, 1.29, 0.35, 0.98 | 650ms |
|
||||
| Expressive fast effects | 0.31, 0.94, 0.34, 1.00 | 150ms |
|
||||
| Expressive default effects | 0.34, 0.80, 0.34, 1.00 | 200ms |
|
||||
| Expressive slow effects | 0.34, 0.88, 0.34, 1.00 | 300ms |
|
||||
| Standard fast spatial | 0.27, 1.06, 0.18, 1.00 | 350ms |
|
||||
| Standard default spatial | 0.27, 1.06, 0.18, 1.00 | 500ms |
|
||||
| Standard slow spatial | 0.27, 1.06, 0.18, 1.00 | 750ms |
|
||||
| Standard fast effects | 0.31, 0.94, 0.34, 1.00 | 150ms |
|
||||
| Standard default effects | 0.34, 0.80, 0.34, 1.00 | 200ms |
|
||||
| Standard slow effects | 0.34, 0.88, 0.34, 1.00 | 300ms |
|
||||
|
||||
#### Legacy easing tokens (`styles/motion/easing-and-duration/tokens-specs`; curves confirmed in
|
||||
androidx `MotionTokens.kt`, noted where Compose's single-cubic-bezier approximation differs from the
|
||||
platform-accurate multi-segment Android `PathInterpolator`)
|
||||
|
||||
| Token | Android | CSS | Flutter | iOS |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `md.sys.motion.easing.emphasized` | PathInterpolator(M 0,0 C 0.05,0 0.133333,0.06 0.166666,0.4 C 0.208333,0.82 0.25,1 1,1) | N/A (use Standard) | `easeInOutCubicEmphasized` | N/A (use Standard) |
|
||||
| `md.sys.motion.easing.emphasized.decelerate` | PathInterpolator(0.05, 0.7, 0.1, 1) | cubic-bezier(0.05,0.7,0.1,1.0) | Cubic(0.05,0.7,0.1,1.0) | ControlPoints 0.05,0.7,0.1,1.0 |
|
||||
| `md.sys.motion.easing.emphasized.accelerate` | PathInterpolator(0.3, 0, 0.8, 0.15) | cubic-bezier(0.3,0.0,0.8,0.15) | Cubic(0.3,0.0,0.8,0.15) | ControlPoints 0.3,0.0,0.8,0.15 |
|
||||
| `md.sys.motion.easing.standard` | PathInterpolator(0.2, 0, 0, 1) | cubic-bezier(0.2,0.0,0,1.0) | Cubic(0.2,0.0,0,1.0) | ControlPoints 0.2,0.0,0.0,1.0 |
|
||||
| `md.sys.motion.easing.standard.decelerate` | PathInterpolator(0, 0, 0, 1) | cubic-bezier(0,0,0,1) | Cubic(0,0,0,1) | ControlPoints 0.0,0.0,0.0,1.0 |
|
||||
| `md.sys.motion.easing.standard.accelerate` | PathInterpolator(0.3, 0, 1, 1) | cubic-bezier(0.3,0,1,1) | Cubic(0.3,0,1,1) | ControlPoints 0.3,0.0,1.0,1.0 |
|
||||
|
||||
Compose `MotionTokens.kt` also defines `EasingLegacyCubicBezier` = CubicBezierEasing(0.4, 0.0, 0.2, 1.0)
|
||||
(M2-era "standard" curve) and `EasingLinearCubicBezier` = (0,0,1,1) — not shown on the site pages fetched
|
||||
(not on the site; from androidx `MotionTokens.kt`).
|
||||
|
||||
#### Legacy duration tokens (site table; matches androidx `MotionTokens.kt` exactly)
|
||||
|
||||
| Token | Value |
|
||||
| --- | --- |
|
||||
| `md.sys.motion.duration.short1` | 50ms |
|
||||
| `md.sys.motion.duration.short2` | 100ms |
|
||||
| `md.sys.motion.duration.short3` | 150ms |
|
||||
| `md.sys.motion.duration.short4` | 200ms |
|
||||
| `md.sys.motion.duration.medium1` | 250ms |
|
||||
| `md.sys.motion.duration.medium2` | 300ms |
|
||||
| `md.sys.motion.duration.medium3` | 350ms |
|
||||
| `md.sys.motion.duration.medium4` | 400ms |
|
||||
| `md.sys.motion.duration.long1` | 450ms |
|
||||
| `md.sys.motion.duration.long2` | 500ms |
|
||||
| `md.sys.motion.duration.long3` | 550ms |
|
||||
| `md.sys.motion.duration.long4` | 600ms |
|
||||
| `md.sys.motion.duration.extra-long1` | 700ms |
|
||||
| `md.sys.motion.duration.extra-long2` | 800ms |
|
||||
| `md.sys.motion.duration.extra-long3` | 900ms |
|
||||
| `md.sys.motion.duration.extra-long4` | 1000ms |
|
||||
|
||||
### M3 vs M3 Expressive differences
|
||||
|
||||
- **Physics-based motion system** (springs: stiffness/damping/initial velocity) replaces the
|
||||
easing-and-duration system as the primary motion model. Legacy easing/duration tokens remain as a
|
||||
fallback and still drive some transitions.
|
||||
- Two schemes, **Expressive** and **Standard**, selectable/customizable at up to 3 levels of depth
|
||||
(default scheme → custom scheme → per-element scheme override).
|
||||
- Spring tokens split into **spatial** vs **effects**, each with **fast/default/slow** — a 2×3 matrix per
|
||||
scheme (12 values total across both schemes).
|
||||
- 21 Jetpack Compose components use the physics system by default; component motion is largely driven by
|
||||
just two tokens in practice: **expressive fast spatial** and **expressive fast effects**.
|
||||
- Shape morph (see Shape section) uses the **expressive** motion scheme by default.
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
- No general "prefers-reduced-motion" policy was found stated on `styles/motion` itself. Reduced-motion
|
||||
handling is documented per component instead — e.g. `components/carousel/accessibility`: "When reduced
|
||||
motion settings are turned on, the parallax effect should be removed and carousel items should no
|
||||
longer expand as they come into view. All items are the same size," and hero carousels should keep the
|
||||
small item only partially visible rather than animating it. (Component-level source, included here
|
||||
because it is the only "reduced motion" guidance found in the crawl.)
|
||||
- `components/menus/guidelines`: "In dense products, such as on desktop, menus can open instantly to
|
||||
reduce motion."
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/motion (= /styles/motion/overview = /styles/motion/overview/how-it-works)
|
||||
- https://m3.material.io/styles/motion/overview/specs
|
||||
- https://m3.material.io/styles/motion/easing-and-duration
|
||||
- https://m3.material.io/styles/motion/easing-and-duration/tokens-specs
|
||||
- https://m3.material.io/styles/motion/transitions
|
||||
- https://m3.material.io/components/carousel/accessibility (reduced motion example)
|
||||
- https://m3.material.io/components/menus/guidelines (reduced motion example)
|
||||
- https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/MotionTokens.kt
|
||||
- .../tokens/ExpressiveMotionTokens.kt
|
||||
- .../tokens/StandardMotionTokens.kt
|
||||
|
||||
---
|
||||
|
||||
## Shape
|
||||
|
||||
### Principles
|
||||
|
||||
- The M3 shape system includes original shapes, a corner radius scale, and built-in shape morphing.
|
||||
- Use abstract shapes thoughtfully to add emphasis and decorative flair; leverage Material shapes for
|
||||
built-in shape morphing.
|
||||
- Rectangular shapes are fully rounded in all corners by default; individual corners can be adjusted to
|
||||
create asymmetrical shapes.
|
||||
- Use shape and type "in harmony" — M3 shapes are designed to echo key visual attributes of M3 typography
|
||||
(e.g. M3 shapes and Google Sans Flex share roundness attributes).
|
||||
- Shape morph should respond to user interaction and connect function and feeling — use it to communicate
|
||||
interaction states (e.g. a selected button), actions in progress (e.g. typing, loading), or environment
|
||||
changes (sound, temperature, time of day).
|
||||
- "Be bold and dare to embrace tension" — contrast (square + rounded, unconventional shapes) creates more
|
||||
dynamic, memorable, expressive design; Material historically favored rounded shapes only.
|
||||
- Shape is **versatile, not semantic** — avoid making a shape literal or assigning it one fixed meaning
|
||||
(e.g. a wavy loading indicator isn't a literal progress waveform and could be reused elsewhere).
|
||||
- Use abstract shapes sparingly — don't compromise clarity for visual design; be intentional and consider
|
||||
how a shape fits the product narrative.
|
||||
- Emphasize aesthetic moments (imagery, avatar masking) with shape — these are the most flexible,
|
||||
creative uses.
|
||||
- Shape (with motion) can create a 2.5D illusion of depth on flat visuals.
|
||||
|
||||
### Rules (do/don't)
|
||||
|
||||
- Components can have symmetric (all corners equal) or asymmetric ("inner corner") shapes; both use the
|
||||
same 10-step scale. Asymmetric/inner corners are used in components with closely-grouped items (menus,
|
||||
split buttons) — inner-corner component tokens always map to individual corner-shape tokens.
|
||||
- Customization happens at **style** level (changing what a named style like "medium" resolves to —
|
||||
affects every component mapped to it, unless overridden) or **component** level (remapping one
|
||||
component to a different named style, e.g. remapping a button's default "full" to "small"/"medium").
|
||||
- The shape style family can be customized from **rounded** to **cut** (straight line instead of curve);
|
||||
add extra padding to avoid clipping content, especially in information-dense components. **Caution**:
|
||||
don't apply large/full corners to information-dense components (e.g. cards).
|
||||
- **Optical roundness**: when nesting rounded objects, don't reuse the same radius for both. Formula:
|
||||
**outer radius − padding = inner radius** (example given: 48dp − 14dp = 34dp). **Do** use different,
|
||||
proportional radii for nested components; **don't** use the same radius as the container.
|
||||
- Use the shape library for mostly visual/decorative elements; avoid unconventional shapes on text-heavy
|
||||
containers; use shapes sparingly for emphasis and delight.
|
||||
|
||||
### Values
|
||||
|
||||
#### Corner radius scale (10 styles; matches androidx `ShapeTokens.kt` exactly)
|
||||
|
||||
| # | Style | Value |
|
||||
| --- | --- | --- |
|
||||
| 1 | None | 0dp |
|
||||
| 2 | Extra small | 4dp |
|
||||
| 3 | Small | 8dp |
|
||||
| 4 | Medium | 12dp |
|
||||
| 5 | Large | 16dp |
|
||||
| 6 | Large increased | 20dp |
|
||||
| 7 | Extra large | 28dp |
|
||||
| 8 | Extra large increased | 32dp |
|
||||
| 9 | Extra extra large | 48dp |
|
||||
| 10 | Full | fully rounded (Compose: `CircleShape`, not a fixed dp value) |
|
||||
|
||||
(M2 used a 3-level shape scale based on component-container size; M3 uses this 10-level scale based on
|
||||
corner roundedness instead.)
|
||||
|
||||
#### Shape library
|
||||
|
||||
35 pre-made shapes in the Material shape library (Figma Design Kit / Jetpack Compose `MaterialShapes`
|
||||
API), designed to morph seamlessly into one another. Used by the standard **button group** and
|
||||
**loading indicator** components by default.
|
||||
|
||||
### M3 vs M3 Expressive differences (May 2025 "M3 Expressive update")
|
||||
|
||||
- Added **35 new shapes** and **shape morphing** to the Material Shape Library (Figma) and Jetpack
|
||||
Compose (`MaterialShapes` API).
|
||||
- Added new shape principles and a refreshed art direction.
|
||||
- Added corner-radius tokens: **Large increased (20dp)**, **Extra large increased (32dp)**,
|
||||
**Extra extra large (48dp)** — these three styles are new to the 10-step scale.
|
||||
- Updated "fully rounded" corners to use the dedicated **Full** style; previously this was defined as
|
||||
50% of the component's size.
|
||||
- Shape morphing uses the **expressive** motion scheme by default (see Motion section); can be switched
|
||||
to the standard scheme. Access is via a platform API — Android: Compose `MaterialShapes`; Web: not
|
||||
currently available.
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
No shape-specific accessibility requirements (contrast ratios, color-alone rule, reduced motion) were
|
||||
found on the fetched shape pages. The only adjacent accessibility-flavored guidance is the "optical
|
||||
roundness" and "cut corners need extra padding" rules above, which are about legibility/clipping rather
|
||||
than a formal accessibility requirement.
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/shape (= /styles/shape/overview-principles)
|
||||
- https://m3.material.io/styles/shape/corner-radius-scale
|
||||
- https://m3.material.io/styles/shape/shape-morph
|
||||
- https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/ShapeTokens.kt
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
### Principles
|
||||
|
||||
- Use typography to make content readable and beautiful.
|
||||
- M3 has **one type scale** containing two sets of type styles: **15 baseline** and **15 emphasized**
|
||||
(added in the Expressive update) — 30 styles total, both sets following the same scale from Display
|
||||
Large to Label Small.
|
||||
- Five style **roles**: **Display, Headline, Title, Body, Label** — each with Large/Medium/Small (Display/
|
||||
Headline/Title/Body) — see the type-scale table below for exact members.
|
||||
- **Display**: largest text on screen; short, important text/numerals; best on large screens; can use
|
||||
a more expressive/handwritten/script font; set optical size appropriately.
|
||||
- **Headline**: short, high-emphasis text on smaller screens; can use expressive typefaces if line
|
||||
height/letter spacing are adjusted to preserve readability.
|
||||
- **Title**: medium-emphasis, relatively short text (e.g. dividing secondary content); use caution with
|
||||
expressive/display/handwritten/script fonts here.
|
||||
- **Body**: longer passages; use typefaces meant for body copy, readable at small size; avoid
|
||||
expressive/decorative fonts.
|
||||
- **Label**: small, utilitarian text inside components (e.g. buttons use Label Large) or captions.
|
||||
- Two typeface roles: **Brand** (larger styles — Display/Headline — focused on expression) and **Plain**
|
||||
(smaller styles — Body/Label — focused on readability). Roboto is the default for both.
|
||||
- Typesetting: use **padding + bounding box** method for Web/iOS (line height = bounding box height, text
|
||||
vertically centered — CSS "half-leading"); use the **baseline** method for Android/platform-agnostic
|
||||
specs (distances measured to the invisible baseline a line of text rests on).
|
||||
- **Line height**: recommend a **1.2×** ratio of type size for larger styles (title/headline/display);
|
||||
recommend **~1.5×** for smaller styles (body/label) — too tight undermines flow, too loose feels
|
||||
incohesive.
|
||||
- Use **tabular (monospaced) numbers**, not proportional digits, wherever values change often (tables,
|
||||
clocks) to prevent layout shift and aid scanning.
|
||||
- Language script height: line height can auto-adapt by script category so components (with vertical
|
||||
padding) don't clip. Categories: **Small/base** (~Latin, Cyrillic, Greek, Hebrew, except Vietnamese);
|
||||
**Medium** (~7% taller: Arabic, Chinese, Hindi, Japanese, Korean, Vietnamese, most others); **Large**
|
||||
(~30% taller: Burmese, Telugu); **Extra large** (~100% taller: Nastaliq). Default to Medium since most
|
||||
languages fall there; components with a fixed height are built for Small and may not auto-adapt.
|
||||
- Material's default type scale follows the **Major Second (1.125)** modular scale, anchored to 14 (the
|
||||
base size for body text).
|
||||
|
||||
### Rules (do/don't)
|
||||
|
||||
- Emphasized styles are **not** used by default by Material components — swap the baseline token for the
|
||||
matching emphasized token (e.g. `md.sys.typescale.display-large` → `md.sys.typescale.emphasized.
|
||||
display-large`) deliberately.
|
||||
- Recommended emphasized-style use: badges, buttons (primary actions), extended FAB, selected list items,
|
||||
selected menu items, and generally selection/actions/headlines/other editorial-treatment moments —
|
||||
not just for decoration.
|
||||
- Emphasized can be combined with **weight** (apply to already-bold text) and **context** (apply
|
||||
selectively to selected/unread/key-interaction states) simultaneously.
|
||||
- When customizing the scale: change brand/plain typeface tokens if swapping fonts; adjust line height
|
||||
and letter spacing to refine appearance; **avoid changing type size** (can break component
|
||||
layout/reflow); keep both baseline and emphasized styles visually consistent (e.g. all wider than
|
||||
baseline, not just some).
|
||||
- Customizing the M3 type scale or individual styles may forgo future Material typography token updates.
|
||||
- Hyperlinks: use **primary** (or **tertiary** for a less prominent link) and the text must be
|
||||
**underlined** — never color alone.
|
||||
- **Do** use the same size and same optical weight for Material Symbols paired with text; **don't** mix.
|
||||
|
||||
### Values
|
||||
|
||||
#### Type scale — baseline set (`TypeScaleTokens.kt`)
|
||||
|
||||
| Style | Size | Line height | Tracking | Weight | Family |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Display Large | 57sp | 64sp | −0.2sp | Regular | Brand |
|
||||
| Display Medium | 45sp | 52sp | 0sp | Regular | Brand |
|
||||
| Display Small | 36sp | 44sp | 0sp | Regular | Brand |
|
||||
| Headline Large | 32sp | 40sp | 0sp | Regular | Brand |
|
||||
| Headline Medium | 28sp | 36sp | 0sp | Regular | Brand |
|
||||
| Headline Small | 24sp | 32sp | 0sp | Regular | Brand |
|
||||
| Title Large | 22sp | 28sp | 0sp | Regular | Brand |
|
||||
| Title Medium | 16sp | 24sp | 0.2sp | Medium | Plain |
|
||||
| Title Small | 14sp | 20sp | 0.1sp | Medium | Plain |
|
||||
| Body Large | 16sp | 24sp | 0.5sp | Regular | Plain |
|
||||
| Body Medium | 14sp | 20sp | 0.2sp | Regular | Plain |
|
||||
| Body Small | 12sp | 16sp | 0.4sp | Regular | Plain |
|
||||
| Label Large | 14sp | 20sp | 0.1sp | Medium | Plain |
|
||||
| Label Medium | 12sp | 16sp | 0.5sp | Medium | Plain |
|
||||
| Label Small | 11sp | 16sp | 0.5sp | Medium | Plain |
|
||||
|
||||
#### Type scale — emphasized set (Expressive; same size/line-height/family as baseline, heavier weight
|
||||
and slightly different tracking on some styles)
|
||||
|
||||
| Style | Size | Line height | Tracking | Weight | Family |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Display Large Emphasized | 57sp | 64sp | 0sp | Medium | Brand |
|
||||
| Display Medium Emphasized | 45sp | 52sp | 0sp | Medium | Brand |
|
||||
| Display Small Emphasized | 36sp | 44sp | 0sp | Medium | Brand |
|
||||
| Headline Large Emphasized | 32sp | 40sp | 0sp | Medium | Brand |
|
||||
| Headline Medium Emphasized | 28sp | 36sp | 0sp | Medium | Brand |
|
||||
| Headline Small Emphasized | 24sp | 32sp | 0sp | Medium | Brand |
|
||||
| Title Large Emphasized | 22sp | 28sp | 0sp | Medium | Brand |
|
||||
| Title Medium Emphasized | 16sp | 24sp | 0.15sp | Bold | Plain |
|
||||
| Title Small Emphasized | 14sp | 20sp | 0.1sp | Bold | Plain |
|
||||
| Body Large Emphasized | 16sp | 24sp | 0.15sp | Medium | Plain |
|
||||
| Body Medium Emphasized | 14sp | 20sp | 0.25sp | Medium | Plain |
|
||||
| Body Small Emphasized | 12sp | 16sp | 0.4sp | Medium | Plain |
|
||||
| Label Large Emphasized | 14sp | 20sp | 0.1sp | Bold | Plain |
|
||||
| Label Medium Emphasized | 12sp | 16sp | 0.5sp | Bold | Plain |
|
||||
| Label Small Emphasized | 11sp | 16sp | 0.5sp | Bold | Plain |
|
||||
|
||||
(Size, line height and font family are unchanged between a baseline style and its emphasized counterpart;
|
||||
weight steps up — Regular→Medium or Medium→Bold — and a few styles gain slightly wider tracking. Source:
|
||||
`TypeScaleTokens.kt`; the site's `styles/typography/type-scale-tokens` page describes these sets in prose
|
||||
and confirms "30 styles: 15 baseline, 15 emphasized" and the naming convention, but renders the actual
|
||||
numeric table only inside an interactive, non-text widget.)
|
||||
|
||||
`TypefaceTokens.kt` weight mapping used above: Regular = `FontWeight.Normal`, Medium = `FontWeight.
|
||||
Medium`, Bold = `FontWeight.Bold`; Brand/Plain both default to the platform sans-serif (Compose fallback;
|
||||
the actual M3 web/design spec default typeface is **Roboto** for both Brand and Plain, per
|
||||
`styles/typography/fonts`).
|
||||
|
||||
#### Fonts
|
||||
|
||||
| Font | Role | Notes |
|
||||
| --- | --- | --- |
|
||||
| Roboto | Default (Brand + Plain) | Static; used in the M3 type scale by default; 3,300+ glyphs |
|
||||
| Roboto Flex | Variable, not yet part of the type scale | Axes: Slant, Width, Weight, Grade, Optical Size, plus advanced axes (thick stroke XOPQ, thin stroke YOPQ, counter width XTRA, uppercase height YTUC, lowercase height YTLC, ascender height YTAS, descender depth YTDE, figure height YTFI); width range 25–150 (example) |
|
||||
| Roboto Serif | Variable | Reading-focused; wide weight/width range |
|
||||
| Roboto Mono | Variable | Axes: Weight, Italic; monospaced, good for code/tabular numbers |
|
||||
| Noto Sans | Fallback | Axes: Width, Weight, Italic; 150+ scripts, used when a language is unsupported |
|
||||
|
||||
Font fallback order (e.g. for Roboto Flex): **Roboto Flex → Roboto → Noto Sans**.
|
||||
|
||||
#### Units
|
||||
|
||||
| Platform | Font size unit | Conversion | Letter spacing unit | Conversion |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Android | sp | 1.0 (base) | em | tracking(px) / font size(sp) |
|
||||
| Web | rem | sp / 16 = rem (16px root default) | rem | tracking(px) / font size(sp) |
|
||||
|
||||
Example: 16sp = 1rem; 24sp = 1.5rem; 60sp = 3.75rem. 0.2 tracking / 16sp = 0.0125 em (or rem on web).
|
||||
|
||||
### M3 vs M3 Expressive differences (May 2025 "M3 Expressive update")
|
||||
|
||||
- Added **15 emphasized type styles** alongside the existing 15 baseline styles — 30 total. Emphasized
|
||||
styles have higher weight (and minor tracking adjustments) and are meant for bold/selection/emphasis
|
||||
moments; baseline and emphasized are meant to be used together, not as a full replacement.
|
||||
- New **emphasized token namespace**: `md.sys.typescale.emphasized.<style>` alongside
|
||||
`md.sys.typescale.<style>`.
|
||||
- (Aug 2026, post-Expressive) **Language script height support**: line height can automatically adapt by
|
||||
language script category (small/medium/large/extra large) — see Principles above.
|
||||
- Roboto Flex / variable-font axis guidance (weight, grade, width, optical size — "editorial treatments")
|
||||
is presented as an Expressive-era authoring technique, though Roboto Flex itself is "not yet part of
|
||||
the M3 type scale."
|
||||
|
||||
### Accessibility requirements
|
||||
|
||||
- Text contrast: **≥3:1** for large text (≥14pt bold / ≥18pt regular) and graphics; **≥4.5:1** for small
|
||||
text (restated from `foundations/designing/color-contrast`).
|
||||
- Default typography color is **on surface** (or **on surface variant**).
|
||||
- **Color-alone rule**: hyperlinked text must be **underlined**, in addition to using primary/tertiary color.
|
||||
- Avoid very light/thin weights for body text — low-resolution displays can struggle to render thin type,
|
||||
especially at small sizes; reserve very light weights for larger sizes such as display type.
|
||||
- Avoid excessive weight/bold at small label sizes — it can reduce readability (navigation-bar example).
|
||||
- Tabular numbers should be used where digits change frequently, to avoid disorienting layout shifts.
|
||||
|
||||
### Source URLs
|
||||
|
||||
- https://m3.material.io/styles/typography (= /styles/typography/overview)
|
||||
- https://m3.material.io/styles/typography/type-scale-tokens
|
||||
- https://m3.material.io/styles/typography/fonts
|
||||
- https://m3.material.io/styles/typography/applying-type
|
||||
- https://m3.material.io/styles/typography/editorial-treatments
|
||||
- https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/TypeScaleTokens.kt
|
||||
- .../tokens/TypefaceTokens.kt
|
||||
Reference in New Issue
Block a user