actual-css 0.4.0 → 0.4.2

package/docs/design-notes/app-ui.md

@@ -0,0 +1,33 @@
+# Application UI boundaries
+
+Actual CSS provides application chrome and content composition without owning
+the application lifecycle.
+
+```text
+app-shell   full-height single-column document flow
+topbar      persistent top application chrome
+app-layout  specialized topbar + internal scroll + adaptive navigation recipe
+app-nav     primary application destinations
+list        repeated application rows with leading/content/trailing regions
+status-bar  passive transient feedback
+```
+
+`app-layout` is selected by that complete behavior, never by product category.
+Public sites and applications with ordinary document scrolling stay on
+semantic landmarks and may use `app-shell`; a site header uses `navbar`.
+
+Routing, navigation history, application state, SPA page lifecycle, service
+workers, manifests, offline policy, and install prompts belong to the
+application. Actual does not prescribe Material breakpoints or device classes;
+the application layout changes when its available viewport can accommodate
+labelled side navigation.
+
+Compact UI vocabulary remains semantic rather than shape-driven:
+
+- use `.btn.sm` for compact actions and `aria-pressed` filters;
+- use `.badge` for passive counts, statuses, and categories;
+- use `.badge > button` when a displayed tag can be removed;
+- use `.status-bar` for passive feedback, not an actionable toast.
+
+There is no generic chip or snackbar component. Those names conflate different
+HTML semantics that the existing components already keep explicit.

package/docs/design-notes/enhancement-contract.md

@@ -72,6 +72,31 @@ creates two independent records that both run.
 The owner of a custom enhancement root must call `disconnect()` when disposing
 that root; the default `document.documentElement` root is not affected.
 
+`enhance(…, root)` owns the lifecycle boundary. It scans additions inside that
+root, preserves instances moved within it, and requests cleanup once an instance
+leaves it—even when the element remains connected elsewhere. An enhancer's
+cleanup must therefore be authoritative and idempotent: it releases its state
+when called and must not repeat the root-membership decision.
+
+Core lifecycle primitives accept a `Document`, `Element`, or `DocumentFragment`
+root, and command targets resolve in the trigger's document or shadow root.
+Built-in auto-registration observes the document tree. It does not discover or
+manage built-ins created inside shadow roots. Applications that own a custom
+root can install their own enhancements with the core APIs and must dispose
+those registrations explicitly.
+
+## Choosing a JavaScript primitive
+
+- Use a command for an immediate trigger-to-current-target action. Commands
+  resolve the DOM at event time and do not own element lifecycle.
+- Use `registerEnhancement()` for an opted-in controller that owns listeners or
+  state for a subtree.
+- Use `enhance()` for a self-describing leaf behavior that needs connection and
+  cleanup lifecycle without a named token.
+- Prefer delegation when no persistent per-element state is required.
+- Give instance-owned listeners an `AbortController`, and abort it from the
+  instance cleanup.
+
 ## CSS must never select on `data-enhance`
 
 CSS rules must not select on `data-enhance` or the runtime marker

package/docs/design-notes/grid.md

@@ -254,7 +254,7 @@ asks.
 It is nevertheless the right **baseline**. Bounded at N, using `auto-fill`, it
 is responsive, overflow-safe, and equal-width at every state, and it needs
 nothing above Actual's Minimal floor. Adopting it as the unenhanced behavior of
-`.grid-N` is what makes the query container an opt-in for precision rather than
+`.grid-N` is what makes the actual-grid container a precision enhancement rather than
 a prerequisite for responsiveness. This is the single most important difference
 from 0.3.1, where a preset used without a wrapper stayed frozen at N columns
 and was a genuine trap.
@@ -380,7 +380,7 @@ Placing the query container on an ancestor preserves the intrinsic sizing behavi
 The relationship is:
 
 ```text
-.container-query
+query container (any ancestor, e.g. .container-query)
         ↓ observes local available width
 .grid-N
         ↓ changes structural subdivision
@@ -391,7 +391,7 @@ The extra ancestor is therefore not accidental ceremony.
 
 It represents a real boundary imposed by the CSS containment model.
 
-Actual should not hide that boundary if hiding it requires changing the sizing semantics of the grid.
+Actual should not hide that boundary if hiding it requires changing the sizing semantics of the grid. Balanced subdivision keys off a container **named** `actual-grid` rather than any anonymous query container, so an incidental `container-type: inline-size` region never changes the grid by accident; `.container-query` is the convenience helper that establishes that named context.
 
 ## Out of scope: explicit per-region placement
 
@@ -496,6 +496,79 @@ Before changing structural-grid thresholds, probes should verify:
 
 The viewport itself should not determine the result; the relevant local container should.
 
+## Why there is no breakpoint scale
+
+Actual exposes no `sm` / `md` / `lg` / `xl` scale, and the structural grid is the
+clearest illustration of why. The whole framework declares two width media
+queries:
+
+```text
+@media (max-width: 30rem)   x2   modal padding on small screens
+@media (min-width: 48rem)   x1   .app-layout, bottom nav -> side nav
+```
+
+Everything else responsive is intrinsic or container-driven. The responsibility
+splits cleanly:
+
+```text
+viewport
+   |
+   +-- the few genuinely viewport-level decisions
+   |     .app-layout
+   |
+   +-- composition and chrome
+          |
+        named query container
+          |
+        actual-grid
+          |
+        2 / 3 / 4 / 6 stages
+```
+
+**Thresholds are local and content-driven.** `28rem`, `48rem` and `64rem`
+describe how much room *this collection* needs for a given density, probed
+against the content each preset targets. They are not device classes, and the
+fact that two of them coincide with widely used framework breakpoints is a
+coincidence, not the justification. A grid does not know what device it is on
+and does not need to.
+
+**The unit is `rem` so the thresholds follow typographic scale.** Container
+query lengths in `rem` resolve against the root font size, so a reader who
+scales their type up moves every threshold with it:
+
+```text
+root 16px   48rem = 768px    768px container -> .grid-3 = 3 columns
+root 20px   48rem = 960px    768px container -> .grid-3 = 1 column
+root 24px   48rem = 1152px   768px container -> .grid-3 = 1 column
+```
+
+That is the correct response, not a rounding artifact: larger type genuinely
+needs more room per item, so the same container honestly supports fewer columns.
+A `px` breakpoint cannot express this.
+
+### Container width is not a monotonic function of viewport width
+
+This is the empirical case against a global scale, and it is measurable inside
+this repository. `demo/templates/dashboard.html` reveals its workspace sidebar
+at `72rem`. Measuring the main region's content box across that boundary:
+
+| Viewport | Container content box | `.grid-4` | `.grid-6` |
+| -------- | --------------------- | --------- | --------- |
+| 1100px   | 65.8rem               | 4         | 6         |
+| 1160px   | 52.6rem               | 2         | 3         |
+
+The viewport grew by 60px and the grid lost half its columns, because the
+composition spent that growth on chrome rather than on content. A viewport-keyed
+system reasons about this backwards by construction: it sees a wider screen and
+infers more room, at the exact moment there is less. No amount of breakpoint
+tuning fixes that, because there is no stable function from viewport width to
+container width — the composition sits in between and is free to change.
+
+A named query container asks the only question with a reliable answer: *how much
+inline space does this collection actually have?* Everything the ladder does
+follows from that measurement, which is why the thresholds can stay content-
+derived instead of device-derived.
+
 ## API guidance
 
 Use `.grid` when the number of columns should emerge naturally from available space.
@@ -547,7 +620,7 @@ inside a query container.
 .grid                      space-driven, auto-fit, --grid-min
 .grid-N                    count-driven baseline, auto-fill bounded at N,
                            may pass through non-divisor column counts
-.container-query .grid-N   balanced subdivision, N -> divisors of N -> 1
+actual-grid .grid-N        balanced subdivision, N -> divisors of N -> 1
 ```
 
 The whole enhancement lives inside `@supports (container-type: inline-size)`.
@@ -603,6 +676,42 @@ The framework does not guess appropriate item size. The author states it by
 choosing a density; the framework then guarantees a clean structural collapse
 of that density.
 
+### Reference container sizes
+
+The thresholds describe the **query container's content box**, not the viewport
+and not the grid's own border box. Padding and borders on the container come off
+the top before the query resolves. Verified states:
+
+| Container content box | `.grid-2` | `.grid-3` | `.grid-4` | `.grid-6` |
+| --------------------- | --------- | --------- | --------- | --------- |
+| `< 28rem`             | 1         | 1         | 1         | 1         |
+| `28rem` – `< 48rem`   | 2         | 1         | 2         | 2         |
+| `48rem` – `< 64rem`   | 2         | 3         | 2         | 3         |
+| `>= 64rem`            | 2         | 3         | 4         | 6         |
+
+Two consequences for anyone sizing a region that hosts a structural grid.
+
+**Size the region to land on a threshold, not just under one.** A region whose
+content box settles at 47rem gives `.grid-3` one column — the same result as
+20rem. The step is a cliff, not a ramp, and `.grid-3` has no intermediate state
+to soften it; that is the invariant, not a defect. If a region is meant to show
+three columns, give it 48rem of content box with room to spare.
+
+**Budget backwards from the content box.** A region that must reach a threshold
+`T` needs `T + its own padding-inline + its own border-inline` of outer width.
+The convenient reference sizes are therefore the thresholds plus the padding the
+region actually carries:
+
+```text
+target 28rem content box   + 2 x 1rem padding + 2 x 1px border   ~= 30.2rem outer
+target 48rem content box   + 2 x 1rem padding + 2 x 1px border   ~= 50.2rem outer
+target 64rem content box   + 2 x 1rem padding + 2 x 1px border   ~= 66.2rem outer
+```
+
+Rounding **up** past that figure is deliberate. Landing on the threshold to the
+pixel means a later padding change, measured in fractions of a rem, silently
+drops the region a state.
+
 ### Why there is no `.grid-5`
 
 The divisors of five are five and one, so the chain would be `5 -> 1` with no
@@ -610,3 +719,67 @@ intermediate state. The system exposes densities that subdivide well, not every
 integer. Proposals to give `.grid-5` a hand-picked `5 -> 2 -> 1` chain are
 covered by the rejected `smart-grid` section above: those steps encode an
 assumption about item count that the class cannot verify.
+
+## Demonstrability is part of the contract
+
+A threshold nobody can reach is indistinguishable from a threshold that does not
+work. This was not hypothetical: the documentation site shipped for some time
+with an article column capped at 48rem, and the live demo previews inside it are
+the query containers. Their content box therefore topped out at **45.9rem at
+every viewport width** — 1280px, 1920px, identical. Every `.grid-3` demo on the
+site rendered one column, `.grid-4` and `.grid-6` rendered two, and the page
+teaching `6 -> 3 -> 2 -> 1` showed the reader its 2-column state as though that
+were the top of the chain.
+
+The bug was reported as a `.grid-3` calibration complaint. It was not one. No
+text-based check could see it, because every class name, every threshold, and
+every rule in the framework was correct.
+
+Two durable rules came out of it.
+
+**The query container must be the element whose content box is the grid's actual
+available space.** Putting `container` on a padded box is correct; putting it on
+an outer wrapper and letting an inner box add the padding makes the query
+resolve against a width the grid does not have, firing every threshold early.
+The demo would then claim a state it cannot honor — a lie in the geometry rather
+than in the CSS.
+
+**A surface that documents the thresholds has to be wide enough to reach them.**
+The docs shell is sized backwards from 64rem plus the preview's own padding, and
+that arithmetic is asserted in `tests/docs-geometry.test.js` against the
+thresholds parsed out of `grid.css`, so raising a threshold without giving the
+documentation room to reach it fails a test instead of quietly degrading every
+demo. The prose keeps its own reading measure inside the wider track: demo
+measure and prose measure are different contracts and should not be forced to
+share a number.
+
+### A probe that correctly changed nothing
+
+The same investigation measured `.choice-card` in a forced 3-up, to ask whether
+`.grid-3`'s 48rem step was simply too conservative:
+
+| Container | px / card | Result             |
+| --------- | --------- | ------------------ |
+| 44rem     | 224       | one line, at ease  |
+| 40rem     | 203       | one line, at limit |
+| 38rem     | 192       | **wraps**          |
+| 32rem     | 160       | wraps badly        |
+
+So those particular cards do fit three-up at roughly 40rem, well below the
+preset's step. That was not a reason to move the step or to add a density
+modifier, and the temptation is worth recording.
+
+`.grid-3` is a generic preset built around ~15.5rem per item, in agreement with
+`.grid-4`'s ~15.4rem. Choice cards are simply smaller than the preset's target
+content. Lowering the step to fit them would have put `.grid-3` at ~14.2rem and
+broken the only clean agreement in the ladder — to fix a symptom whose actual
+cause was 2rem of documentation padding.
+
+A modifier introducing a second density ladder becomes defensible only when
+*several unrelated* content families independently show the standard steps to be
+too conservative while wanting identical balanced-collapse behavior. One
+component in one miscalibrated container is not that evidence. A per-component
+threshold would also collide with the established meaning of `.compact` in
+Actual, which is padding density on a component (`.card.compact`,
+`.table.compact`) and never a layout threshold.
+

package/docs/design-notes/references.md

@@ -221,7 +221,7 @@ Prior Actual CSS libraries:
 - https://smolcss.dev/#smol-container
 - https://every-layout.dev/layouts/center/
 
-### Layout: List
+### Component: List
 
 - https://daisyui.com/components/list/
 - https://html.spec.whatwg.org/multipage/grouping-content.html#the-li-element

package/docs/navigation.json

@@ -36,7 +36,7 @@
         "scroll-target",
         "frame",
         "app-shell",
-        "list"
+        "app-layout"
       ]
     },
     {
@@ -45,6 +45,7 @@
       "pages": [
         "accordion",
         "alert",
+        "app-navigation",
         "aura",
         "avatar",
         "badge",
@@ -55,13 +56,17 @@
         "dialog",
         "drawer",
         "fab",
+        "indicator",
         "key",
+        "list",
         "meter",
         "navbar",
         "pagination",
         "progress",
+        "rating",
         "skeleton",
         "spinner",
+        "steps",
         "table"
       ]
     },
@@ -95,6 +100,7 @@
         "actions",
         "navigation-list",
         "icon-input",
+        "icon-slot",
         "structured-lists",
         "hierarchical-nav",
         "code-block",

package/docs/pages/components/alert.md

@@ -14,6 +14,11 @@
 - Use `.sm` or `.lg` for density changes. The inline padding stays stable.
 - Use `.alert-dismiss` for a compact dismiss button. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions. It uses the shared `--icon-close` mask and the `--dismiss` runtime command — no icon font or custom JS.
 
+Because alerts are soft by default, adding `.soft` to an intent (`.alert.soft.primary`,
+`.alert.soft.danger`, …) is a no-op: it already resolves to a soft version of that
+intent. Reach for `.solid` (stronger) or `.outline` (quieter) when the emphasis
+itself needs to change, not `.soft`.
+
 ## Class reference
 
 | Class            | Kind        | Description                                                                       |

package/docs/pages/components/app-navigation.md

@@ -0,0 +1,34 @@
+# App Navigation
+
+> Primary application destinations in a persistent bottom bar or labelled side navigation.
+
+Use one `.app-nav` landmark for the application's primary destinations. Links
+remain links, and `aria-current="page"` is the only current-page state.
+
+```html demo
+<nav class="app-nav" aria-label="Primary">
+  <a href="#today" aria-current="page">
+    <span aria-hidden="true">☀</span>
+    <span>Today</span>
+  </a>
+  <a href="#tasks">
+    <span aria-hidden="true">✓</span>
+    <span>Tasks</span>
+  </a>
+  <a href="#settings">
+    <span aria-hidden="true">⚙</span>
+    <span>Settings</span>
+  </a>
+</nav>
+```
+
+On its own, `.app-nav` is a sticky bottom bar. Compose it as a direct child of
+`.app-layout` to let the layout turn the same landmark into side navigation when space
+permits. The component contains no JavaScript and does not manage routing.
+The icon slot accepts SVGs, images, and decorative elements such as icon-font
+`i` elements marked with `aria-hidden="true"`.
+
+### Hooks
+
+- `--app-nav-size` controls the minimum bottom-bar size.
+- `--app-nav-gap` controls spacing between destinations.

package/docs/pages/components/avatar.md

@@ -41,6 +41,16 @@
 The avatar keeps the same visual box across semantics — as a link or button it
 gains hover and pressed feedback.
 
+For an accessible initials label, prefer `<abbr title="Full name">` so the
+expansion is available to assistive tech; the UA dotted underline it would draw
+is suppressed inside the avatar.
+
+```html demo
+<div class="avatar" role="img">
+  <abbr title="Ada Meridian">AM</abbr>
+</div>
+```
+
 ```html demo
 <a href="#" class="avatar">
   <img src="https://mockmind-api.uifaces.co/content/human/219.jpg" alt="Jane Doe" />

package/docs/pages/components/badge.md

@@ -77,6 +77,8 @@ The dot conveys no text, so an `aria-label` is required for it to mean anything.
 ## Removable tag pattern
 
 Use `.badge soft` for tag visuals. Add a direct dismiss button only when the tag can actually be removed. There is no separate chip component.
+For a compact action or filter, use `.btn.sm` instead; badges describe content
+and must not be turned into toggle controls merely to obtain a compact shape.
 
 ```html demo
 <span class="badge primary soft">

package/docs/pages/components/button.md

@@ -61,6 +61,18 @@ foreground by default, including on a contrasting `.inverted` surface. A local
 intent class still wins: `.danger.outline` uses the danger color in either
 context. Filled buttons own their surface and keep their normal intent recipe.
 
+`.btn.link` is a link-style action: it keeps button behavior and states, but
+remains intrinsically sized like text instead of stretching with its layout
+container. For a plain text link, use a bare `<a>` with no class.
+
+```html demo
+<div class="cluster">
+  <a href="#">Normal link</a>
+  <a class="btn link" href="#">Button-like link</a>
+  <button class="btn link" type="button">Button with link appearance</button>
+</div>
+```
+
 ```html demo
 <div class="cluster">
   <button class="btn outline" type="button">Outline</button>
@@ -117,6 +129,24 @@ change typography.
 
 ## States
 
+### Compact filters and actions
+
+A compact filter is still a button, not a separate chip semantic. Compose the
+small size with `aria-pressed`; application code owns the state change.
+
+```html demo
+<div class="cluster" aria-label="Task filters">
+  <button class="btn sm" type="button" aria-pressed="true">All</button>
+  <button class="btn sm outline" type="button" aria-pressed="false">Open</button>
+  <button class="btn sm outline" type="button" aria-pressed="false">Done</button>
+</div>
+```
+
+Use `.badge` for a passive category or count and the removable-tag composition
+when a displayed value needs its own remove action. Actual intentionally has no
+generic `.chip` component: action, selection, and information retain their HTML
+semantics.
+
 ### Disabled
 
 Disable a `<button>` or `<input>` with the native `disabled` attribute. Anchors

package/docs/pages/components/card.md

@@ -18,7 +18,10 @@ Use semantic elements inside the card. A direct `<header>` or `<footer>` is the
 card's structural slot. A direct `<footer>` is anchored to the bottom of the
 card when extra block space is available, so prices and actions line up across
 equal-height cards. Cards do not own page spacing — compose them with layout
-primitives like `.grid`.
+primitives like `.grid`. A bare card owns the rhythm between its direct
+children through `--card-gap`; applying a layout primitive such as `.stack` or
+`.media` to the same element gives that primitive control of the layout and
+gap.
 
 ```html demo
 <div style="max-inline-size: 32rem">
@@ -197,3 +200,4 @@ variants.
 - `--card-radius` — corner radius.
 - `--card-max-inline-size` — maximum width.
 - `--card-pad` — inner padding; also drives the negative offsets that let a `.bleed` child reach the card edge. `.compact` lowers it.
+- `--card-gap` — space between direct children of a bare card. A composed layout primitive owns its own gap instead. `.compact` does not change this hook.

package/docs/pages/components/fab.md

@@ -4,6 +4,8 @@
 
 FAB fixes a primary action near the viewport's block-end and inline-end edges.
 The existing button component owns its size, shape, intent, and interaction.
+As a direct child of `.app-layout`, it instead overlays the main grid area so
+the layout keeps it clear of adaptive application navigation and safe areas.
 
 ```html
 <div class="fab">

package/docs/pages/components/indicator.md

@@ -0,0 +1,52 @@
+# Indicator
+
+> Attach any component to one of a container's four corners.
+
+`.indicator` creates the positioning context and `.indicator-item` positions
+its child at the top-end corner. The primitive does not add a background,
+size, border, or contrast ring: compose it with `.badge` or another component
+that owns its appearance.
+
+## Class reference
+
+| Class             | Kind      | Description                                      |
+|-------------------|-----------|--------------------------------------------------|
+| `.indicator`      | Component | Positioning context for an overlaid child.       |
+| `.indicator-item` | Part      | Item attached to the top-end corner by default.  |
+| `.start`          | Placement | Moves the item to the inline-start corner.       |
+| `.bottom`         | Placement | Moves the item to the bottom corner.             |
+
+Combine `.bottom.start` for bottom-start. Logical inline placement follows the
+document direction automatically.
+
+```html demo
+<div class="cluster" style="padding: var(--space-40);">
+  <button class="btn indicator" type="button">
+    Inbox
+    <span class="indicator-item badge danger solid">3</span>
+  </button>
+
+  <article class="card indicator" style="max-inline-size: 18rem;">
+    <span class="indicator-item start badge success">New</span>
+    <h2>Quarterly report</h2>
+    <p>The latest figures are ready to review.</p>
+  </article>
+</div>
+```
+
+## Four corners
+
+```html demo
+<div class="indicator card" style="inline-size: 12rem; min-block-size: 7rem; margin: var(--space-40);">
+  <span class="indicator-item badge solid" aria-label="Top end">TE</span>
+  <span class="indicator-item start badge solid" aria-label="Top start">TS</span>
+  <span class="indicator-item bottom badge solid" aria-label="Bottom end">BE</span>
+  <span class="indicator-item bottom start badge solid" aria-label="Bottom start">BS</span>
+  <p class="muted">Four logical corners</p>
+</div>
+```
+
+The item extends beyond the container edge. An ancestor with clipped overflow
+can cut it off; leave overflow visible or provide enough inset space in that
+composition. Avatar status dots keep their dedicated circle-aware placement
+and contrast ring; continue to use `.avatar > .badge:empty` for that pattern.

package/docs/pages/components/list.md

@@ -0,0 +1,62 @@
+# List
+
+> Repeated application rows with optional leading and trailing regions.
+
+Use `.list` when a collection repeatedly needs leading content, flexible text,
+and trailing metadata or controls. Use `.media` for a single two-part
+media/content relationship, `.nav-list` for navigation structure, and native
+list markers when order or bullets carry meaning.
+
+```html demo
+<ul class="list">
+  <li class="list-item">
+    <span class="avatar sm"><abbr>AM</abbr></span>
+    <span class="list-item-content">
+      <strong class="list-item-title">Ada Morgan</strong>
+      <span class="list-item-text">Design systems · Brussels</span>
+    </span>
+    <span class="badge success">Online</span>
+  </li>
+  <li class="list-item">
+    <input class="check" type="checkbox" aria-label="Select quarterly review">
+    <span class="list-item-content">
+      <strong class="list-item-title">Quarterly review</strong>
+      <span class="list-item-text">Due tomorrow</span>
+    </span>
+    <time class="list-item-trailing" datetime="09:30">09:30</time>
+  </li>
+</ul>
+```
+
+Leading and trailing content are unconstrained: avatars, native choices,
+badges, text, switches, and buttons retain their own component sizing. The
+middle region has no minimum content floor, so supporting text and long tokens
+wrap instead of widening the page.
+
+For a navigable row, keep the list semantics and put `.list-item` on the link:
+
+```html demo
+<ul class="list">
+  <li>
+    <a class="list-item" href="#profile">
+      <span aria-hidden="true">👤</span>
+      <span class="list-item-content">
+        <strong class="list-item-title">Profile</strong>
+        <span class="list-item-text">Name, photo, and contact details</span>
+      </span>
+      <span class="list-item-trailing" aria-hidden="true">›</span>
+    </a>
+  </li>
+</ul>
+```
+
+Do not attach click JavaScript to the entire row. Use a link for navigation and
+a button or native control for actions.
+
+### Hooks
+
+- `--list-item-min-size` controls the row's minimum touch height.
+- `--list-item-pad-block` and `--list-item-pad-inline` control row padding.
+- `--list-item-gap` controls spacing between the three regions.
+- `--list-divider` controls the leading and inter-row dividers. The final row
+  deliberately has no trailing divider.

package/docs/pages/components/navbar.md

@@ -8,6 +8,10 @@
 - `.nav-list` is the shared vertical navigation list, reused by `.drawer` for stacked links.
 - Mark the current page with `aria-current="page"` on the active `.nav-link`.
 
+For a public or normally scrolling page, `.navbar` belongs inside the semantic
+site header. Do not use `.topbar` or `.app-layout` unless the page actually has
+the specialized persistent application-shell behavior those APIs describe.
+
 `.navbar-nav` and `.nav-list` are mutually exclusive: `.navbar-nav` is a horizontal
 flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
 `.nav-list` (vertical) — pick one per container.
@@ -36,6 +40,8 @@ flex list, `.nav-list` a vertical grid. Putting both on one element resolves to
 ```
 
 For a vertical sidebar nav, use `.nav-list` inside the drawer or sidebar.
+Links inside `.nav-list` stretch to the available inline size, providing a
+full-row hit target for vertical navigation.
 
 ## Responsive: navbar + drawer