@expressivecss/expressive 0.15.0 → 0.16.0

package/src/sass/tokens/_contrast.scss

@@ -0,0 +1,94 @@
+@use "sass:list";
+@use "sass:map";
+@use "sass:string";
+@use "../abstracts" as *;
+
+// Contrast levels. M3 offers standard, medium and high contrast schemes; the
+// standard one is tokens/_theme.scss. `contrast="medium"` or
+// `contrast="high"` on the root or on any subtree moves the accent roles,
+// on-surface-variant and the outlines to darker tones in the light scheme
+// and lighter tones in the dark one, from the same ramps, so a runtime
+// --md-source change still reaches them. Surfaces stay where they are.
+//
+// The tones are picked to meet M3's contrast targets against the surfaces
+// (about 4.5:1 for accents in medium and 7:1 in high, 3:1 and more for
+// outlines). They approximate material-color-utilities' contrast curves,
+// which solve a tone per color; they are not that solver's output.
+//
+// `prefers-contrast: more` applies the high scheme unless a `contrast`
+// attribute says otherwise; `contrast="standard"` opts out.
+//
+// The live roles are redeclared here, not the -light/-dark pairs, because a
+// role resolves its pair where it is declared. A page that overrides a pair
+// to re-theme should override it inside its own [contrast] rule too.
+
+// Role name pattern ("#" is the ramp) and [light tone, dark tone].
+$_accent-tones: (
+  "medium": ("#": (30, 87), "on-#": (100, 10), "#-container": (50, 60), "on-#-container": (100, 0)),
+  "high": ("#": (20, 95), "on-#": (100, 0), "#-container": (30, 80), "on-#-container": (100, 0)),
+);
+
+// Role and [ramp, light tone, dark tone].
+$_neutral-tones: (
+  "medium": (
+    "on-surface-variant": ("neutral-variant", 25, 87),
+    "outline": ("neutral-variant", 40, 70),
+    "outline-variant": ("neutral-variant", 60, 50),
+  ),
+  "high": (
+    "on-surface": ("neutral", 0, 100),
+    "on-surface-variant": ("neutral-variant", 20, 90),
+    "outline": ("neutral-variant", 25, 80),
+    "outline-variant": ("neutral-variant", 40, 70),
+  ),
+);
+
+// The error ramp is literal hex and has no tone 87.
+@function _palette($ramp, $tone) {
+  @if $ramp == "error" and $tone == 87 { $tone: 90; }
+  @return var(--md-ref-palette-#{$ramp}#{$tone});
+}
+
+@mixin _role($role, $ramp, $light, $dark) {
+  --md-sys-color-#{$role}: light-dark(#{_palette($ramp, $light)}, #{_palette($ramp, $dark)});
+}
+
+@mixin _scheme($level) {
+  @each $ramp in ("primary", "secondary", "tertiary", "error") {
+    @each $pattern, $tones in map.get($_accent-tones, $level) {
+      $at: string.index($pattern, "#");
+      $role: string.slice($pattern, 1, $at - 1) + $ramp + string.slice($pattern, $at + 1);
+      @include _role($role, $ramp, list.nth($tones, 1), list.nth($tones, 2));
+    }
+  }
+  @each $role, $spec in map.get($_neutral-tones, $level) {
+    @include _role($role, list.nth($spec, 1), list.nth($spec, 2), list.nth($spec, 3));
+  }
+}
+
+// Back to the standard pairs, for a subtree inside a page that asked for
+// more contrast.
+[contrast='standard'],
+:host([contrast='standard']) {
+  @each $role in map.keys(map.get($_neutral-tones, "high")) {
+    --md-sys-color-#{$role}: light-dark(var(--md-sys-color-#{$role}-light), var(--md-sys-color-#{$role}-dark));
+  }
+  @each $ramp in ("primary", "secondary", "tertiary", "error") {
+    @each $pattern in map.keys(map.get($_accent-tones, "high")) {
+      $at: string.index($pattern, "#");
+      $role: string.slice($pattern, 1, $at - 1) + $ramp + string.slice($pattern, $at + 1);
+      --md-sys-color-#{$role}: light-dark(var(--md-sys-color-#{$role}-light), var(--md-sys-color-#{$role}-dark));
+    }
+  }
+}
+
+[contrast='medium'],
+:host([contrast='medium']) { @include _scheme("medium"); }
+
+[contrast='high'],
+:host([contrast='high']) { @include _scheme("high"); }
+
+@media (prefers-contrast: more) {
+  :root:not([contrast]),
+  :host(:not([contrast])) { @include _scheme("high"); }
+}

package/src/sass/tokens/_elevation.scss

@@ -0,0 +1,16 @@
+@use "../abstracts" as *;
+
+// Elevation tokens: one --md-sys-elevation-level<N> shadow per key of
+// $elevations in abstracts/_elevation.scss. The z-depth() mixin and the
+// .z-depth-* classes read these, so a theme can change a level at runtime:
+//
+//   :root { --md-sys-elevation-level1: 0 1px 3px rgb(0 0 0 / 0.3); }
+//
+// Level 0 is `none`, which cancels a shadow.
+
+:root,
+:host {
+  @each $level, $shadow in $elevations {
+    --md-sys-elevation-level#{$level}: #{$shadow};
+  }
+}

package/src/sass/tokens/_index.scss

@@ -4,4 +4,9 @@
 @forward "reference";  // raw ramps + resolved light/dark pairs
 @forward "theme";      // maps the pairs onto the live --md-sys-color-* names
 @forward "vibrant";    // [vibrant] remaps the surface family onto an accent
+@forward "contrast";   // [contrast] medium and high schemes, and prefers-contrast: more
 @forward "state";      // md.sys.state.* state layer opacities
+@forward "motion";     // md.sys.motion.* easing curves and durations
+@forward "shape";      // md.sys.shape.corner.* corner scale
+@forward "elevation";  // md.sys.elevation.level* shadows
+@forward "stacking";   // z-index order for fixed and floating surfaces

package/src/sass/tokens/_motion.scss

@@ -0,0 +1,109 @@
+// Material Design 3 motion tokens: md.sys.motion.easing.* and
+// md.sys.motion.duration.*.
+//
+// Values match material-web/tokens/versions/latest/sass/_md-sys-motion.scss.
+// CSS cannot draw the emphasized curve, which M3 defines as a path, so
+// `emphasized` uses the same cubic-bezier as `standard`, as material-web does.
+//
+// Components read these instead of writing their own curves and times, so
+// one override changes the pace of everything on that step:
+//
+//   :root { --md-sys-motion-duration-short4: 150ms; }
+//
+// Off-scale times (a 2.1s indeterminate loop, a 180ms tooltip) stay literal.
+
+@use "sass:list";
+@use "sass:map";
+@use "../abstracts" as *;
+
+:root,
+:host {
+  --md-sys-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
+  --md-sys-motion-easing-standard-accelerate: cubic-bezier(0.3, 0, 1, 1);
+  --md-sys-motion-easing-standard-decelerate: cubic-bezier(0, 0, 0, 1);
+  --md-sys-motion-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
+  --md-sys-motion-easing-emphasized-accelerate: cubic-bezier(0.3, 0, 0.8, 0.15);
+  --md-sys-motion-easing-emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1);
+  --md-sys-motion-easing-linear: cubic-bezier(0, 0, 1, 1);
+
+  --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 Expressive springs: [damping ratio, stiffness] per speed and kind.
+// Spatial springs move and resize things; effects springs change color and
+// opacity and never overshoot. The expressive scheme only changes the
+// spatial ones. Values from Material's MotionScheme (standard and
+// expressive). Each becomes an easing token and a -duration token.
+$_springs: (
+  "standard": (
+    "fast-spatial": (0.9, 1400), "default-spatial": (0.9, 700), "slow-spatial": (0.9, 300),
+    "fast-effects": (1, 3800), "default-effects": (1, 1600), "slow-effects": (1, 800),
+  ),
+  "expressive": (
+    "fast-spatial": (0.6, 800), "default-spatial": (0.8, 380), "slow-spatial": (0.8, 200),
+  ),
+);
+
+@mixin _springs($scheme) {
+  @each $name, $spring in map.get($_springs, $scheme) {
+    $damping: list.nth($spring, 1);
+    $stiffness: list.nth($spring, 2);
+    --md-sys-motion-spring-#{$name}: #{spring($damping, $stiffness)};
+    --md-sys-motion-spring-#{$name}-duration: #{spring-duration($damping, $stiffness)};
+    // The spring itself, for motion solved at run time from where it is.
+    --md-sys-motion-spring-#{$name}-damping: #{$damping};
+    --md-sys-motion-spring-#{$name}-stiffness: #{$stiffness};
+  }
+}
+
+// Standard is the default; motion="expressive" on the root or a subtree
+// switches the spatial springs, and motion="standard" switches them back.
+:root,
+:host,
+[motion='standard'],
+:host([motion='standard']) {
+  @include _springs("standard");
+}
+
+[motion='expressive'],
+:host([motion='expressive']) {
+  @include _springs("expressive");
+}
+
+// Reduced motion, once for every component that reads these tokens: every
+// duration, scale step and spring alike, becomes 0s, so the change lands
+// without moving. No !important, so a page can still opt an element back in
+// for motion it needs. Off-scale literal times, such as the 2.1s progress
+// loop, are not tokens; their components cancel them in their own
+// reduced-motion rules.
+@media (prefers-reduced-motion: reduce) {
+  :root,
+  :host,
+  [motion],
+  :host([motion]) {
+    @each $step in ("short", "medium", "long", "extra-long") {
+      @for $i from 1 through 4 {
+        --md-sys-motion-duration-#{$step}#{$i}: 0s;
+      }
+    }
+    @each $name in map.keys(map.get($_springs, "standard")) {
+      --md-sys-motion-spring-#{$name}-duration: 0s;
+    }
+  }
+}
+

package/src/sass/tokens/_reference.scss

@@ -1,4 +1,5 @@
 @use "sass:map";
+@use "../abstracts" as *;
 
 // Material Design 3 reference palette.
 //
@@ -21,12 +22,9 @@
 // tests/color-drift.test.js recomputes every generated value and fails if it
 // moves more than DRIFT_BUDGET from the checked-in Material Theme Builder
 // reference, so this cannot regress silently. That test validates the formula
-// against #006495, the one source there is ground truth for - $md-source below
-// is a branding choice and is free to change without failing it.
-
-// Mist Iris is the default seed for the generated ramps. Primary, secondary,
-// tertiary and neutral colors derive from it; the error ramp stays fixed.
-$md-source: #c6a0f6 !default;
+// against #006495, the one source there is ground truth for - $md-source (in
+// abstracts/_variables) is a branding choice and is free to change without
+// failing it.
 
 // tone -> OKLCH lightness. Fitted against the reference ramps; see the test.
 $tones: (
@@ -35,7 +33,7 @@ $tones: (
   40: 48.14%, 50: 56.83%, 60: 65.42%, 70: 74.04%, 80: 82.63%, 87: 88.72%,
   90: 91.33%, 92: 93.05%, 94: 94.76%, 95: 95.62%, 96: 96.50%, 98: 98.25%,
   99: 99.19%, 100: 100%
-) !default;
+);
 
 // Per-ramp hue offset from the source hue, and target chroma. Chroma is a
 // fixed per-role value, not taken from the source - that is M3's model, and it
@@ -56,7 +54,7 @@ $ramps: (
   "tertiary":        ("hue": 62,  "chroma": 0.058),
   "neutral":         ("hue": 17,  "chroma": 0.004),
   "neutral-variant": ("hue":  9,  "chroma": 0.013)
-) !default;
+);
 
 // Which ramp entry each system color resolves to, per scheme.
 $sys-light: (
@@ -83,10 +81,8 @@ $sys-light: (
   "outline": "neutral-variant50", "outline-variant": "neutral-variant80",
   "inverse-surface": "neutral20", "inverse-on-surface": "neutral95",
   "inverse-primary": "primary80",
-  "scrim": "neutral0", "shadow": "neutral0",
-  "background": "neutral98", "on-background": "neutral10",
-  "surface-variant": "neutral-variant90", "surface-tint": "primary40"
-) !default;
+  "scrim": "neutral0", "shadow": "neutral0"
+);
 
 $sys-dark: (
   "primary": "primary80", "on-primary": "primary20",
@@ -112,15 +108,43 @@ $sys-dark: (
   "outline": "neutral-variant60", "outline-variant": "neutral-variant30",
   "inverse-surface": "neutral90", "inverse-on-surface": "neutral10",
   "inverse-primary": "primary40",
-  "scrim": "neutral0", "shadow": "neutral0",
-  "background": "neutral6", "on-background": "neutral90",
-  "surface-variant": "neutral-variant30", "surface-tint": "primary80"
-) !default;
+  "scrim": "neutral0", "shadow": "neutral0"
+);
+
+// M3 type roles: typeface (brand or plain), weight, size, line height, tracking.
+$_typescale: (
+  ("display-large",   brand, 400, 3.5625rem, 4rem,    -0.015625rem),
+  ("display-medium",  brand, 400, 2.8125rem, 3.25rem, 0rem),
+  ("display-small",   brand, 400, 2.25rem,   2.75rem, 0rem),
+  ("headline-large",  brand, 400, 2rem,      2.5rem,  0rem),
+  ("headline-medium", brand, 400, 1.75rem,   2.25rem, 0rem),
+  ("headline-small",  brand, 400, 1.5rem,    2rem,    0rem),
+  ("body-large",      plain, 400, 1rem,      1.5rem,  0.03125rem),
+  ("body-medium",     plain, 400, 0.875rem,  1.25rem, 0.015625rem),
+  ("body-small",      plain, 400, 0.75rem,   1rem,    0.025rem),
+  ("label-large",     plain, 500, 0.875rem,  1.25rem, 0.00625rem),
+  ("label-medium",    plain, 500, 0.75rem,   1rem,    0.03125rem),
+  ("label-small",     plain, 500, 0.6875rem, 1rem,    0.03125rem),
+  ("title-large",     brand, 400, 1.375rem,  1.75rem, 0rem),
+  ("title-medium",    plain, 500, 1rem,      1.5rem,  0.009375rem),
+  ("title-small",     plain, 500, 0.875rem,  1.25rem, 0.00625rem),
+);
+
+// Emphasized weights, from Google's typography guidance: medium for display,
+// headline, title-large and body, bold for title-medium, title-small and
+// label. base/_fonts.scss bundles the 500 and 700 faces.
+$_emphasized-weights: (
+  "display-large": 500, "display-medium": 500, "display-small": 500,
+  "headline-large": 500, "headline-medium": 500, "headline-small": 500,
+  "title-large": 500, "title-medium": 700, "title-small": 700,
+  "body-large": 500, "body-medium": 500, "body-small": 500,
+  "label-large": 700, "label-medium": 700, "label-small": 700,
+);
 
 :root, :host {
   --md-source: #{$md-source};
 
-  /* primary, secondary, tertiary, neutral, neutral-variant - all generated */
+  // primary, secondary, tertiary, neutral, neutral-variant - all generated
   @each $name, $cfg in $ramps {
     $off: map.get($cfg, "hue");
     @each $tone, $l in $tones {
@@ -128,20 +152,16 @@ $sys-dark: (
       $c: map.get($cfg, "chroma");
       @if $tone == 0 or $tone == 100 { $c: 0; }
 
-      @if $off == 0 {
-        --md-ref-palette-#{$name}#{$tone}: oklch(from var(--md-source) #{$l} #{$c} h);
-      } @else {
-        --md-ref-palette-#{$name}#{$tone}: oklch(from var(--md-source) #{$l} #{$c} calc(h + #{$off}));
-      }
+      --md-ref-palette-#{$name}#{$tone}: oklch(from var(--md-source) #{$l} #{$c} calc(h + #{$off}));
     }
   }
 
-  /* error - deliberately NOT generated.
-     M3 fixes the error hue rather than deriving it: "this went wrong" should
-     not rebrand when someone changes their brand color. It is also the ramp
-     where OKLab and CIELAB lightness diverge most (it carries the highest
-     chroma), so generating it was the only one to exceed the JND - 0.027
-     against 0.008 for everything else. Both reasons point the same way. */
+  // error - deliberately NOT generated.
+  // M3 fixes the error hue rather than deriving it: "this went wrong" should
+  // not rebrand when someone changes their brand color. It is also the ramp
+  // where OKLab and CIELAB lightness diverge most (it carries the highest
+  // chroma), so generating it was the only one to exceed the JND - 0.027
+  // against 0.008 for everything else. Both reasons point the same way.
   --md-ref-palette-error0: #000000;
   --md-ref-palette-error10: #410002;
   --md-ref-palette-error20: #690005;
@@ -159,128 +179,39 @@ $sys-dark: (
   --md-ref-palette-error99: #fffbff;
   --md-ref-palette-error100: #ffffff;
 
-  /* light scheme */
+  // light scheme
   @each $role, $ref in $sys-light {
     --md-sys-color-#{$role}-light: var(--md-ref-palette-#{$ref});
   }
 
-  /* dark scheme */
+  // dark scheme
   @each $role, $ref in $sys-dark {
     --md-sys-color-#{$role}-dark: var(--md-ref-palette-#{$ref});
   }
 
-  /* typefaces
-     M3 separates expressive large type (brand) from readable small type
-     (plain). Roboto is the default for both. Noto Sans follows it as the
-     language fallback recommended by Material. Override either brand/plain
-     token to customize the scale without rewriting every role. */
+  // typefaces
+  // M3 separates expressive large type (brand) from readable small type
+  // (plain). Roboto is the default for both. Noto Sans follows it as the
+  // language fallback recommended by Material. Override either brand/plain
+  // token to customize the scale without rewriting every role.
   --md-ref-typeface-brand: "Roboto";
   --md-ref-typeface-plain: "Roboto";
-  --md-ref-typeface-fallback: "Noto Sans", sans-serif;
+  --md-ref-typeface-fallback: "Noto Sans", "Noto Sans Arabic", "Noto Sans Hebrew", "Noto Sans Thai", sans-serif;
 
-  /* display - large */
-  --md-sys-typescale-display-large-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-display-large-font-family-style: Regular;
-  --md-sys-typescale-display-large-font-weight: 400;
-  --md-sys-typescale-display-large-font-size: 3.5625rem;
-  --md-sys-typescale-display-large-line-height: 4rem;
-  --md-sys-typescale-display-large-letter-spacing: -0.015625rem;
-  /* display - medium */
-  --md-sys-typescale-display-medium-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-display-medium-font-family-style: Regular;
-  --md-sys-typescale-display-medium-font-weight: 400;
-  --md-sys-typescale-display-medium-font-size: 2.8125rem;
-  --md-sys-typescale-display-medium-line-height: 3.25rem;
-  --md-sys-typescale-display-medium-letter-spacing: 0rem;
-  /* display - small */
-  --md-sys-typescale-display-small-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-display-small-font-family-style: Regular;
-  --md-sys-typescale-display-small-font-weight: 400;
-  --md-sys-typescale-display-small-font-size: 2.25rem;
-  --md-sys-typescale-display-small-line-height: 2.75rem;
-  --md-sys-typescale-display-small-letter-spacing: 0rem;
-  /* headline - large */
-  --md-sys-typescale-headline-large-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-headline-large-font-family-style: Regular;
-  --md-sys-typescale-headline-large-font-weight: 400;
-  --md-sys-typescale-headline-large-font-size: 2rem;
-  --md-sys-typescale-headline-large-line-height: 2.5rem;
-  --md-sys-typescale-headline-large-letter-spacing: 0rem;
-  /* headline - medium */
-  --md-sys-typescale-headline-medium-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-headline-medium-font-family-style: Regular;
-  --md-sys-typescale-headline-medium-font-weight: 400;
-  --md-sys-typescale-headline-medium-font-size: 1.75rem;
-  --md-sys-typescale-headline-medium-line-height: 2.25rem;
-  --md-sys-typescale-headline-medium-letter-spacing: 0rem;
-  /* headline - small */
-  --md-sys-typescale-headline-small-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-headline-small-font-family-style: Regular;
-  --md-sys-typescale-headline-small-font-weight: 400;
-  --md-sys-typescale-headline-small-font-size: 1.5rem;
-  --md-sys-typescale-headline-small-line-height: 2rem;
-  --md-sys-typescale-headline-small-letter-spacing: 0rem;
-  /* body - large */
-  --md-sys-typescale-body-large-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-body-large-font-family-style: Regular;
-  --md-sys-typescale-body-large-font-weight: 400;
-  --md-sys-typescale-body-large-font-size: 1rem;
-  --md-sys-typescale-body-large-line-height: 1.5rem;
-  --md-sys-typescale-body-large-letter-spacing: 0.03125rem;
-  /* body - medium */
-  --md-sys-typescale-body-medium-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-body-medium-font-family-style: Regular;
-  --md-sys-typescale-body-medium-font-weight: 400;
-  --md-sys-typescale-body-medium-font-size: 0.875rem;
-  --md-sys-typescale-body-medium-line-height: 1.25rem;
-  --md-sys-typescale-body-medium-letter-spacing: 0.015625rem;
-  /* body - small */
-  --md-sys-typescale-body-small-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-body-small-font-family-style: Regular;
-  --md-sys-typescale-body-small-font-weight: 400;
-  --md-sys-typescale-body-small-font-size: 0.75rem;
-  --md-sys-typescale-body-small-line-height: 1rem;
-  --md-sys-typescale-body-small-letter-spacing: 0.025rem;
-  /* label - large */
-  --md-sys-typescale-label-large-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-label-large-font-family-style: Medium;
-  --md-sys-typescale-label-large-font-weight: 500;
-  --md-sys-typescale-label-large-font-size: 0.875rem;
-  --md-sys-typescale-label-large-line-height: 1.25rem;
-  --md-sys-typescale-label-large-letter-spacing: 0.00625rem;
-  /* label - medium */
-  --md-sys-typescale-label-medium-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-label-medium-font-family-style: Medium;
-  --md-sys-typescale-label-medium-font-weight: 500;
-  --md-sys-typescale-label-medium-font-size: 0.75rem;
-  --md-sys-typescale-label-medium-line-height: 1rem;
-  --md-sys-typescale-label-medium-letter-spacing: 0.03125rem;
-  /* label - small */
-  --md-sys-typescale-label-small-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-label-small-font-family-style: Medium;
-  --md-sys-typescale-label-small-font-weight: 500;
-  --md-sys-typescale-label-small-font-size: 0.6875rem;
-  --md-sys-typescale-label-small-line-height: 1rem;
-  --md-sys-typescale-label-small-letter-spacing: 0.03125rem;
-  /* title - large */
-  --md-sys-typescale-title-large-font-family-name: var(--md-ref-typeface-brand), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-title-large-font-family-style: Regular;
-  --md-sys-typescale-title-large-font-weight: 400;
-  --md-sys-typescale-title-large-font-size: 1.375rem;
-  --md-sys-typescale-title-large-line-height: 1.75rem;
-  --md-sys-typescale-title-large-letter-spacing: 0rem;
-  /* title - medium */
-  --md-sys-typescale-title-medium-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-title-medium-font-family-style: Medium;
-  --md-sys-typescale-title-medium-font-weight: 500;
-  --md-sys-typescale-title-medium-font-size: 1rem;
-  --md-sys-typescale-title-medium-line-height: 1.5rem;
-  --md-sys-typescale-title-medium-letter-spacing: 0.009375rem;
-  /* title - small */
-  --md-sys-typescale-title-small-font-family-name: var(--md-ref-typeface-plain), var(--md-ref-typeface-fallback);
-  --md-sys-typescale-title-small-font-family-style: Medium;
-  --md-sys-typescale-title-small-font-weight: 500;
-  --md-sys-typescale-title-small-font-size: 0.875rem;
-  --md-sys-typescale-title-small-line-height: 1.25rem;
-  --md-sys-typescale-title-small-letter-spacing: 0.00625rem;
+  // Type roles.
+  @each $role, $face, $weight, $size, $line-height, $tracking in $_typescale {
+    --md-sys-typescale-#{$role}-font-family-name: var(--md-ref-typeface-#{$face}), var(--md-ref-typeface-fallback);
+    --md-sys-typescale-#{$role}-font-family-style: #{map.get((400: Regular, 500: Medium), $weight)};
+    --md-sys-typescale-#{$role}-font-weight: #{$weight};
+    --md-sys-typescale-#{$role}-font-size: #{$size};
+    --md-sys-typescale-#{$role}-line-height: #{$line-height};
+    --md-sys-typescale-#{$role}-letter-spacing: #{$tracking};
+  }
+
+  // emphasized - M3 Expressive's heavier counterpart of each role. Only the
+  // weight changes; the family, size, line height and tracking are the
+  // baseline role's.
+  @each $role, $weight in $_emphasized-weights {
+    --md-sys-typescale-emphasized-#{$role}-font-weight: #{$weight};
+  }
 }

package/src/sass/tokens/_shape.scss

@@ -0,0 +1,38 @@
+// Material Design 3 corner tokens: md.sys.shape.corner.*, including the
+// Expressive steps (large-increased, extra-large-increased,
+// extra-extra-large).
+//
+// Component shape tokens point at these, the way material-web's do, so a
+// brand that wants squarer or rounder corners overrides the scale once:
+//
+//   :root { --md-sys-shape-corner-medium: 8px; }
+//
+// A component token still wins for one component. `full` is a pill at any
+// height the framework draws; a true circle on a square box is `.circle`.
+
+:root,
+:host {
+  --md-sys-shape-corner-none: 0px;
+  --md-sys-shape-corner-extra-small: 4px;
+  --md-sys-shape-corner-small: 8px;
+  --md-sys-shape-corner-medium: 12px;
+  --md-sys-shape-corner-large: 16px;
+  --md-sys-shape-corner-large-increased: 20px;
+  --md-sys-shape-corner-extra-large: 28px;
+  --md-sys-shape-corner-extra-large-increased: 32px;
+  --md-sys-shape-corner-extra-extra-large: 48px;
+  --md-sys-shape-corner-full: 9999px;
+
+  // The corner family: `round`, or `bevel` for M3's cut corners. Read by
+  // the container surfaces listed in utilities/_helpers.scss.
+  --md-sys-shape-corner-family: round;
+}
+
+// corners="cut" on the root or a subtree cuts its surfaces' corners;
+// corners="round" puts them back. Browsers without `corner-shape` keep
+// rounded corners.
+[corners='cut'],
+:host([corners='cut']) { --md-sys-shape-corner-family: bevel; }
+
+[corners='round'],
+:host([corners='round']) { --md-sys-shape-corner-family: round; }

package/src/sass/tokens/_stacking.scss

@@ -0,0 +1,27 @@
+// Stacking order for everything that floats above the page. Material has no
+// z-index tokens, so these are ours.
+//
+// Lowest to highest: fixed toolbars, top app bars and fixed navigation bars,
+// the modal navigation rail, non-modal sheets, tooltips, docked pickers,
+// snackbars, then the confetti overlay where it cannot use the top layer.
+// Dialogs, modal sheets, open menus, an open lightbox and open popovers sit
+// in the top layer, above all of these, whatever their z-index.
+// --expressive-z-lightbox is kept for pages that read it; the lightbox no
+// longer uses it.
+//
+// Override one to slot an application layer between two of them:
+//
+//   :root { --expressive-z-tooltip: 1500; }
+
+:root,
+:host {
+  --expressive-z-toolbar: 996;
+  --expressive-z-app-bar: 997;
+  --expressive-z-modal-rail: 998;
+  --expressive-z-sheet: 1100;
+  --expressive-z-lightbox: 1200;
+  --expressive-z-tooltip: 2000;
+  --expressive-z-menu: 9999;
+  --expressive-z-snackbar: 10000;
+  --expressive-z-confetti: 10001;
+}

package/src/sass/tokens/_state.scss

@@ -13,8 +13,6 @@
 // `opacity` directly; a `color-mix()` tint needs a percentage, which
 // `state-opacity()` in abstracts supplies.
 
-@use "../abstracts" as *;
-
 :root,
 :host {
   --md-sys-state-hover-state-layer-opacity: 0.08;

package/src/sass/tokens/_theme.scss

@@ -32,7 +32,7 @@
   }
 }
 
-/* ===================================================================== Themes */
+// ===================================================================== Themes
 
 // Opting out of the OS preference. Every token above re-resolves from these.
 // `auto` is the explicit follow-OS value — same as omitting the attribute.
@@ -42,3 +42,12 @@
 :host([theme='dark']) { color-scheme: dark; }
 :root[theme='auto'],
 :host([theme='auto']) { color-scheme: light dark; }
+
+// More contrast is tokens/_contrast.scss: the contrast attribute and
+// prefers-contrast: more.
+
+// Paper is white, and browsers drop backgrounds when printing by default, so
+// a dark scheme prints light text on nothing. Print is always light.
+@media print {
+  :root, :root[theme], :host, :host([theme]) { color-scheme: light; }
+}

package/src/sass/tokens/_vibrant.scss

@@ -34,7 +34,6 @@
 //   outline roles    neutral-variant in M3, not an opacity of the text color.
 //                    Deriving them from on-*-container turns every checkbox,
 //                    radio and switch border inside the subtree translucent.
-//   surface-tint     an accent despite the name - it is the elevation tint.
 //   inverse-*, scrim they exist to contrast with the page, not to follow it.
 //
 // The elevation ladder does collapse: every surface-container rung resolves to
@@ -52,11 +51,10 @@
 // Every surface role, derived rather than restated: a rung added to
 // $sys-color-roles and forgotten here would keep its neutral value and sit as a
 // grey patch on an accent one. `on-` and `inverse-surface` are excluded by the
-// prefix test; surface-tint by name, per the note above.
+// prefix test.
 $_vibrant-surfaces: ();
 @each $role in $sys-color-roles {
-  @if $role == "background" or
-      (string.index($role, "surface") == 1 and $role != "surface-tint") {
+  @if string.index($role, "surface") == 1 {
     $_vibrant-surfaces: list.append($_vibrant-surfaces, $role);
   }
 }
@@ -72,5 +70,4 @@ $_vibrant-surfaces: ();
 
   --md-sys-color-on-surface: var(--md-sys-color-on-tertiary-container);
   --md-sys-color-on-surface-variant: var(--md-sys-color-on-tertiary-container);
-  --md-sys-color-on-background: var(--md-sys-color-on-tertiary-container);
 }

package/src/sass/utilities/_defer-render.scss

@@ -0,0 +1,17 @@
+@use "../abstracts" as *;
+
+// The browser skips layout and paint for each child while it is off screen.
+// A skipped child reserves --defer-render-row-size, or the list item height
+// inside .list, and keeps its last rendered size after it has been on screen.
+// Paint containment clips what a child draws outside its box, so focus rings
+// inside a child are drawn inset, and rows with swipe actions, which wait past
+// the row's end, are left alone. Table rows ignore containment.
+.defer-render > :not(:has(> .swipe-actions)) {
+  content-visibility: auto;
+  contain-intrinsic-block-size: auto var(--defer-render-row-size, var(--md-comp-list-item-height, #{rem(56px)}));
+
+  // -3px is the focus-ring mixin's outline width.
+  :focus-visible {
+    outline-offset: -3px;
+  }
+}