@expressivecss/expressive 0.14.1 → 0.16.0

package/src/sass/README.md

@@ -1,8 +1,8 @@
 # src/sass
 
 ```
-expressive.scss     entry point - decides cascade order, nothing else
-custom.scss         optional entry - selected partials in the same layers
+expressive.scss     entry point - forwards custom.scss with its defaults
+custom.scss         decides cascade order; optionally loads selected partials
 abstracts/          variables, functions, mixins        (emits no CSS)
 tokens/             M3 design tokens as :root custom properties
 base/               normalize, element defaults, typography, grid
@@ -13,7 +13,8 @@ utilities/          single-purpose helper classes
 `custom.scss` accepts `$components` and `$utilities` lists of partial names,
 in load order. `null` loads the complete group; `()` loads none. Tokens and base
 are always loaded, and the existing font configuration still applies. Its
-default output must equal `expressive.scss`. Use one entry per consumer sheet.
+default output is `expressive.scss`, which forwards it with `$components` and
+`$utilities` hidden. Use one entry per consumer sheet.
 Keep selections in the order of the existing indexes, with icons first, and
 include supporting partials. See the README's smaller-build recipes.
 
@@ -34,7 +35,7 @@ Everything else was removed.
 
 ## Two rules
 
-**1. Every partial starts with the same line.**
+**1. A partial that needs the shared helpers starts with the same line.**
 
 ```scss
 @use "../abstracts" as *;   // components/, base/, tokens/, utilities/
@@ -43,13 +44,13 @@ Everything else was removed.
 
 That single line brings in the breakpoint mixins, the Sass variables (grid,
 font sizes), `z-depth()`, and the `btn-*` mixins.
-There is never a second project-local `@use` to work out — if you find yourself
-adding one, see rule 2.
+A partial that uses none of them leaves the line out. There is never a second
+project-local `@use` to work out — if you find yourself adding one, see rule 2.
 
 **2. Nothing outside `abstracts/` is ever imported by another partial.**
 
 Dependencies point one way: everything depends on `abstracts`, `abstracts`
-depends on nothing. This is what keeps `expressive.scss` the only place cascade
+depends on nothing. This is what keeps `custom.scss` the only place cascade
 order is decided. (This is the Sass dependency graph, not the CSS `@layer`
 list — they happen to be described by the same word.)
 
@@ -61,11 +62,11 @@ decided where its CSS landed in the output. Use a mixin instead:
 ```scss
 // no
 @extend .z-depth-1;
-@extend .surface-variant;
+@extend .surface-container-highest;
 
 // yes
 @include z-depth("1");
-background-color: var(--md-sys-color-surface-variant);
+background-color: var(--md-sys-color-surface-container-highest);
 ```
 
 `@extend` within a single file (placeholders, `.btn-large { @extend .btn; }`) is
@@ -112,6 +113,11 @@ Setting `--md-source` re-themes the whole system at runtime, with no rebuild:
 :root { --md-source: #6750a4; }   /* everything but the error ramp follows */
 ```
 
+To change the compiled default instead, configure the Sass variable:
+`@use "expressive" with ($md-source: #6750a4);`. It lives in
+`abstracts/_variables.scss`, because only `abstracts` is forwarded and
+`meta.load-css()` passes no configuration to the layers.
+
 Two things about that file are load-bearing and non-obvious. **M3 "tone" is
 CIELAB L\*, not OKLCH lightness** — `oklch(40% c h)` is not tone 40, and using it
 drifts far past the just-noticeable difference; the `$tones` table is the
@@ -124,10 +130,10 @@ so they stay. Consume the live name:
 
 ```scss
 // no - locks the rule to one theme
-border-bottom: 1px solid var(--md-sys-color-surface-variant-light);
+border-bottom: 1px solid var(--md-sys-color-outline-variant-light);
 
 // yes
-border-bottom: 1px solid var(--md-sys-color-surface-variant);
+border-bottom: 1px solid var(--md-sys-color-outline-variant);
 ```
 
 `light-dark()` resolves against the element's used `color-scheme` at the point
@@ -222,11 +228,11 @@ the wrong file.
 | A colour/type token | `tokens/_reference.scss` | wire it up in `tokens/_theme.scss` |
 
 Anything under `abstracts/` that emits a selector is a bug: it would put CSS in
-the output at a position `expressive.scss` does not control.
+the output at a position `custom.scss` does not control.
 
 ## Cascade layers
 
-`expressive.scss` declares `@layer tokens, base, components, utilities;` and
+`custom.scss` declares `@layer tokens, base, components, utilities;` and
 loads each layer with `meta.load-css()` — `@forward` cannot appear inside
 `@layer`, which is the only reason the entry file uses a different mechanism
 from every other index file.
@@ -247,8 +253,11 @@ it is not. Layer order *reverses* for important declarations, but the rule that
 matters here is simpler: a normal declaration inside a layer loses to any
 unlayered declaration. Drop the flag from `.hide` and it stops beating a
 consumer's own `display` — silently, and in the common case. Classes whose whole
-job is to be unconditional (`.hide`, `.m-3`, the palette classes) keep it.
-
-A few rules in `components/` still use `!important` for UA resets
-(modal float, staggered-list transitions, textarea padding), not for
-JS-driven geometry. Tap target and the preloader no longer need the flag.
+job is to be unconditional (`.hide`, `.m-3`) keep it.
+
+A few rules in `components/` still use `!important`: reduced-motion resets,
+`.scale-transition` (it must replace the transition of whatever component it
+is added to), the map's overrides of MapLibre's own `!important` styles, and
+the print rules that hide navigation, snackbars, tooltips and the FAB menu.
+None of them is for JS-driven geometry. Tap target, the circular progress
+indicator and `.expressive-textarea` padding no longer need the flag.

package/src/sass/abstracts/_breakpoints.scss

@@ -1,5 +1,4 @@
 @use "sass:map";
-@use "sass:list";
 
 // Material 3 window size classes, expressed as media-query boundaries.
 //

package/src/sass/abstracts/_elevation.scss

@@ -6,8 +6,9 @@
 // only resolves if the extending partial loads the module that defines the
 // class, which forced every component to `@use` a CSS-emitting file and let
 // the dependency graph - not expressive.scss - decide the output order.
-// The `.z-depth-N` classes in base/_global.scss are generated from this map,
-// so the class list and the mixin can never drift apart.
+// The `.z-depth-N` classes in utilities/_z-depth.scss and the
+// --md-sys-elevation-level* tokens in tokens/_elevation.scss are generated
+// from this map, so the classes, the tokens and the mixin cannot drift apart.
 
 $elevations: (
   "0": none,
@@ -19,15 +20,20 @@ $elevations: (
   "5": (0 24px 38px 3px rgba(0, 0, 0, 0.14), 0 9px 46px 8px rgba(0, 0, 0, 0.12), 0 11px 15px -7px rgba(0, 0, 0, 0.2))
 ) !default;
 
-@mixin z-depth($level) {
+@mixin z-depth($level, $important: false) {
   $key: "#{$level}";
   @if not map.has-key($elevations, $key) {
     @error "Unknown elevation `#{$level}`. Available: #{map.keys($elevations)}.";
   }
-  $shadow: map.get($elevations, $key);
-  @if $shadow == none {
-    // Level 0 stays !important: it is used to cancel a shadow a component set.
-    box-shadow: none !important;
+  // Read the system token, so a theme can change a level at runtime;
+  // tokens/_elevation.scss emits one per key of this map.
+  $shadow: var(--md-sys-elevation-level#{$key});
+  // Only the .z-depth-0 utility and the map popup pass $important; the popup
+  // has to beat maplibre-gl.css, which is unlayered. Inside the components
+  // layer an !important would beat every unlayered consumer rule, so a
+  // component that cancels a shadow has to out-specify the rule that set it.
+  @if $important {
+    box-shadow: $shadow !important;
   } @else {
     box-shadow: $shadow;
   }

package/src/sass/abstracts/_index.scss

@@ -5,3 +5,4 @@
 @forward "breakpoints";  // $breakpoints map + bp-up()/bp-down()/bp-between()
 @forward "variables";    // Sass-time knobs: grid, font sizes, flow text
 @forward "mixins";       // btn-*, focus-visible, chart()
+@forward "spring";       // spring(), spring-duration(): M3 springs as linear() easings