@greese/ui 0.0.0-stage → 1.0.0

package/src/styles/_kit.scss

@@ -0,0 +1,1548 @@
+// greese ui's SCSS kit for themes and component overrides, compiled in your
+// build (docs/adr/0010-theme-kit-and-studio.md). For example:
+//   @use 'pkg:@greese/ui/scss/kit' as greese;
+//   @include greese.tokens((color: (primary: (light: lavender-600, dark: lavender-300))));
+//   @include greese.component(Button) {
+//     font-weight: 700;
+//     @include greese.vars((tone: greese.token(color, positive)));
+//     @include greese.modifier(outline) { border-width: 2px; }
+//     @include greese.part(icon) { opacity: 0.8; }
+//     @include greese.motion((durations: (fast: 80ms)));
+//   }
+// You write names (`Button`, `icon`, `outline`); the kit adds the `greese-`
+// prefix and the BEM separators, and stops the build on a name the library
+// doesn't have. Token overrides go in `@layer greese.theme`, component
+// overrides in `@layer greese.overrides`: above component styles, below style
+// props and the `greese` prop, and below any unlayered CSS of yours.
+// Using this module emits no CSS by itself. Call its mixins at the top level
+// of a stylesheet, or inside `theme()`.
+@use 'sass:color';
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:math';
+@use 'sass:meta';
+@use 'sass:string';
+@use '../../dist/maps' as defaults;
+@use 'manifest';
+@use 'config';
+@use 'effect';
+@use 'type-emit';
+@forward 'mixins' show up, down, hover, focus-ring, touch-target, motion-safe;
+
+/// Stop the build on unknown components, parts, modifiers, variables and
+/// tokens. Turn off to target classes this version doesn't know yet.
+$strict: true !default;
+$_ordered: false;
+$_theme: null;
+
+// Tokens declared with `tokens(…, $extend: …)`, by group, so `token()` and
+// `component()` variables accept them from then on.
+$_extended: ();
+$_block: null;
+$_part: null;
+$_scheme-attr: 'data-greese-scheme';
+$_theme-attr: 'data-greese-theme';
+
+// Effects defined with `effect()`, by kebab-case name, over the built-in ones.
+$_defined: ();
+$_eases: ('linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'in', 'out', 'in-out');
+
+// --- helpers ---------------------------------------------------------------
+
+/// `primaryContent` → `primary-content`, `lineHeight` → `line-height`; kebab-case stays.
+@function _kebab($name) {
+  $name: '#{$name}';
+  $out: '';
+
+  @for $i from 1 through string.length($name) {
+    $char: string.slice($name, $i, $i);
+    $lower: string.to-lower-case($char);
+
+    @if $char != $lower {
+      $out: $out + '-' + $lower;
+    } @else {
+      $out: $out + $char;
+    }
+  }
+
+  @return string.unquote($out);
+}
+
+@function _join($items) {
+  $out: '';
+
+  @each $item in $items {
+    @if $out == '' {
+      $out: '#{$item}';
+    } @else {
+      $out: '#{$out}, #{$item}';
+    }
+  }
+
+  @if $out == '' {
+    @return '(none)';
+  }
+
+  @return $out;
+}
+
+@function _check($ok, $message) {
+  @if not $ok and $strict {
+    @error 'greese ui kit: #{$message}';
+  }
+
+  @return $ok;
+}
+
+/// A value as CSS text: quoted strings unquote, lists keep inner quotes, and
+/// a palette name (`lavender-600`) becomes its color.
+@function _css($value) {
+  @if meta.type-of($value) == string {
+    @return _palette-name($value) or string.unquote($value);
+  }
+
+  @if meta.type-of($value) == list {
+    @return string.unquote(meta.inspect($value));
+  }
+
+  @return $value;
+}
+
+@function _in($list, $item) {
+  @return list.index($list, $item) != null;
+}
+
+@function _info($block) {
+  @return map.get(manifest.$blocks, $block);
+}
+
+@function _scoped($selector) {
+  @if $_theme {
+    @return "[#{$_theme-attr}='#{$_theme}'] #{$selector}";
+  }
+
+  @return $selector;
+}
+
+@function _scheme($scheme) {
+  @return "[#{$_scheme-attr}='#{$scheme}']";
+}
+
+/// The layer order, once per stylesheet, before the first rule: every
+/// greese ui sheet starts with it, so whichever loads first the order holds.
+/// Without it, a theme loaded before greese ui's CSS would make
+/// `greese.theme` the first, weakest layer.
+@mixin _layer-order {
+  @if not $_ordered {
+    $_ordered: true !global;
+
+    // stylelint-disable-next-line layer-name-pattern -- the whole list, interpolated
+    @layer #{defaults.$layer-order};
+  }
+}
+
+// --- names -----------------------------------------------------------------
+
+@function _block-name($name) {
+  $name: '#{$name}';
+  $known: map.has-key(manifest.$blocks, $name);
+  $checked: _check(
+    $known,
+    'no component `#{$name}`. Components are PascalCase, as in the docs: #{_join(map.keys(manifest.$blocks))}.'
+  );
+
+  @return string.unquote($name);
+}
+
+@function _part-name($block, $part) {
+  $part: _kebab($part);
+  $info: _info($block);
+
+  @if $info {
+    $parts: map.get($info, parts);
+    $checked: _check(
+      _in($parts, $part),
+      '`#{$block}` has no part `#{$part}`. Parts: #{_join($parts)}.'
+    );
+  }
+
+  @return $part;
+}
+
+@function _modifier-name($block, $part, $modifier) {
+  $modifier: _kebab($modifier);
+  $info: _info($block);
+
+  @if $info {
+    @if $part {
+      $mods: map.get($info, part-modifiers, $part) or ();
+      $checked: _check(
+        _in($mods, $modifier),
+        '`#{$block}-#{$part}` has no modifier `#{$modifier}`. Modifiers: #{_join($mods)}.'
+      );
+    } @else {
+      $mods: map.get($info, modifiers);
+      $checked: _check(
+        _in($mods, $modifier),
+        '`#{$block}` has no modifier `#{$modifier}`. Modifiers: #{_join($mods)}.'
+      );
+    }
+  }
+
+  @return $modifier;
+}
+
+/// The selector for a component, part or modifier, prefix included:
+/// `class(Button, $part: icon)` is `.greese-Button-icon`. For your own
+/// selectors: `#{greese.class(Card)} > p { … }`.
+@function class($component, $part: null, $modifier: null) {
+  $block: _block-name($component);
+  $selector: 'greese-#{$block}';
+
+  @if $part {
+    $part: _part-name($block, $part);
+    $selector: '#{$selector}-#{$part}';
+  }
+
+  @if $modifier {
+    $selector: '#{$selector}--#{_modifier-name($block, $part, $modifier)}';
+  }
+
+  @return string.unquote('.#{$selector}');
+}
+
+/// A palette color: `palette(lavender, 600)` is `#7e5bd0`. As a token or
+/// variable value, `lavender-600` does the same.
+@function palette($hue, $shade) {
+  $shades: map.get(defaults.$palette, '#{$hue}');
+  $checked: _check(
+    $shades,
+    'no palette hue `#{$hue}`. Hues: #{_join(map.keys(defaults.$palette))}.'
+  );
+  $value: null;
+
+  @if $shades {
+    $value: map.get($shades, $shade);
+  }
+
+  $checked: _check(
+    $value,
+    'no `#{$hue}` shade `#{$shade}`. Shades: #{_join(map.keys($shades or ()))}.'
+  );
+
+  @return $value;
+}
+
+/// `lavender-600` → `#7e5bd0`; null for anything else. No CSS value looks like
+/// a hue and a shade, so this can't capture one.
+@function _palette-name($value) {
+  $value: '#{$value}';
+  $dash: string.index($value, '-');
+
+  @if not $dash or $dash == 1 {
+    @return null;
+  }
+
+  $shades: map.get(defaults.$palette, string.slice($value, 1, $dash - 1));
+
+  @if not $shades {
+    @return null;
+  }
+
+  $shade: string.slice($value, $dash + 1);
+
+  @each $key, $color in $shades {
+    @if '#{$key}' == $shade {
+      @return $color;
+    }
+  }
+
+  @return null;
+}
+
+@function _is-extended($group, $key) {
+  @return list.index(map.get($_extended, '#{$group}') or (), '#{$key}') != null;
+}
+
+/// A design token: `token(color, accent)` is `var(--greese-color-accent)`.
+@function token($group, $key) {
+  $group: _kebab($group);
+  $key: _kebab($key);
+
+  @if _is-extended($group, $key) {
+    @return var(--greese-#{$group}-#{$key});
+  }
+
+  @if $group == color {
+    $checked: _check(
+      map.has-key(defaults.$color, $key),
+      'no color token `#{$key}`. Colors: #{_join(map.keys(defaults.$color))}.'
+    );
+  } @else {
+    $values: map.get(defaults.$scalars, $group);
+    $checked: _check(
+      $values,
+      'no token group `#{$group}`. Groups: color, #{_join(map.keys(defaults.$scalars))}.'
+    );
+
+    @if $values {
+      $checked: _check(
+        map.has-key($values, '#{$key}'),
+        'no `#{$group}` token `#{$key}`. Keys: #{_join(map.keys($values))}.'
+      );
+    }
+  }
+
+  @return var(--greese-#{$group}-#{$key});
+}
+
+@function _is-token-var($name) {
+  @each $group, $keys in $_extended {
+    @each $key in $keys {
+      @if $name == '--greese-#{$group}-#{$key}' {
+        @return true;
+      }
+    }
+  }
+
+  @each $role, $unused in defaults.$color {
+    @if $name == '--greese-color-#{$role}' {
+      @return true;
+    }
+  }
+
+  @each $group, $values in defaults.$scalars {
+    @each $key, $unused in $values {
+      @if $name == '--greese-#{$group}-#{$key}' {
+        @return true;
+      }
+    }
+  }
+
+  @return false;
+}
+
+/// A component variable's full name. `tone` inside `component(Button)` is
+/// `--greese-button-tone`; full names (`button-tone`, `radius-md`) work
+/// anywhere. Tokens are allowed too: they rescope to that component.
+@function _var-name($name) {
+  $name: _kebab($name);
+  $full: '--greese-#{$name}';
+
+  @if _is-token-var($full) {
+    @return $full;
+  }
+
+  @if $_block {
+    $vars: map.get(_info($_block), variables) or ();
+    $short: '--greese-#{string.to-lower-case($_block)}-#{$name}';
+
+    @if _in($vars, $short) {
+      @return $short;
+    }
+
+    $checked: _check(
+      _in($vars, $full),
+      '`#{$_block}` has no variable `#{$name}`. Its variables: #{_join($vars)}; or any token, such as `radius-md`.'
+    );
+  } @else {
+    $all: ();
+
+    @each $_, $info in manifest.$blocks {
+      $all: list.join($all, map.get($info, variables));
+    }
+
+    $checked: _check(_in($all, $full), 'no variable `#{$full}`.');
+  }
+
+  @return $full;
+}
+
+/// A component variable or token, as `var()`: `variable(button-tone)`.
+@function variable($name) {
+  @return var(#{_var-name($name)});
+}
+
+// --- component overrides ---------------------------------------------------
+
+/// Styles for one component, in `@layer greese.overrides`. Nest `part()`,
+/// `modifier()`, `vars()`, `motion()` and plain declarations inside.
+@mixin component($name) {
+  $block: _block-name($name);
+  $outer-block: $_block;
+  $outer-part: $_part;
+  $_block: $block !global;
+  $_part: null !global;
+
+  @include _layer-order;
+
+  @layer greese.overrides {
+    #{_scoped('.greese-#{$block}')} {
+      @content;
+    }
+  }
+
+  $_block: $outer-block !global;
+  $_part: $outer-part !global;
+}
+
+@function _require-component($mixin) {
+  @return _check($_block, '#{$mixin}() goes inside component().') or true;
+}
+
+/// A part of the component: `part(icon)` is `& .greese-Button-icon`.
+@mixin part($name) {
+  $checked: _require-component('part');
+  $part: _part-name($_block, $name);
+  $outer: $_part;
+  $_part: $part !global;
+
+  & .greese-#{$_block}-#{$part} {
+    @content;
+  }
+
+  $_part: $outer !global;
+}
+
+/// A modifier of the component, or of the enclosing part:
+/// `modifier(solid)` is `&.greese-Button--solid`.
+@mixin modifier($name) {
+  $checked: _require-component('modifier');
+  $modifier: _modifier-name($_block, $_part, $name);
+  $base: 'greese-#{$_block}';
+
+  @if $_part {
+    $base: '#{$base}-#{$_part}';
+  }
+
+  &.#{$base}--#{$modifier} {
+    @content;
+  }
+}
+
+@function _is-duration($name) {
+  @return string.index($name, '--greese-duration-') == 1;
+}
+
+/// Custom properties, prefix added: `vars((tone: red, radius-md: 2px))`.
+/// A `(light: …, dark: …)` value becomes `light-dark()`, which follows the
+/// nearest color scheme. Duration tokens stay out of reduced motion.
+@mixin vars($values) {
+  $calm: ();
+
+  @each $name, $value in $values {
+    $property: _var-name($name);
+
+    @if meta.type-of($value) == map {
+      $value: light-dark(#{_css(map.get($value, light))}, #{_css(map.get($value, dark))});
+    }
+
+    @if _is-duration($property) {
+      $calm: map.set($calm, $property, $value);
+    } @else {
+      #{$property}: #{_css($value)};
+    }
+  }
+
+  @if list.length($calm) > 0 {
+    @media (prefers-reduced-motion: no-preference) {
+      @each $property, $value in $calm {
+        #{$property}: #{_css($value)};
+      }
+    }
+  }
+}
+
+// --- motion ----------------------------------------------------------------
+
+@function _ease($ease) {
+  @if meta.type-of($ease) == string and _in($_eases, _kebab($ease)) {
+    @return var(--greese-ease-#{_kebab($ease)});
+  }
+
+  @return _css($ease);
+}
+
+/// Theme-wide motion for the component: what the `greese` prop does per
+/// instance, as a default for every instance. Pure CSS, behind
+/// `prefers-reduced-motion: no-preference`.
+///
+///   enter      a preset (`fade-up`, `scale-in`, …) played when it appears
+///   keyframes  your own `@keyframes` name, instead of a preset
+///   exit       how an overlay leaves: fade-out, fade-out-up, fade-out-down, scale-out
+///   duration, delay, ease, distance   tune the entrance (`ease: out` or a cubic-bezier())
+///   durations  the component's transition speeds: (fast: 80ms, normal: 150ms)
+///   easings    its transition curves: (standard: cubic-bezier(…))
+///
+/// An instance's own `greese` entrance replaces this one; its `duration`,
+/// `delay` and `ease` tune it.
+@mixin motion($options) {
+  $checked: _require-component('motion');
+  $known: (enter, keyframes, exit, duration, delay, ease, distance, durations, easings);
+
+  @each $key, $unused in $options {
+    $checked: _check(
+      _in($known, $key),
+      'motion() has no option `#{$key}`. Options: #{_join($known)}.'
+    );
+  }
+
+  $enter: map.get($options, enter);
+  $name: map.get($options, keyframes);
+
+  @if $enter {
+    $enter: _kebab($enter);
+    $checked: _check(
+      _in(_effects-with(enter), $enter),
+      'no entrance `#{$enter}`. Effects that end at rest: #{_join(_effects-with(enter))}.'
+    );
+    $name: greese-#{$enter};
+  }
+
+  @if map.has-key($options, distance) {
+    --greese-motion-distance: #{_css(map.get($options, distance))};
+  }
+
+  $exit: map.get($options, exit);
+
+  @if $exit {
+    $exit: _kebab($exit);
+    $checked: _check(
+      _in(_effects-with(exit), $exit),
+      'no exit `#{$exit}`. Effects that end away from rest: #{_join(_effects-with(exit))}.'
+    );
+
+    // As the `exit` classes in Motion.scss: only what the effect changes, so
+    // `fade-out` keeps the overlay's own exit.
+    @each $property, $value in map.get(map.get(_effects(), $exit), exit) {
+      --greese-motion-exit-#{$property}: #{string.unquote($value)};
+    }
+  }
+
+  $tokens: ();
+
+  @each $key, $value in map.get($options, durations) or () {
+    $tokens: map.set($tokens, duration-#{_kebab($key)}, $value);
+  }
+
+  @each $key, $value in map.get($options, easings) or () {
+    $tokens: map.set($tokens, easing-#{_kebab($key)}, $value);
+  }
+
+  @if list.length($tokens) > 0 {
+    @include vars($tokens);
+  }
+
+  @if $name {
+    $duration: _css(map.get($options, duration) or 0.5s);
+    $delay: _css(map.get($options, delay) or 0s);
+    $ease: _ease(map.get($options, ease) or out);
+
+    // `backwards`, as the presets: the first frame holds during the delay,
+    // then the component's own styles apply again.
+    @media (prefers-reduced-motion: no-preference) {
+      animation: #{$name} var(--greese-motion-duration, #{$duration})
+        var(--greese-motion-ease, #{$ease}) var(--greese-motion-delay, #{$delay})
+        backwards;
+    }
+  }
+}
+
+/// Every effect by kebab-case name: the built-in ones and those defined with
+/// `effect()` (which can't take a built-in's name).
+@function _effects() {
+  @return map.merge(defaults.$effects, $_defined);
+}
+
+/// The names of the effects whose plan has `$key`: `enter` (ends at rest, plays
+/// as CSS) or `exit` (ends away from rest, an overlay can leave with it).
+@function _effects-with($key) {
+  $out: ();
+
+  @each $name, $plan in _effects() {
+    @if map.has-key($plan, $key) {
+      $out: list.append($out, $name, comma);
+    }
+  }
+
+  @return $out;
+}
+
+/// The custom properties `motion-defaults()` writes for `$options`, checked.
+@mixin _role-declarations($options, $lists) {
+  $known: map.get($lists, known);
+  $entrances: map.get($lists, entrances);
+  $exits: map.get($lists, exits);
+  $page-entrances: map.get($lists, page-entrances);
+  $page-exits: map.get($lists, page-exits);
+  $page-keywords: map.get($lists, page-keywords);
+  $durations: map.get($lists, durations);
+  $eases: map.get($lists, eases);
+
+  @each $key, $value in $options {
+    $checked: _check(
+      _in($known, $key),
+      'motion-defaults() has no option `#{$key}`. Options: #{_join($known)}.'
+    );
+
+    @if _in($page-entrances, $key) or _in($page-exits, $key) {
+      // A page role names the keyframes its snapshot plays.
+      $name: _kebab($value);
+      $kind: enter;
+      $what: 'entrance';
+      $ends: 'at rest';
+
+      @if _in($page-exits, $key) {
+        $kind: exit;
+        $what: 'exit';
+        $ends: 'away from rest';
+      }
+
+      @if $name != none {
+        $checked: _check(
+          _in(_effects-with($kind), $name),
+          'motion-defaults(): no #{$what} `#{$name}` for `#{$key}`. Effects that end #{$ends}: #{_join(_effects-with($kind))}.'
+        );
+        $name: greese-#{$name};
+      }
+
+      --greese-motion-#{$key}: #{$name};
+    } @else if map.has-key($page-keywords, $key) {
+      $allowed: map.get($page-keywords, $key);
+      $checked: _check(
+        _in($allowed, $value),
+        'motion-defaults(): `#{$key}` is one of #{_join($allowed)}, not `#{$value}`.'
+      );
+
+      --greese-motion-#{$key}: #{$value};
+    } @else if _in($exits, $key) {
+      // An exit by name: everything it sets, under the role's prefix.
+      $name: _kebab($value);
+      $checked: _check(
+        _in(_effects-with(exit), $name),
+        'motion-defaults(): no exit `#{$name}` for `#{$key}`. Effects that end away from rest: #{_join(_effects-with(exit))}.'
+      );
+
+      @each $property, $v in map.get(map.get(_effects(), $name), exit) {
+        --greese-motion-#{$key}-#{$property}: #{string.unquote($v)};
+      }
+    } @else {
+      @if $key == ease {
+        $value: _ease($value);
+      } @else if _in($entrances, $key) {
+        $name: _kebab($value);
+
+        @if $name == none {
+          $value: none;
+        } @else {
+          $checked: _check(
+            _in(_effects-with(enter), $name),
+            'motion-defaults(): no entrance `#{$name}` for `#{$key}`. Effects that end at rest: #{_join(_effects-with(enter))}.'
+          );
+          $value: greese-#{$name};
+        }
+      } @else if _in($durations, $key) and _in((fast, normal, slow), $value) {
+        $value: var(--greese-duration-#{$value});
+      } @else if _in($eases, $key) and _in((standard, enter, exit), $value) {
+        $value: var(--greese-easing-#{$value});
+      } @else if _in($eases, $key) {
+        $value: _ease($value);
+      }
+
+      --greese-motion-#{$key}: #{_css($value)};
+    }
+  }
+}
+
+/// Tunes every `greese` prop entrance on the page (or in the theme), and
+/// assigns the theme's motion roles (ADR 0025):
+///
+///   duration, delay, ease, distance, stagger   every `greese` entrance's pacing
+///   theme      the entrance `greese="theme"` plays (base: fade-up)
+///   content    a tab panel's, an opening accordion's children (base: a short rise)
+///   rows       a table's rows, one after another (base: none)
+///   toast, backdrop                            their entrances
+///   overlay    every overlay's entrance but a drawer's; `dialog`, `popover`
+///              (menus and speed-dial actions too), `tooltip` and `drawer`
+///              (the sidebar too) for one kind
+///   overlay-exit, dialog-exit, popover-exit, tooltip-exit, drawer-exit
+///              how they leave: an exit by name
+///   content-duration, rows-duration, overlay-duration, toast-duration,
+///   backdrop-duration, exit-duration           a duration token (`fast`,
+///              `normal`, `slow`) or a time
+///   enter-ease, exit-ease                      an easing token (`standard`,
+///              `enter`, `exit`), an ease name or a curve
+///   page, page-back                            a page transition's entrance,
+///              going forward and back (ADR 0029; base: fade-in)
+///   page-exit, page-back-exit                  how the old page leaves: an exit
+///              by name (base: fade-out)
+///   page-duration, share-duration              a duration token or a time:
+///              the page's, and a shared element's morph
+///   page-ease, share-ease                      an easing, as above
+///   page-stagger                               seconds between a live exit's
+///              members (base: the entrance stagger)
+///   page-exit-order                            `reverse` (base), `document` or
+///              `together`: the order a live exit's members leave in
+///   page-mode                                  `auto` (base), `snapshot` or
+///              `live`: how a page change plays
+///
+/// `motion-defaults((content: wipe-open-x, dialog: iris-in, dialog-exit: iris-out,
+/// content-duration: slow))`. A role points at an effect or a token: the
+/// effects keep their keyframes and the tokens their values.
+@mixin motion-defaults($options) {
+  $pacing: (duration, delay, ease, distance, stagger);
+  $entrances: (
+    theme,
+    content,
+    rows,
+    toast,
+    backdrop,
+    overlay,
+    dialog,
+    popover,
+    tooltip,
+    drawer
+  );
+  $exits: (overlay-exit, dialog-exit, popover-exit, tooltip-exit, drawer-exit);
+
+  // A page transition's roles (ADR 0029): its entrances and exits are
+  // `@keyframes` names, played on the view transition's snapshots.
+  $page-entrances: (page, page-back);
+  $page-exits: (page-exit, page-back-exit);
+  $page-keywords: (
+    page-exit-order: (
+      reverse,
+      document,
+      together,
+    ),
+    page-mode: (
+      auto,
+      snapshot,
+      live,
+    ),
+  );
+  $durations: (
+    content-duration,
+    rows-duration,
+    overlay-duration,
+    toast-duration,
+    backdrop-duration,
+    exit-duration,
+    page-duration,
+    share-duration
+  );
+  $eases: (enter-ease, exit-ease, page-ease, share-ease);
+  $known: list.join(
+    list.join(list.join($pacing, $entrances), $exits),
+    list.join($durations, $eases)
+  );
+  $known: list.join(
+    $known,
+    list.join(
+      list.join($page-entrances, $page-exits),
+      list.join((page-stagger), map.keys($page-keywords))
+    )
+  );
+  $root: ':root';
+
+  @include _layer-order;
+
+  @if $_theme {
+    $root: "[#{$_theme-attr}='#{$_theme}']";
+  }
+
+  $lists: (
+    known: $known,
+    entrances: $entrances,
+    exits: $exits,
+    page-entrances: $page-entrances,
+    page-exits: $page-exits,
+    page-keywords: $page-keywords,
+    durations: $durations,
+    eases: $eases,
+  );
+
+  @layer greese.overrides {
+    #{$root} {
+      @include _role-declarations($options, $lists);
+    }
+
+    // A theme scoped to an element: its page roles go on the root as well,
+    // while that element is on the page, because a view transition's
+    // snapshots inherit from the root, not from anything inside the page
+    // (ADR 0029).
+    @if $_theme {
+      $page: ();
+
+      @each $key, $value in $options {
+        @if string.index('#{$key}', 'page') == 1 or string.index('#{$key}', 'share') == 1
+        {
+          $page: map.set($page, $key, $value);
+        }
+      }
+
+      @if list.length($page) > 0 {
+        :root:has(#{$root}) {
+          @include _role-declarations($page, $lists);
+        }
+      }
+    }
+  }
+
+  // The keyframes of the entrances it assigns, so the theme works on a page
+  // that hasn't loaded the Motion styles: the effects' own, unchanged.
+  $played: ();
+
+  @each $key, $value in $options {
+    $role: _in($entrances, $key) or _in($page-entrances, $key) or _in($page-exits, $key);
+
+    @if $role and _kebab($value) != none {
+      $played: map.set($played, _kebab($value), true);
+    }
+  }
+
+  @if list.length($played) > 0 {
+    @layer greese.utilities {
+      @media (prefers-reduced-motion: no-preference) {
+        @each $name, $unused in $played {
+          @include effect.keyframes($name, map.get(_effects(), $name), $leave: true);
+        }
+      }
+    }
+  }
+}
+
+/// Selector rules for page transitions (ADR 0029): during a greese page
+/// change, each selector's elements get a snapshot of their own, with their
+/// own effects, rather than moving with the page.
+///
+///   page-transitions((
+///     'header, footer': still,
+///     '.greese-Card': (exit: scale-out, enter: pop-in, duration: fast),
+///     '[data-hero]': (exit: fade-out-up, delay: 0.1s),
+///   ))
+///
+/// A rule is `still` (kept in place, not animated) or a map of `enter` (an
+/// entrance), `exit` (an exit), `duration` (a token or a time), `delay` and
+/// `ease`. What a rule leaves out follows the theme's page roles. The elements
+/// are named only while a greese page change runs
+/// (`:active-view-transition-type(greese-page)`), so other view transitions
+/// never capture them; where that selector or `match-element` isn't supported
+/// they move with the page. Every named element is a snapshot of its own:
+/// name sections, not every item of a long list.
+@mixin page-transitions($rules) {
+  $known: (enter, exit, duration, delay, ease);
+  $during: ':root:active-view-transition-type(greese-page)';
+  $prefix: base;
+  $played: ();
+  $i: 0;
+
+  @if $_theme {
+    $prefix: $_theme;
+  }
+
+  @include _layer-order;
+
+  @layer greese.overrides {
+    @each $selector, $rule in $rules {
+      $i: $i + 1;
+      $class: greese-page-#{$prefix}-#{$i};
+      $classes: string.unquote(
+        'greese-PageTransition greese-PageTransition--theme #{$class}'
+      );
+
+      @if $rule == still {
+        $classes: string.unquote('greese-PageTransition greese-PageTransition--still');
+      } @else {
+        $checked: _check(
+          meta.type-of($rule) == map,
+          'page-transitions(): the rule for `#{$selector}` is `still` or a map of #{_join($known)}.'
+        );
+
+        @each $key, $unused in $rule {
+          $checked: _check(
+            _in($known, $key),
+            'page-transitions(): `#{$selector}` has no option `#{$key}`. Options: #{_join($known)}.'
+          );
+        }
+      }
+
+      // Named only while a greese page change runs; under a theme, only
+      // inside it (the attribute may be on the root itself).
+      @if $_theme {
+        #{$during} [#{$_theme-attr}='#{$_theme}'] :is(#{$selector}),
+        :root[#{$_theme-attr}='#{$_theme}']:active-view-transition-type(greese-page)
+          :is(#{$selector}) {
+          view-transition-name: match-element;
+          view-transition-class: $classes;
+        }
+      } @else {
+        #{$during} :is(#{$selector}) {
+          view-transition-name: match-element;
+          view-transition-class: $classes;
+        }
+      }
+
+      @if $rule != still {
+        $pacing: ();
+
+        @if map.has-key($rule, duration) {
+          $duration: map.get($rule, duration);
+
+          @if _in((fast, normal, slow), $duration) {
+            $duration: var(--greese-duration-#{$duration});
+          }
+
+          $pacing: map.set($pacing, animation-duration, $duration);
+        }
+
+        @if map.has-key($rule, delay) {
+          $pacing: map.set($pacing, animation-delay, map.get($rule, delay));
+        }
+
+        @if map.has-key($rule, ease) {
+          $pacing: map.set(
+            $pacing,
+            animation-timing-function,
+            _ease(map.get($rule, ease))
+          );
+        }
+
+        @each $side, $kind in (enter: enter, exit: exit) {
+          $name: null;
+
+          @if map.has-key($rule, $side) {
+            $name: _kebab(map.get($rule, $side));
+
+            @if $name != none {
+              $checked: _check(
+                _in(_effects-with($kind), $name),
+                'page-transitions(): `#{$selector}` has no #{$side} `#{$name}`. Effects that #{$side}: #{_join(_effects-with($kind))}.'
+              );
+              $played: map.set($played, $name, true);
+            }
+          }
+
+          $pseudo: new;
+
+          @if $side == exit {
+            $pseudo: old;
+          }
+
+          @if $name or $pacing != () {
+            @media (prefers-reduced-motion: no-preference) {
+              html::view-transition-#{$pseudo}(*.#{$class}) {
+                @if $name == none {
+                  animation-name: none;
+                } @else if $name {
+                  animation-name: greese-#{$name};
+                }
+
+                @each $property, $value in $pacing {
+                  #{$property}: #{_css($value)};
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // The keyframes the rules play, so they work without PageTransition's
+  // stylesheet: the effects' own, unchanged.
+  @if list.length($played) > 0 {
+    @layer greese.utilities {
+      @media (prefers-reduced-motion: no-preference) {
+        @each $name, $unused in $played {
+          @include effect.keyframes($name, map.get(_effects(), $name), $leave: true);
+        }
+      }
+    }
+  }
+}
+
+/// Adds a `@keyframes` of your own, for a component's `motion((keyframes: …))`:
+/// `keyframes(greese-float-up, (from: (opacity: 0, translate: 0 2rem), to:
+/// (opacity: 1, translate: 0 0)))`. Steps are `from`, `to` or percentages
+/// (quoted: `'60%'`). A built-in effect's name is refused: a built-in keeps its
+/// keyframes, and a theme assigns another where it wants one (ADR 0025).
+@mixin keyframes($name, $steps) {
+  $checked: _check(
+    string.index('#{$name}', 'greese-') == 1,
+    'keyframes() names start with `greese-`, like `greese-float-up`.'
+  );
+  $checked: _check(
+    not map.has-key(defaults.$effects, string.slice('#{$name}', 8)),
+    'keyframes(#{$name}): a built-in effect keeps its keyframes. Name yours differently and assign it.'
+  );
+
+  @include _layer-order;
+
+  @layer greese.utilities {
+    @keyframes #{$name} {
+      @each $at, $declarations in $steps {
+        #{$at} {
+          @each $property, $value in $declarations {
+            #{$property}: #{_css($value)};
+          }
+        }
+      }
+    }
+  }
+}
+
+/// Defines an effect as CSS, as the built-in ones are: `plan` is `(enter:
+/// (from: (opacity: 0), '60%': (opacity: 1)))` for an effect that ends at the
+/// element's resting state (its `@keyframes`, without the 100% step), or
+/// `(exit: (scale: 0.9))` for one that ends away from it (what an overlay's exit
+/// changes). Theme Studio writes these from its effects, with `cssPlan()` in
+/// @greese/ui, so a new effect works in `motion()` like a built-in, and a
+/// built-in's name is retuned. Names are kebab-case.
+@mixin effect($name, $plan) {
+  $name: _kebab($name);
+  $plan: _normal($plan);
+
+  // A built-in always does what its name says; a theme assigns another
+  // effect where it wants one (ADR 0025), it doesn't rewrite this one.
+  $checked: _check(
+    not map.has-key(defaults.$effects, $name),
+    'effect(#{$name}): `#{$name}` is a built-in effect, which keeps its own plan. Name yours differently and assign it.'
+  );
+  $checked: _check(
+    map.has-key($plan, enter) or map.has-key($plan, exit),
+    'effect(#{$name}) needs a plan with `enter` or `exit`.'
+  );
+  $_defined: map.set($_defined, $name, $plan) !global;
+
+  @include _layer-order;
+
+  @layer greese.utilities {
+    @include effect.classes($name, $plan);
+
+    @media (prefers-reduced-motion: no-preference) {
+      @include effect.keyframes($name, $plan, $leave: true);
+    }
+  }
+}
+
+// --- tokens and themes -----------------------------------------------------
+
+/// Declarations for the token overrides, split by scheme.
+// --- derived brand colors (createTheme's deriveColors, in Sass) -------------
+
+$_derived: (primary, secondary, tertiary, accent, negative);
+
+// The WCAG formula's constants need their full precision, and the inks are
+// literal colors by definition (the same ones @greese/ui uses).
+// stylelint-disable number-max-precision, color-no-hex, color-hex-length
+
+/// WCAG relative luminance of a color.
+@function _luminance($c) {
+  $sum: 0;
+
+  @each $channel, $weight in ('red': 0.2126, 'green': 0.7152, 'blue': 0.0722) {
+    $s: math.div(color.channel($c, $channel, $space: rgb), 255);
+    $linear: math.div($s, 12.92);
+
+    @if $s > 0.04045 {
+      $linear: math.pow(math.div($s + 0.055, 1.055), 2.4);
+    }
+
+    $sum: $sum + $weight * $linear;
+  }
+
+  @return $sum;
+}
+
+@function _ratio($a, $b) {
+  $la: _luminance($a);
+  $lb: _luminance($b);
+
+  @return math.div(math.max($la, $lb) + 0.05, math.min($la, $lb) + 0.05);
+}
+
+/// A color from a hex string (`"#c2410c"`, `"#fff"`), as Theme Studio and
+/// JSON-driven themes write them; colors pass through. Null otherwise.
+@function _hex-color($value) {
+  @if meta.type-of($value) == color {
+    @return $value;
+  }
+
+  @if meta.type-of($value) != string {
+    @return null;
+  }
+
+  $s: string.to-lower-case(string.unquote('#{$value}'));
+
+  @if string.slice($s, 1, 1) != '#' {
+    @return null;
+  }
+
+  $hex: string.slice($s, 2);
+
+  @if string.length($hex) == 3 {
+    $short: $hex;
+    $hex: '';
+
+    @for $i from 1 through 3 {
+      $hex: $hex + string.slice($short, $i, $i) + string.slice($short, $i, $i);
+    }
+  }
+
+  @if string.length($hex) != 6 {
+    @return null;
+  }
+
+  $digits: '0123456789abcdef';
+  $channels: ();
+
+  @for $i from 0 through 2 {
+    $high: string.index($digits, string.slice($hex, $i * 2 + 1, $i * 2 + 1));
+    $low: string.index($digits, string.slice($hex, $i * 2 + 2, $i * 2 + 2));
+
+    @if not $high or not $low {
+      @return null;
+    }
+
+    $channels: list.append($channels, ($high - 1) * 16 + $low - 1);
+  }
+
+  @return rgb(list.nth($channels, 1), list.nth($channels, 2), list.nth($channels, 3));
+}
+
+// The content inks: white, and steel-999 (the dark scheme's content color), as
+// `CONTENT_LIGHT` and `CONTENT_DARK` in contrast.ts (a test keeps them equal).
+$_white: #fff;
+$_dark-ink: #11171c;
+
+/// Text for content on `$c`: as `contentColor()` in @greese/ui, the
+/// more readable of white and near-black if it reaches AA, else black. Null
+/// for anything that isn't a color (a `var()`), which keeps the default.
+@function _content($c) {
+  @if meta.type-of($c) != color {
+    @return null;
+  }
+
+  $light: _ratio($c, $_white);
+  $dark: _ratio($c, $_dark-ink);
+  $best: '#ffffff';
+  $ratio: $light;
+
+  @if $dark > $light {
+    $best: '#11171c';
+    $ratio: $dark;
+  }
+
+  @if $ratio < 4.5 {
+    $best: '#000000';
+  }
+
+  @return string.unquote($best);
+}
+
+// stylelint-enable number-max-precision, color-no-hex, color-hex-length
+
+/// Fills in `-content` and `-strong` for brand colors the overrides set,
+/// unless they set those too.
+@function _derive($colors) {
+  @each $role in $_derived {
+    $main: map.get($colors, '#{$role}');
+
+    @if $main {
+      $pair: $main;
+
+      @if meta.type-of($pair) != map {
+        $pair: (
+          light: $main,
+          dark: $main,
+        );
+      }
+
+      @if not map.has-key($colors, '#{$role}-content') {
+        $fallback: map.get(defaults.$color, '#{$role}-content');
+        $colors: map.set(
+          $colors,
+          '#{$role}-content',
+          (
+            light: _content(_hex-color(_css(map.get($pair, light)))) or
+              map.get($fallback, light),
+            dark: _content(_hex-color(_css(map.get($pair, dark)))) or
+              map.get($fallback, dark),
+          )
+        );
+      }
+
+      @if map.has-key(defaults.$color, '#{$role}-strong') and not
+        map.has-key($colors, '#{$role}-strong')
+      {
+        $self: 'var(--greese-color-#{$role})';
+        $colors: map.set(
+          $colors,
+          '#{$role}-strong',
+          (
+            light: string.unquote('color-mix(in oklab, #{$self} 80%, #000)'),
+            dark: string.unquote('color-mix(in oklab, #{$self} 70%, #fff)'),
+          )
+        );
+      }
+    }
+  }
+
+  @return $colors;
+}
+
+/// The extended tokens known so far, plus these.
+@function _register-extended($extend) {
+  $known: $_extended;
+
+  @each $group, $values in $extend {
+    $list: map.get($known, _kebab($group)) or ();
+
+    @each $key, $unused in $values {
+      $list: list.append($list, '#{_kebab($key)}', comma);
+    }
+
+    $known: map.set($known, _kebab($group), $list);
+  }
+
+  @return $known;
+}
+
+@function _token-decls($overrides, $complete, $extend: ()) {
+  $base: ();
+  $light: ();
+  $dark: ();
+  $durations: ();
+  $type-base: ();
+
+  @each $group, $values in $overrides {
+    $group: _kebab($group);
+    $checked: _check(
+      $group == color or map.has-key(defaults.$scalars, $group),
+      'no token group `#{$group}`. Groups: color, #{_join(map.keys(defaults.$scalars))}.'
+    );
+
+    @each $key, $unused in $values {
+      $key: '#{_kebab($key)}';
+      $known: map.get(defaults.$scalars, $group) or ();
+
+      @if $group == color {
+        $known: defaults.$color;
+      }
+
+      $checked: _check(
+        map.has-key($known, $key),
+        'no `#{$group}` token `#{$key}`. Keys: #{_join(map.keys($known))}.'
+      );
+    }
+  }
+
+  // Normalised overrides: kebab keys, so they match the defaults.
+  $colors: ();
+  $scalars: ();
+
+  @each $group, $values in $overrides {
+    @each $key, $value in $values {
+      @if _kebab($group) == color {
+        $colors: map.set($colors, '#{_kebab($key)}', $value);
+      } @else {
+        $scalars: map.set($scalars, '#{_kebab($group)}', '#{_kebab($key)}', $value);
+      }
+    }
+  }
+
+  $colors: _derive($colors);
+
+  @each $role, $pair in defaults.$color {
+    $value: map.get($colors, $role);
+
+    @if $value or $complete {
+      $value: $value or $pair;
+
+      @if meta.type-of($value) != map {
+        $value: (
+          light: $value,
+          dark: $value,
+        );
+      }
+
+      $pair: $value;
+      $light: map.set($light, --greese-color-#{$role}, _css(map.get($pair, light)));
+      $dark: map.set($dark, --greese-color-#{$role}, _css(map.get($pair, dark)));
+    }
+  }
+
+  // A complete theme declares the type system too: its smallest-screen
+  // values with the tokens, the changes in media queries (see `tokens()`).
+  @if $complete {
+    @each $property, $v in type-emit.base(config.$typography) {
+      $type-base: map.set($type-base, $property, type-emit.value($v));
+    }
+  }
+
+  @each $group, $values in defaults.$scalars {
+    @each $key, $fallback in $values {
+      $value: map.get($scalars, $group, $key);
+
+      @if $value or $complete {
+        $base: map.set($base, --greese-#{$group}-#{$key}, _css($value or $fallback));
+
+        @if $group == duration {
+          $durations: map.set($durations, --greese-#{$group}-#{$key}, 0.01ms);
+        }
+      }
+    }
+  }
+
+  // New tokens: declared, never guessed. Each is `--greese-<group>-<key>`,
+  // alongside the built-in ones; a color takes one value or a light/dark pair.
+  @each $group, $values in $extend {
+    $group: _kebab($group);
+    $checked: _check(
+      $group == color or map.has-key(defaults.$scalars, $group),
+      'no token group `#{$group}` to extend. Groups: color, #{_join(map.keys(defaults.$scalars))}.'
+    );
+
+    @each $key, $value in $values {
+      $key: '#{_kebab($key)}';
+      $known: map.get(defaults.$scalars, $group) or ();
+
+      @if $group == color {
+        $known: defaults.$color;
+      }
+
+      $checked: _check(
+        not map.has-key($known, $key),
+        '`#{$group}` token `#{$key}` already exists: set it in tokens(), not $extend.'
+      );
+      $checked: _check(
+        string.index($key, ' ') == null and string.length($key) > 0,
+        'new token names are kebab-case words, got `#{$key}`.'
+      );
+
+      @if $group == color {
+        @if meta.type-of($value) != map {
+          $value: (
+            light: $value,
+            dark: $value,
+          );
+        }
+
+        $light: map.set($light, --greese-color-#{$key}, _css(map.get($value, light)));
+        $dark: map.set($dark, --greese-color-#{$key}, _css(map.get($value, dark)));
+      } @else {
+        $base: map.set($base, --greese-#{$group}-#{$key}, _css($value));
+
+        @if $group == duration {
+          $durations: map.set($durations, --greese-#{$group}-#{$key}, 0.01ms);
+        }
+      }
+    }
+  }
+
+  @return (
+    base: map.merge($base, $type-base),
+    light: $light,
+    dark: $dark,
+    durations: $durations
+  );
+}
+
+@mixin _declare($map) {
+  @each $property, $value in $map {
+    #{$property}: #{$value};
+  }
+}
+
+/// Token overrides, compiled: the build-time `createTheme()`. Takes the same
+/// groups as `createTheme` in kebab-case, and a color takes one value or a
+/// `(light: …, dark: …)` pair:
+///
+///   @include greese.tokens((
+///     color: (primary: (light: #7c3aed, dark: #c4b5fd), primary-content: #fff),
+///     radius: (md: 12px),
+///   ));
+///
+/// At the top level it changes the page's defaults, overriding only what you
+/// pass. Inside `theme(name)` it declares a complete theme, as `createTheme`
+/// does, for `data-greese-theme="name"`.
+///
+/// To add tokens the system doesn't have, name them in `$extend` (same shape):
+///
+///   @include greese.tokens((), $extend: (
+///     color: (brand-ink: (light: #1b1340, dark: #e5defc)),
+///     space: (9: 4rem),
+///   ));
+///
+/// Each becomes `--greese-<group>-<key>` in the built CSS, and `token()` and
+/// component overrides accept it from then on. Names that already exist, or
+/// groups that don't, still stop the build. (A new `space` key is a variable
+/// only: the responsive classes come with the stylesheet's build.)
+@mixin tokens($overrides, $extend: ()) {
+  $_extended: _register-extended($extend) !global;
+  $d: _token-decls($overrides, $_theme != null, $extend);
+  $base: map.get($d, base);
+  $light: map.get($d, light);
+  $dark: map.get($d, dark);
+  $durations: map.get($d, durations);
+
+  @include _layer-order;
+
+  @layer greese.theme {
+    @if $_theme {
+      $t: "[#{$_theme-attr}='#{$_theme}']";
+      $s: '[#{$_scheme-attr}]';
+
+      #{$t} {
+        @include _declare($base);
+        @include _declare($light);
+      }
+
+      @media (prefers-color-scheme: dark) {
+        #{$t}:not(#{_scheme(light)}) {
+          @include _declare($dark);
+        }
+      }
+
+      #{$t}#{_scheme(dark)},
+      :root#{_scheme(dark)} #{$t}:not(#{$s}) {
+        @include _declare($dark);
+      }
+
+      @include type-emit.emit-media(config.$typography, $t);
+
+      :root#{_scheme(light)} #{$t}:not(#{$s}) {
+        @include _declare($light);
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        #{$t} {
+          @include _declare($durations);
+        }
+      }
+    } @else {
+      // The selectors of the default tokens (tokens.css), one layer up.
+      @if list.length($base) > 0 {
+        :root {
+          @include _declare($base);
+        }
+      }
+
+      @if list.length($light) > 0 {
+        :root,
+        #{_scheme(light)},
+        #{_scheme(system)} {
+          @include _declare($light);
+        }
+
+        @media (prefers-color-scheme: dark) {
+          :root:not(#{_scheme(light)}),
+          #{_scheme(system)} {
+            @include _declare($dark);
+          }
+        }
+
+        #{_scheme(dark)} {
+          @include _declare($dark);
+        }
+      }
+
+      @if list.length($durations) > 0 {
+        @media (prefers-reduced-motion: reduce) {
+          :root {
+            @include _declare($durations);
+          }
+        }
+      }
+    }
+  }
+}
+
+/// The type system's values, for the page or (inside `theme(name)`) for that
+/// theme. Name a variant, then `base` or a breakpoint, then properties; what
+/// you set replaces the default at that point, and the rest stays:
+///
+///   @include greese.typography((
+///     h1: (base: (font-size: 2rem), lg: (font-size: 4rem, letter-spacing: -0.03em)),
+///     caption: (base: (text-transform: uppercase)),
+///   ));
+///
+/// Properties: the CSS names, font-size, font-weight, letter-spacing,
+/// line-height, and font-family, font-style, text-transform,
+/// font-feature-settings, font-variation-settings, font-stretch, text-wrap,
+/// word-spacing, font-variant-numeric, color. Variants: p1-p3,
+/// h1-h6, s1, s2, caption, button. Names that don't exist stop the build.
+@mixin typography($changes) {
+  $merged: ();
+
+  @each $variant, $spec in $changes {
+    $variant: '#{$variant}';
+    $current: map.get(config.$typography, $variant);
+    $checked: _check(
+      $current != null,
+      'no type variant `#{$variant}`. Variants: #{_join(map.keys(config.$typography))}.'
+    );
+
+    @each $point, $style in $spec {
+      $point: '#{$point}';
+      $checked: _check(
+        $point == base or map.has-key(config.$breakpoints, $point),
+        'no breakpoint `#{$point}` for `#{$variant}`. Use base or #{_join(map.keys(config.$breakpoints))}.'
+      );
+
+      @each $prop, $unused in $style {
+        $checked: _check(
+          list.index(defaults.$type-props, '#{$prop}') != null,
+          'no type property `#{$prop}`. Properties: #{_join(defaults.$type-props)}.'
+        );
+      }
+    }
+
+    // Everything this variant has, so its breakpoints stay in step: a theme
+    // layer rule at one point would otherwise beat the defaults above it.
+    $merged: map.set($merged, $variant, map.deep-merge($current, _normal($spec)));
+  }
+
+  @include _layer-order;
+
+  @layer greese.theme {
+    @if $_theme {
+      @include type-emit.emit($merged, "[#{$_theme-attr}='#{$_theme}']");
+    } @else {
+      @include type-emit.emit($merged);
+    }
+  }
+}
+
+/// Keys as strings, so they match the defaults' whatever way they're written.
+@function _normal($map) {
+  $out: ();
+
+  @each $key, $value in $map {
+    @if meta.type-of($value) == map {
+      $value: _normal($value);
+    }
+
+    $out: map.set($out, '#{$key}', $value);
+  }
+
+  @return $out;
+}
+
+/// A named theme: `tokens()` inside declares it for
+/// `data-greese-theme="name"` (set it with `<ThemeProvider>`'s
+/// `data-greese-theme`, or on any element), and `component()`,
+/// `motion-defaults()` inside apply only within it.
+@mixin theme($name) {
+  $checked: _check(
+    meta.type-of($name) == string and string.length('#{$name}') > 0,
+    'theme() needs a name: letters, digits and `-`.'
+  );
+  $outer: $_theme;
+  $_theme: '#{$name}' !global;
+
+  @content;
+
+  $_theme: $outer !global;
+}