Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Material Design 3 foundations

icedtea maps its design system to Material Design 3. A dated snapshot of the spec pages used in gallery QA lives in .grok/skills/gallery-qa/references/material/ (just material-snapshot). Applying a new number into src/m3 is a human edit after reading that snapshot.

Color roles

Tokens::scheme() maps short token fields onto m3::Scheme roles. light and dark are the desktop pair, not the M3 baseline palettes. Field mapping:

Tokens fieldM3 role
canvassurface
surfacesurface_container
panelsurface_container_high
texton_surface
mutedon_surface_variant
primaryprimary
accentsecondary
dangererror
borderoutline
selectionsecondary_container
selection_texton_secondary_container

Full roles (containers, inverse, scrim) are available via Tokens::scheme(). Success and warning are desktop extensions.

Type

m3::TypeRole implements the M3 type scale (display through label). UI text still uses platform sans (typo::UI); code uses typo::MONO. Constructors read sizes through Tokens::type_px so Tokens::with_font_scale (0.75–1.5) scales body, titles, and code together.

Shape and elevation

m3::Shape is the full M3 scale (0 / 4 / 8 / 12 / 16 / 28 dp and Full). Public controls map through m3::Component. ShapePolicy on Tokens picks the map:

  • Desktop — every family is shape None (0 dp). This is the default.
  • Tight / Soft — one corner (4 / 12 dp) on rounded families. Tabs, app bars, banners, and exclusive segments stay flush (0 dp). Checkbox stays extra-small (4 dp) so the box is not a circle.
  • Pill — buttons, chips, badges, search, and tracks are full; cards, fields, menus, dialogs, toasts, and tooltips stay boxes (12 dp); tabs, app bars, banners, and exclusive segments stay flush.
  • Material — buttons extra-small, chips and badges small (8 dp), toasts and tooltips extra-small (4 dp), cards medium, dialogs and search extra-large (28 dp), tracks full, flush chrome None.

Switch thumbs stay circular via geometry. Tracks use Component::Track. m3::Elevation uses tonal surface containers plus optional shadow. Resting heights match the Material table (0 / 1 / 3 / 6 / 8 / 12 dp). Desktop Level 1 is a visible drop. Elevated buttons raise one level on hover. ElevationPolicy::Flat drops the shadow; surfaces stay on their tonal container. The shape scale is the ten Material steps (0 / 4 / 8 / 12 / 16 / 20 / 28 / 32 / 48 dp) plus Full.

Density

4 dp grid (m3::GRID). Default density: 8 dp space, 12 dp pad, 48 dp touch target.

Components

Every public catalog id is listed in m3::mapping::MAP with fate Map (M3 component family), Desktop (desktop chrome in M3 tokens), or Delete (removed; no dual path). Guide and gallery only host Map and Desktop rows.

Motion

m3::DurationStep and m3::Ease are the M3 duration and easing tokens. Desktop chrome uses the short and medium steps (50–250 ms). Tokens::with_reduced_motion(true) collapses every duration to 0 ms. Constructors take a 0–1 progress; the application owns a motion::Run for a Job (enter, switch, disclose, attention, value). Overlay chrome uses motion::overlay. Next/previous peers use motion::switch (SwitchFace::SharedAxis). Determinate progress uses motion::value_animation; the linear busy bar uses motion::progress_run. See Motion.

Control states

m3::ControlState: enabled, disabled, hovered, focused, pressed, selected, error — matching M3 interactive states.