@expressivecss/expressive 0.1.0-alpha.3 → 0.2.0

package/dist/{js → types}/components/slider.d.ts

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement } from '../foundation/component';
+import { Component, BaseOptions, InitElements, MElement } from '../core/component';
 export interface SliderOptions extends BaseOptions {
     /**
      * Set to false to hide slide indicators.
@@ -42,7 +42,7 @@ export interface SliderOptions extends BaseOptions {
 export declare class Slider extends Component<SliderOptions> {
     /** Index of current slide. */
     activeIndex: number;
-    interval: string | number | NodeJS.Timeout;
+    interval: ReturnType<typeof setTimeout>;
     eventPause: boolean;
     _slider: HTMLUListElement;
     _slides: HTMLLIElement[];
@@ -70,6 +70,7 @@ export declare class Slider extends Component<SliderOptions> {
     destroy(): void;
     private _setupEventHandlers;
     private _removeEventHandlers;
+    private _handleVisibilityChange;
     private _handleIndicatorClick;
     private _handleAutoPauseHover;
     private _handleAutoPauseFocus;

package/dist/{js → types}/components/tabs.d.ts

@@ -1,5 +1,5 @@
 import { Carousel } from './carousel';
-import { Component, BaseOptions, InitElements, MElement } from '../foundation/component';
+import { Component, BaseOptions, InitElements, MElement } from '../core/component';
 export interface TabsOptions extends BaseOptions {
     /**
      * Transition duration in milliseconds.
@@ -27,7 +27,7 @@ export interface TabsOptions extends BaseOptions {
 export declare class Tabs extends Component<TabsOptions> {
     _tabLinks: NodeListOf<HTMLAnchorElement>;
     _index: number;
-    _indicator: HTMLLIElement;
+    _indicator: HTMLElement;
     _tabWidth: number;
     _tabsWidth: number;
     _tabsCarousel: Carousel;
@@ -56,6 +56,7 @@ export declare class Tabs extends Component<TabsOptions> {
     _setupEventHandlers(): void;
     _removeEventHandlers(): void;
     _handleWindowResize: () => void;
+    _queryTabLinks(): NodeListOf<HTMLAnchorElement>;
     _handleTabClick: (e: MouseEvent) => void;
     _createIndicator(): void;
     _setupActiveTabLink(): void;

package/dist/{js/components/tap-target.d.ts → types/components/tapTarget.d.ts}

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement, Openable } from '../foundation/component';
+import { Component, BaseOptions, InitElements, MElement, Openable } from '../core/component';
 export interface TapTargetOptions extends BaseOptions {
     /**
      * Callback function called when Tap Target is opened.
@@ -39,7 +39,7 @@ export declare class TapTarget extends Component<TapTargetOptions> implements Op
     destroy(): void;
     _setupEventHandlers(): void;
     _removeEventHandlers(): void;
-    _handleThrottledResize: () => void;
+    _handleThrottledResize: (...args: unknown[]) => any;
     _handleKeyboardInteraction: (e: KeyboardEvent) => void;
     _handleTargetToggle: () => void;
     _handleResize: () => void;

package/dist/{js → types}/components/timepicker.d.ts

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement, I18nOptions } from '../foundation/component';
+import { Component, BaseOptions, InitElements, MElement, I18nOptions } from '../core/component';
 export type Views = 'hours' | 'minutes';
 export interface TimepickerOptions extends BaseOptions {
     /**
@@ -129,8 +129,8 @@ export declare class Timepicker extends Component<TimepickerOptions> {
      */
     amOrPm: 'AM' | 'PM';
     static _template: any;
-    /** Vibrate device when dragging clock hand. */
-    vibrate: 'vibrate' | 'webkitVibrate' | null;
+    /** Whether this device exposes the Vibration API at all. */
+    canVibrate: boolean;
     _canvas: HTMLElement;
     hoursView: HTMLElement;
     spanAmPm: HTMLSpanElement;
@@ -140,9 +140,11 @@ export declare class Timepicker extends Component<TimepickerOptions> {
     bg: Element;
     bearing: Element;
     g: Element;
-    toggleViewTimer: string | number | NodeJS.Timeout;
-    vibrateTimer: NodeJS.Timeout | number;
+    toggleViewTimer: ReturnType<typeof setTimeout>;
+    vibrateTimer: ReturnType<typeof setTimeout>;
     private displayPlugin;
+    /** Whether the dial (ticks + SVG + AM/PM buttons) has been built yet. */
+    private _clockBuilt;
     constructor(el: HTMLInputElement, options: Partial<TimepickerOptions>);
     static get defaults(): TimepickerOptions;
     /**
@@ -173,6 +175,12 @@ export declare class Timepicker extends Component<TimepickerOptions> {
     _insertHTMLIntoDOM(): void;
     _setupVariables(): void;
     _pickerSetup(): void;
+    /**
+     * Build the dial, once. Cheap to call repeatedly - every entry point that
+     * touches the clock calls it first, so the picker cannot be interacted with
+     * before it exists.
+     */
+    private _ensureClockBuilt;
     _clockSetup(): void;
     _buildSVGClock(): void;
     _buildHoursView(): void;

package/dist/{js/components/toast.d.ts → types/components/toasts.d.ts}

@@ -1,10 +1,25 @@
-import { BaseOptions } from '../foundation/component';
+import { BaseOptions } from '../core/component';
 export interface ToastOptions extends BaseOptions {
     /**
      * The content of the Toast.
      * @default ""
      */
     text: string;
+    /**
+     * Optional action label. Rendered as a trailing text button.
+     * @default ""
+     */
+    action: string;
+    /**
+     * Called when the action button is pressed. The toast still dismisses.
+     * @default null
+     */
+    onAction: () => void;
+    /**
+     * Show a trailing close icon button.
+     * @default false
+     */
+    dismissible: boolean;
     /**
      * Element Id for the tooltip.
      * @default ""
@@ -56,7 +71,9 @@ export declare class Toast {
     panning: boolean;
     options: ToastOptions;
     message: string;
-    counterInterval: NodeJS.Timeout | number;
+    counterTimeout: ReturnType<typeof setTimeout>;
+    /** Wall-clock time the toast is due to dismiss, for pause/resume. */
+    private _deadline;
     wasSwiped: boolean;
     startingXPos: number;
     xPos: number;
@@ -82,10 +99,17 @@ export declare class Toast {
     _createToast(): HTMLElement;
     _animateIn(): void;
     /**
-     * Create setInterval which automatically removes toast when timeRemaining >= 0
-     * has been reached.
+     * Arm the dismissal timer.
+     *
+     * One timeout, not a 20ms interval ticking a counter down: the old form woke
+     * the page up 50 times a second per toast purely to subtract 20 from a
+     * number. Dragging pauses the countdown via _pauseTimer/_resumeTimer instead.
      */
     _setTimer(): void;
+    /** Stop the countdown, banking the time that was left on it. */
+    _pauseTimer(): void;
+    /** Restart a countdown stopped by {@link _pauseTimer}. */
+    _resumeTimer(): void;
     /**
      * Dismiss toast with animation.
      */

package/dist/{js → types}/components/tooltip.d.ts

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement } from '../foundation/component';
+import { Component, BaseOptions, InitElements, MElement } from '../core/component';
 export type TooltipPosition = 'top' | 'right' | 'bottom' | 'left';
 export interface TooltipOptions extends BaseOptions {
     /**
@@ -24,7 +24,7 @@ export interface TooltipOptions extends BaseOptions {
     /**
      * Set distance tooltip appears away from its activator
      * excluding transitionMovement.
-     * @default 5
+     * @default 4
      */
     margin: number;
     /**

package/dist/types/core/bounding.d.ts

@@ -0,0 +1,6 @@
+export declare class Bounding {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}

package/dist/{js/foundation → types/core}/component.d.ts

@@ -20,7 +20,7 @@ export interface Openable {
     close(): void;
 }
 /**
- * Base class implementation for Materialize components.
+ * Base class implementation for Expressive components.
  */
 export declare class Component<O extends BaseOptions> {
     /**

package/dist/types/core/edges.d.ts

@@ -0,0 +1,6 @@
+export declare class Edges {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+}

package/dist/{js/foundation → types/core}/utils.d.ts

@@ -1,15 +1,5 @@
-export interface Edges {
-    top: boolean;
-    right: boolean;
-    bottom: boolean;
-    left: boolean;
-}
-export interface Bounding {
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-}
+import { Edges } from './edges';
+import { Bounding } from './bounding';
 /**
  * Class with utilitary functions for global usage.
  */
@@ -32,6 +22,14 @@ export declare class Utils {
         ARROW_RIGHT: string[];
         DELETE: string[];
     };
+    /**
+     * Keys that count as keyboard navigation, precomputed.
+     *
+     * These handlers run at capture phase on the document for every keystroke on
+     * the page, and used to rebuild three arrays and spread them into a fourth
+     * on each one.
+     */
+    private static _navigationKeys;
     /**
      * Detects when a key is pressed.
      * @param e Event instance.
@@ -52,6 +50,15 @@ export declare class Utils {
      * @param e Event instance.
      */
     static docHandleBlur(e: FocusEvent): void;
+    /**
+     * Run `callback` once the document is parsed.
+     *
+     * The document-level behaviors all used a bare DOMContentLoaded listener,
+     * which never fires if the bundle is loaded after that event - an async or
+     * deferred script tag, or a dynamic import. Checking readyState first covers
+     * both orders.
+     */
+    static onDocumentReady(callback: () => void): void;
     /**
      * Generates a unique string identifier.
      */
@@ -99,10 +106,10 @@ export declare class Utils {
      * @param wait Wait time.
      * @param options Additional options.
      */
-    static throttle(func: (Function: object) => void, wait: number, options?: Partial<{
+    static throttle(func: (...args: unknown[]) => void, wait: number, options?: Partial<{
         leading: boolean;
         trailing: boolean;
-    }>): (...args: any[]) => any;
+    }>): (...args: unknown[]) => any;
     /**
      * Renders confirm/close buttons with callback function
      */

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from './components';
+export { Dialogs } from './behaviors/dialogs';
+export { Forms } from './behaviors/forms';
+export { Waves } from './behaviors/waves';
+export { AutoInit } from './components/registry';
+export type { AutoInitOptions } from './components/registry';
+export declare const version = "0.2.0";

package/dist/{js/plugins/docked-display.d.ts → types/plugins/dockedDisplayPlugin.d.ts}

@@ -22,6 +22,13 @@ export declare class DockedDisplayPlugin {
     private options;
     private visible;
     constructor(el: HTMLElement, container: HTMLElement, options: Partial<DockedDisplayPluginOptions>);
+    private _handleDocumentClick;
+    /**
+     * Tears the plugin down. The document listener holds a reference to this
+     * instance - and through it the whole picker subtree - so the owning
+     * component must call this from its own destroy().
+     */
+    destroy: () => void;
     /**
      * Initializes instance of DockedDisplayPlugin
      * @param el HTMLElement to position to

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@expressivecss/expressive",
-  "version": "0.1.0-alpha.3",
-  "description": "Material Design 3 CSS framework based on Materialize",
+  "version": "0.2.0",
+  "description": "ExpressiveCSS - a Material Design 3 front-end framework.",
   "license": "MIT",
-  "author": "Javier Baez",
+  "author": "BaezFJ <baezdevs@gmail.com>",
+  "homepage": "https://github.com/BaezFJ/ExpressiveCSS#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BaezFJ/ExpressiveCSS.git"
   },
-  "homepage": "https://github.com/BaezFJ/ExpressiveCSS#readme",
   "bugs": {
     "url": "https://github.com/BaezFJ/ExpressiveCSS/issues"
   },
@@ -18,54 +18,78 @@
     "scss",
     "material-design",
     "material-design-3",
+    "md3",
+    "front-end",
     "framework",
     "ui",
     "components",
-    "responsive",
-    "materialize"
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/js/expressive.cjs",
+  "module": "./dist/js/expressive.mjs",
+  "types": "./dist/types/index.d.ts",
+  "unpkg": "./dist/js/expressive.min.js",
+  "jsdelivr": "./dist/js/expressive.min.js",
+  "sideEffects": [
+    "./dist/js/*",
+    "*.css",
+    "*.scss"
   ],
-  "main": "dist/js/expressive.js",
-  "module": "dist/js/expressive.mjs",
-  "types": "dist/js/index.d.ts",
-  "style": "dist/css/expressive.css",
-  "sass": "src/scss/expressive.scss",
   "exports": {
     ".": {
-      "types": "./dist/js/index.d.ts",
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/js/expressive.mjs",
-      "require": "./dist/js/expressive.js"
+      "require": "./dist/js/expressive.cjs",
+      "default": "./dist/js/expressive.mjs"
     },
     "./css": "./dist/css/expressive.css",
     "./css/min": "./dist/css/expressive.min.css",
-    "./scss": "./src/scss/expressive.scss"
+    "./scss": "./src/sass/expressive.scss",
+    "./scss/*": "./src/sass/*"
   },
+  "files": [
+    "dist",
+    "src/sass"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "dist/",
-    "src/scss/",
-    "LICENSE"
-  ],
-  "sideEffects": [
-    "*.css",
-    "dist/js/expressive.js"
-  ],
   "scripts": {
-    "build:ts": "rollup -c",
-    "build:css": "sass src/scss/expressive.scss dist/css/expressive.css --no-source-map",
-    "build:css:min": "sass src/scss/expressive.scss dist/css/expressive.min.css --no-source-map --style=compressed",
-    "check:ts": "tsc --noEmit",
-    "build": "npm run build:ts && npm run build:css && npm run build:css:min",
-    "prepublishOnly": "npm run build"
+    "prepack": "npm run build",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "run-s clean build:css build:js build:types",
+    "build:css": "run-s build:css:expanded build:css:min",
+    "build:css:expanded": "sass src/sass/expressive.scss dist/css/expressive.css --style=expanded --source-map --load-path=src/sass",
+    "build:css:min": "sass src/sass/expressive.scss dist/css/expressive.min.css --style=compressed --source-map --load-path=src/sass",
+    "build:js": "run-s build:js:esm build:js:cjs build:js:iife build:js:iife-min",
+    "build:js:esm": "esbuild src/ts/index.ts --bundle --format=esm --target=es2020 --outfile=dist/js/expressive.mjs --sourcemap",
+    "build:js:cjs": "esbuild src/ts/index.ts --bundle --format=cjs --target=es2020 --outfile=dist/js/expressive.cjs --sourcemap",
+    "build:js:iife": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.js --sourcemap",
+    "build:js:iife-min": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.min.js --minify --sourcemap",
+    "build:types": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "run-s build:js test:run",
+    "test:run": "node --test",
+    "test:watch": "node --test --watch",
+    "watch": "run-p watch:css watch:js",
+    "watch:css": "sass --watch src/sass/expressive.scss:dist/css/expressive.css --style=expanded --source-map --load-path=src/sass",
+    "watch:js": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.js --sourcemap --watch=forever"
+  },
+  "engines": {
+    "node": ">=20"
   },
+  "browserslist": [
+    "last 5 Chrome versions",
+    "last 5 Firefox versions",
+    "not IE 11",
+    "not dead"
+  ],
   "devDependencies": {
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^12.1.2",
-    "@types/node": "^25.2.1",
-    "rollup": "^4.30.1",
-    "sass": "^1.97.3",
-    "tslib": "^2.8.1",
-    "typescript": "^5.7.3"
+    "esbuild": "^0.28.2",
+    "jsdom": "^30.0.1",
+    "npm-run-all2": "^9.0.3",
+    "sass": "^1.102.0",
+    "typescript": "^7.0.2"
   }
 }

package/src/sass/README.md

@@ -0,0 +1,200 @@
+# src/sass
+
+```
+expressive.scss     entry point - decides cascade order, nothing else
+abstracts/          variables, functions, mixins        (emits no CSS)
+tokens/             M3 design tokens as :root custom properties
+base/               normalize, element defaults, typography, grid
+components/         one file per widget (+ components/forms/)
+utilities/          single-purpose helper classes
+```
+
+## Browser support
+
+The last 5 versions of Chrome and Firefox. No IE, no Edge Legacy. Declared in
+`package.json` under `browserslist` - nothing reads it automatically, since
+there is no autoprefixer or postcss step, but it is the baseline every
+judgement call in here is made against.
+
+That baseline is what licenses `@layer`, `light-dark()`, `color-mix()`,
+`aspect-ratio`, `clamp()`, `inset` and media-query range syntax to be used
+directly, with no fallback. A vendor prefix is only justified now if the
+property is non-standard with no unprefixed equivalent
+(`-webkit-tap-highlight-color`, `-webkit-font-smoothing`) or the selector is an
+engine's private pseudo-element (`::-webkit-slider-thumb`, `::-moz-range-track`).
+Everything else was removed.
+
+## Two rules
+
+**1. Every partial starts with the same line.**
+
+```scss
+@use "../abstracts" as *;   // components/, base/, tokens/, utilities/
+@use "../../abstracts" as *;  // components/forms/
+```
+
+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.
+
+**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
+order is decided. (This is the Sass dependency graph, not the CSS `@layer`
+list — they happen to be described by the same word.)
+
+The trap is `@extend`: it only resolves if the extending file loads the module
+that defines the class, so `@extend .z-depth-1` used to force components to
+`@use` a CSS-emitting file, and whichever partial got loaded first silently
+decided where its CSS landed in the output. Use a mixin instead:
+
+```scss
+// no
+@extend .z-depth-1;
+@extend .surface-variant;
+
+// yes
+@include z-depth("1");
+background-color: var(--md-sys-color-surface-variant);
+```
+
+`@extend` within a single file (placeholders, `.btn-large { @extend .btn; }`) is
+fine — it crosses no boundary.
+
+## Breakpoints
+
+Three of them, in `abstracts/_breakpoints.scss`, reached through mixins:
+
+```scss
+@include bp-up("small")   { }   // @media (width >= 601px)
+@include bp-down("large") { }   // @media (width < 993px)
+@include bp-between("small", "large") { }
+```
+
+Names are `small` (601px), `large` (993px), `xlarge` (1201px) — the boundary a
+query sits on, not the size of the screen it targets. Range syntax has an
+exclusive comparator, so the old `600.99px` / `992.99px` values used to stop
+`max-width` and `min-width` both matching on the boundary pixel are gone, and
+each boundary is written once.
+
+The interpolated-string form (`@media #{$medium-and-up}`) still compiles and now
+produces the same range queries, but it is deprecated and unused in here.
+
+## Theming
+
+`tokens/_reference.scss` **generates** five of the six M3 tonal ramps from
+`--md-source` with relative color syntax, then resolves them into a
+`--md-sys-color-<role>-light` / `-dark` pair per role. `tokens/_theme.scss` maps
+each pair onto the live `--md-sys-color-<role>` name with `light-dark()`, in one
+`@each` over `$sys-color-roles`.
+
+The shipped seed is `#006A79`, a teal. It is chosen, not arbitrary: the error
+ramp is pinned at hue 27.7°, and both primary and tertiary (source + 62°) derive
+from the seed, so the seed has to keep both clear of red. Warm "appetising" hues
+(0–60°) put primary on top of error — ΔEok 0.07–0.12 against ~0.28 for teal.
+Green is avoided so it stays available for a "settled/paid" role, which Material
+does not supply. See the comment above `$md-source`.
+
+Setting `--md-source` re-themes the whole system at runtime, with no rebuild:
+
+```css
+:root { --md-source: #6750a4; }   /* everything but the error ramp follows */
+```
+
+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
+conversion. And the **error ramp is literal hex on purpose**, because Material
+fixes the error hue rather than deriving it. `tests/color-drift.test.js` enforces
+both.
+
+The pairs are public API — the docs' Themes page tells people to override them —
+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);
+
+// yes
+border-bottom: 1px solid var(--md-sys-color-surface-variant);
+```
+
+`light-dark()` resolves against the element's used `color-scheme` at the point
+of *use*, not where the custom property was declared. So `:root[theme='dark']`
+only has to set `color-scheme: dark` and all 30 tokens re-resolve — and setting
+`color-scheme` on any subtree re-themes just that subtree. `color-scheme` is
+load-bearing now; changing it is not cosmetic.
+
+## Translucent colors
+
+```scss
+// no - tokens are hex, not channels; the browser drops the whole declaration
+background-color: rgba(var(--md-sys-color-primary), 0.06);
+
+// yes
+background-color: color-mix(in oklab, var(--md-sys-color-primary) 6%, transparent);
+```
+
+Mix `in oklab`, not `in srgb`. sRGB interpolation darkens and desaturates
+through the midtones, so a 50% tint reads muddier than either endpoint; OKLab is
+perceptually uniform, so a 16% state layer looks like 16% on every hue. Use
+`oklab` rather than `oklch` for mixing: `oklch` interpolates the hue *angle*,
+which can swing a tint through unrelated hues on its way between two colors.
+
+A `var()` that names an undefined custom property fails the same silent way, so
+a typo costs you the rule with no warning at build time. To audit the compiled
+sheet, compare every `var(--x)` reference against every `--x:` definition — the
+names use hyphens, and a regex of `[\w-]+` (not `[a-z-]+`) will also catch
+stragglers written with underscores.
+
+## Where things go
+
+| Adding | Goes in | Then |
+| --- | --- | --- |
+| A component | `components/_thing.scss` | add `@forward "thing";` to `components/_index.scss` |
+| A helper class | `utilities/` — `_z-depth`, `_spacing`, `_visibility`, `_helpers`, `_colors` | add to `utilities/_index.scss` if it is a new file |
+| A shared value or mixin | `abstracts/` | add to `abstracts/_index.scss` |
+| An element default | `base/_global.scss` | — |
+
+A rule is a **utility** when it is one job, one class, and independent of any
+component (`.hide`, `.m-3`, `.truncate`). It belongs in **base** when it styles
+bare elements (`a`, `table`, `blockquote`), and in **components** when it only
+exists to serve one widget — including widgets whose CSS is driven by
+JavaScript rather than by a user-applied class (`.pinned`, `.display-docked`,
+`ul.staggered-list li`). If a selector in `base/` names a component, it is in
+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.
+
+## Cascade layers
+
+`expressive.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.
+
+Three consequences worth knowing:
+
+**Utilities beat components, without specificity.** Layer order outranks
+specificity entirely, so `.hide` wins over `.collection .collection-item` even
+though it is less specific. Utilities used to be emitted *before* components and
+had to out-shout them; they are now last.
+
+**Unlayered CSS beats every layer.** A consumer overriding the framework writes
+plain `.btn { … }` and wins — no specificity war, no dependence on where
+Expressive sits in their bundle. This is the main thing layers buy.
+
+**`!important` is deliberately kept on utilities.** It looks redundant now, and
+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.
+
+The `!important` in `components/` is a different thing again: `.pushpin`,
+`.tap-target` and the preloader set JS-driven geometry that must not be
+overridable. Those stay too.