maverick-wave 5.8.0 → 5.10.0

package/.claude/skills/mw-maverick-wave/SKILL.md

@@ -44,14 +44,14 @@ Load the one you need - do not read them all up front.
 ```html
 <link
   rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/maverick-wave@5.8.0/maverick-wave.min.css"
+  href="https://cdn.jsdelivr.net/npm/maverick-wave@5.9.0/maverick-wave.min.css"
 />
 <link
   rel="stylesheet"
   href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css"
 />
 ...
-<script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.8.0/maverick-wave.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.9.0/maverick-wave.min.js"></script>
 ```
 
 Pin the version. The JS file is optional and only for server-rendered/static pages -
@@ -151,9 +151,9 @@ keys at all (negative gap is invalid CSS and is not generated).
 `5xl` 3, `6xl` 4.3 rem.
 
 **Breakpoints**: `xs` 375, `sm` 576, `md` 768, `lg` 992, `xl` 1200, `2xl` 1400 px.
-Column grids and most components are mobile-first (`min-width`); the ranges do
-not overlap, `media-down` stops 0.02px short of its breakpoint. Blocks that only
-adjust something on a phone stay `max-width`.
+Column grids and most components are mobile-first. The mixins emit range syntax
+(`media-up` is `width >= bp`, `media-down` is `width < bp`), so the two never
+overlap at the breakpoint itself and neither has to stop a fraction short of it.
 
 **Overriding.** Everything the framework emits sits in
 `@layer mw.reset, mw.base, mw.forms, mw.components, mw.layout, mw.utilities`.
@@ -187,16 +187,23 @@ Two shadows per level - a tight contact layer plus a wide ambient one:
 `0` is explicitly flat. Never write a `box-shadow` by hand - the twelve one-off
 values that used to exist are exactly what this replaced.
 
+**Glow** (`mw-glow`, `mw-glow-{primary,secondary,info,success,warning,danger}`).
+The same two-layer idea without the offset, so the surface reads as giving off
+the light rather than casting a shadow. For the one element on a screen that has
+to be seen first, and for nothing else.
+
 **Motion** `--mw-duration-instant|fast|base|slow|slower` = 110/180/300/520/900ms
 plus `--mw-duration-zoom` (650ms, for a large surface actually travelling),
 `--mw-ease-out` (things arriving - the default), `--mw-ease-in-out` (A to B and
 back), `--mw-ease-spring` (a pop). Two ready-made transitions:
 `var(--mw-transition)` for hover and focus states, `var(--mw-transition-fast)`
 for anything that should feel instant under the pointer. Both list their
-properties explicitly rather than saying `all`.
+properties explicitly rather than saying `all`. All six durations are multiplied
+by `--mw-motion-scale` (default 1), the tempo counterpart to
+`--mw-radius-scale`; `prefers-reduced-motion` overrides the result.
 
 **Control sizes** `--mw-control-height-sm|base|lg` = 1.875 / 2.125 / 2.375rem (an
-even 30 / 34 / 38px step) and
+even 30 / 34 / 38px step, moved by `mw-density-compact` and `-roomy`) and
 `--mw-control-font-sm|base|lg` = 0.8 / 0.9 / 1rem, shared by `mw-input`,
 `mw-select`, `mw-textarea` and `mw-btn`. A field and the button beside it are
 the same height by construction. Buttons run one font step above the fields.
@@ -264,7 +271,8 @@ feature frame) ·
 `mw-skip-link` · `mw-row-split` (+ `center`) · `mw-text-numeric` /
 `mw-text-currency` · `mw-text-truncate` / `mw-text-clamp-2..5` /
 `mw-text-break` / `mw-text-nowrap` · `mw-text-balance` / `mw-text-pretty` /
-`mw-text-eyebrow` / `mw-text-measure` · `mw-elevation-0..5` ·
+`mw-text-eyebrow` / `mw-text-measure` · `mw-elevation-0..5` · `mw-glow` /
+`mw-glow-{primary,secondary,info,success,warning,danger}` ·
 `mw-corner-plain` ·
 `mw-aspect-square|video|wide|portrait|photo` · `mw-d-{sm,md,lg,xl}-*` /
 `mw-hide-mobile` / `mw-hide-desktop` · `mw-overflow-*` / `mw-snap-x` ·
@@ -342,10 +350,12 @@ feature frame) ·
     and the open state come from, and it works without script. The framework JS
     only adds Escape and click-outside. Writing your own div-plus-click loses all
     of it.
-17. **An open dropdown is clipped by anything that hides its overflow.** The menu
-    is absolutely positioned. The framework's own containers - panel, card, tile,
-    modal body, responsive table - lift the clip while a menu is open. On your
-    own container it is one line:
+17. **An open dropdown can be clipped by anything that hides its overflow.**
+    Where the browser supports anchor positioning the menu is `position: fixed`
+    and anchored to its trigger, so it escapes the clip on its own. Everywhere
+    else it is absolutely positioned and cut off. Either way the framework's own
+    containers (panel, card, tile, modal body, responsive table) lift the clip
+    while a menu is open. On your own container it is one line:
     `:has(.mw-dropdown[open]) { overflow: visible }`.
 18. **Never write `box-shadow` by hand.** Use `var(--mw-elevation-1..5)` or the
     `mw-elevation-*` class. A hand-rolled shadow is the wrong colour in one of

package/.claude/skills/mw-maverick-wave/examples/angular-services.md

@@ -18,7 +18,13 @@ const STORAGE_KEY = 'mw-theme';
 
 @Injectable({ providedIn: 'root' })
 export class ThemeService {
-  readonly light = signal(localStorage.getItem(STORAGE_KEY) === 'light');
+  // With nothing stored the stylesheet already follows the OS, so the initial
+  // value only has to agree with what is on screen
+  readonly light = signal(
+    localStorage.getItem(STORAGE_KEY)
+      ? localStorage.getItem(STORAGE_KEY) === 'light'
+      : matchMedia('(prefers-color-scheme: light)').matches
+  );
 
   constructor() {
     effect(() => {
@@ -27,6 +33,9 @@ export class ThemeService {
 
       root.classList.add('mw-theme-switching');
       document.body.classList.toggle('mw-theme-light', light);
+      // the explicit counterpart - without it a dark choice on a light machine
+      // falls back to the OS preference
+      document.body.classList.toggle('mw-theme-dark', !light);
       void root.offsetHeight; // commit the colours with transitions off
       root.classList.remove('mw-theme-switching');
 

package/.claude/skills/mw-maverick-wave/examples/static-landing-page.md

@@ -20,7 +20,7 @@ accordion FAQ.
 
     <link
       rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.8.0/maverick-wave.min.css"
+      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.9.0/maverick-wave.min.css"
     />
     <link
       rel="stylesheet"
@@ -487,7 +487,7 @@ accordion FAQ.
       <div class="mw-modal-backdrop" onclick="closeModal('demo')"></div>
     </div>
 
-    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.8.0/maverick-wave.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.9.0/maverick-wave.min.js"></script>
     <script>
       // The only thing the shipped script does not cover: opening a modal.
       // Closing works through .mw-modal-close, the backdrop is wired above.
@@ -505,7 +505,8 @@ accordion FAQ.
 ## Notes
 
 - The theme toggle needs no code - the script persists the choice under
-  `localStorage['mw-theme']`, toggles `mw-theme-light` on `<body>` and wraps the
+  `localStorage['mw-theme']`, toggles `mw-theme-light` / `mw-theme-dark` on
+  `<body>` and wraps the
   flip in `mw-theme-switching` so it starts no transitions.
 - The scroll spy sets `mw-active` on the `mw-navbar-link` whose `href` matches
   the `section[id]` currently in view - the `<section id="…">` elements are

package/.claude/skills/mw-maverick-wave/references/components.md

@@ -224,13 +224,21 @@ picker.
   means it sits right, not left. Everything is vertically centered, so plain text
   lines up with a button next to it. Actions that no longer fit next to each
   other wrap.
-- The footer stacks to full-width children once the **card** is narrower than
-  360px, not once the window is - a card in a three-column grid is just as narrow
-  on a 1200px desktop as it is on a phone, and now looks the same in both. This
-  is a container query: a card that has a footer declares
-  `container: mw-card / inline-size` and takes `width: 100%`, so it fills its
-  slot instead of sizing to its content. Give such a card an explicit width if
-  you need it to hug its content.
+- The card measures **itself**, not the window - a card in a three-column grid
+  is just as narrow on a 1200px desktop as it is on a phone, and looks the same
+  in both. Every card declares `container: mw-card / inline-size` and takes
+  `width: 100%`, so it fills its slot instead of sizing to its content. Give a
+  card an explicit width if you need it to hug its content.
+- What steps on the card's own width: the footer stacks to full-width children
+  below 360px, and the title, the subtitle and the body padding step up at
+  420px. The image height is the one that still follows the window, because it
+  is declared on the card itself and a container cannot query itself.
+- `mw-tile` works the same way, and so do `mw-stepper` and both timelines: the
+  step labels shrink and the two-sided timeline collapses to one side once the
+  component is narrow, whatever the window does. One catch on tiles: a tile
+  clips its overflow, and being a container makes it the containing block for
+  `position: fixed`, so a `data-tooltip` **inside** a tile is cut off at its
+  edge. Cards do not clip and are unaffected.
 - `mw-card-badge` (top right corner) and `mw-card-ribbon` (diagonal banner) are
   absolutely positioned overlays; colour them with `mw-card-addon-primary`,
   `-secondary`, `-success`, `-warning`, `-danger`, `-info`.
@@ -813,6 +821,10 @@ tables you know overflow, leave it off the ones that fit.
 A board is a grid of equally wide lanes; a ticket is a plain `mw-card` with
 `mw-kanban-card` on top. Everything except the counters and the composer is CSS.
 
+The board puts as many lanes in a row as fit at 260px each and wraps the rest
+onto the next. It measures its own width for that, so a board inside a panel or
+a half-width column wraps on a desktop too.
+
 ```html
 <div class="mw-kanban" style="--mw-kanban-column-min-height: 390px">
   <div class="mw-kanban-column">
@@ -1207,8 +1219,10 @@ Parts: `mw-dropdown-menu`, `-item`, `-item-danger`, `-divider`, `-label`,
 picks rather than acts. Icons inside items keep one column, so labels line up
 whether or not every item has one.
 
-The menu is absolutely positioned and is clipped by any ancestor that hides its
-overflow. The framework's own containers lift that clip while a menu is open; on
+Where the browser supports anchor positioning the menu is `position: fixed`,
+anchored to its trigger and flipped into whichever side has room, so it escapes
+a clipping ancestor by itself. Everywhere else it is absolutely positioned and
+is clipped by any ancestor that hides its overflow. The framework's own containers lift that clip while a menu is open; on
 your own it is `:has(.mw-dropdown[open]) { overflow: visible }`.
 
 On a coarse pointer the rows grow to 2.75rem and the menu takes at least the

package/.claude/skills/mw-maverick-wave/references/javascript.md

@@ -33,7 +33,7 @@ classes are the entire contract.
 | Mobile nav          | Toggles `open` on `mw-menu-btn` and `mw-navbar`, writes `aria-expanded` when the button is a `<button>`, closes on anchor click and on Escape (focus returns to the button)                                                                                                     | One signal, bound to both; reset it on navigation end                                                                                                                                                                        |
 | Scroll spy          | Sets `mw-active` on `mw-navbar-link` from the scroll position                                                                                                                                                                                                                   | Router-based: `routerLinkActive="mw-active"`                                                                                                                                                                                 |
 | Anchor scrolling    | Intercepts `a[href^="#"]` and runs its own eased scroll - duration scales with distance, capped at 1.4s, cancelled by wheel or touch. Lands on `scroll-padding-top`, moves focus to the target, writes the hash with `replaceState`, and measures a sticky target unpinned      | The router; for in-page anchors `scrollIntoView({ behavior: 'smooth' })` or your own animation                                                                                                                               |
-| Theme toggle        | `localStorage['mw-theme']`, toggles `mw-theme-light` on `<body>` and `mw-active` on the toggle, wrapped in `mw-theme-switching` on `<html>` so the flip starts no transitions                                                                                                   | A theme service - see `examples/angular-services.md`                                                                                                                                                                         |
+| Theme toggle        | `localStorage['mw-theme']`, toggles `mw-theme-light` / `mw-theme-dark` on `<body>` and `mw-active` on the toggle, wrapped in `mw-theme-switching` on `<html>` so the flip starts no transitions. With nothing stored it takes `prefers-color-scheme` and keeps following it     | A theme service - see `examples/angular-services.md`                                                                                                                                                                         |
 | Progress bar        | `IntersectionObserver` sets `width` from `data-value`                                                                                                                                                                                                                           | Bind `[style.width.%]="value()"` on `mw-progress-fill`                                                                                                                                                                       |
 | Slider              | On `input`, sets `--value` (track fill) and `data-value` (badge text)                                                                                                                                                                                                           | Bind `[style.--value.%]` and `[attr.data-value]`                                                                                                                                                                             |
 | Alerts              | Close button adds `mw-alert-closing` (fade out), then `mw-alert-closed` (`display: none`) after `--mw-duration-base`                                                                                                                                                            | Remove the alert from the list/signal                                                                                                                                                                                        |

package/.claude/skills/mw-maverick-wave/references/layout.md

@@ -183,8 +183,8 @@ as the header's first child under the same condition.
 `data-tooltip="..."` is a global attribute hook, not a class - it works on any
 element and shows a tooltip above it on hover or keyboard focus. It is pure CSS
 (a pseudo element on the trigger), which also means anything that clips its
-overflow cuts it off: a scroll container, or a card carrying a ribbon - plain
-cards do not clip. Close to the screen edge the bubble can run out of the
+overflow cuts it off: a scroll container, a tile, or a card carrying a ribbon -
+plain cards do not clip. Close to the screen edge the bubble can run out of the
 viewport, so keep long tooltips off the outermost elements.
 
 ## Sections
@@ -444,7 +444,7 @@ automatically.
 `mw-d-inline-block`, `mw-d-grid`, `mw-d-none`, `mw-d-contents`.
 
 **Responsive display** - `mw-d-{sm|md|lg|xl}-{none|block|flex|inline-flex|grid|inline-block}`.
-Mobile-first and min-width, like everything else here: `mw-d-md-flex` means
+Mobile-first like everything else here: `mw-d-md-flex` means
 "flex from the md breakpoint up", and the unprefixed class beside it is what
 applies below that. The pair `mw-d-none mw-d-md-flex` is hidden on a phone and a
 row from a tablet on. `mw-hide-mobile` (gone below md) and `mw-hide-desktop`
@@ -469,6 +469,11 @@ with it; `mw-text-capitalize` is the plain transform.
 **Elevation** - `mw-elevation-0` through `-5`, the same ramp every component
 uses. See the scale table in `SKILL.md`. Never hand-roll a `box-shadow`.
 
+**Glow** - `mw-glow` plus
+`mw-glow-{primary,secondary,info,success,warning,danger}`. Elevation without the
+offset, so the surface gives off the light instead of casting it. Once per
+screen at most.
+
 **Scroll entrance** - `mw-reveal` lets a block rise briefly as it scrolls into
 view, driven by the browser's scroll timeline (`animation-timeline: view()`).
 The block stays hidden while it is still below the bottom edge and has arrived

package/.claude/skills/mw-maverick-wave/references/theming.md

@@ -135,8 +135,19 @@ Two rules that prevent most colour bugs:
 
 ## Light & dark
 
-- Dark is the base. Light is applied by putting `mw-theme-light` on `<body>` -
-  that class only re-points the theme aliases at the `--mw-light-*` set.
+- Every theme token is declared once on `:root` as `light-dark(light, dark)`.
+  Which half applies is decided by `color-scheme` on the element that **uses**
+  the token, and `:root` carries `color-scheme: light dark` - so a page follows
+  the OS until someone chooses otherwise.
+- `mw-theme-light` and `mw-theme-dark` on `<body>` are that choice. They set
+  little more than `color-scheme`, and every token follows. `mw-theme-dark` is
+  not redundant: without it, a reader who picks dark on a machine set to light
+  would be pulled straight back to the OS preference.
+- Chrome 119-122 and Safari 16.4-17.4 are in the browserslist but predate
+  `light-dark()`. `base/_base.scss` keeps the old route for them behind
+  `@supports` - dark on `:root`, light by class, no OS tracking.
+- `--mw-hero-image-filter` is the one theme value that is not a colour and so
+  cannot ride along; it follows `prefers-color-scheme` instead.
 - Card, footer and border are derived from the page background by scaling its
   OKLch lightness and chroma by one factor. A card steps **away from the text
   colour** - darker than the page in the dark theme, lighter in the light one.
@@ -176,7 +187,9 @@ Two rules that prevent most colour bugs:
   or move it down with the bar.
 - Persisting the choice, the toggle UI and the initial class are the
   application's job in a SPA (`examples/angular-services.md`). The shipped JS
-  does it for static pages using `localStorage` under the key `mw-theme`.
+  does it for static pages using `localStorage` under the key `mw-theme`. With
+  nothing stored it takes the OS preference and keeps tracking it live, so
+  changing the system theme moves the page until the reader picks a side.
 - **Suppress transitions while the class flips.** Colour changes on nearly every
   element at once, and the shared `--mw-transition` turns that into thousands of
   concurrent animations - on a documentation-sized page it is seconds of blocked
@@ -189,29 +202,35 @@ const root = document.documentElement;
 
 root.classList.add('mw-theme-switching');
 document.body.classList.toggle('mw-theme-light', isLight);
+document.body.classList.toggle('mw-theme-dark', !isLight);
 void root.offsetHeight; // commit the new colours with transitions off
 root.classList.remove('mw-theme-switching');
 ```
 
 ## Site-wide variants
 
-Twelve classes on `<html>` and five custom properties retune the whole look
-without a rebuild. They stack, and none of them need a class per element.
-
-| Class               | Effect                                                                                                                                                                          |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mw-corners-even`   | Drops the surface signature - every card, panel and modal becomes an evenly rounded `radius('md')` box                                                                          |
-| `mw-accent-single`  | `--mw-secondary-color` follows the primary; `mw-btn-secondary` turns outline so the two stay apart                                                                              |
-| `mw-shadows-flat`   | Elevation 1-3 to `none`. The dropdown (4) and the modal (5) keep their shadow                                                                                                   |
-| `mw-surfaces-flush` | Card, panel and footer background drop to the page colour and the border is redrawn from the ink, because the old one is a neighbouring shade of a surface that is now the page |
-| `mw-hover-static`   | No hover travels - lifts, image zooms and slides go. Colour and border still respond                                                                                            |
-| `mw-scroll-static`  | No scroll entrance - `mw-reveal` and `mw-reveal-stagger` blocks sit where they land                                                                                             |
-| `mw-sections-plain` | The diagonal hatch behind `mw-section-alternate` collapses into the page colour                                                                                                 |
-| `mw-headings-caps`  | `h1`-`h3` in capitals with 0.045em tracking                                                                                                                                     |
-| `mw-btn-pill`       | `mw-btn` fully rounded. Form fields keep their own radius                                                                                                                       |
-| `mw-btn-square`     | `mw-btn` to `border-radius: 0`. The other end of the same axis, and unlike `--mw-radius-scale: 0` it leaves the rest of the page rounded                                        |
-| `mw-btn-glass`      | Filled buttons become tinted glass: translucent wash, vertical ramp, specular top edge. No `backdrop-filter` - it would trap a fixed-position tooltip inside the button         |
-| `mw-btn-tactile`    | The four solid variants stand on a 3px edge mixed toward black and travel its full height on `:active`. Outline, ghost and link have no fill to darken and are untouched        |
+Fifteen classes on `<html>` and six custom properties retune the whole look
+without a rebuild. They stack, and none of them need a class per element. The
+showcase at https://maverick-wave.m1well.com has a picker for the set, and its
+URL carries the choice - a link is how a look gets agreed on before it is built.
+
+| Class                | Effect                                                                                                                                                                              |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mw-corners-even`    | Drops the surface signature - every card, panel and modal becomes an evenly rounded `radius('md')` box                                                                              |
+| `mw-accent-single`   | `--mw-secondary-color` follows the primary; `mw-btn-secondary` turns outline so the two stay apart                                                                                  |
+| `mw-shadows-flat`    | Elevation 1-3 to `none`. The dropdown (4) and the modal (5) keep their shadow                                                                                                       |
+| `mw-surfaces-flush`  | Card, panel and footer background drop to the page colour and the border is redrawn from the ink, because the old one is a neighbouring shade of a surface that is now the page     |
+| `mw-hover-static`    | No hover travels - lifts, image zooms and slides go. Colour and border still respond                                                                                                |
+| `mw-scroll-static`   | No scroll entrance - `mw-reveal` and `mw-reveal-stagger` blocks sit where they land                                                                                                 |
+| `mw-sections-plain`  | The diagonal hatch behind `mw-section-alternate` collapses into the page colour                                                                                                     |
+| `mw-headings-caps`   | `h1`-`h3` in capitals with 0.045em tracking                                                                                                                                         |
+| `mw-links-underline` | `mw-link`, `mw-link-muted` and `mw-btn-link` carry their underline at rest. The hover signal moves to the stroke, which thickens to 3px - `mw-link` has no colour change of its own |
+| `mw-btn-pill`        | `mw-btn` fully rounded. Form fields keep their own radius                                                                                                                           |
+| `mw-btn-square`      | `mw-btn` to `border-radius: 0`. The other end of the same axis, and unlike `--mw-radius-scale: 0` it leaves the rest of the page rounded                                            |
+| `mw-btn-glass`       | Filled buttons become tinted glass: translucent wash, vertical ramp, specular top edge. No `backdrop-filter` - it would trap a fixed-position tooltip inside the button             |
+| `mw-btn-tactile`     | The four solid variants stand on a 3px edge mixed toward black and travel its full height on `:active`. Outline, ghost and link have no fill to darken and are untouched            |
+| `mw-density-compact` | Card and panel padding and the three control heights drop one step down the spacing scale. Type is untouched - `--mw-root-font-size` is the switch that scales everything together  |
+| `mw-density-roomy`   | The same one step up                                                                                                                                                                |
 
 | Property                     | Effect                                                                                                                      |
 | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -220,20 +239,24 @@ without a rebuild. They stack, and none of them need a class per element.
 | `--mw-font-family-heading`   | Headline typeface; body copy is untouched                                                                                   |
 | `--mw-container-width`       | Where the content stops growing                                                                                             |
 | `--mw-section-padding-block` | Air above and below each section                                                                                            |
+| `--mw-motion-scale`          | Multiplies all six duration tokens - `0.6` brisk, `1.6` relaxed. `prefers-reduced-motion` still overrides it                |
 
 **Writing your own.** A variant that retunes a _theme-bound_ token - anything in
-the dark/light maps, elevation and shadow above all - cannot be written on
-`:root` alone: `mw-theme-light` re-declares those on `<body>`, which shadows the
-root value for the entire subtree and the switch does nothing in light mode.
-Target both:
+the dark/light maps - cannot be written on `:root` alone: `mw-theme-light`
+re-declares those on `<body>`, which shadows the root value for the entire
+subtree and the switch does nothing in light mode. Target both:
 
 ```scss
 :root.my-variant,
 :root.my-variant .mw-theme-light {
-  --mw-elevation-2: none;
+  --mw-card-background: var(--mw-page-background);
 }
 ```
 
+`--mw-elevation-1..5` are the exception and need only `:root`: the ramp is one
+set for both themes and reaches the theme through `--mw-shadow-near/-far`, so
+there is no second declaration further down the tree to shadow it.
+
 The same trap the other way round: never copy a theme alias _into_ a token on
 `:root` (`--mw-x: var(--mw-page-background)`), because up there it still holds
 the dark value. Write that rule on the element instead.

package/CHANGELOG.md

@@ -6,6 +6,19 @@ Patch releases are only for test purposes - here I only document major and minor
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.10.0] - 2026-09-13
+
+### Fixed
+
+- technical issues
+
+## [5.9.0] - 2026-09-13
+
+### Changed
+
+- finalized showcase variants
+- changed some little glow up
+
 ## [5.8.0] - 2026-09-12
 
 ### Added

package/README.md

@@ -23,7 +23,7 @@ The result is a framework that balances utility with simplicity, offering develo
 - A five-step elevation ramp and a motion scale, so every shadow and every transition in the framework comes from one place
 - Mobile as a first-class target: 44px touch targets on a coarse pointer, modals that become bottom sheets, press states on everything, and hover effects that do not latch after a tap
 - Easy Customization via CSS Custom Properties
-- Built-in Light & Dark Mode with optional theme switching
+- Built-in Light & Dark Mode - follows the OS by default, switchable per reader
 - SCSS Source Files for advanced customization (Dart Sass, `@use`/`@forward`)
 - Modals as `<div>` or as `<dialog>` - the latter brings the focus trap, Escape and the inert background from the platform
 - Native form validation is styled through `:user-invalid`, alongside the class-driven error states for reactive forms
@@ -42,12 +42,12 @@ The result is a framework that balances utility with simplicity, offering develo
     <title>My MaverickWave Project</title>
     <link
       rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.8.0/maverick-wave.min.css"
+      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.9.0/maverick-wave.min.css"
     />
   </head>
   <body>
     <!-- Your content here -->
-    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.8.0/maverick-wave.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.9.0/maverick-wave.min.js"></script>
   </body>
 </html>
 ```
@@ -130,7 +130,8 @@ assembled rather than designed.
 :root {
   /* Elevation. Each level is two shadows - a tight contact layer that gives
      the box weight, and a wide ambient one that says how high it floats.
-     Declared per theme, because the tones they are mixed from differ. */
+     One ramp for both themes; the theme arrives through the shadow tokens
+     the levels are built from. */
   --mw-elevation-1: /* resting: inputs, tags, small controls */;
   --mw-elevation-2: /* raised: cards and panels at rest */;
   --mw-elevation-3: /* floating: a card under the pointer */;
@@ -347,32 +348,42 @@ layer of its own:
 
 ### Site-wide variants
 
-Twelve classes on `<html>` retune the whole look without touching markup or
+Fifteen classes on `<html>` retune the whole look without touching markup or
 rebuilding. They stack.
 
-| Class               | Effect                                                                  |
-| ------------------- | ----------------------------------------------------------------------- |
-| `mw-corners-even`   | Drops the surface signature - every panel becomes an evenly rounded box |
-| `mw-accent-single`  | One brand colour instead of two; `mw-btn-secondary` turns outline       |
-| `mw-shadows-flat`   | Elevation 1-3 to `none`; dropdown and modal keep theirs                 |
-| `mw-surfaces-flush` | Cards, panels and footer on the page colour, held by their border       |
-| `mw-hover-static`   | No hover travels - lifts and image zooms go, colour still responds      |
-| `mw-scroll-static`  | No scroll entrance - `mw-reveal` blocks sit where they land             |
-| `mw-sections-plain` | The hatch behind `mw-section-alternate` collapses into the page colour  |
-| `mw-headings-caps`  | `h1`-`h3` in capitals                                                   |
-| `mw-btn-pill`       | Fully rounded buttons; form fields keep their radius                    |
-| `mw-btn-square`     | Buttons cut to a hard corner while the page keeps its radius            |
-| `mw-btn-glass`      | Filled buttons become a translucent wash with a lit top edge            |
-| `mw-btn-tactile`    | Filled buttons stand on a darker edge and sink onto it when pressed     |
-
-Five properties do the rest: `--mw-radius-scale` multiplies every radius (`0`
+| Class                | Effect                                                                  |
+| -------------------- | ----------------------------------------------------------------------- |
+| `mw-corners-even`    | Drops the surface signature - every panel becomes an evenly rounded box |
+| `mw-accent-single`   | One brand colour instead of two; `mw-btn-secondary` turns outline       |
+| `mw-shadows-flat`    | Elevation 1-3 to `none`; dropdown and modal keep theirs                 |
+| `mw-surfaces-flush`  | Cards, panels and footer on the page colour, held by their border       |
+| `mw-hover-static`    | No hover travels - lifts and image zooms go, colour still responds      |
+| `mw-scroll-static`   | No scroll entrance - `mw-reveal` blocks sit where they land             |
+| `mw-sections-plain`  | The hatch behind `mw-section-alternate` collapses into the page colour  |
+| `mw-headings-caps`   | `h1`-`h3` in capitals                                                   |
+| `mw-links-underline` | Links underlined at rest; the stroke thickens on hover                  |
+| `mw-btn-pill`        | Fully rounded buttons; form fields keep their radius                    |
+| `mw-btn-square`      | Buttons cut to a hard corner while the page keeps its radius            |
+| `mw-btn-glass`       | Filled buttons become a translucent wash with a lit top edge            |
+| `mw-btn-tactile`     | Filled buttons stand on a darker edge and sink onto it when pressed     |
+| `mw-density-compact` | Less padding in cards, panels and controls; type stays put              |
+| `mw-density-roomy`   | More of the same                                                        |
+
+Six properties do the rest: `--mw-radius-scale` multiplies every radius (`0`
 squares the framework off), `--mw-root-font-size` moves the whole rem scale,
-plus `--mw-font-family-heading`, `--mw-container-width` and
+`--mw-motion-scale` the tempo of every transition, plus
+`--mw-font-family-heading`, `--mw-container-width` and
 `--mw-section-padding-block`.
 
+The [showcase](https://maverick-wave.m1well.com) has a picker for all of them,
+and the URL carries whatever is set - send that link and the next person opens
+the page exactly as you left it. The panel prints the same setup as markup and
+CSS to copy into a project.
+
 A variant of your own that retunes a theme-bound token has to target
 `:root.your-class` **and** `:root.your-class .mw-theme-light` - the light theme
-re-declares those on `<body>` and would shadow a root-only value.
+re-declares those on `<body>` and would shadow a root-only value. The elevation
+tokens are the exception and need only `:root`.
 
 ### SCSS Source
 
@@ -458,7 +469,7 @@ above):
 > change detection. The behaviors it covers (accordion, tabs, modal close, mobile
 > nav, scroll spy, theme toggle, progress bars, sliders, alerts, galleries) are a
 > few lines each in a component - the framework's state classes are the whole
-> contract. Theme switching, for example, is a single class on `<body>`:
+> contract. Theme switching, for example, is a pair of classes on `<body>`:
 
 ```typescript
 // theme.service.ts - mw-theme-switching suppresses the transitions the flip
@@ -467,10 +478,16 @@ const root = document.documentElement;
 
 root.classList.add('mw-theme-switching');
 document.body.classList.toggle('mw-theme-light', isLight);
+// the explicit counterpart - without it a dark choice on a light machine
+// falls back to the OS preference
+document.body.classList.toggle('mw-theme-dark', !isLight);
 void root.offsetHeight;
 root.classList.remove('mw-theme-switching');
 ```
 
+With neither class the page follows `prefers-color-scheme`, so an app that has
+nothing stored yet can simply leave both off.
+
 The `mw-field` wrapper groups label, control, hint and error. Bind the error
 state yourself - the framework does not style Angular's `ng-invalid` /
 `ng-touched` classes: