maverick-wave 4.28.0 → 5.0.0

package/.claude/settings.local.json

@@ -11,5 +11,33 @@
       "Bash(npm audit:*)",
       "Bash(npx prettier *)"
     ]
-  }
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f '/Users/m1well/.claude/skills/impeccable/scripts/impeccable' ] || '/Users/m1well/.claude/skills/impeccable/scripts/impeccable' hook",
+            "timeout": 5,
+            "statusMessage": "Checking UI changes"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f '/Users/m1well/.claude/skills/impeccable/scripts/impeccable' ] || '/Users/m1well/.claude/skills/impeccable/scripts/impeccable' hook",
+            "timeout": 30,
+            "statusMessage": "Design deep pass"
+          }
+        ]
+      }
+    ]
+  },
+  "description": "Impeccable design detector: immediate-tier checks after Edit/Write on UI files, full-rule deep pass on Stop."
 }

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@4.28.0/maverick-wave.min.css"
+  href="https://cdn.jsdelivr.net/npm/maverick-wave@5.0.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@4.28.0/maverick-wave.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.0.0/maverick-wave.min.js"></script>
 ```
 
 Pin the version. The JS file is optional and only for server-rendered/static pages -
@@ -116,18 +116,18 @@ leave a second tab lit.
 
 The classes that mean something _other_ than "on" keep their own names:
 
-| Component                                    | State class                         |
-| -------------------------------------------- | ----------------------------------- |
-| Anything switchable, "on"                    | `mw-active` (`active` deprecated)   |
-| Burger button + navbar drawer                | `open` (no prefix)                  |
-| Stepper indicator / label / connector / step | `mw-active`, `mw-done`              |
-| Checkbox list item (`li`)                    | `mw-selected`                       |
-| Calendar day, picked                         | `mw-selected`                       |
-| Kanban ticket being edited                   | `mw-kanban-editing`                 |
-| Modal overlay                                | `mw-modal-open`                     |
-| Alert, after dismissal                       | `mw-alert-closed` (`display: none`) |
-| Field wrapper in error                       | `mw-field-has-error`                |
-| Single form control in error                 | `mw-form-element-error`             |
+| Component                                    | State class                                              |
+| -------------------------------------------- | -------------------------------------------------------- |
+| Anything switchable, "on"                    | `mw-active` (`active` deprecated)                        |
+| Burger button + navbar drawer                | `open` (no prefix)                                       |
+| Stepper indicator / label / connector / step | `mw-active`, `mw-done`                                   |
+| Checkbox list item (`li`)                    | `mw-selected`                                            |
+| Calendar day, picked                         | `mw-selected`                                            |
+| Kanban ticket being edited                   | `mw-kanban-editing`                                      |
+| Modal overlay                                | `mw-modal-open`                                          |
+| Alert, dismissing / dismissed                | `mw-alert-closing` → `mw-alert-closed` (`display: none`) |
+| Field wrapper in error                       | `mw-field-has-error`                                     |
+| Single form control in error                 | `mw-form-element-error`                                  |
 
 `mw-active` and `mw-selected` are not the same thing and not interchangeable:
 active is the one of several that is currently showing, selected is a choice the
@@ -150,8 +150,22 @@ keys at all (negative gap is invalid CSS and is not generated).
 `sm` 0.9, `base` 1, `md` 1.1, `lg` 1.3, `xl` 1.5, `2xl` 1.8, `3xl` 2.2, `4xl` 2.5,
 `5xl` 3, `6xl` 4.3 rem.
 
-**Breakpoints** (max-width, mobile-first markup / desktop-first media queries):
-`xs` 375, `sm` 576, `md` 768, `lg` 992, `xl` 1200, `2xl` 1400 px.
+**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`.
+
+**Overriding.** Everything the framework emits sits in
+`@layer mw.reset, mw.base, mw.forms, mw.components, mw.layout, mw.utilities`.
+Any rule written outside a layer beats all of it, so a single `.mw-card {}` in
+your own stylesheet wins - no `!important`, no doubled selectors. `!important`
+is not a stronger version of this but a weaker one: important declarations
+reverse the layer order and unlayered comes last, so an important rule in
+`mw.base` beats an important one of yours even behind an ID selector. The flip
+side: third-party CSS loaded unlayered also wins, so pull it into a layer of
+its own:
+`@import url('font-awesome.css') layer(vendor);` with `@layer vendor, mw;`
+declared before it.
 
 **Radius** (`mw-radius-none|xs|sm|md|lg|xl|2xl|full`): 0, 2, 5, 10, 15, 20, 30 px, 50%.
 
@@ -370,14 +384,15 @@ feature frame) ·
     comment. If your component really does need to animate a size, name that
     property - do not reach for `all`.
 27. **A control is a `<button>`, never a styled `<div>`.** `mw-tabs-nav-item`,
-    `mw-theme-toggle`, `mw-gallery-dot` and `mw-accordion-header` are all
-    written for one, and all four shipped as divs and spans - the first three
-    until 4.11, the accordion header until 4.12 - that no keyboard could reach.
-    Each class clears what a `<button>` brings with it, so
-    `<button type="button" class="mw-tabs-nav-item" data-tab="...">` is the
-    whole markup. If you build your own clickable thing: the element decides
-    whether anyone without a mouse can use it, the class only decides how it
-    looks.
+    `mw-theme-toggle`, `mw-gallery-dot`, `mw-accordion-header` and `mw-menu-btn`
+    are all written for one, and all five shipped as divs and spans - the first
+    three until 4.11, the accordion header until 4.12, the burger after that -
+    that no keyboard could reach. Each class clears what a `<button>` brings
+    with it, so `<button type="button" class="mw-tabs-nav-item" data-tab="...">`
+    is the whole markup. The burger is the worst of the five to get wrong:
+    below the collapse breakpoint it is the only route to the navigation.
+    If you build your own clickable thing: the element decides whether anyone
+    without a mouse can use it, the class only decides how it looks.
 28. **A link in running text is `mw-link`, not `mw-btn mw-btn-link`.** Since
     4.13.0 there is a class for exactly that. `mw-btn` is `inline-flex` with
     `min-height: var(--mw-control-height)`, so a link written that way pulls its

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

@@ -7,7 +7,9 @@ service or a component per behaviour, none of them longer than a screen.
 ## Theme service
 
 The framework only needs one class on `<body>`. Everything else - persistence,
-the toggle UI, the initial value - belongs to the application.
+the toggle UI, the initial value - belongs to the application. The second class,
+`mw-theme-switching` on `<html>`, is not optional on a page of any size: without
+it the flip starts a transition on every element that changes colour.
 
 ```ts
 import { Injectable, effect, signal } from '@angular/core';
@@ -21,7 +23,13 @@ export class ThemeService {
   constructor() {
     effect(() => {
       const light = this.light();
+      const root = document.documentElement;
+
+      root.classList.add('mw-theme-switching');
       document.body.classList.toggle('mw-theme-light', light);
+      void root.offsetHeight; // commit the colours with transitions off
+      root.classList.remove('mw-theme-switching');
+
       localStorage.setItem(STORAGE_KEY, light ? 'light' : 'dark');
     });
   }
@@ -308,13 +316,17 @@ on every navigation.
             <span class="mw-profile-btn-name">{{ user().name }}</span>
           </button>
 
-          <div
+          <button
+            type="button"
             class="mw-menu-btn"
+            aria-label="Menu"
+            aria-controls="main-nav"
+            [attr.aria-expanded]="menuOpen()"
             [class.open]="menuOpen()"
             (click)="menuOpen.set(!menuOpen())"
           >
-            <div class="mw-menu-btn-burger"></div>
-          </div>
+            <span class="mw-menu-btn-burger"></span>
+          </button>
         </div>
       </div>
     </header>

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@4.28.0/maverick-wave.min.css"
+      href="https://cdn.jsdelivr.net/npm/maverick-wave@5.0.0/maverick-wave.min.css"
     />
     <link
       rel="stylesheet"
@@ -78,7 +78,15 @@ accordion FAQ.
             </div>
           </button>
 
-          <div class="mw-menu-btn"><div class="mw-menu-btn-burger"></div></div>
+          <button
+            type="button"
+            class="mw-menu-btn"
+            aria-label="Menu"
+            aria-expanded="false"
+            aria-controls="main-nav"
+          >
+            <span class="mw-menu-btn-burger"></span>
+          </button>
         </div>
       </div>
     </header>
@@ -479,7 +487,7 @@ accordion FAQ.
       <div class="mw-modal-backdrop" onclick="closeModal('demo')"></div>
     </div>
 
-    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@4.28.0/maverick-wave.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/maverick-wave@5.0.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.
@@ -497,7 +505,8 @@ accordion FAQ.
 ## Notes
 
 - The theme toggle needs no code - the script persists the choice under
-  `localStorage['mw-theme']` and toggles `mw-theme-light` on `<body>`.
+  `localStorage['mw-theme']`, toggles `mw-theme-light` 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
   the contract.

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

@@ -544,8 +544,12 @@ Toggling is JS - see `references/javascript.md`; the shipped script keeps
 ```html
 <div class="mw-tabs">
   <div class="mw-tabs-nav">
-    <div class="mw-tabs-nav-item mw-active" data-tab="tab1">Details</div>
-    <div class="mw-tabs-nav-item" data-tab="tab2">History</div>
+    <button type="button" class="mw-tabs-nav-item mw-active" data-tab="tab1">
+      Details
+    </button>
+    <button type="button" class="mw-tabs-nav-item" data-tab="tab2">
+      History
+    </button>
   </div>
   <div class="mw-tabs-content">
     <div class="mw-tabs-panel mw-active" id="tab1">...</div>
@@ -558,6 +562,9 @@ Toggling is JS - see `references/javascript.md`; the shipped script keeps
   `mw-tabs-pills`.
 - `data-tab` matches the panel `id` - that pairing is only needed for the
   shipped JS. In a SPA, bind `mw-active` yourself and drop the attribute.
+- The shipped JS turns the strip into a real tablist: `role`, `aria-selected`,
+  `aria-controls`, `aria-labelledby`, a roving `tabindex` and arrow/Home/End
+  keys. Without it, that is yours to add - see `references/javascript.md`.
 - The nav scrolls horizontally instead of wrapping, and says so: a shadow shows
   on whichever side still has tabs behind it and disappears once that end is
   reached. Pure CSS, no scroll listener. The fade colour comes from
@@ -602,6 +609,35 @@ Toggling is JS - see `references/javascript.md`; the shipped script keeps
 
 Angular: `<div class="mw-modal-overlay" [class.mw-modal-open]="isOpen()">`.
 
+### The same modal as a `<dialog>`
+
+Same classes, no overlay wrapper and no backdrop element:
+
+```html
+<dialog id="delete-modal" class="mw-modal mw-modal-sm" closedby="any">
+  <div class="mw-modal-header">
+    <h4 class="mw-modal-title">Delete invoice</h4>
+    <button class="mw-modal-close" type="button" aria-label="Close">
+      &#120299;
+    </button>
+  </div>
+  <div class="mw-modal-body">…</div>
+  <div class="mw-modal-footer">…</div>
+</dialog>
+```
+
+- Escape, the focus trap, `inert` on the page behind it and the scroll lock all
+  come from the element. Prefer this shape for anything that asks a question.
+- Opened with `showModal()`, closed with `close()`. `main.js` wires the close
+  buttons and exposes `mwOpenModal(id)` / `mwCloseModal(id)`, both of which take
+  either shape. A trigger can also carry `data-mw-modal="delete-modal"`.
+- `closedby="any"` dismisses it on a backdrop click; where that attribute is not
+  understood the script handles the click instead.
+- Sizes, the bottom sheet below 576px and every `mw-modal-*` part behave exactly
+  as above - those rules are class-based.
+
+Angular: bind nothing, call `showModal()` on a `viewChild` ref.
+
 ## Alerts & toasts
 
 ```html
@@ -618,9 +654,10 @@ Angular: `<div class="mw-modal-overlay" [class.mw-modal-open]="isOpen()">`.
 ```
 
 Variants: `mw-alert-primary`, `-secondary`, `-success`, `-warning`, `-danger`,
-`-info`. `mw-alert-title` and the close button are optional. `mw-alert-closed`
-hides a dismissed alert (`display: none`) - in a SPA prefer removing it from the
-list instead.
+`-info`. `mw-alert-title` and the close button are optional. Dismissal runs in
+two steps: `mw-alert-closing` fades the alert out over `--mw-duration-base`, then
+`mw-alert-closed` hides it (`display: none`) - in a SPA prefer removing it from
+the list instead.
 
 **Toasts** are alerts inside a fixed stack:
 

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

@@ -45,14 +45,26 @@ reactive form control.
 ```
 
 - `mw-required` on the label appends a red asterisk (`data-required="true"`
-  works too).
+  works too). A label sitting directly in front of a control with the `required`
+  attribute gets the asterisk without either class - useful for template-driven
+  and plain HTML forms, where the marker then cannot drift out of step with the
+  validation.
 - `mw-field-hint` is the small muted helper line, `mw-field-error` the small red
   one. Render only one of them at a time.
 - `mw-field-has-error` on the **wrapper** turns the border of the contained
   `mw-input` / `mw-select` / `mw-textarea` red and adds a soft red halo.
 - `mw-form-element-error` does the same for a single control that has no field
   wrapper - it also works on `mw-checkbox-group`, `mw-radio-group` and
-  `mw-slider-container`.
+  `mw-slider-container`. On the two groups it adds the inset a field brings with
+  it, so the rows do not sit flush against the border.
+- Native validation is styled too: a control that fails `required`, `type` or
+  `pattern` gets the same red border and halo through `:user-invalid`, and the
+  `mw-field-hint` beside it turns red. `:user-invalid` and not `:invalid`, so an
+  untouched empty field is not red on page load. Nothing has to be bound for
+  this - which is exactly why the classes still exist for the case below, where
+  the validator lives in the component rather than on the element.
+- `mw-textarea` grows with its content (`field-sizing`) between 3 lines and
+  60dvh, where the browser supports it.
 
 > **The framework does not style Angular's `ng-invalid` / `ng-touched` classes.**
 > Bind the framework classes to the control state yourself:

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

@@ -28,14 +28,14 @@ classes are the entire contract.
 | Behaviour           | What the shipped JS does                                                                                                                                                                                                                                                        | What to do instead                                                                                                                                                                                                           |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Accordion           | Toggles `mw-active` on `mw-accordion-header` and the following `mw-accordion-content`, and writes `aria-expanded` when the header is a `<button>`                                                                                                                               | `[class.mw-active]="isOpen()"` and `[attr.aria-expanded]="isOpen()"` on the header, `mw-active` on the panel                                                                                                                 |
-| Tabs                | `data-tab` → panel `id`; sets `mw-active` on nav item and panel                                                                                                                                                                                                                 | Track the selected index/key, bind `mw-active` on both; drop `data-tab`                                                                                                                                                      |
+| Tabs                | `data-tab` → panel `id`; sets `mw-active` on nav item and panel, and wires the whole tablist: `role`, `aria-selected`, `aria-controls`, `aria-labelledby`, a roving `tabindex` and arrow/Home/End keys                                                                          | Track the selected index/key, bind `mw-active` on both; drop `data-tab`                                                                                                                                                      |
 | Modal               | Click on `mw-modal-close` removes `mw-modal-open` from the overlay                                                                                                                                                                                                              | `[class.mw-modal-open]="isOpen()"`; backdrop click closes. Opening is not in the script at all (the showcase has its own `openModal`)                                                                                        |
-| Mobile nav          | Toggles `open` on `mw-menu-btn` and `mw-navbar`, closes on anchor click                                                                                                                                                                                                         | One signal, bound to both; reset it on navigation end                                                                                                                                                                        |
+| 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"`                                                                                                                                                                                 |
-| Theme toggle        | `localStorage['mw-theme']`, toggles `mw-theme-light` on `<body>` and `mw-active` on the toggle                                                                                                                                                                                  | A theme service - see `examples/angular-services.md`                                                                                                                                                                         |
+| 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`                                                                                                                                                                         |
 | 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-closed` (`display: none`)                                                                                                                                                                                                                           | Remove the alert from the list/signal                                                                                                                                                                                        |
+| 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                                                                                                                                                                                        |
 | Checkbox lists      | Adds `mw-selected` to the `li`, emits a `checkboxToggle` event, exposes `window.toggleCheckbox`                                                                                                                                                                                 | `[class.mw-selected]="item.checked"`                                                                                                                                                                                         |
 | Gallery             | Generates the dots, moves the track, swipe handling, writes `mw-gallery-desc`                                                                                                                                                                                                   | Render dots in the template, bind the track transform and `mw-active` on the current dot                                                                                                                                     |
 | Image slider        | Toggles `mw-active` on the overlay image and the control button with the matching `data-index`                                                                                                                                                                                  | Bind `mw-active` from the selected index                                                                                                                                                                                     |
@@ -47,6 +47,19 @@ classes are the entire contract.
 | Dropdown            | Delegated to the document: closes the open `mw-dropdown` on Escape, on a click elsewhere and on a click on a `mw-dropdown-item`, and returns focus to the `summary`                                                                                                             | The `<details>` does the opening, the keyboard and the state on its own. Rebuild only the two behaviours markup cannot express - or bind `[attr.open]` and keep them in the component                                        |
 | Language switcher   | Keeps the trigger's flag and code in step with the chosen item, moves `mw-active` and `aria-current`, and fires `mw-language-change` (`detail: { lang, name }`) on the switcher                                                                                                 | Bind the trigger from your locale signal and switch the language in your own i18n service; the menu itself is a `<details>` and needs nothing                                                                                |
 
+## Modals and progress bars
+
+`mwOpenModal(id)` / `mwCloseModal(id)` are on `window` and handle both modal
+shapes - the `mw-modal-overlay` div and a `<dialog class="mw-modal">`. Close
+buttons and `data-mw-modal="<id>"` triggers are delegated from the document, so
+markup rendered later still works. A `<dialog>` needs none of it in a SPA: call
+`showModal()` and `close()` on the element.
+
+`mw-progress-fill` takes its target width from `data-value="75"` or an inline
+`style="width: 75%"`. Where scroll-driven animations are supported the bar fills
+with the scroll position and the script only hands the value over; elsewhere it
+falls back to setting the width once the bar comes into view.
+
 ## A note on the state class
 
 Since 4.0.0 the script writes `mw-active` and clears both `mw-active` and the

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

@@ -59,11 +59,11 @@ its children are styled through descendant selectors:
 <header class="mw-header">
   <div class="mw-container">
     <div class="mw-logo">
-      <button type="button"><img src="logo.svg" alt="Logo" /></button>
+      <a href="#start"><img src="logo.svg" alt="Logo" /></a>
     </div>
 
     <div class="mw-header-actions">
-      <nav class="mw-navbar mw-navbar-medium">
+      <nav class="mw-navbar mw-navbar-medium" id="main-nav">
         <ul class="mw-navbar-list">
           <li class="mw-navbar-item">
             <a href="#start" class="mw-navbar-link mw-active">Start</a>
@@ -74,17 +74,29 @@ its children are styled through descendant selectors:
         </ul>
       </nav>
 
-      <div class="mw-theme-toggle mw-ml-5">
+      <button
+        type="button"
+        class="mw-theme-toggle mw-ml-5"
+        aria-label="Toggle light and dark theme"
+      >
         <div class="mw-theme-toggle-slider">
           <div class="mw-theme-toggle-icon"><i class="fas fa-moon"></i></div>
         </div>
-      </div>
+      </button>
 
-      <button class="mw-login-btn" type="button">
+      <button class="mw-login-btn" type="button" aria-label="Log in">
         <i class="fas fa-lock"></i>
       </button>
 
-      <div class="mw-menu-btn"><div class="mw-menu-btn-burger"></div></div>
+      <button
+        type="button"
+        class="mw-menu-btn"
+        aria-label="Menu"
+        aria-expanded="false"
+        aria-controls="main-nav"
+      >
+        <span class="mw-menu-btn-burger"></span>
+      </button>
     </div>
   </div>
 </header>
@@ -94,7 +106,9 @@ its children are styled through descendant selectors:
   at `md`, `mw-navbar-medium` (4-5) at `lg`, `mw-navbar-large` (6+) at `xl`.
   Pick the class by how many links you have.
 - Below the breakpoint the list is hidden and `mw-menu-btn` appears. Opening the
-  drawer means adding `open` to **both** `mw-menu-btn` and `mw-navbar`.
+  drawer means adding `open` to **both** `mw-menu-btn` and `mw-navbar`, and
+  setting `aria-expanded` on the button - below the breakpoint it is the only
+  route to the navigation, so it has to be a real `<button>`, not a `<div>`.
 - The active link carries `mw-active` (bare `active` still works but is
   deprecated).
 - `mw-profile-btn` is the signed-in pill, next to or instead of the login button:
@@ -162,14 +176,14 @@ viewport, so keep long tooltips off the outermost elements.
 
 ## Sections
 
-| Class                               | Use                                                                                                            |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `mw-section`                        | Vertical rhythm for a page band - `--mw-section-padding-block`, 3.3rem (2.5rem below `md`, 1.75rem below `sm`) |
-| `mw-section-alternate`              | Diagonal pattern background; combine with `mw-section`                                                         |
-| `mw-section-title`                  | Centered `3xl` heading with a decorative primary underline - landing pages                                     |
-| `mw-section-intro`                  | The lead paragraph under a section title - centred, muted, 46rem measure                                       |
-| `mw-section-subtitle`               | Centered `2xl` heading with a thin secondary underline                                                         |
-| `mw-section-nav` + `mw-section-btn` | Centered, wrapping row of outline-style jump links                                                             |
+| Class                               | Use                                                                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `mw-section`                        | Vertical rhythm for a page band - `--mw-section-padding-block`, 3.3rem (2.5rem below `md`, 1.75rem below `sm`)     |
+| `mw-section-alternate`              | Diagonal pattern background; combine with `mw-section`                                                             |
+| `mw-section-title`                  | Centered `3xl` heading with a decorative primary underline - landing pages                                         |
+| `mw-section-intro`                  | The lead paragraph under a section title - centred, muted, 46rem measure                                           |
+| `mw-section-subtitle`               | Centered `2xl` heading with a thin secondary underline                                                             |
+| `mw-section-nav` + `mw-section-btn` | Sticky single-row strip of outline-style jump links; parks under the header and scrolls sideways when it overflows |
 
 ```html
 <section class="mw-section mw-section-alternate">
@@ -187,6 +201,10 @@ viewport, so keep long tooltips off the outermost elements.
 </section>
 ```
 
+The strip sticks at `--mw-header-height` and is `--mw-section-nav-height` tall
+(3.7rem). Anything it can cover on a jump needs the sum as `scroll-margin-top`;
+a block wrapping a `mw-section-subtitle` gets that from the framework already.
+
 ## Page header
 
 The application counterpart to `mw-section-title`: title and subtitle left,
@@ -264,6 +282,12 @@ Components that paint their own surface (`mw-card`, `mw-panel`, `mw-modal`,
 `mw-tile`, `mw-calendar`) are exempt and keep the theme's ink - a card in the
 hero is still a card.
 
+`mw-btn-outline` is exempt the other way round: inside the hero it takes the
+hero's ink plus a dark scrim and a blur, because its usual border and label are
+tuned for the page background and go quiet over a photograph. A second call to
+action next to `mw-btn-primary` therefore looks different here than it does
+further down the page - that is deliberate, not a stray override.
+
 **Scroll cue** - `mw-scroll-hint` is the "scroll down" cue on the lower edge of
 the hero. An `<a>` that is a sibling of `mw-hero`, directly in the container:
 
@@ -286,8 +310,10 @@ is taken on a phone. The bobbing stops under `prefers-reduced-motion`.
 ## Grid
 
 All grid classes are `display: grid` with a preset gap (`mw-gap-*` overrides
-it). They collapse to fewer columns on their own - no responsive suffixes to
-manage.
+it). They handle their own column count - no responsive suffixes to manage. One
+column is the base and each breakpoint adds to it, so a phone renders them
+without evaluating a single media query; the table below reads the same either
+way.
 
 | Class             | Columns                                         | Collapses                    |
 | ----------------- | ----------------------------------------------- | ---------------------------- |
@@ -414,6 +440,11 @@ chip-sized `mw-card-simple`, a swatch, a marker in a layout demo. A card with
 content in it never needs this, and it is not the way to switch the signature
 off across a project - restyle `--mw-corner-accent` for that.
 
+**Squircle corners** - `mw-squircle` draws the same silhouette with a
+superellipse instead of a circular arc: same four radii, fuller curve, and the
+corner accent follows. Opt-in, because `corner-shape` only lands in Chromium so
+far - everywhere else the box is simply the normal one.
+
 **Aspect ratio** - `mw-aspect-square|video|wide|portrait|photo`. Reserves the
 box before the image inside it has loaded, so the page does not reflow when the
 picture arrives. The child fills the box and crops rather than stretching.
@@ -513,11 +544,14 @@ do not.
 **Flex** - `mw-flex-row`, `mw-flex-column`, `mw-flex-wrap`, `mw-flex-nowrap`,
 `mw-flex-1`, `mw-flex-grow-1`, `mw-flex-shrink-0`,
 `mw-justify-start|end|center|between|around|evenly`,
-`mw-items-start|end|center|stretch`.
+`mw-items-start|end|center|stretch`,
+`mw-self-start|end|center|stretch`.
 
 `mw-flex-1` sets `flex: 1` (basis 0, all items equal). `mw-flex-grow-1` only
 grows and keeps the content width as the basis - that is the one you want next
-to an avatar or an icon.
+to an avatar or an icon. `mw-self-*` is the per-item counterpart to
+`mw-items-*`: it goes on the child, for the one that sits differently from the
+rest of the row.
 
 **Text** - alignment `mw-text-left|center|right`; colour `mw-text-primary`,
 `-secondary`, `-success`, `-warning`, `-danger`, `-info`, `-muted`,

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

@@ -78,6 +78,7 @@ Safari 16.4+, Firefox 128+. The same range is declared as `browserslist` in
 | `--mw-kanban-background`, `--mw-kanban-lane-border`, `--mw-kanban-column-min-height`                                                                                         | Per-board surface, lane border and lane floor (120px, 90px on `mw-kanban-compact`)                                                                                                                                                                                                                                                      |
 | `--mw-container-gutter`, `--mw-container-width`                                                                                                                              | Page gutter of `mw-container` (fluid `clamp(1rem, 4.2vw + 0.5rem, 4rem)`, never below the safe-area inset) and the width derived from it (`min(1200px, 100% - 2 * gutter)`)                                                                                                                                                             |
 | `--mw-section-padding-block`                                                                                                                                                 | Top/bottom rhythm of `mw-section` (3.3rem, stepping down to 2.5rem below `md` and 1.75rem below `sm`)                                                                                                                                                                                                                                   |
+| `--mw-section-nav-height`                                                                                                                                                    | Height the sticky `mw-section-nav` reserves (3.7rem). Add it to `--mw-header-height` for the `scroll-margin-top` of anything the strip can cover                                                                                                                                                                                        |
 | `--mw-calendar-dot`                                                                                                                                                          | Colour of a single calendar dot - set it per dot or per cell; the `mw-calendar-dot-*` classes are presets for it                                                                                                                                                                                                                        |
 | `--mw-scroll-hint-cover`                                                                                                                                                     | Colour the scroll hint on a tab bar fades into. Preset to the page, re-pointed to the card background inside `mw-card`, `mw-panel`, `mw-modal`, `mw-tile`, `mw-calendar`                                                                                                                                                                |
 | `--mw-elevation-1` … `-5`                                                                                                                                                    | Every shadow in the framework. Two layers per level - contact plus ambient. Never write a `box-shadow` by hand: a hand-rolled one is the wrong colour in one of the two themes                                                                                                                                                          |
@@ -171,9 +172,20 @@ Two rules that prevent most colour bugs:
 - 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`.
+- **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
+  style and layout. `mw-theme-switching` on `<html>` kills them for the flip; the
+  forced reflow between the two class changes is what commits the new colours
+  before transitions come back.
 
 ```ts
+const root = document.documentElement;
+
+root.classList.add('mw-theme-switching');
 document.body.classList.toggle('mw-theme-light', isLight);
+void root.offsetHeight; // commit the new colours with transitions off
+root.classList.remove('mw-theme-switching');
 ```
 
 ## SCSS configuration
@@ -262,6 +274,29 @@ they are all `var()` references anyway:
 }
 ```
 
+## Overriding a component
+
+Tokens cover colour and rhythm; for anything else write a normal rule. The
+framework emits everything inside
+`@layer mw.reset, mw.base, mw.forms, mw.components, mw.layout, mw.utilities`,
+and an unlayered rule beats every layer regardless of weight:
+
+```css
+/* wins over .mw-card, no !important and no doubled selector */
+.mw-card {
+  border-radius: 12px;
+}
+```
+
+The same rule cuts the other way: third-party CSS loaded unlayered also beats
+the framework, which is what makes an icon font quietly win over `mw-tags-icon`.
+Give it a layer of its own:
+
+```css
+@layer vendor, mw;
+@import url('font-awesome.css') layer(vendor);
+```
+
 ## Importing only what you need
 
 The full stylesheet is ~200 kB raw / ~31 kB gzipped. Marketing components
@@ -272,7 +307,9 @@ Angular bundle budgets notice.
 Every layer forwards one module per file, and no `@extend` crosses a file
 boundary, so partial imports are safe. **The one thing you must not drop is
 `base`** - it carries the `:root` tokens; without it every component renders
-colourless.
+colourless. The cascade layer order comes along on its own: every module loads
+`abstracts`, which declares it, so a hand-picked subset orders itself the same
+way the full build does.
 
 ```scss
 // styles.scss - configure first, then pick

package/.impeccable/config.local.json

@@ -0,0 +1,5 @@
+{
+  "hook": {
+    "consent": "accepted"
+  }
+}

package/.impeccable/hook.cache.json

@@ -0,0 +1 @@
+{"version":1,"sessions":{"5682ec58-6688-479f-994f-990ff918c05d":{"updatedAt":1789084033412,"files":{"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/layout/_header.scss":{"editCount":3,"findings":[],"stopBaseline":{"version":1,"engine":"0.1.5","counts":{}},"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/form-elements/_slider.scss":{"editCount":1,"findings":[],"stopBaseline":{"version":1,"engine":"0.1.5","counts":{}},"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/js/main.js":{"editCount":7,"findings":[]},"/Users/m1well/Dev/workspace/css/maverick-wave/index.html":{"editCount":2,"findings":["low-contrast:0:3.3:1 (need 4.5:1) — text #7d85a5 on #313746","pulsing-dot:0:.mw-spinner-dots>div — 16x16px dot with infinite \"mw-bounce\" animation","dark-glow:0:Colored box-shadow glow (#d1bb21) on dark page"]},"/Users/m1well/Dev/workspace/css/maverick-wave/src/partials/typography-container.html":{"editCount":2,"findings":[],"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/base/_base.scss":{"editCount":2,"findings":[],"stopBaseline":{"version":1,"engine":"0.1.5","counts":{}},"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/layout/_section.scss":{"editCount":7,"findings":[],"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/form-elements/_form.scss":{"editCount":1,"findings":[],"stopBaseline":{"version":1,"engine":"0.1.5","counts":{}},"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/components/_alerts.scss":{"editCount":1,"findings":["side-tab:83"],"stopBaseline":{"version":1,"engine":"0.1.5","counts":{"62d926b4b80efa38e6fbf0fe65f45cf171d9b8a80be0b2ee47ac4cbb6c9498d0":1}},"cleanAcked":true},"/Users/m1well/Dev/workspace/css/maverick-wave/src/scss/layout/_main.scss":{"editCount":1,"findings":[],"stopBaseline":{"version":1,"engine":"0.1.5","counts":{}},"cleanAcked":true}},"footerShown":true}}}