@expressivecss/expressive 0.14.1 → 0.16.0

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

@@ -10,10 +10,8 @@
 // pressed are 0.1, not the 0.12 quoted in some secondary sources.
 //
 // Two shapes consume these. An overlay pseudo-element uses the number as an
-// `opacity` directly; a ring drawn with `color-mix()` needs a percentage, so it
-// multiplies by 100% - see the `state-layer-ring` mixin in abstracts.
-
-@use "../abstracts" as *;
+// `opacity` directly; a `color-mix()` tint needs a percentage, which
+// `state-opacity()` in abstracts supplies.
 
 :root,
 :host {

package/src/sass/tokens/_theme.scss

@@ -18,7 +18,7 @@
 //
 // The --md-sys-color-*-light / -dark pairs are deliberately left in place.
 // They are the documented way to re-theme the framework (see the docs' Themes
-// page) and several components reference them directly.
+// page). Components read the live names, not the pairs.
 
 :root, :host {
   // `light dark` means: follow the OS unless an ancestor says otherwise.
@@ -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/_colors.scss

@@ -19,7 +19,12 @@ $_role-named: "primary-container", "secondary-container", "tertiary-container";
 $_role-named-hosts: ":not(.extend):not(.fab-menu)";
 
 @each $role in $sys-color-roles {
-  #{if(list.index($_role-named, $role), ".#{$role}#{$_role-named-hosts}", ".#{$role}")} {
+  $fill: ".#{$role}";
+  @if list.index($_role-named, $role) {
+    $fill: "#{$fill}#{$_role-named-hosts}";
+  }
+
+  #{$fill} {
     background-color: var(--md-sys-color-#{$role});
   }
 

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;
+  }
+}