Usability — applying M3 Expressive

mandatory

Foundation guidance on applying Material 3 Expressive without sacrificing usability. Emphasis ladder (5 levels × 5 vectors), decision matrix for when to emphasize, accessibility constraints (Expressive cannot break AAA contrast or reduced-motion contract).

Spec — Usability (applying M3 Expressive)

Foundational companion para todas as specs Expressive. Resolve: "this surface uses M3 Expressive — qual nível de emphasis aplico? Como manter usabilidade?"

Princípios

*mphasis is a ladder*— 5 níveis (subtle / standard / emphasized / hero / critical).
*ive vectors*— color / shape / size / motion / containment.
*ierarchy = restraint*— only ONE hero element per screen typically.
*ccessibility non~~negotiable*— Expressive cannot break AAA contrast, reduced~~motion, screen-reader semantics.
*esearch-grounded*— based on Google 46 research studies, 18k+ participants (M3 Expressive launch).

R1 — Emphasis ladder

Level	Visual signature	Typical use
ubtle	text-muted color; baseline shape; standard size; no motion	Tertiary text, hint labels, secondary chips
tandard	text color; standard shape; baseline size; standard motion	Default body content, most UI elements
mphasized	primary color OR weight bump; tighter radius OR slightly larger; 1.05 scale on hover	Section headers, secondary CTAs, featured cards
ero	display typography OR primary~~container; rounded~~extra-large radius; large size; spring entrance	Page title, primary CTA, featured artifact
ritical	error/warning color; high contrast; banner; confirmation-required actions	Destructive actions, warnings, alerts

Per screen guidance:

* hero element max*(page title OR primary CTA — choose one).
*-3 emphasized elements*acceptable (section headers, featured cards).
*tandard is default*— most content stays here.
*ubtle for support*— hints, captions.
*ritical sparingly*— overuse → habituation → ignored.

R2 — Five emphasis vectors

Vector	How it scales	Token source
olor	text-muted → text → primary → error/warning	`themes/color-roles.kmd`
hape	sharp → standard radius → larger radius → pill/extra-large	`themes/shape-library.kmd`
ize	small → default → large → display	`themes/typography.kmd` R1+R4 (scale per window class)
otion	no animation → standard → spring → expressive overshoot	`themes/motion.kmd` R9
ontainment	no container → outlined → filled~~tonal → filled~~elevated	`themes/color-roles.kmd` containers

A "hero" element pushes ALL 5 vectors. A "subtle" element pushes NONE.

R3 — Decision matrix: when to emphasize

Is this content the most important on this screen?
├── YES, and it's the primary user goal → hero (R1 level 4)
├── YES, but secondary support → emphasized (R1 level 3)
└── NO:
    ├── User needs to find/read this often → standard (R1 level 2)
    ├── Background/tertiary content → subtle (R1 level 1)
    └── Destructive/critical action → critical (R1 level 5)

Anti-patterns:

*verything emphasized* → user can't find what's important.
*ero on every screen* → hero loses signal value.
*ritical for routine actions* → user ignores genuine critical alerts.
*ubtle for primary text* → readability failure.

R4 — Accessibility constraints (NORMATIVE)

Expressive MUST NOT compromise:

R4.1 — Contrast (AAA per WCAG 2.2)

Text + background combinations always meet AAA in both light + dark themes.
Per themes/color-roles.kmd R4 — Expressive colors are subset of role tokens, not exceptions.
Emphasized text (per typography.kmd R9) MUST still pass AAA — heavier weight does NOT loosen contrast.

R4.2 — Reduced-motion

All motion.kmd R6 reduced-motion rules apply to Expressive springs (R9 motion tokens).
Hero element entrance animation → instant under prefers-reduced-motion.
Shape morph cycles → static fallback.
Hover scale → disabled.

Visual emphasis does NOT replace semantic HTML/ARIA.
A body-large-emphasized is still <p>, not <h2>.
An emphasized button is still role="button", NOT a custom widget.
Containment shifts (R2 vector 5) do NOT replace semantic landmarks.

R4.4 — Touch targets

ALL interactive Expressive elements ≥ 48dp tap area (per Material baseline).
Shape morph on press does NOT reduce target.
Compact button group sizes (XS = 28dp) — accept ≥ 28dp em hover-only contexts (desktop); mobile/touch enforces ≥ 32dp.

R5 — Research backing

Google M3 Expressive launch (2025) ran 46 research studies, 18k+ participants. Key findings adopted as Koder normative:

Finding	Koder application
Emphasized elements increase task completion by ~12% when used sparingly	R1 hero limit (1 per screen)
Over-emphasis (everything emphasized) reduces completion by ~8%	R3 anti-pattern "everything emphasized"
Reduced~~motion users equally task~~efficient when fallbacks honored	R4.2 reduced-motion NORMATIVE
Color emphasis WITHOUT shape emphasis often missed by colorblind users	R2 prefer multi-vector emphasis (color + shape/size)

R6 — Per-preset variation

Emphasis ladder respects preset:

Preset	Hero level visual
`material3`	Subtle emphasized (subtle shape morph + spring)
`material_expressive`	Full emphasized (shape morph + spring + hover scale)
`material2`	Color + size only (no shape morph, no spring)
`terminal_classic`	Uppercase + asterisk markers only (no visual change)
`brutalist`	Sharp corners + 2px border on hero; no spring
`cyberpunk_neon`	Glow + neon outline on hero/critical
`minimalist_mono`	Bold weight + larger size only; no color shift

R7 — Surface bindings

Foundation-level — guidance only; no widget. Applied implicitly via:

koder_kit widgets honor emphasis parameter where applicable (e.g., KoderAIMessageBubble({emphasis: "emphasized"})).
Default emphasis = standard.

R8 — i18n

Foundation-level — no UI strings.

T-suite

Foundation~~level — verified via per~~spec T-clauses that consume this guidance:

Hero limit per screen: per~~product audit (no per~~page validation possible at framework).
AAA contrast (R4.1): verified per widget via existing color-roles.kmd T-suite.
Reduced~~motion fallback (R4.2): verified per widget T~~clauses (Wave 1-5 AI namespace each cover).
Screen-reader (R4.3): per widget aria semantic tests.
Touch targets (R4.4): per widget size-class tests.

This spec acts as *olicy reference*consumed by component specs.

Cross-link

All `themes