npm - @stackific/md3 - Versions diffs - 0.1.2 → 0.1.3 - Mend

@stackific/md3 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,38 +1,149 @@
 # @stackific/md3
-Material Design 3 framework — SCSS + plain JavaScript. No build step required. No React, Vue, or other framework lock-in. Drop it into any HTML page and write semantic markup.
+> Material Design 3 framework. Compiled CSS + plain-JS runtime. Drop into any HTML page; no framework required.
-- **Light + dark + auto** modes that follow OS preference, persist across reloads, and update live when the OS theme flips.
-- **Multiple named brand themes** in a single bundle, swap with one attribute.
-- **No JS framework required.** Works in plain HTML, also fine with React, Vue, Svelte, htmx, etc.
-- **Runtime weight**: ~17 kB JS, ~22 kB CSS (gzipped) for the full default build.
-- **Optional dynamic theming** from a hex / image / file via `material-dynamic-colors` (opt-in dependency).
+- Light, dark, and OS-following `auto` modes — CSS-driven, no JS needed.
+- 18 baked brand themes, swap with one attribute.
+- Optional runtime theme generation from a hex / image / file (via `material-dynamic-colors`).
+- Material Symbols icon fonts ship inside the CSS — no Google Fonts import.
 ---
-## Quick start (CDN)
+## Table of contents
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Bootstrap](#bootstrap) — `data-theme`, `data-mode`, `data-ui`
+- [Runtime API](#runtime-api) — `ui(...)`
+- [Main layout](#main-layout)
+- **Components**
+  - [Badge](#badge)
+  - [Button](#button)
+  - [Card](#card)
+  - [Checkbox](#checkbox)
+  - [Chip](#chip)
+  - [Container](#container)
+  - [Dialog](#dialog)
+  - [Divider](#divider)
+  - [Expansion](#expansion)
+  - [Field](#field) (Input · Select · Textarea · Search · Custom inputs)
+  - [Grid](#grid)
+  - [Header & Footer](#header--footer)
+  - [Icon](#icon)
+  - [Layout](#layout) (`.absolute` / `.fixed`)
+  - [List](#list)
+  - [Media](#media) (`<img>`, `<svg>`, `<video>`)
+  - [Menu](#menu)
+  - [Navigation](#navigation)
+  - [Overlay](#overlay)
+  - [Page](#page)
+  - [Progress](#progress)
+  - [Radio](#radio)
+  - [Shape](#shape)
+  - [Slider](#slider)
+  - [Snackbar](#snackbar)
+  - [Switch](#switch)
+  - [Table](#table)
+  - [Tabs](#tabs)
+  - [Tooltip](#tooltip)
+  - [Typography](#typography)
+- **Helpers**
+  - [Alignments](#alignments)
+  - [Blurs](#blurs)
+  - [Color roles](#color-roles)
+  - [Directions](#directions)
+  - [Elevations](#elevations)
+  - [Forms](#forms-helpers) (border, round, corners, …)
+  - [Margins](#margins)
+  - [Opacities](#opacities)
+  - [Paddings](#paddings)
+  - [Positions](#positions)
+  - [Responsive](#responsive)
+  - [Ripples](#ripples)
+  - [Scrolls](#scrolls)
+  - [Shadows](#shadows)
+  - [Sizes](#sizes)
+  - [Spaces](#spaces)
+  - [Waves](#waves)
+  - [Zoom](#zoom)
+- [Design tokens](#design-tokens)
+- [Themes](#themes)
+- [Theme & Mode selector](#theme-and-mode-selector)
+- [Breakpoints](#breakpoints)
+- [Repository](#repository)
-Paste into any HTML file:
+---
+## Install
+**CDN** — paste into any HTML page:
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stackific/md3/dist/md3.css">
+<script type="module" src="https://cdn.jsdelivr.net/npm/@stackific/md3/dist/md3.js"></script>
+```
+**npm / pnpm / yarn:**
+```sh
+npm install @stackific/md3
+# or: pnpm add @stackific/md3
+# or: yarn add @stackific/md3
+```
+```js
+import "@stackific/md3";        // runtime, registers globalThis.ui
+import "@stackific/md3/style";  // compiled CSS
+```
+**Local files** — download `dist/md3.css`, `dist/md3.js`, and the `dist/assets/*` they reference from the published package, then serve them from your own host:
+```html
+<link rel="stylesheet" href="/md3/md3.css">
+<script type="module" src="/md3/md3.js"></script>
+```
+For Vite users, build with `assetsInlineLimit: 0` to keep the bundled CSS at its original size (otherwise the font files get inlined as data URIs).
+**Optional — runtime theme generation from a hex / image / file:**
+```sh
+npm install material-dynamic-colors
+```
+```js
+import "material-dynamic-colors";   // once, at app entry
+await ui("theme", "#1447E6");
+```
+Without it, only baked-theme swaps and precomputed `{ light, dark }` objects work via `ui("theme", …)`.
+---
+## Quick start
 ```html
 <!doctype html>
-<html data-theme="stackific">
+<html data-theme="stackific" data-mode="auto">
   <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stackific/md3/dist/md3.css">
     <script type="module" src="https://cdn.jsdelivr.net/npm/@stackific/md3/dist/md3.js"></script>
+    <title>Hello M3</title>
   </head>
   <body>
     <main class="responsive">
       <h1>Hello, M3</h1>
-      <button>Click me</button>
-      <div class="field label">
-        <input type="text">
-        <label>Your name</label>
-      </div>
-      <label class="switch">
-        <input type="checkbox">
-        <span></span>
-      </label>
+      <nav>
+        <button>Primary</button>
+        <button class="border">Outlined</button>
+        <button class="transparent circle"><i>search</i></button>
+      </nav>
+      <article>
+        <h5>Card</h5>
+        <p>Drop md3 into a plain HTML page and write semantic markup.</p>
+      </article>
     </main>
   </body>
 </html>
@@ -40,235 +151,2462 @@ Paste into any HTML file:
 That's it. You should see an M3-styled page that picks light or dark automatically from your OS preference.
-## Install via npm
+---
-```sh
-npm install @stackific/md3
-# or: pnpm add @stackific/md3
-# or: yarn add @stackific/md3
+## Bootstrap
+```html
+<html data-theme="stackific" data-mode="auto">
 ```
-In your app entry:
+| Attribute    | Values                       | Notes                                                  |
+| ------------ | ---------------------------- | ------------------------------------------------------ |
+| `data-theme` | any baked theme name         | Pure attribute swap; no JS required for static pages. Omit to use the default (`stackific`). |
+| `data-mode`  | `auto` \| `light` \| `dark`  | `auto` follows `prefers-color-scheme` in CSS (no JS).  |
+| `data-ui`    | `#some-id`                   | On any element, clicking delegates to `ui("#some-id")`. Anchors without `href` also respond to Enter. |
-```js
-import "@stackific/md3";          // runtime — registers window.ui()
-import "@stackific/md3/style";    // compiled CSS with M3 tokens + utilities
-```
+Mode is persisted to `localStorage["md3:mode"]`, theme to `localStorage["md3:theme"]`. The stored value beats the hardcoded `data-mode` / `data-theme` on `<html>`.
+---
+## Runtime API
-The CSS includes all `@font-face` declarations for Material Symbols, so icons render without any Google Fonts import.
+A single global function `ui(...)` (also `import { ui } from "@stackific/md3"`). The runtime auto-rescans the DOM via a `MutationObserver`, so calling `ui()` after injecting markup is usually optional.
+| Call                                | Effect                                                          |
+| ----------------------------------- | --------------------------------------------------------------- |
+| `ui()`                              | Re-scan the DOM (fields, sliders, ripples, progress, triggers). |
+| `ui("guid")`                        | Returns a UUIDv4 string.                                        |
+| `ui("mode")`                        | Returns current mode: `"auto"` \| `"light"` \| `"dark"`.        |
+| `ui("mode", "dark")`                | Set mode. Persists to `localStorage["md3:mode"]`.               |
+| `ui("themes")`                      | Returns array of baked theme names.                             |
+| `ui("theme", "stackific")`          | Swap baked theme. Persists to `localStorage["md3:theme"]`.      |
+| `await ui("theme", "#1447E6")`      | Generate theme from hex. Requires `material-dynamic-colors`.    |
+| `await ui("theme", url \| File \| Blob)` | Generate theme from image / blob. Requires `material-dynamic-colors`. |
+| `ui("theme", { light, dark })`      | Apply precomputed CSS-string per mode.                          |
+| `await ui("theme")`                 | Returns the currently-applied `{ light, dark }` token strings.  |
+| `ui("#my-dialog")`                  | Toggle a `<dialog>`.                                            |
+| `ui("#my-menu")`                    | Toggle a `<menu>`.                                              |
+| `ui("#my-snackbar")`                | Show snackbar for 6000 ms.                                      |
+| `ui("#my-snackbar", 3000)`          | Show snackbar for N ms.                                         |
+| `ui("#my-snackbar", -1)`            | Show until clicked.                                             |
+| `ui("#my-page")`                    | Activate a `.page` (siblings deactivate).                       |
+| `ui("#anything-else")`              | Toggle `.active` on the target.                                 |
+`ui("#id")` toggles: calling it on an open element closes it, calling it on a closed one opens it.
+**The JS file is almost optional.** Theme/mode swapping, dialogs, menus, snackbars, overlays, pages, and tabs all work through the CSS `.active` class plus `data-ui="#id"` clicks the browser handles natively. The runtime is required only for: slider value rendering, textarea auto-resize (on browsers without `field-sizing`), the file/color/password field wiring, and `await ui("theme", …)` MDC generation.
 ---
-## Theme + mode
+## Main layout
-Two HTML attributes drive everything:
+Any element that contains `<main>` becomes a grid with slots for edge `<nav>`s, `<header>`, `<main>`, and `<footer>`. You don't need to use every slot.
 ```html
-<html data-theme="stackific" data-mode="auto">
+<nav class="left">...</nav>
+<nav class="right">...</nav>
+<nav class="top">...</nav>
+<nav class="bottom">...</nav>
+<header class="responsive | fixed">...</header>
+<main class="responsive">...</main>
+<footer class="responsive | fixed">...</footer>
 ```
-| Attribute | Values | Purpose |
-|---|---|---|
-| `data-theme` | any name listed in `$themes` | Which brand theme supplies the tokens |
-| `data-mode` | `"auto"`, `"light"`, `"dark"` | Color mode preference |
+Grid composition:
-`data-mode="auto"` is a real attribute state — CSS handles the `auto → dark` switch via `@media (prefers-color-scheme: dark)`, so the page tracks your OS preference live. No JavaScript needed for that to work.
+```
+nav.left | nav.top    | nav.right
+nav.left | header     | nav.right
+nav.left | main       | nav.right
+nav.left | footer     | nav.right
+nav.left | nav.bottom | nav.right
+```
-### Switching at runtime
+`.responsive` caps content at 75 rem and centers it. `.fixed` makes header / footer sticky. For RTL languages set `dir="rtl"` on `<body>` or any ancestor.
-```js
-ui("mode", "dark");                                    // or "light", or "auto"
-document.documentElement.dataset.theme = "another";    // pure attribute swap, no deps
+### Compact (mobile)
+```html
+<nav class="bottom">
+  <a><i>home</i><span>Home</span></a>
+  <a><i>search</i><span>Search</span></a>
+  <a><i>share</i><span>Share</span></a>
+</nav>
+<main class="responsive">
+  <h3>Compact</h3>
+</main>
+```
+### Medium (tablet rail)
+```html
+<nav class="left">
+  <a><i>home</i><span>Home</span></a>
+  <a><i>search</i><span>Search</span></a>
+  <a><i>share</i><span>Share</span></a>
+</nav>
+<main class="responsive">
+  <h3>Medium</h3>
+</main>
 ```
-Mode is persisted to `localStorage` under the key `md3:mode` and restored on the next page load. Theme is persisted to `md3:theme`.
+### Expanded (desktop drawer)
+```html
+<nav class="left max">
+  <a><i>home</i><span>Home</span></a>
+  <a><i>search</i><span>Search</span></a>
+  <a><i>share</i><span>Share</span></a>
+</nav>
+<main class="responsive">
+  <h3>Expanded</h3>
+</main>
+```
-### Listing available themes
+### Multi-pane
-```js
-ui("themes");   // → ["stackific", "hello-pumpkin", "coral-bloom", ...]
+```html
+<nav class="left">…</nav>
+<main class="responsive">
+  <div class="grid">
+    <div class="s12 m6 l6"><h3>Pane 1</h3></div>
+    <div class="s12 m6 l6"><h3>Pane 2</h3></div>
+  </div>
+</main>
 ```
-### Adding a brand theme
+### Empty state
-If you've cloned the source, `pnpm theme add acme '#ff5722'` bakes a new theme from a single hex color, then `pnpm build` makes it reachable as `<html data-theme="acme">`. See [Local development](#local-development) below for the full workflow.
+```html
+<div class="fill medium-height middle-align center-align">
+  <div class="center-align">
+    <i class="extra">mail</i>
+    <h5>You have no new messages</h5>
+    <p>Click the button to start a conversation</p>
+    <div class="space"></div>
+    <nav class="center-align">
+      <button class="round">Send a message</button>
+    </nav>
+  </div>
+</div>
+```
 ---
-## Customize tokens
+## Components
-All M3 design tokens are CSS custom properties. Override at any scope — no rebuild required.
+### Badge
-```css
-/* whole site */
-:root {
-  --primary: #ff5722;
-  --on-primary: #ffffff;
-  --primary-container: #ffe0d6;
-}
+Corner indicators placed inside another element. Default error-colored.
-/* one card */
-article.alert {
-  --surface-container-low: #fff3e0;
-}
+```html
+<button class="circle">
+  <i>mail</i>
+  <div class="badge">3</div>
+</button>
+<button class="chip circle">
+  <i>mail</i>
+  <div class="badge">3</div>
+</button>
 ```
-Common tweaks:
+| Class                                                                | Result                                |
+| -------------------------------------------------------------------- | ------------------------------------- |
+| _(none)_                                                             | Top-right of parent, `error` colors.  |
+| `.top` / `.bottom` / `.left` / `.right`                              | Corner override.                      |
+| `.fill` / `.primary` / `.secondary` / `.tertiary`                    | Role-colored background.              |
+| `.border`                                                            | Outlined on surface background.       |
+| `.circle` / `.square` / `.round` / `.no-round` / corner-round classes | Shape variants.                     |
+| `.min`                                                               | Dot only (no text).                   |
+| `.none`                                                              | Inline (not absolutely positioned).   |
-```css
-:root {
-  --size: 1.1rem;                          /* 10% larger everywhere */
-  --font: "Inter Variable", system-ui;     /* body font */
-  --font-icon: "Material Symbols Rounded"; /* see icon styles below */
-}
+### Button
+```html
+<button>Button</button>
+<a class="button">Link button</a>
+<button>
+  <i>home</i>
+  <span>Button</span>
+</button>
 ```
-### Full token list
+`<button>` and `<a class="button">` are interchangeable. Variants combine on the same element.
+| Class                                                                                  | Result                                                       |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| _(none)_                                                                               | Filled with `primary`, 2.5 rem high, fully-rounded.          |
+| `.small` / `.large` / `.extra`                                                         | 2 / 3 / 3.5 rem high.                                        |
+| `.border`                                                                              | Outlined; `primary-text` on transparent background.          |
+| `.fill`                                                                                | `secondary-container` background.                            |
+| `.primary` / `.secondary` / `.tertiary`                                                | Role-colored background.                                     |
+| `.transparent`                                                                         | Drops background and box-shadow; for icon buttons.           |
+| `.square` / `.circle`                                                                  | No padding; equal block/inline size.                          |
+| `.round` / `.no-round` / `.small-round` / `.large-round`                               | Corner-radius scale.                                          |
+| `.left-round` / `.right-round` / `.top-round` / `.bottom-round`                        | Per-corner radius.                                            |
+| `.responsive`                                                                          | Fills the container's inline-size.                            |
+| `.horizontal` / `.vertical`                                                            | Row vs column flow of children.                               |
+| `.extend`                                                                              | Collapses to icon; expands label on hover or `.active`.      |
+| `.active`                                                                              | `primary-container` background.                              |
+| `[disabled]`                                                                           | 50% opacity, no pointer-events.                              |
+#### Responsive button
+Stretches to fill its container.
-| Group | Tokens |
-|---|---|
-| Primary | `--primary`, `--on-primary`, `--primary-container`, `--on-primary-container` |
-| Secondary | `--secondary`, `--on-secondary`, `--secondary-container`, `--on-secondary-container` |
-| Tertiary | `--tertiary`, `--on-tertiary`, `--tertiary-container`, `--on-tertiary-container` |
-| Error | `--error`, `--on-error`, `--error-container`, `--on-error-container` |
-| Neutral | `--background`, `--on-background`, `--surface`, `--on-surface`, `--surface-variant`, `--on-surface-variant`, `--outline`, `--outline-variant`, `--shadow`, `--scrim` |
-| Surface tonal | `--surface-dim`, `--surface-bright`, `--surface-container-lowest`, `--surface-container-low`, `--surface-container`, `--surface-container-high`, `--surface-container-highest` |
-| Inverse | `--inverse-surface`, `--inverse-on-surface`, `--inverse-primary` |
-| Structural | `--size`, `--font`, `--font-icon`, `--speed1`..`--speed4`, `--active`, `--overlay`, `--elevate1`..`--elevate3`, `--top`, `--bottom`, `--left`, `--right`, `--image` |
+```html
+<button class="responsive">Button</button>
-### Icon styles
+<button class="responsive">
+  <i>home</i>
+  <span>Button</span>
+</button>
+```
-Four Material Symbols variants are pre-bundled in `dist/fonts/`. Switch by changing one variable:
+#### FAB
-```css
-:root {
-  --font-icon: "Material Symbols Rounded";
-  /* "Material Symbols Outlined" (default)
-     "Material Symbols Rounded"
-     "Material Symbols Sharp"
-     "Material Symbols Subset" (smaller; common icons only) */
-}
+Floating Action Button — the primary action of a screen.
+```html
+<button class="circle extra">
+  <i>add</i>
+</button>
+<button class="square extra">
+  <i>add</i>
+</button>
+<button class="circle extra left-round top-round">
+  <i>add</i>
+</button>
 ```
----
+#### Extended FAB
-## Runtime API
+Wider FAB with a text label.
+```html
+<button class="extend circle">
+  <i>add</i>
+  <span>Create</span>
+</button>
+<button class="extend square">
+  <i>add</i>
+  <span>Create</span>
+</button>
+```
+#### FAB menu
+A FAB that opens a menu of related actions.
+```html
+<div>
+  <button class="circle extra">
+    <i>more_horiz</i>
+  </button>
+  <menu class="group no-wrap small-space top">
+    <li><button class="fill"><i>search</i><span>Search</span></button></li>
+    <li><button class="fill"><i>home</i><span>Home</span></button></li>
+    <li><button class="fill"><i>more_vert</i><span>About</span></button></li>
+  </menu>
+</div>
+```
+#### Icon button
+A transparent button shaped only on hover/press.
+```html
+<button class="transparent circle">
+  <i>search</i>
+</button>
+<button class="transparent circle">
+  <img class="responsive" src="/avatar.png">
+</button>
+```
+#### Button groups
+Standard groups, connected groups, and split buttons. Children should use directional corner rounds.
+```html
+<nav class="group">
+  <button class="left-round">Left</button>
+  <button class="no-round">Center</button>
+  <button class="right-round">Right</button>
+</nav>
+<nav class="group connected">
+  <button class="left-round">Left</button>
+  <button class="no-round">Center</button>
+  <button class="right-round">Right</button>
+</nav>
+<nav class="group split">
+  <button class="left-round">
+    <i>add_circle</i>
+    <span>Action</span>
+  </button>
+  <button class="right-round square">
+    <i>keyboard_arrow_down</i>
+  </button>
+</nav>
+```
+Add `.secondary` / `.tertiary` on `nav.group.split` to colorize the group.
+### Card
+```html
+<article>
+  <h5>Title</h5>
+  <p>Description</p>
+  <nav>
+    <button>Action</button>
+  </nav>
+</article>
+```
+| Class                                                                                       | Result                              |
+| ------------------------------------------------------------------------------------------- | ----------------------------------- |
+| _(none)_                                                                                    | Elevated, `surface-container-low`.  |
+| `.border`                                                                                   | No shadow, outline border.          |
+| `.fill` / `.primary-container` / `.secondary-container` / `.tertiary-container`             | Role-colored background.            |
+| `.small` / `.medium` / `.large`                                                             | 12 / 20 / 32 rem block-size.        |
+| `.round` / `.no-round` / `.left-round` / `.right-round` / `.top-round` / `.bottom-round`    | Corner radius.                      |
+| `.padding` / `.no-padding` / `.tiny-padding` / `.small-padding` / `.medium-padding` / `.large-padding` | Inner padding override.   |
+| `.elevate` / `.no-elevate` / `.small-elevate` / `.medium-elevate` / `.large-elevate`        | Shadow override.                    |
+#### Card with leading media
+```html
+<article>
+  <div class="row">
+    <img class="circle large" src="/avatar.png">
+    <div class="max">
+      <h5>Title</h5>
+      <div>Supporting text</div>
+    </div>
+  </div>
+  <nav>
+    <button>Action</button>
+  </nav>
+</article>
+```
+#### Card with hero media
+```html
+<article class="no-padding">
+  <img class="responsive medium" src="/hero.jpg">
+  <div class="row absolute bottom left right padding bottom-shadow">
+    <h5>Title</h5>
+    <div class="max"></div>
+    <button class="circle transparent"><i>more_vert</i></button>
+  </div>
+</article>
+```
+#### Side-by-side card
+```html
+<article class="no-padding">
+  <div class="grid no-space">
+    <div class="s6"><img class="responsive" src="/photo.jpg"></div>
+    <div class="s6">
+      <div class="padding">
+        <h5>Title</h5>
+        <p>Description</p>
+        <nav><button class="border round">Action</button></nav>
+      </div>
+    </div>
+  </div>
+</article>
+```
+### Checkbox
+```html
+<label class="checkbox">
+  <input type="checkbox">
+  <span></span>
+</label>
+<label class="checkbox">
+  <input type="checkbox">
+  <span>Click here</span>
+</label>
+```
+Sizes: `.small`, _(default)_, `.large`, `.extra`.
+#### With icons
-A single global function `ui()` (or named import `ui`) handles everything.
+```html
+<label class="checkbox icon">
+  <input type="checkbox">
+  <span>
+    <i>close</i>
+    <i>done</i>
+  </span>
+</label>
+```
+#### Inside a field
+```html
+<div class="field middle-align">
+  <nav>
+    <label class="checkbox"><input type="checkbox"><span>Item 1</span></label>
+    <label class="checkbox"><input type="checkbox"><span>Item 2</span></label>
+    <label class="checkbox"><input type="checkbox"><span>Item 3</span></label>
+  </nav>
+  <output>Helper text</output>
+</div>
+```
-### Mode + theme
+#### Indeterminate state
+Set via JavaScript — there is no HTML attribute for this:
 ```js
-ui("mode");                          // → "auto" | "light" | "dark"
-ui("mode", "dark");                  // set mode; persisted to localStorage
-ui("themes");                        // → ["stackific", ...] list of baked themes
-ui("theme", "stackific");            // swap to a baked theme (no extra deps)
-await ui("theme", "#1447E6");        // generate a theme from a hex — needs MDC
+document.getElementById("my-checkbox").indeterminate = true;
+```
+### Chip
+```html
+<button class="chip">Chip</button>
+<button class="chip">
+  <i>home</i>
+  <span>Chip</span>
+</button>
+<a class="chip">Link chip</a>
+```
+`<button class="chip">` and `<a class="chip">` are interchangeable.
+| Class                                                                    | Result                          |
+| ------------------------------------------------------------------------ | ------------------------------- |
+| _(none)_                                                                 | 2 rem, outlined.                |
+| `.small` / `.medium` / `.large`                                          | 2 / 2.5 / 3 rem.                |
+| `.fill`                                                                  | Filled (no border).             |
+| `.primary` / `.secondary` / `.tertiary`                                  | Role-colored background.        |
+| `.border` / `.no-border`                                                 | Border control.                 |
+| `.circle` / `.square`                                                    | Equal block/inline size.        |
+| `.round` / `.no-round` / corner-round classes                            | Corner radius.                  |
+| `.horizontal` / `.vertical`                                              | Child flow.                     |
+Canonical chip patterns:
+```html
+<!-- Suggestion -->
+<button class="chip">Suggestion</button>
+<!-- Input (removable) -->
+<button class="chip">
+  <span>Input</span>
+  <i>close</i>
+</button>
+<!-- Filter -->
+<button class="chip">
+  <i>done</i>
+  <span>Filter</span>
+</button>
+<!-- Assist with leading icon -->
+<button class="chip">
+  <i class="primary-text">today</i>
+  <span>Assist</span>
+</button>
+<!-- With image -->
+<button class="chip">
+  <img src="/favicon.png">
+  <span>Image</span>
+</button>
+```
+### Container
+The main content of a page.
+```html
+<main class="responsive">…</main>
 ```
-`ui("theme", source)` accepts a baked theme name, hex string, image URL, `File`, or a pre-computed `{ light, dark }` object. **Only the hex/URL/File forms require [`material-dynamic-colors`](https://www.npmjs.com/package/material-dynamic-colors)** to be loaded in the page:
+`.responsive` caps inline-size at 75 rem and centers; `.max` removes the cap.
+### Dialog
+```html
+<dialog>
+  <h5>Title</h5>
+  <p>Content of dialog</p>
+  <nav class="right-align no-space">
+    <button class="transparent link">Cancel</button>
+    <button class="transparent link">Confirm</button>
+  </nav>
+</dialog>
+```
+| Class                                                                                       | Result                                                      |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| _(none)_                                                                                    | Centered modal, 80% max block-size.                         |
+| `.small` / `.medium` / `.large`                                                             | 25% / 50% / 75%.                                            |
+| `.left` / `.right`                                                                          | Slides in from the side, full height. With `.small` 20 rem / `.medium` 32 rem / `.large` 44 rem. |
+| `.top` / `.bottom`                                                                          | Slides in vertically, full width. With `.small` 16 rem / `.medium` 24 rem / `.large` 32 rem. |
+| `.max`                                                                                      | Full-screen.                                                |
+| `.modal`                                                                                    | Opens via native `showModal()` (native backdrop, Escape, scroll lock). |
+| `.fill` / `.primary-container` / `.secondary-container` / `.tertiary-container`             | Role-colored background.                                    |
+| `.border` / `.round` / `.no-round` / corner-round classes                                   | Border and corner radius.                                   |
+| `.padding` / `.no-padding` / `.tiny-padding` / `.small-padding` / `.medium-padding` / `.large-padding` | Padding override.                                 |
+| `.elevate` / `.no-elevate` / `.small-elevate` / `.medium-elevate` / `.large-elevate`        | Shadow override.                                            |
+| `.active`                                                                                   | Open state (also `[open]` from native API).                 |
+#### Opening and closing — 5 methods
+**1. Add/remove `active` class**
+```html
+<dialog class="active">…</dialog>
+```
+**2. Native HTML `<dialog>` API**
 ```js
-import "material-dynamic-colors";    // once, at app entry
-await ui("theme", "#1447E6");        // now works
+document.querySelector("#dialog").show();        // non-modal
+document.querySelector("#dialog").showModal();   // modal
+document.querySelector("#dialog").close();
 ```
-The framework itself does not bundle MDC — install and import it yourself when you need dynamic generation.
+**3. `data-ui` attribute**
+```html
+<button data-ui="#dialog">Open</button>
+<dialog id="dialog">
+  <h5>Title</h5>
+  <nav class="right-align no-space">
+    <button data-ui="#dialog">Cancel</button>
+    <button data-ui="#dialog">Confirm</button>
+  </nav>
+</dialog>
+```
-### Component triggers
+**4. `ui()` call**
 ```js
-ui("#my-dialog");           // toggle a <dialog>
-ui("#my-snackbar");         // show snackbar for 6s
-ui("#my-snackbar", 3000);   // show for 3s
-ui("#my-snackbar", -1);     // show until clicked
-ui("#my-page");             // activate a .page (tab-style content)
+ui("#dialog");
 ```
-These are equivalent to clicking an element with `[data-ui="#id"]`.
+**5. Popover API**
+```html
+<button popovertarget="dialog">Open</button>
-### Utilities
+<dialog id="dialog" popover>
+  <h5>Title</h5>
+</dialog>
+```
 ```js
-ui();           // re-scan the DOM (call after dynamically injecting markup)
-ui("guid");     // → UUID-v4 string, handy for unique input ids
+document.querySelector("#dialog").showPopover();
+document.querySelector("#dialog").hidePopover();
+document.querySelector("#dialog").togglePopover();
 ```
----
+#### Custom overlay
-## Local development
+Place an `.overlay` sibling immediately before the dialog; modifier classes on the overlay are honored:
+```html
+<div class="overlay blur"></div>
+<dialog id="dialog">…</dialog>
+```
-These commands are for hacking on the framework itself, not for consumers of the published package.
+#### Navigation drawer
-```sh
-git clone https://github.com/stackific/md3
-cd md3
-pnpm install
-pnpm build              # → dist/md3.css + dist/md3.js
-pnpm demo               # build + start the demo Vue app at http://localhost:5001
+```html
+<div class="overlay"></div>
+<dialog id="drawer" class="left">
+  <header>
+    <nav>
+      <img class="circle large" src="/avatar.png">
+      <h6 class="max">Title</h6>
+      <button class="transparent circle large" data-ui="#drawer">
+        <i>close</i>
+      </button>
+    </nav>
+  </header>
+  <ul class="list">
+    <li class="wave round"><i>inbox</i><span class="max">Inbox</span><b>24</b></li>
+    <li class="wave round"><i>send</i><span>Outbox</span></li>
+    <li class="wave round"><i>favorite</i><span>Favorites</span></li>
+    <li class="wave round"><i>delete</i><span>Trash</span></li>
+  </ul>
+</dialog>
 ```
-### Adding or removing a brand theme
+### Divider
-```sh
-pnpm theme add acme '#ff5722'    # quote the hex
-pnpm theme remove acme
-pnpm build                        # re-emit dist/
+```html
+<hr>
+<hr class="small">
+<hr class="medium">
+<hr class="large">
+<div class="divider"></div>
+<div class="divider vertical"></div>
+```
+`.small` / `.medium` / `.large` control vertical margin (0.5 / 1 / 1.5 rem). `.vertical` produces a vertical rule.
+### Expansion
+Use native `<details>` / `<summary>`.
+```html
+<details>
+  <summary>Header</summary>
+  <p>Body content</p>
+</details>
 ```
-`add` derives the M3 light + dark token sets and a 10-step tonal palette from the source color, then writes both:
+Multi-level:
-- `src/styles/_config.scss` → upserts the entry in `$material-palette` so `.acme`, `.acme1`..`.acme10`, `.acme-text`, `.acme-border` utility classes become available.
-- `src/styles/settings/_themes.scss` → upserts a named block in `$themes` so `<html data-theme="acme">` activates it.
+```html
+<details>
+  <summary>Level 1</summary>
+  <details>
+    <summary>Level 2</summary>
+    <details>
+      <summary>Level 3</summary>
+      <p>Body</p>
+    </details>
+  </details>
+</details>
+```
+Custom summary (hides the marker):
+```html
+<details>
+  <summary class="none">
+    <button>Custom trigger</button>
+  </summary>
+  <p>Body</p>
+</details>
+```
+### Field
+Wrapper for inputs, selects, textareas, and composite controls.
+```html
+<div class="field border">
+  <input type="text">
+</div>
+```
+`.label` is optional; with it, the label floats above the input when focused or filled.
+```html
+<div class="field label border">
+  <input type="text" placeholder=" ">
+  <label>Label</label>
+</div>
+```
+| Class                                       | Result                                            |
+| ------------------------------------------- | ------------------------------------------------- |
+| `.label`                                    | Adds a floating label child.                      |
+| `.border`                                   | Outlined.                                         |
+| `.fill`                                     | Filled (`surface-variant`).                       |
+| `.round`                                    | Pill shape.                                       |
+| `.small` / _(default)_ / `.large` / `.extra` | 2.5 / 3 / 3.5 / 4 rem input height.              |
+| `.prefix`                                   | Extra start-padding for a leading icon child.     |
+| `.suffix`                                   | Extra end-padding for a trailing icon child.      |
+| `.invalid`                                  | Error coloring; shows `<output class="invalid">`. |
+#### Input
+```html
+<div class="field border">
+  <input type="text">
+</div>
+<div class="field border">
+  <input type="text">
+  <output>Helper text</output>
+</div>
+<div class="field invalid border">
+  <input type="text">
+  <output class="invalid">Error text</output>
+</div>
+<div class="field label border">
+  <input type="text" placeholder=" ">
+  <label>Label</label>
+</div>
+<div class="field label prefix border">
+  <i>search</i>
+  <input type="text">
+  <label>Label</label>
+</div>
+<div class="field label suffix border">
+  <input type="text">
+  <label>Label</label>
+  <i>visibility</i>
+</div>
+<div class="field label prefix suffix border">
+  <i>search</i>
+  <input type="text">
+  <label>Label</label>
+  <i>tune</i>
+</div>
+```
+Clickable prefix/suffix icons — wrap in `<a>` or use `<i class="front">`:
+```html
+<div class="field label prefix border">
+  <a><i>search</i></a>
+  <input type="text">
+  <label>Label</label>
+</div>
+<div class="field label prefix border">
+  <i class="front">search</i>
+  <input type="text">
+  <label>Label</label>
+</div>
+```
+Floating-label triggers — either add `placeholder=" "` (pure CSS) or let the runtime toggle `.active`:
+```html
+<!-- CSS-only -->
+<div class="field label border">
+  <input type="text" placeholder=" ">
+  <label>Label</label>
+</div>
+<!-- Manual control -->
+<div class="field label border">
+  <input type="text" class="active">
+  <label class="active">Label</label>
+</div>
+```
+Password fields auto-wire a visibility toggle when a child `<i>visibility</i>` is present:
+```html
+<div class="field label suffix border">
+  <input type="password">
+  <label>Password</label>
+  <i>visibility</i>
+</div>
+```
-`remove` strips both.
+#### Select
-### Editing tokens directly
+```html
+<div class="field suffix border">
+  <select>
+    <option>Item 1</option>
+    <option>Item 2</option>
+    <option>Item 3</option>
+  </select>
+  <i>arrow_drop_down</i>
+</div>
+<div class="field label suffix border">
+  <select>
+    <option>Item 1</option>
+    <option>Item 2</option>
+  </select>
+  <label>Label</label>
+  <i>arrow_drop_down</i>
+  <output>Helper text</output>
+</div>
+```
+#### Textarea
+Auto-resizes unless `[rows]` is set.
+```html
+<div class="field border">
+  <textarea></textarea>
+</div>
+<div class="field border">
+  <textarea rows="10"></textarea>
+</div>
+<div class="field label border">
+  <textarea placeholder=" "></textarea>
+  <label>Label</label>
+</div>
+```
+#### Search
+Search field with auto-suggestion menu.
+```html
+<div class="field large prefix round fill">
+  <i class="front">search</i>
+  <input>
+  <menu class="min">
+    <li class="transparent">
+      <div class="field large prefix">
+        <i class="front">arrow_back</i>
+        <input>
+      </div>
+    </li>
+    <li><i>history</i><div>Recent 1</div></li>
+    <li><i>history</i><div>Recent 2</div></li>
+    <li><i>history</i><div>Recent 3</div></li>
+  </menu>
+</div>
+```
+FAB-anchored search:
+```html
+<div>
+  <button class="extra circle fill">
+    <i>search</i>
+  </button>
+  <menu class="no-wrap left min">
+    <li class="transparent">
+      <div class="field large prefix">
+        <i class="front">arrow_back</i>
+        <input>
+      </div>
+    </li>
+    <li><i>history</i><div>Recent 1</div></li>
+  </menu>
+</div>
+```
+#### Custom inputs (file, color, date, time)
+Wrap a hidden input in a button trigger; the runtime mirrors values back into a sibling text input.
+```html
+<div>
+  <button class="circle"><i>attach_file</i></button>
+  <input type="file">
+</div>
+<div>
+  <button class="circle"><i>palette</i></button>
+  <input type="color">
+</div>
+<div>
+  <button class="circle"><i>today</i></button>
+  <input type="date">
+</div>
+<div>
+  <button class="circle"><i>schedule</i></button>
+  <input type="time">
+</div>
+<!-- With label -->
+<div>
+  <button><i>attach_file</i><span>File</span></button>
+  <input type="file">
+</div>
+```
+### Grid
-If you'd rather edit token values by hand instead of running `pnpm theme add`, the shape of `$themes` is:
+12-column grid with 1 rem gap. Cell wrappers live immediately inside `.grid` — don't put `.grid` and `.s1`–`.s12` on the same element.
-```scss
-$themes: (
-  "stackific": (
-    "light": ( "primary": #1c4bea, "on-primary": #ffffff, /* ... */ ),
-    "dark":  ( "primary": #b9c3ff, /* ... */ ),
-  ),
-);
+```html
+<div class="grid">
+  <div class="s12 m6 l3"><h5>First</h5></div>
+  <div class="s12 m6 l3"><h5>Second</h5></div>
+  <div class="s12 m6 l3"><h5>Third</h5></div>
+  <div class="s12 m6 l3"><h5>Fourth</h5></div>
+</div>
 ```
-Token keys are kebab-cased and match the CSS custom-property names verbatim.
+| Class            | Active             |
+| ---------------- | ------------------ |
+| `.s1` … `.s12`   | Always.            |
+| `.m1` … `.m12`   | ≥ 601 px.          |
+| `.l1` … `.l12`   | ≥ 993 px.          |
-### Configure which roles get utility classes
+Gap modifiers on `.grid`: `.no-space`, `.space`, `.small-space`, `.medium-space` (1.5 rem), `.large-space` (2 rem).
-`src/styles/_config.scss` controls which M3 roles generate `.role`, `.role-text`, `.role-border`, `.role-container`, and `nav.role`/`menu.role` active-state recoloring:
+✅ **Do** put component elements inside the cell:
-```scss
-$theme-roles-paired:      ("primary", "secondary", "tertiary", "error", "background");
-$theme-roles-with-edges:  ("primary", "secondary", "tertiary", "error");
-$theme-roles-container:   ("primary", "secondary", "tertiary", "error");
-$theme-roles-nav-active:  ("primary", "secondary", "tertiary");
+```html
+<div class="grid">
+  <div class="s12 m6 l3"><article>…</article></div>
+  <div class="s12 m6 l3"><div class="field">…</div></div>
+</div>
 ```
-### Other things you can edit in SCSS
+🚫 **Don't** put grid classes directly on the element:
-| File | What's there |
-|---|---|
-| `src/styles/_config.scss` | `$material-palette`, role lists, `$breakpoints`, mixins |
-| `src/styles/settings/_themes.scss` | `$themes` (light/dark tokens per brand) |
-| `src/styles/settings/_fonts.scss` | Material Symbols `@font-face` declarations |
-| `src/styles/elements/_*.scss` | Per-component scales (`$-button-sizes`, `$-chip-sizes`, etc.) |
-| `src/styles/elements/_shapes.scss` | `$-shapes` list of SVG-backed shape utilities |
+```html
+<div class="grid">
+  <article class="s12 m6 l3">…</article>      <!-- breaks layout -->
+</div>
+```
-## Publish
+### Header & Footer
-```bash
-pnpm prepublishOnly
-npm publish --access public --dry-run
-npm publish --access public
+```html
+<header>
+  <nav>
+    <button class="circle transparent"><i>arrow_back</i></button>
+    <h5 class="max">Title</h5>
+    <button class="circle transparent"><i>more_vert</i></button>
+  </nav>
+</header>
+<footer>
+  <nav>
+    <button class="circle transparent"><i>check_box</i></button>
+    <button class="circle transparent"><i>brush</i></button>
+    <div class="max"></div>
+    <button class="square round extra primary"><i>add</i></button>
+  </nav>
+</footer>
 ```
+| Class                              | Result                                                        |
+| ---------------------------------- | ------------------------------------------------------------- |
+| _(none)_                           | 4 rem min (header), 5 rem min (footer).                       |
+| `.fixed`                           | Sticky inside the container.                                  |
+| `.responsive`                      | Caps content at 75 rem and centers it.                        |
+| `.max`                             | Removes the 75 rem cap.                                       |
+When `.fixed` and a scrollable parent are used together, header/footer stick to the parent's top/bottom edge:
+```html
+<article class="small-width small-height scroll">
+  <header class="fixed bold">Fixed header</header>
+  <p>Long body content…</p>
+  <p>…that scrolls underneath.</p>
+  <footer class="fixed bold">Fixed footer</footer>
+</article>
+```
+### Icon
+Material Symbols ligature. Four font variants ship inside the CSS bundle.
+```html
+<i>home</i>
+<i>
+  <svg viewBox="0 0 24 24">
+    <path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z"></path>
+  </svg>
+</i>
+<i>
+  <img src="/icon.png">
+</i>
+```
+| Class    | Size     |
+| -------- | -------- |
+| `.tiny`  | 1 rem    |
+| `.small` | 1.25 rem |
+| _(none)_ | 1.5 rem  |
+| `.large` | 1.75 rem |
+| `.extra` | 2 rem    |
+| `.fill`  | Filled (`FILL=1`) variation. Also auto-applied inside `<a class="active">` / `<button class="active">`. |
+Switch font variant via `--font-icon`:
+```css
+:root { --font-icon: "Material Symbols Rounded"; }
+/* "Material Symbols Outlined" (default), "Material Symbols Rounded",
+   "Material Symbols Sharp", "Material Symbols Subset" (smaller bundle), or none */
+```
+Sharing one SVG sprite across multiple icons:
+```html
+<svg viewBox="0 0 24 24" style="display: none">
+  <g id="home"><path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z"/></g>
+  <g id="star"><path d="M12,17.27L18.18,21L16.54,13.97L22,9.24L14.81,8.62L12,2L9.19,8.62L2,9.24L7.45,13.97L5.82,21L12,17.27Z"/></g>
+</svg>
+<i><svg viewBox="0 0 24 24"><use href="#home"/></svg></i>
+<i><svg viewBox="0 0 24 24"><use href="#star"/></svg></i>
+```
+Third-party icon fonts work too (Font Awesome, MDI, …) — load them yourself:
+```html
+<i class="fa-regular fa-clock"></i>
+<i class="mdi mdi-clock-outline"></i>
+```
+### Layout
+Positioning containers — absolute (relative to parent) or fixed (relative to viewport).
+```html
+<article class="small">
+  <div class="absolute left bottom right">
+    <h5>Pinned to container bottom</h5>
+  </div>
+</article>
+<div class="fixed left bottom right">
+  <h5>Pinned to viewport bottom</h5>
+</div>
+```
+| Class                                                          | Effect                                          |
+| -------------------------------------------------------------- | ----------------------------------------------- |
+| `.absolute` / `.fixed`                                         | Positioning context.                            |
+| `.left` / `.right` / `.top` / `.bottom`                        | Pin to that edge.                               |
+| `.front` / `.back`                                             | z-index +10 / −10.                              |
+| `.center` / `.middle`                                          | Horizontal / vertical centering.                |
+| `.small` / `.medium` / `.large`                                | With `.left.right`: 20 / 28 / 44 rem block-size. With `.top.bottom`: same inline-size. |
+```html
+<article class="small">
+  <span class="absolute center middle">Centered</span>
+</article>
+<article class="small center-align middle-align">
+  <span>Centered via alignment</span>
+</article>
+```
+### List
+```html
+<ul class="list">
+  <li>Item</li>
+  <li>Item</li>
+</ul>
+<ol class="list">
+  <li>Item</li>
+</ol>
+```
+| Class                                                     | Result                       |
+| --------------------------------------------------------- | ---------------------------- |
+| _(none)_                                                  | 3.5 rem rows, no dividers.   |
+| `.border`                                                 | Bottom divider between rows. |
+| `.no-space` / `.space` / `.small-space`                   | 2.5 / 3 / 3.5 rem rows.      |
+| `.medium-space` / `.large-space`                          | 4.5 / 5.5 rem rows.          |
+#### Nested
+```html
+<ul class="list">
+  <li>Item</li>
+  <li>
+    <ul class="list">
+      <li>Nested</li>
+      <li>Nested</li>
+    </ul>
+  </li>
+</ul>
+```
+#### Expansion list
+```html
+<ul class="list">
+  <li>Item</li>
+  <li>
+    <details>
+      <summary>Header</summary>
+      <ul class="list">
+        <li>Inner</li>
+      </ul>
+    </details>
+  </li>
+</ul>
+```
+#### Headline and supporting text
+```html
+<ul class="list border">
+  <li>
+    <button class="circle">A</button>
+    <div class="max">
+      <h6 class="small">Headline</h6>
+      <div>Supporting text</div>
+    </div>
+    <label>+15 min</label>
+  </li>
+</ul>
+```
+With leading icon or avatar:
+```html
+<ul class="list">
+  <li>
+    <i>home</i>
+    <div class="max">
+      <h6 class="small">Headline</h6>
+      <div>Supporting text</div>
+    </div>
+    <label>+15 min</label>
+  </li>
+  <li>
+    <img class="round" src="/avatar.png">
+    <div class="max">
+      <h6 class="small">Headline</h6>
+      <div>Supporting text</div>
+    </div>
+  </li>
+</ul>
+```
+### Media
+```html
+<img src="/image.png" class="circle extra">
+<video class="circle extra">
+  <source src="/video.mp4" type="video/mp4">
+</video>
+<svg class="circle extra" viewBox="0 0 24 24">
+  <path d="…"/>
+</svg>
+```
+| Class                                                              | Result                                              |
+| ------------------------------------------------------------------ | --------------------------------------------------- |
+| `.tiny` / `.small` / _(default)_ / `.large` / `.extra`             | 2 / 2.5 / 3 / 3.5 / 4 rem square.                   |
+| `.circle` / `.round` / `.square`                                   | Border-radius style.                                |
+| `.no-round` / `.left-round` / `.right-round` / `.top-round` / `.bottom-round` | Per-corner radius.                       |
+| `.responsive`                                                      | 100% inline-size.                                   |
+| `.responsive.tiny` / `.small` / `.medium` / `.large` / `.extra`    | Fixed block-size 4 / 8 / 12 / 16 / 20 rem.          |
+| `.empty-state`                                                     | Max 24 rem wide; for empty-state illustrations.     |
+### Menu
+```html
+<div>
+  <button>
+    <span>Menu</span>
+    <i>arrow_drop_down</i>
+  </button>
+  <menu>
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </menu>
+</div>
+```
+With links:
+```html
+<div>
+  <button>
+    <span>Links</span>
+    <i>arrow_drop_down</i>
+  </button>
+  <menu>
+    <li><a href="#">Item 1</a></li>
+    <li><a href="#">Item 2</a></li>
+  </menu>
+</div>
+```
+With divider:
+```html
+<menu>
+  <li>Item 1</li>
+  <li><hr></li>
+  <li>Item 2</li>
+</menu>
+```
+Selected state:
+```html
+<menu>
+  <li>Item 1</li>
+  <li class="active">Item 2</li>
+  <li>Item 3</li>
+</menu>
+```
+| Class                                                                                   | Result                                          |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| _(none)_                                                                                | Anchored below trigger, full width.             |
+| `.no-wrap`                                                                              | Width fits content; never wraps.                |
+| `.wrap`                                                                                 | Allow item wrap.                                |
+| `.min`                                                                                  | Compact anchored popover.                       |
+| `.max`                                                                                  | Full-screen.                                    |
+| `.top` / `.bottom` / `.left` / `.right`                                                 | Open direction / alignment.                     |
+| `.border`                                                                               | Outlined.                                       |
+| `.group`                                                                                | Visually merges with parent (no shadow / bg).   |
+| `.no-space` / `.space` / `.tiny-space` / `.small-space` / `.medium-space` / `.large-space` / `.extra-space` | Gap scale.                  |
+#### Submenu
+```html
+<div>
+  <button>
+    <span>Menu</span>
+    <i>arrow_drop_down</i>
+  </button>
+  <menu>
+    <li>
+      <span>Submenu</span>
+      <menu>
+        <li>Item</li>
+        <li>Item</li>
+      </menu>
+    </li>
+  </menu>
+</div>
+```
+#### Grouped menu
+`.group` makes the menu transparent and stacks groups visually.
+```html
+<div>
+  <button>
+    <span>Grouped</span>
+    <i>arrow_drop_down</i>
+  </button>
+  <menu class="group">
+    <li>
+      <menu>
+        <li>Item</li>
+        <li>Item</li>
+      </menu>
+    </li>
+    <li>
+      <menu>
+        <li>Item</li>
+        <li>Item</li>
+      </menu>
+    </li>
+  </menu>
+</div>
+```
+#### Opening and closing
+Three patterns:
+1. **Active class:** `<menu class="active">…</menu>`
+2. **`data-ui` attribute:** `<div data-ui="#menu"><menu id="menu">…</menu></div>`
+3. **`ui()` call:** `ui("#menu")`
+Clicking outside an open menu closes it automatically.
+### Navigation
+`<nav>` and `.row` are interchangeable containers — `<nav>` is semantic, `.row` is not.
+```html
+<nav>
+  <button>Button</button>
+  <a class="chip">Chip</a>
+  <a><img class="circle" src="/avatar.png"></a>
+  <label class="checkbox"><input type="checkbox"></label>
+</nav>
+<div class="row">
+  <div>min</div>
+  <div class="max">max</div>
+  <div>min</div>
+</div>
+```
+| Class on `<nav>` / `.row`                                                                       | Result                                |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `.no-space` / `.tiny-space` / `.small-space` / `.medium-space` / `.large-space`                 | Gap: 0 / 0.5 / 1 / 1.5 / 2 rem.       |
+| `.left-align` / `.center-align` / `.right-align`                                                | Justify-content (also `text-align`).  |
+| `.top-align` / `.middle-align` / `.bottom-align`                                                | Align-items.                          |
+| `.horizontal` / `.vertical`                                                                     | Flow direction.                       |
+| `.wrap` / `.no-wrap`                                                                            | Flex-wrap behavior.                   |
+| `.min`                                                                                          | Inline-flex; shrinks to content.      |
+| `.max`                                                                                          | `flex: 1` (children with `.max` grow). |
+| `.border` / `.round` / `.no-round` / corner-round classes                                       | Border and corner radius.             |
+| `.margin` / `.no-margin` / `.tiny-margin` / `.small-margin` / `.medium-margin` / `.large-margin` | Outer margin.                         |
+| `.fill` / `.primary-container` / `.secondary-container` / `.tertiary-container`                 | Role-colored background.              |
+| `.elevate` / `.no-elevate` / `.small-elevate` / `.medium-elevate` / `.large-elevate`            | Shadow.                               |
+#### Navigation rail (vertical edge)
+```html
+<nav class="left">
+  <a><i>home</i><div>Home</div></a>
+  <a><i>search</i><div>Search</div></a>
+  <a><i>more_vert</i><div>More</div></a>
+</nav>
+<nav class="left max">
+  <a><i>home</i><div>Home</div></a>
+  <a><i>search</i><div>Search</div></a>
+</nav>
+```
+#### Navigation bar (horizontal edge)
+```html
+<nav class="bottom">
+  <a><i>home</i><div>Home</div></a>
+  <a><i>search</i><div>Search</div></a>
+  <a><i>more_vert</i><div>More</div></a>
+</nav>
+<nav class="top max">
+  <a><i>home</i><div>Home</div></a>
+</nav>
+```
+#### Tabbed nav
+```html
+<nav class="tabbed">
+  <a class="active"><i>info</i><span>Overview</span></a>
+  <a><i>style</i><span>Specs</span></a>
+  <a><i>design_services</i><span>Guidelines</span></a>
+</nav>
+```
+`nav.tabbed`: default 4 rem height, `.small` 3 rem, `.large` 5 rem.
+#### Toolbar
+```html
+<nav class="toolbar">
+  <a><i>videocam_off</i></a>
+  <a><i>mic</i></a>
+  <a class="active"><i>front_hand</i></a>
+  <a><i>more_vert</i></a>
+</nav>
+```
+`.fill` (primary-container), `.vertical`, `.max` (full width) all work on `nav.toolbar`.
+#### Group / connected / split
+```html
+<nav class="group">
+  <button class="left-round">Left</button>
+  <button class="no-round">Center</button>
+  <button class="right-round">Right</button>
+</nav>
+<nav class="group connected">
+  <button class="left-round">Left</button>
+  <button class="no-round">Center</button>
+  <button class="right-round">Right</button>
+</nav>
+<nav class="group split">
+  <button class="left-round"><i>add_circle</i><span>Action</span></button>
+  <button class="right-round square"><i>keyboard_arrow_down</i></button>
+</nav>
+```
+#### List form
+```html
+<nav>
+  <ul>
+    <li><button>Button</button></li>
+    <li><a class="chip">Chip</a></li>
+  </ul>
+</nav>
+```
+### Overlay
+Scrim that blocks the screen. Used with dialogs or as a standalone loading curtain.
+```html
+<div class="overlay center-align middle-align">
+  <progress class="circle"></progress>
+</div>
+```
+| Class                                                                       | Result                          |
+| --------------------------------------------------------------------------- | ------------------------------- |
+| `.active`                                                                   | Shown.                          |
+| `.blur` / `.small-blur` / `.medium-blur` / `.large-blur`                    | Backdrop-blur effect.           |
+| `.left-align` / `.right-align` / `.center-align` / `.top-align` / `.bottom-align` / `.middle-align` | Align inner content. |
+Opening and closing — same three patterns:
+1. **Active class:** `<div class="overlay active">…</div>`
+2. **`data-ui`:** `<button data-ui="#overlay">Show</button>` + `<div class="overlay" id="overlay">…</div>`
+3. **`ui()`:** `ui("#overlay")`
+### Page
+```html
+<div class="page active">
+  <h5>Title</h5>
+</div>
+```
+| Class                                          | Result                                |
+| ---------------------------------------------- | ------------------------------------- |
+| `.active`                                      | Visible.                              |
+| `.left` / `.right` / `.top` / `.bottom`        | Entry transform direction.            |
+Activating a page — three patterns:
+1. **Active class:** add `.active` to one, remove from siblings.
+2. **`data-ui`:** `<a data-ui="#page1">Open</a>` — siblings at the same level deactivate.
+3. **`ui()`:** `ui("#page1")`.
+### Progress
+```html
+<progress></progress>                                <!-- indeterminate -->
+<progress value="25" max="100"></progress>           <!-- linear -->
+<progress class="wavy"></progress>
+<progress class="wavy" value="25" max="100"></progress>
+<progress class="circle"></progress>                 <!-- circular indeterminate -->
+<progress class="circle" value="25" max="100"></progress>
+<progress class="circle wavy"></progress>
+<progress class="circle wavy" value="25" max="100"></progress>
+```
+| Class            | Result                                       |
+| ---------------- | -------------------------------------------- |
+| _(none)_         | Linear, 0.25 rem thick.                      |
+| `.small` / `.medium` / `.large` | 0.25 / 0.35 / 0.45 rem thick. |
+| `.indeterminate` | Forces animated indeterminate state.         |
+| `.wavy`          | Wavy SVG track (linear or circle).           |
+| `.circle`        | Circular; `.small` 1.5 rem / _(default)_ 2.5 / `.large` 3.5. |
+| `.max`           | Absolutely fills the parent (use inside `<article>`, `<button>`, …). |
+A bare `<progress></progress>` is auto-promoted to indeterminate at boot.
+### Radio
+```html
+<label class="radio">
+  <input type="radio">
+  <span></span>
+</label>
+<label class="radio">
+  <input type="radio">
+  <span>Click here</span>
+</label>
+```
+Sizes: `.small`, _(default)_, `.large`, `.extra`.
+#### With icons
+```html
+<label class="radio icon">
+  <input type="radio">
+  <span>
+    <i>close</i>
+    <i>done</i>
+  </span>
+</label>
+```
+#### Group inside a field
+```html
+<div class="field middle-align">
+  <nav>
+    <label class="radio"><input type="radio" name="g"><span>Item 1</span></label>
+    <label class="radio"><input type="radio" name="g"><span>Item 2</span></label>
+    <label class="radio"><input type="radio" name="g"><span>Item 3</span></label>
+  </nav>
+  <output>Helper text</output>
+</div>
+```
+### Shape
+SVG-masked decorative element. Place inside `<button>`, `<div>`, or a sized container.
+```html
+<div class="shape sunny"></div>
+<div class="shape sunny">
+  <img class="responsive" src="/favicon.png">
+</div>
+<div class="small-width small-height">
+  <div class="shape sunny max"></div>
+</div>
+```
+| Class                                                                          | Result                          |
+| ------------------------------------------------------------------------------ | ------------------------------- |
+| `.tiny` / `.small` / _(default)_ / `.medium` / `.large` / `.extra`             | 2.5 / 3 / 3.5 / 4.5 / 5.5 / 6.5 rem. |
+| `.max`                                                                         | Fills the parent.               |
+| `.space` / `.no-space` / `.tiny-space` / `.small-space` / `.medium-space` / `.large-space` / `.extra-space` | Inner mask padding. |
+| `.rotate` / `.slow-rotate` / `.fast-rotate`                                    | Rotation animation (12 s / 24 s / 6 s). |
+**Shape names** (one per class):
+`arch`, `arrow`, `boom`, `bun`, `burst`, `circle`, `clamshell`, `diamond`, `fan`, `flower`, `gem`, `ghost-ish`, `heart`, `leaf-clover4`, `leaft-clover8`, `loading-indicator`, `oval`, `pentagon`, `pill`, `pixel-circle`, `pixel-triangle`, `puffy`, `puffy-diamond`, `semicircle`, `sided-cookie4`, `sided-cookie6`, `sided-cookie7`, `sided-cookie9`, `sided-cookie12`, `slanted`, `soft-boom`, `soft-burst`, `square`, `sunny`, `triangle`, `very-sunny`, `wavy`, `wavy-circle`.
+Inside a button:
+```html
+<button class="circle extra transparent">
+  <span class="shape sided-cookie12 max medium-space"></span>
+</button>
+```
+Spinner:
+```html
+<div class="shape sided-cookie12 transparent rotate">
+  <button class="responsive">
+    <i>search</i>
+  </button>
+</div>
+```
+### Slider
+Default range is 0–100.
+```html
+<div class="slider">
+  <input type="range">
+  <span></span>
+</div>
+<div class="slider">
+  <input type="range" min="4" max="8">
+  <span></span>
+</div>
+```
+| Class                                                              | Track size |
+| ------------------------------------------------------------------ | ---------- |
+| `.tiny`                                                            | 1 rem      |
+| `.small`                                                           | 1.5 rem    |
+| `.medium`                                                          | 2.5 rem    |
+| `.large`                                                           | 3.5 rem    |
+| `.extra`                                                           | 6 rem      |
+| `.vertical`                                                        | Rotates 90°. |
+| `.max`                                                             | Fills the parent (container slider). |
+#### Dual thumb
+```html
+<div class="slider">
+  <input type="range" value="25">
+  <input type="range" value="50">
+  <span></span>
+</div>
+```
+#### Value tooltip
+```html
+<div class="slider">
+  <input type="range">
+  <span></span>
+  <div class="tooltip"></div>
+</div>
+```
+#### Inset icon
+The icon appears only with `.medium`, `.large`, or `.extra`.
+```html
+<div class="slider medium">
+  <input type="range">
+  <span><i>sunny</i></span>
+</div>
+```
+#### Inside a field
+```html
+<div class="field middle-align">
+  <div class="slider">
+    <input type="range">
+    <span></span>
+  </div>
+  <output>Helper</output>
+</div>
+```
+#### Container slider
+```html
+<article>
+  <div class="slider max">
+    <input type="range">
+    <span></span>
+  </div>
+</article>
+```
+### Snackbar
+```html
+<div class="snackbar">
+  <i>warning</i>
+  <span>I'm a snackbar</span>
+</div>
+```
+| Class                                                       | Result                                  |
+| ----------------------------------------------------------- | --------------------------------------- |
+| _(none)_                                                    | Bottom-centered; auto-hides after 6 s.  |
+| `.top` / `.bottom`                                          | Anchor position.                        |
+| `.error` / `.primary` / `.secondary` / `.tertiary`          | Role-colored background.                |
+| `.active`                                                   | Shown.                                  |
+#### With action
+```html
+<div class="snackbar">
+  <div class="max">Item moved to trash</div>
+  <a class="inverse-primary-text">Undo</a>
+</div>
+```
+Opening — four patterns:
+1. **Active class:** add `.active`.
+2. **`data-ui`:** `<button data-ui="#snack">Show</button>`.
+3. **`ui()`:** `ui("#snack")` — default 6000 ms; `ui("#snack", 3000)` for a custom timeout; `ui("#snack", -1)` to keep open until click.
+4. **Popover API:**
+   ```html
+   <button popovertarget="snack">Show</button>
+   <div class="snackbar" id="snack" popover>I'm a snackbar</div>
+   ```
+   ```js
+   document.querySelector("#snack").showPopover();
+   document.querySelector("#snack").hidePopover();
+   document.querySelector("#snack").togglePopover();
+   ```
+Only one snackbar shows at a time — opening one dismisses any open siblings.
+### Switch
+```html
+<label class="switch">
+  <input type="checkbox">
+  <span></span>
+</label>
+<nav>
+  <div class="max">
+    <h6>Title</h6>
+    <div>Complementary text</div>
+  </div>
+  <label class="switch">
+    <input type="checkbox">
+    <span></span>
+  </label>
+</nav>
+```
+Sizes: `.small`, _(default)_, `.large`, `.extra`.
+#### With icons
+```html
+<label class="switch icon">
+  <input type="checkbox">
+  <span><i>wifi</i></span>
+</label>
+<label class="switch icon">
+  <input type="checkbox">
+  <span>
+    <i>close</i>
+    <i>done</i>
+  </span>
+</label>
+```
+#### Inside a field
+```html
+<div class="field middle-align">
+  <nav>
+    <div class="max">
+      <h6>Title</h6>
+      <div>Complementary text</div>
+    </div>
+    <label class="switch">
+      <input type="checkbox">
+      <span></span>
+    </label>
+  </nav>
+</div>
+```
+### Table
+```html
+<table>
+  <thead>
+    <tr><th>Header</th><th>Header</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Cell</td><td>Cell</td></tr>
+    <tr><td>Cell</td><td>Cell</td></tr>
+  </tbody>
+  <tfoot>
+    <tr><th>Footer</th><th>Footer</th></tr>
+  </tfoot>
+</table>
+```
+| Class on `<table>`                                                                       | Result            |
+| ---------------------------------------------------------------------------------------- | ----------------- |
+| `.border`                                                                                | Row dividers.     |
+| `.stripes`                                                                               | Zebra rows.       |
+| `.no-space` / `.space` / `.small-space` / `.medium-space` / `.large-space`               | Cell padding.     |
+| `.left-align` / `.center-align` / `.right-align`                                         | Text alignment.   |
+`<th class="fixed">`, `<thead class="fixed">`, `<tfoot class="fixed">` for sticky headers/footers inside a scrolling container. `<td class="min">` / `<th class="min">` shrinks the cell to its content.
+#### Scroll
+```html
+<div class="scroll small-height">
+  <table>
+    <thead class="fixed">
+      <tr><th>Header</th><th>Header</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Cell</td><td>Cell</td></tr>
+    </tbody>
+  </table>
+</div>
+```
+### Tabs
+```html
+<div class="tabs">
+  <a class="active">Tab 1</a>
+  <a>Tab 2</a>
+  <a>Tab 3</a>
+</div>
+<div class="page padding active"><h5>Tab 1</h5></div>
+<div class="page padding"><h5>Tab 2</h5></div>
+<div class="page padding"><h5>Tab 3</h5></div>
+```
+| Class on `.tabs`                                          | Result                |
+| --------------------------------------------------------- | --------------------- |
+| `.small` / `.large`                                       | 2 / 4 rem min height. |
+| `.min`                                                    | Shorter active underline. |
+| `.max`                                                    | Tabs grow to fill.    |
+| `.left-align` / `.center-align` / `.right-align`          | Justify-content.      |
+| `.horizontal` / `.vertical`                               | Flow direction.       |
+Activating tabs — two patterns:
+1. **Active class:** add `.active` to one tab `<a>` and one matching `.page`, remove from siblings.
+2. **`data-ui`:** `<a data-ui="#page1">Tab 1</a>` — the matching `.page` activates, siblings hide.
+### Tooltip
+A child of the trigger element.
+```html
+<button>
+  <span>Button</span>
+  <span class="tooltip">I'm a tooltip</span>
+</button>
+<div>
+  <button class="chip round">Hover me</button>
+  <div class="tooltip">I'm a tooltip</div>
+</div>
+```
+| Class                                              | Result                              |
+| -------------------------------------------------- | ----------------------------------- |
+| _(none)_                                           | Above the parent.                   |
+| `.left` / `.right` / `.bottom`                     | Position override.                  |
+| `.small` / `.medium` / `.large`                    | 8 / 12 / 16 rem wide, multi-line.   |
+| `.max`                                             | Block-level 20 rem rich tooltip.    |
+| `.no-space` / `.medium-space` / `.large-space`     | Gap from anchor: 0 / −1 / −1.5 rem. |
+#### Rich tooltip
+```html
+<div>
+  <button class="chip round">Rich tooltip</button>
+  <div class="tooltip max">
+    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
+    <nav>
+      <button>Action</button>
+    </nav>
+  </div>
+</div>
+```
+### Typography
+```html
+<h1>Display</h1>
+<h2>Display</h2>
+<h3>Display</h3>
+<h4>Headline</h4>
+<h5>Headline</h5>
+<h6>Headline</h6>
+```
+Heading size modifiers: `.small`, `.large`.
+#### Formatting
+```html
+<a class="link">link</a>
+<a class="inverse-link">inverse-link</a>
+<p class="italic">italic</p>
+<p class="bold">bold</p>
+<p class="underline">underline</p>
+<p class="overline">overline</p>
+<p class="upper">upper</p>
+<p class="lower">lower</p>
+<p class="capitalize">capitalize</p>
+<p class="small-text">small (0.75 rem)</p>
+<p class="medium-text">medium (0.875 rem)</p>
+<p class="large-text">large (1 rem)</p>
+<p class="truncate">long single-line text…</p>
+```
+#### Line spacing
+`.no-line`, `.tiny-line` (1.25 rem), `.small-line` (1.5), `.medium-line` (1.75), `.large-line` (2), `.extra-line` (2.25).
+#### Blockquote, pre, code
+```html
+<blockquote>Quoted text.</blockquote>
+<pre>Preformatted.</pre>
+<pre>
+  <code>console.log("hello");</code>
+</pre>
+<p>
+  The function <code>console.log()</code> prints a log message.
+</p>
+```
+`<pre>` and `<blockquote>` modifiers: `.border`, `.no-border`, `.scroll`.
+---
+## Helpers
+### Alignments
+```html
+<div class="center-align middle-align">…</div>
+```
+`.left-align`, `.right-align`, `.center-align` (justify + text), `.top-align`, `.middle-align`, `.bottom-align` (align-items).
+### Blurs
+Backdrop-blur with a translucent background.
+```html
+<header class="blur">…</header>
+<article class="blur">…</article>
+<button class="blur">Blurred</button>
+<button class="chip blur">Chip</button>
+```
+`.blur` (1 rem), `.small-blur` (0.5), `.large-blur` (1.5). Add `.light` or `.dark` to force a light/dark surface tint.
+### Color roles
+The only color tokens are the M3 role-based ones. Every role yields a paired surface utility (`.<role>` paints background + on-role text), a `-text` utility, a `-border` utility, and where applicable a `-container` utility.
+```html
+<div class="primary">primary surface + on-primary text</div>
+<div class="primary-container">primary container surface + on-primary-container text</div>
+<span class="primary-text">primary text only</span>
+<div class="primary-border border">primary border only</div>
+```
+| Role group     | Surface             | Text                  | Border                  | Container              |
+| -------------- | ------------------- | --------------------- | ----------------------- | ---------------------- |
+| **Primary**    | `.primary`          | `.primary-text`       | `.primary-border`       | `.primary-container`   |
+| **Secondary**  | `.secondary`        | `.secondary-text`     | `.secondary-border`     | `.secondary-container` |
+| **Tertiary**   | `.tertiary`         | `.tertiary-text`      | `.tertiary-border`      | `.tertiary-container`  |
+| **Error**      | `.error`            | `.error-text`         | `.error-border`         | `.error-container`     |
+**Neutral surface family** (background only — `on-surface` text is inherited):
+`.background`, `.surface`, `.surface-variant`, `.surface-dim`, `.surface-bright`, `.surface-container-lowest`, `.surface-container-low`, `.surface-container`, `.surface-container-high`, `.surface-container-highest`, `.inverse-surface`.
+**Inverse primary:**
+`.inverse-primary`, `.inverse-primary-text`, `.inverse-primary-border`.
+**Transparent (structural):**
+`.transparent`, `.transparent-text`, `.transparent-border`.
+### Directions
+`.horizontal` (row flex), `.vertical` (column flex). Both work on `<a>`, `<button>`, `.chip`, `nav`, `.row`, `.tabs`.
+### Elevations
+`.elevate`, `.no-elevate`, `.small-elevate`, `.medium-elevate`, `.large-elevate`.
+### Forms (helpers)
+Shape and surface helpers.
+| Class                                                                  | Effect                            |
+| ---------------------------------------------------------------------- | --------------------------------- |
+| `.border` / `.no-border`                                               | 1 px outline / no border.         |
+| `.round` / `.no-round` / `.small-round` / `.large-round`               | Border-radius scale (0.5 / 2 / 3.5 rem). |
+| `.left-round` / `.right-round` / `.top-round` / `.bottom-round`        | Per-side radius.                  |
+| `.circle` / `.square`                                                  | Round / no border-radius equal-size shape. |
+| `.fill`                                                                | Filled surface (`surface-variant`). |
+| `.extend`                                                              | Extendable label (buttons).       |
+### Margins
+`.margin` (1 rem default). Scale modifiers: `.no-margin`, `.auto-margin`, `.tiny-margin` (0.25), `.small-margin` (0.5), `.large-margin` (1.5). Directional: `.left-margin`, `.right-margin`, `.top-margin`, `.bottom-margin`, `.horizontal-margin`, `.vertical-margin`.
+Combine: `<div class="margin large-margin top-margin">`.
+### Opacities
+`.opacity` (1), `.no-opacity` (0), `.small-opacity` (0.25), `.medium-opacity` (0.5), `.large-opacity` (0.75).
+### Paddings
+Identical scale and directional set as margins: `.padding`, `.no-padding`, `.tiny-padding`, `.small-padding`, `.large-padding`, `.left-padding`, `.right-padding`, `.top-padding`, `.bottom-padding`, `.horizontal-padding`, `.vertical-padding`.
+### Positions
+| Class                                  | Effect                                        |
+| -------------------------------------- | --------------------------------------------- |
+| `.left` / `.right` / `.top` / `.bottom` | Pin to the edge (inset-inline / inset-block). |
+| `.center`                              | Horizontally centered (`translateX(-50%)`).   |
+| `.middle`                              | Vertically centered (`translateY(-50%)`).     |
+| `.middle.center`                       | Fully centered.                               |
+| `.front`                               | `z-index: 10`.                                |
+| `.back`                                | `z-index: -10`.                               |
+### Responsive
+`.responsive` fills available inline-size. `.s` (visible < 601 px), `.m` (601 – 992 px), `.l` (≥ 993 px). Combine to span ranges (e.g. `.m.l` hides on small only).
+### Ripples
+Pointer-driven hover/focus tint plus speed scale.
+```html
+<button class="ripple">Default</button>
+<button class="fast-ripple">Fast (200 ms)</button>
+<button class="slow-ripple">Slow (1800 ms)</button>
+<button class="chip ripple">Chip with ripple</button>
+```
+### Scrolls
+`.scroll` (`overflow: auto`), `.no-scroll` (`overflow: hidden`).
+### Shadows
+Inset / directional gradient shadows. Useful behind text overlaid on media.
+```html
+<header class="left-shadow">…</header>
+<article class="bottom-shadow">…</article>
+<button class="left-shadow">Button</button>
+<button class="chip left-shadow">Chip</button>
+```
+`.shadow`, `.left-shadow`, `.right-shadow`, `.top-shadow`, `.bottom-shadow`.
+### Sizes
+| Class                                                                 | Effect                                |
+| --------------------------------------------------------------------- | ------------------------------------- |
+| `.tiny` / `.small` / `.medium` / `.large` / `.extra`                  | Component-scoped size scale.          |
+| `.wrap` / `.no-wrap`                                                  | Block + wrap / flex no-wrap.          |
+| `.max`                                                                | `flex: 1` inside flex containers.     |
+| `.small-width` / `.medium-width` / `.large-width` / `.auto-width`     | 12 / 24 / 36 rem / `auto` inline-size. |
+| `.small-height` / `.medium-height` / `.large-height` / `.auto-height` | Same scale for block-size.            |
+### Spaces
+Vertical spacer blocks (suppressed inside `nav`, `.row`, `.grid`, `table`, `.tooltip`, `.list`, `menu`, `.shape`).
+| Class                       | Height   |
+| --------------------------- | -------- |
+| `.tiny-space`               | 0.5 rem  |
+| `.space` / `.small-space`   | 1 rem    |
+| `.medium-space`             | 2 rem    |
+| `.large-space`              | 3 rem    |
+| `.extra-space`              | 4 rem    |
+On `<nav>` / `.row` / `.grid` / `menu`, the same class names control gap instead of block-size.
+### Waves
+Material radial-gradient wave on hover / focus (auto-applied to `.button`, `button`, `.chip`, `.tabs > a`, `nav.tabbed > a`, `nav.toolbar > a`, and rail-nav items). Add `.wave` to opt arbitrary elements in; `.no-wave` to opt out.
+```html
+<div class="wave padding round">Custom wave target</div>
+<button class="no-wave">No wave</button>
+```
+### Zoom
+CSS `zoom` scaling. `.zoom` (2×), `.tiny-zoom` (2), `.small-zoom` (3), `.medium-zoom` (4), `.large-zoom` (5), `.extra-zoom` (6).
+---
+## Design tokens
+Override any CSS custom property at any scope — no rebuild required.
+```css
+:root {
+  --primary: #ff5722;
+  --on-primary: #fff;
+  --primary-container: #ffe0d6;
+  --on-primary-container: #410001;
+}
+article.alert {
+  --surface-container-low: #fff3e0;
+}
+```
+**Color roles** — same quartet for `secondary`, `tertiary`, `error`:
+`--primary`, `--on-primary`, `--primary-container`, `--on-primary-container`
+**Neutrals:** `--background`, `--on-background`, `--surface`, `--on-surface`, `--surface-variant`, `--on-surface-variant`, `--outline`, `--outline-variant`, `--shadow`, `--scrim`.
+**Surface tonal:** `--surface-dim`, `--surface-bright`, `--surface-container-lowest`, `--surface-container-low`, `--surface-container`, `--surface-container-high`, `--surface-container-highest`.
+**Inverse:** `--inverse-surface`, `--inverse-on-surface`, `--inverse-primary`.
+**Structural:**
+| Token                                    | Default                                                         |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| `--size`                                 | `1rem` (scale all sizing)                                       |
+| `--font`                                 | `Inter, Roboto, "Helvetica Neue", "Arial Nova", "Nimbus Sans", "Noto Sans", Arial, sans-serif` |
+| `--font-icon`                            | `"Material Symbols Outlined"`                                   |
+| `--speed1` … `--speed4`                  | `0.1s` / `0.2s` / `0.3s` / `0.4s`                               |
+| `--active`                               | `rgb(128 128 128 / 0.192)` (hover / pressed overlay)            |
+| `--overlay`                              | `rgb(0 0 0 / 0.5)` (modal scrim)                                |
+| `--elevate1` / `--elevate2` / `--elevate3` | Shadow tiers.                                                 |
+| `--top`, `--bottom`, `--left`, `--right` | `env(safe-area-inset-*)` for notched devices.                   |
+Switch icon variant:
+```css
+:root { --font-icon: "Material Symbols Rounded"; }
+/* "Material Symbols Outlined" (default), "Material Symbols Rounded",
+   "Material Symbols Sharp", "Material Symbols Subset" (smaller bundle, used by
+   checkbox/radio/switch), or `none` to disable icons entirely. */
+```
+Use a custom body font:
+```css
+@import url("https://fonts.googleapis.com/css2?family=Roboto+Flex:wght@400;500;700&display=swap");
+:root { --font: "Roboto Flex"; }
+```
+Ship a narrower Symbols subset (import only the glyphs you use) to shrink the bundle:
+```css
+@import url("https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:FILL@0..1&icon_names=check,check_box,check_box_outline_blank,indeterminate_check_box,radio_button_checked&display=swap");
+:root { --font-icon: "Material Symbols Outlined"; }
+```
+### Full token override template
+To replace the default theme entirely, override every role token at `:root` and provide a `[data-mode="dark"]` variant:
+```css
+:root,
+:root[data-mode="light"] {
+  --primary: #6750a4;
+  --on-primary: #ffffff;
+  --primary-container: #e9ddff;
+  --on-primary-container: #22005d;
+  --secondary: #625b71;
+  --on-secondary: #ffffff;
+  --secondary-container: #e8def8;
+  --on-secondary-container: #1e192b;
+  --tertiary: #7e5260;
+  --on-tertiary: #ffffff;
+  --tertiary-container: #ffd9e3;
+  --on-tertiary-container: #31101d;
+  --error: #ba1a1a;
+  --on-error: #ffffff;
+  --error-container: #ffdad6;
+  --on-error-container: #410002;
+  --background: #fffbff;
+  --on-background: #1c1b1e;
+  --surface: #fdf8fd;
+  --on-surface: #1c1b1e;
+  --surface-variant: #e7e0eb;
+  --on-surface-variant: #49454e;
+  --outline: #7a757f;
+  --outline-variant: #cac4cf;
+  --shadow: #000000;
+  --scrim: #000000;
+  --inverse-surface: #313033;
+  --inverse-on-surface: #f4eff4;
+  --inverse-primary: #cfbcff;
+  --surface-dim: #ddd8dd;
+  --surface-bright: #fdf8fd;
+  --surface-container-lowest: #ffffff;
+  --surface-container-low: #f7f2f7;
+  --surface-container: #f2ecf1;
+  --surface-container-high: #ece7eb;
+  --surface-container-highest: #e6e1e6;
+}
+:root[data-mode="dark"] {
+  --primary: #cfbcff;
+  --on-primary: #381e72;
+  --primary-container: #4f378a;
+  --on-primary-container: #e9ddff;
+  --secondary: #cbc2db;
+  --on-secondary: #332d41;
+  --secondary-container: #4a4458;
+  --on-secondary-container: #e8def8;
+  --tertiary: #efb8c8;
+  --on-tertiary: #4a2532;
+  --tertiary-container: #633b48;
+  --on-tertiary-container: #ffd9e3;
+  --error: #ffb4ab;
+  --on-error: #690005;
+  --error-container: #93000a;
+  --on-error-container: #ffb4ab;
+  --background: #1c1b1e;
+  --on-background: #e6e1e6;
+  --surface: #141316;
+  --on-surface: #e6e1e6;
+  --surface-variant: #49454e;
+  --on-surface-variant: #cac4cf;
+  --outline: #948f99;
+  --outline-variant: #49454e;
+  --shadow: #000000;
+  --scrim: #000000;
+  --inverse-surface: #e6e1e6;
+  --inverse-on-surface: #313033;
+  --inverse-primary: #6750a4;
+  --surface-dim: #141316;
+  --surface-bright: #3a383c;
+  --surface-container-lowest: #0f0e11;
+  --surface-container-low: #1c1b1e;
+  --surface-container: #201f22;
+  --surface-container-high: #2b292d;
+  --surface-container-highest: #363438;
+}
+```
+---
+## Themes
+Baked themes ship in the bundle and swap via `<html data-theme="<name>">`:
+`stackific` _(default)_, `hello-pumpkin`, `sea-lettuce`, `olive`, `nord`, `vega-violet`, `wild-strawberry`, `heliotrope-magenta`, `voodoo-violet`, `red-orchid`, `green-brown`, `shakshuka`, `purple-honeycreeper`, `maldives`, `verditer`, `fennel`, `gold`, `burtuqali`.
+Each theme sets the full M3 role-token set (`--primary`, `--secondary`, `--tertiary`, `--surface-*`, etc.) for both light and dark modes.
+```html
+<html data-theme="nord" data-mode="dark">
+```
+```js
+ui("theme", "vega-violet");      // swap to a baked theme
+await ui("theme", "#1447E6");    // generate from hex (needs material-dynamic-colors)
+```
+---
+## Theme and mode selector
+If your page anchors the theme menu inside another element with `overflow: hidden` or `overflow: auto`, also add this so the popover can position itself:
+```html
+<style>
+  /* Positioning context for md3's <menu> popover relative to its trigger. */
+  *:has(> menu[data-theme-picker]) {
+    position: relative;
+  }
+</style>
+```
+### The two triggers (anywhere in `<body>`)
+The theme picker is a `<button data-ui="#…">` paired with an empty `<menu data-theme-picker>` — md3 toggles the menu's `active` class when the button is clicked; the init script fills the menu with the available theme slugs. The appearance toggle is any element with `data-theme-toggle`;
+the init script cycles `auto → light → dark` on click and keeps the inner `<i>` in sync with the current mode.
+```html
+<!-- Theme picker -->
+<div>
+  <button data-ui="#theme-picker" aria-label="Pick theme">
+    <i aria-hidden="true">style</i>
+  </button>
+  <menu id="theme-picker" class="no-wrap" data-theme-picker></menu>
+</div>
+<!-- Appearance (auto / light / dark) -->
+<button
+  data-theme-toggle
+  aria-label="Cycle appearance (auto, light, dark)">
+  <i aria-hidden="true">brightness_auto</i>
+</button>
+```
+Notes:
+- The `<menu>`'s `id` must match the trigger's `data-ui` value.
+- Add `top` / `left` / `right` classes to the `<menu>` to anchor the popover side (e.g. `class="no-wrap top"` if the trigger sits at the bottom of the page).
+- You can attach `data-theme-toggle` to multiple buttons (e.g. desktop + mobile) — the script wires all of them and keeps their icons in sync.
+### Init script (before `</body>`)
+Pure, no dependencies beyond md3's global `ui()`. Cycles the mode, populates the picker from `ui("themes")`, and writes selections back through `ui("mode", …)` / `ui("theme", …)`. md3 persists both choices to `localStorage` (`md3:mode`, `md3:theme`) so the page reopens in the same state.
+```html
+<script type="module">
+  const MODE_CYCLE = ["auto", "light", "dark"];
+  const modeIcon = (pref) =>
+    pref === "light" ? "light_mode"
+    : pref === "dark" ? "dark_mode"
+    : "brightness_auto";
+  function currentMode() {
+    const v = window.ui("mode");
+    return v === "light" || v === "dark" || v === "auto" ? v : "auto";
+  }
+  function syncIcons() {
+    const icon = modeIcon(currentMode());
+    for (const el of document.querySelectorAll("[data-theme-toggle] i")) {
+      el.textContent = icon;
+    }
+  }
+  function cycleMode() {
+    const current = currentMode();
+    const next =
+      MODE_CYCLE[(MODE_CYCLE.indexOf(current) + 1) % MODE_CYCLE.length];
+    window.ui("mode", next);
+    syncIcons();
+  }
+  const unslugify = (slug) =>
+    slug
+      .split("-")
+      .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+      .join(" ");
+  function fillThemePickers() {
+    const themes = (window.ui("themes") ?? []).slice().sort();
+    for (const menu of document.querySelectorAll("[data-theme-picker]")) {
+      menu.replaceChildren();
+      for (const slug of themes) {
+        const li = document.createElement("li");
+        li.className = "wave round";
+        li.textContent = unslugify(slug);
+        li.dataset.themeSlug = slug;
+        li.addEventListener("click", (e) => {
+          window.ui("theme", slug);
+          e.currentTarget.closest("menu")?.classList.remove("active");
+        });
+        menu.appendChild(li);
+      }
+    }
+  }
+  function start() {
+    for (const btn of document.querySelectorAll("[data-theme-toggle]")) {
+      btn.addEventListener("click", cycleMode);
+    }
+    syncIcons();
+    fillThemePickers();
+  }
+  // md3.js loads as a module — wait until window.ui is registered.
+  function whenUiReady(fn) {
+    if (typeof window.ui === "function") return fn();
+    const id = setInterval(() => {
+      if (typeof window.ui === "function") {
+        clearInterval(id);
+        fn();
+      }
+    }, 50);
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => whenUiReady(start));
+  } else {
+    whenUiReady(start);
+  }
+</script>
+```
+---
+## Breakpoints
+| Name | Min width |
+| ---- | --------- |
+| `s`  | 600 px    |
+| `m`  | 993 px    |
+| `l`  | 1240 px   |
+Used by `.s` / `.m` / `.l` show-hide and the `.s1`–`.s12` / `.m1`–`.m12` / `.l1`–`.l12` grid spans.
+---
+## Authoring conventions
+**Don't fight the framework.** md3 is opinionated by design: semantic HTML + a single component class + composable helpers + design-token overrides. If you find yourself reaching for BEM-style sub-element classes (`.card-header`, `.card-body`), wrapping every tag in extra divs, or writing custom CSS that re-implements a helper, stop — there's almost always a built-in helper for that. The framework is small (≈100 classes) precisely so you can hold all of it in your head and compose instead of layering.
+If a helper doesn't exist for what you need, override a [design token](#design-tokens) at the scope you need it. That's the escape hatch — not a parallel class system.
+Three rules keep markup predictable and styles composable.
+### ✅ Do
+```html
+<!-- One element + N helpers on the same tag -->
+<button class="border round large">…</button>
+<div class="field label border">…</div>
+<!-- One <main> per document -->
+<body>
+  <main class="responsive">…</main>
+</body>
+<!-- Inline/block elements inside block elements -->
+<div>
+  <div>block</div>
+  <span>inline</span>
+</div>
+```
+```css
+/* Helper composition */
+.button.border { … }
+/* Direct-child component nesting */
+.field > input { … }
+.field > .max { … }
+```
+### 🚫 Don't
+```html
+<!-- N elements on one tag -->
+<div class="field button border">…</div>
+<button class="chip">…</button>      <!-- NO, this collides;
+                                         use .chip OR <button>, not both as elements -->
+<!-- Custom sub-element class trees -->
+<div class="card">
+  <div class="card-header">…</div>
+  <div class="card-content">…</div>
+  <div class="card-footer">…</div>
+</div>
+<!-- Multiple <main> -->
+<body>
+  <main>…</main>
+  <main>…</main>
+</body>
+<!-- Block inside inline -->
+<span>
+  <div>…</div>
+</span>
+```
+```css
+/* Don't double-class the same element type */
+.button.button { … }
+/* Don't descend through unrelated elements */
+.button .chip { … }
+```
+### Tips
+1. Reach for [Helpers](#helpers) before writing custom CSS.
+2. To customize the theme, override the [Design tokens](#design-tokens).
+3. Quick-learn by scanning the per-component class tables.
+4. Slider value rendering, textarea auto-resize, and the file/color/password field wiring require the JS runtime. Theme/mode/dialog/menu/snackbar/page work via CSS + `data-ui`.
+5. For Vite users, build with `assetsInlineLimit: 0` so the bundled Material Symbols fonts aren't base64-inlined.
 ---
-## License
+## Repository
-Apache-2.0. See `LICENSE` and `NOTICE`. The published source includes patterns and SCSS structure derived from [beercss](https://github.com/beercss/beercss) (MIT) — full attribution in `THIRD-PARTY-NOTICES`.
+https://github.com/stackific/md3 — Apache-2.0.