Usability — applying M3 Expressive

foundations specs/foundations/usability.kmd

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).

Quando esta spec se aplica

Triggers primários

Choose between baseline and Expressive variant

Todos os triggers

Apply Expressive (color/shape/motion) to a Koder surface
Audit Expressive deployment for usability regression
Decide emphasis level for a UI element

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

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

R1 — Emphasis ladder

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

Per screen guidance:

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

R2 — Five emphasis vectors

Vector	How it scales	Token source
Color	text-muted → text → primary → error/warning	`themes/color-roles.kmd`
Shape	sharp → standard radius → larger radius → pill/extra-large	`themes/shape-library.kmd`
Size	small → default → large → display	`themes/typography.kmd` R1+R4 (scale per window class)
Motion	no animation → standard → spring → expressive overshoot	`themes/motion.kmd` R9
Containment	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:

Everything emphasized: → user can't find what's important.
Hero on every screen: → hero loses signal value.
Critical for routine actions: → user ignores genuine critical alerts.
Subtle 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 policy reference consumed by component specs.

Cross-link

All themes/*.kmd (color/shape/motion/typography) provide the vectors.
All components/*.kmd apply emphasis levels in their R-suite.
elements.kmd — companion (foundational design principles).
themes/typography.kmd R9 — emphasized scale tokens.
themes/shape-library.kmd R5 — per-preset shape availability.
policies/security.kmd — accessibility contract overlap.
Refs: M3 Usability applying-m3-expressive; Google research blog

Referências

specs/themes/motion.kmd
specs/themes/shape-library.kmd
specs/themes/typography.kmd
specs/themes/color-roles.kmd
specs/foundations/elements.kmd