actual-css 0.3.1 → 0.4.1

package/docs/pages/guides/modular-import.md

@@ -0,0 +1,173 @@
+# Modular imports
+
+Actual CSS ships one minimal core (`actual-css`) and one all-in entrypoint (`actual-css/full`). Projects can also compose the framework from family manifests or individual modules.
+
+## Entrypoints
+
+```css
+@import "actual-css";        /* minimal core */
+@import "actual-css/full";   /* complete framework */
+```
+
+`actual-css` contains the shared baseline: reset, tokens, theme, document defaults, intents, universal variants, focus, and print.
+
+It contains no typography, layout, forms, components, effects, or utilities.
+
+`actual-css/full` starts from the core and adds every family in cascade order:
+
+```text
+core → typography → layout → forms → components → effects → utilities
+```
+
+### Focus is a core invariant
+
+The core provides a visible `:focus` outline as the compatibility baseline. Modern browsers limit it to `:focus-visible`, hiding the pointer-focus outline.
+
+Components may enhance or replace that treatment in interactive states, but their base styles must not cancel the shared fallback.
+
+When an interactive state replaces the outline, it must preserve a visible focus indicator in forced-colors, either with an outline-based fallback or by keeping the replacement out of forced-colors.
+
+## Family manifests
+
+| Family           | Import                      | Contents                                                                                                                        |
+| ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Core             | `actual-css/css`            | reset, tokens, theme, base, intents, variants, focus, print                                                                     |
+| Typography       | `actual-css/css/typography` | prose, overline, fluid                                                                                                          |
+| Layout           | `actual-css/css/layout`     | stack, cluster, center, frame, media, switcher, sidebar-layout, grid, scroller, scroll-snap, topbar, container-query, app-shell |
+| Forms            | `actual-css/css/forms`      | native control baseline                                                                                                         |
+| Forms (complete) | `actual-css/css/forms/all`  | base plus input-icon, switch, range, choice-card, custom-select, floating-field, otp                                            |
+| Components       | `actual-css/css/components` | buttons, surfaces, overlays, feedback, navigation, data and composed controls                                                   |
+| Effects          | `actual-css/css/effects`    | aura                                                                                                                            |
+| Utilities        | `actual-css/css/utilities`  | base and extra utilities                                                                                                        |
+
+Individual modules can be imported through their domain path:
+
+```css
+@import "actual-css/css/forms/otp";
+@import "actual-css/css/components/chat";
+@import "actual-css/css/effects/aura";
+@import "actual-css/css/layout/scroller";
+@import "actual-css/css/typography/fluid";
+@import "actual-css/css/utilities/extra";
+```
+
+## Use your existing CSS pipeline
+
+Actual CSS is plain CSS and does not require its own build tool.
+
+If a project already uses Vite, PostCSS, Webpack, Parcel, Lightning CSS, or another CSS pipeline, keep using it and import the Actual CSS package exports directly.
+
+For example:
+
+```css
+@import "actual-css/css";
+@import "actual-css/css/layout";
+@import "actual-css/css/forms/all";
+@import "actual-css/css/components/button";
+@import "actual-css/css/components/card";
+
+@import "./theme.css";
+@import "./app.css";
+```
+
+The consuming pipeline remains responsible for features such as asset handling, URL rebasing, source maps, CSS Modules, import modifiers, transpilation, and browser targeting.
+
+Actual CSS intentionally does not require a particular bundler or transpiler.
+
+## Optional CLI bundler
+
+For projects without a CSS pipeline, Actual CSS includes a small zero-dependency import flattener:
+
+```sh
+npx actual-css bundle src/app.css --out public/app.css
+```
+
+or:
+
+```sh
+bunx actual-css bundle src/app.css --out public/app.css
+```
+
+Add `--minify` for lightweight whitespace/comment minification:
+
+```sh
+npx actual-css bundle src/app.css --out public/app.css --minify
+```
+
+The CLI resolves and inlines:
+
+```css
+@import "./local.css";
+@import "actual-css/css/layout";
+@import "actual-css/css/components/card";
+```
+
+It deliberately does **not** transpile CSS. Modern syntax such as nesting, `@container`, `@scope`, `:has()`, `color-mix()`, `light-dark()`, and media-query range syntax is preserved for the browser.
+
+The CLI is a simple flattener, not a general-purpose CSS build pipeline.
+
+### Limitations
+
+Local and package imports may be plain imports, or carry a layer modifier:
+
+```css
+@import "./local.css";
+@import "./local.css" layer(components);
+@import "./local.css" layer;
+```
+
+A layered import is flattened into the block it stands for, so `@import "actual-css/css" layer(actual)` becomes `@layer actual { … }`. A layer declared inside the imported file becomes a sublayer of that wrapper, exactly as the import did.
+
+Conditional modifiers are not flattened:
+
+```css
+@import "./local.css" supports(display: grid);
+@import "./local.css" screen;
+@import "./local.css" layer(components) supports(display: grid);
+```
+
+Use an existing CSS pipeline when these features are required.
+
+One further case is refused rather than guessed: a remote import inside a layered subtree, because hoisting it before ordinary rules would move it out of its layer.
+
+The CLI also does not process or rebase asset URLs such as:
+
+```css
+background-image: url("../images/card.svg");
+```
+
+Those paths remain exactly as written, so projects with relative assets should generally let their existing build pipeline handle CSS imports.
+
+Remote and absolute imports are preserved rather than fetched and are moved before ordinary rules so they remain valid CSS.
+
+## Cascade layers
+
+Actual CSS can participate in a project-owned cascade layer:
+
+```css
+@layer actual;
+
+@import "actual-css/full" layer(actual);
+```
+
+Or, when composing families:
+
+```css
+@layer actual;
+
+@import "actual-css/css" layer(actual);
+@import "actual-css/css/typography" layer(actual);
+@import "actual-css/css/layout" layer(actual);
+@import "actual-css/css/forms/all" layer(actual);
+@import "actual-css/css/components" layer(actual);
+```
+
+`actual-css/css/layer` also exposes the minimal core wrapped in `@layer actual`.
+
+All of these recipes flatten with `actual-css bundle`: the CLI understands layer modifiers, so a public entrypoint of the framework is never something its own bundler has to refuse.
+
+## Custom properties
+
+Component-prefixed custom properties documented on component pages are author hooks.
+
+Color and sizing otherwise stay within the shared intent, variant, control, and button APIs.

package/docs/pages/guides/progressive-enhancement.md

@@ -2,11 +2,12 @@
 
 > The optional JavaScript runtime that progressively enhances Actual's semantic markup — self-registering side-effect modules, the `enhance()` DOM lifecycle, stateless command routing, and the floating and surface contracts for custom widgets.
 
-Actual's JavaScript modules are optional. Importing `actual-css/js` registers the
-complete default runtime — every built-in enhancer, including validation and
-status; importing a specific module registers only that behavior. The runtime
-does not require `DOMContentLoaded` or manual init calls, and it never touches
-`window`: there is no global object to call into.
+Actual's JavaScript modules are optional. Importing `actual-css/js/full`
+registers the complete default runtime — every built-in enhancer, including
+validation and status. Importing `actual-css/js` registers only the enhancement
+manifest loader; importing a specific module registers only that behavior. The
+runtime does not require `DOMContentLoaded` or manual init calls, and it never
+touches `window`: there is no global object to call into.
 
 ## Browser support
 
@@ -16,12 +17,12 @@ unsupported — it is not tested, documented as supported, or preserved when the
 runtime evolves. The runtime assumes the modern platform primitives available
 across Minimal and ships no compatibility layer or polyfill.
 
-| Tier | Firefox | Safari | Chromium |
-|---|---|---|---|
-| Degraded | 78+ | 14+ | 88+ |
-| **Minimal** | **98+** | **15.4+** | **99+** |
-| Intermediate | 121+ | 16+ | 106+ |
-| Recommended | 129+ | 17.5+ | 123+ |
+| Tier         | Firefox | Safari    | Chromium |
+|--------------|---------|-----------|----------|
+| Degraded     | 78+     | 14+       | 88+      |
+| **Minimal**  | **98+** | **15.4+** | **99+**  |
+| Intermediate | 121+    | 16+       | 106+     |
+| Recommended  | 129+    | 17.5+     | 123+     |
 
 The tier definitions live in the browser-support design note.
 
@@ -57,13 +58,14 @@ handle, and cleanup happens per element when an element leaves the DOM.
 
 ## The default runtime
 
-Loading `dist/actual.js` as a plain `<script>` (no `type="module"`, no bundler,
-no `import`) gets the full runtime. Static HTML that needs to trigger something
-from its own inline `<script>` dispatches the module's public event instead of
-calling into a global — `actual:status` for the status bar, for example:
+Loading `dist/actual.full.js` as a plain `<script>` (no `type="module"`, no
+bundler, no `import`) gets the full runtime. Static HTML that needs to trigger
+something from its own inline `<script>` dispatches the module's public event
+instead of calling into a global — `actual:status` for the status bar, for
+example:
 
 ```html
-<script src="actual.js"></script>
+<script src="actual.full.js"></script>
 <script>
   document.dispatchEvent(new CustomEvent("actual:status", {
     bubbles: true,
@@ -72,24 +74,24 @@ calling into a global — `actual:status` for the status bar, for example:
 </script>
 ```
 
-| Module | Behavior |
-|---|---|
-| `actual-css/js/flyout` | Trigger → panel surface: positioning, open/close, sheet mode (token `flyout`) |
-| `actual-css/js/context-menu` | Context menus on `data-context-menu` |
-| `actual-css/js/focus-group` | Reusable roving-focus controller; no automatic discovery |
-| `actual-css/js/dialog` | Native `<dialog>` behavior, focus management, dismissal |
-| `actual-css/js/dismiss` | The generic `--dismiss` command |
-| `actual-css/js/tab` | Tab panels and arrow-key navigation (token `tabs`) |
-| `actual-css/js/tooltip` | Tooltips on `data-tooltip` |
-| `actual-css/js/scrollspy` | Scroll-driven nav highlighting (token `scrollspy`) |
-| `actual-css/js/filter` | Input value filtering on `data-filter` |
-| `actual-css/js/mask` | Input masks on `data-mask` |
-| `actual-css/js/password` | Password reveal toggle |
-| `actual-css/js/validation` | Form validation (token `validation`) |
-| `actual-css/js/status` | Singleton status bar on `[data-status][role="status"]` |
-| `actual-css/js/enhancement-loader` | Declared enhancement manifests (`data-enhance-modules`, `Enhance-Modules`) |
-
-Use `actual-css/js` for demos, playgrounds, and smoke tests where one import
+| Module                             | Behavior                                                                      |
+|------------------------------------|-------------------------------------------------------------------------------|
+| `actual-css/js/flyout`             | Trigger → panel surface: positioning, open/close, sheet mode (token `flyout`) |
+| `actual-css/js/context-menu`       | Context menus on `data-context-menu`                                          |
+| `actual-css/js/focus-group`        | Reusable roving-focus controller; no automatic discovery                      |
+| `actual-css/js/dialog`             | Native `<dialog>` behavior, focus management, dismissal                       |
+| `actual-css/js/dismiss`            | The generic `--dismiss` command                                               |
+| `actual-css/js/tab`                | Tab panels and arrow-key navigation (token `tabs`)                            |
+| `actual-css/js/tooltip`            | Tooltips on `data-tooltip`                                                    |
+| `actual-css/js/scrollspy`          | Scroll-driven nav highlighting (token `scrollspy`)                            |
+| `actual-css/js/filter`             | Input value filtering on `data-filter`                                        |
+| `actual-css/js/mask`               | Input masks on `data-mask`                                                    |
+| `actual-css/js/password`           | Password reveal toggle                                                        |
+| `actual-css/js/validation`         | Form validation (token `validation`)                                          |
+| `actual-css/js/status`             | Singleton status bar on `[data-status][role="status"]`                        |
+| `actual-css/js/enhancement-loader` | Declared enhancement manifests (`data-enhance-modules`, `Enhance-Modules`)    |
+
+Use `actual-css/js/full` for demos, playgrounds, and smoke tests where one import
 enables every built-in behavior. Production apps can import individual modules
 such as `actual-css/js/validation` or `actual-css/js/status` when only those are
 needed.
@@ -122,15 +124,16 @@ For building custom widgets (select, tags, date picker) on Actual's primitives,
 see the widget-primitives design note. Every primitive subpath is published in
 `package.json#exports`:
 
-| Subpath | Purpose |
-|---|---|
-| `actual-css/js/enhance` | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
-| `actual-css/js/events` | The `actual:*` event name constants |
-| `actual-css/js/floating` | Positioning engine (`reposition`, `repositionAt`, `autoUpdate`) |
-| `actual-css/js/focus` | Focusable-item lookup and helpers |
-| `actual-css/js/keys` | Roving-focus item navigation helpers |
-| `actual-css/js/menu` | Menu keyboard/click wiring, item vocabulary |
-| `actual-css/js/surface` | Surface lifecycle (`openSurface`, `closeSurface`, …) |
+| Subpath                  | Purpose                                                          |
+|--------------------------|------------------------------------------------------------------|
+| `actual-css/js/enhance`  | DOM lifecycle engine: `enhance()`, `registerEnhancement`, tokens |
+| `actual-css/js/escape`   | Per-document LIFO Escape dismissal stack                         |
+| `actual-css/js/events`   | The `actual:*` event name constants                              |
+| `actual-css/js/floating` | Positioning engine (`reposition`, `repositionAt`, `autoUpdate`)  |
+| `actual-css/js/focus`    | Focusable-item lookup and helpers                                |
+| `actual-css/js/keys`     | Roving-focus item navigation helpers                             |
+| `actual-css/js/menu`     | Menu keyboard/click wiring, item vocabulary                      |
+| `actual-css/js/surface`  | Surface lifecycle (`openSurface`, `closeSurface`, …)             |
 
 The exports map is explicit — it *is* the statement of what is public.
 
@@ -152,14 +155,14 @@ const stop = autoUpdate(float, () => {
 
 Options passed to `reposition()`:
 
-| Option | Default | Contract |
-|---|---|---|
-| `placement` | `"bottom-start"` | Preferred side and alignment (`-start` / `-end`) |
-| `distance` | `0` | Gap between the reference and the floating element |
-| `flip` | `true` | Flip to the opposite side when the preferred side is out of view |
-| `shift` | `true` | Shift along the main axis to stay within the boundary |
-| `shiftPadding` | `4` | Minimum space kept from the boundary |
-| `scope` | viewport | Boundary element for overflow decisions |
+| Option         | Default          | Contract                                                         |
+|----------------|------------------|------------------------------------------------------------------|
+| `placement`    | `"bottom-start"` | Preferred side and alignment (`-start` / `-end`)                 |
+| `distance`     | `0`              | Gap between the reference and the floating element               |
+| `flip`         | `true`           | Flip to the opposite side when the preferred side is out of view |
+| `shift`        | `true`           | Shift along the main axis to stay within the boundary            |
+| `shiftPadding` | `4`              | Minimum space kept from the boundary                             |
+| `scope`        | viewport         | Boundary element for overflow decisions                          |
 
 `autoUpdate(element, callback)` batches scroll, resize, and element-resize
 callbacks per document and returns a stop handle; it does not keep a closed or
@@ -195,30 +198,30 @@ Two non-obvious requirements:
 
 Lifecycle: `prepareSurface` → `openSurface` → `closeSurface` →
 `disconnectSurface`. `retainSurface(panel)` reference-counts a surface shared by
-several triggers and returns a release function; `registerEscapeDismissal` adds
-an element to the per-document Escape dismiss stack; `isSurfaceOpen` and
-`getSurfaceAutoClose` read current state.
+several triggers and returns a release function; `isSurfaceOpen` and
+`getSurfaceAutoClose` read current state. The separate `escape` primitive adds
+visible dismissable UI to the shared per-document Escape stack.
 
 `openSurface(menu, opts)` dispatches a cancelable `actual:surface-open` event —
 widgets can veto or decorate opens, and context menus inject their own
 `source`/`restoreFocusTo` through it.
 
-| Option | Default | Contract |
-|---|---|---|
-| `trigger` | — | Anchoring element; also the focus-restore target by default |
-| `source` | — | Alternate anchor when there is no trigger |
-| `x`, `y` | — | Position at a fixed viewport point instead of an anchor (context menus) |
-| `placement` | `"bottom-start"` | Preferred placement |
-| `distance` | `4` | Gap between anchor and surface |
-| `flip` | `true` | Flip when the preferred side is out of view |
-| `shift` | `true` | Shift to stay within the boundary |
-| `shiftPadding` | `4` | Minimum space kept from the boundary |
-| `scope` | viewport | Boundary element |
-| `mobile` | `"auto"` | `"auto"`, `"sheet"`, `"none"`, or `"anchored"` sheet behavior |
-| `breakpoint` | `768` | Max viewport width for an automatic sheet |
-| `autoClose` | `"outside"` | `"true"` closes for inside and outside clicks; `"inside"` and `"outside"` limit the side; `"false"` disables automatic click closing. Invalid values use `"true"` |
-| `dismissOnScroll` | `false` | Close when scrolling outside the surface follows a new user input; opening/focus scroll is ignored |
-| `restoreFocusTo` | `trigger` or `source` | Element focused on close |
+| Option            | Default               | Contract                                                                                                                                                          |
+|-------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `trigger`         | —                     | Anchoring element; also the focus-restore target by default                                                                                                       |
+| `source`          | —                     | Alternate anchor when there is no trigger                                                                                                                         |
+| `x`, `y`          | —                     | Position at a fixed viewport point instead of an anchor (context menus)                                                                                           |
+| `placement`       | `"bottom-start"`      | Preferred placement                                                                                                                                               |
+| `distance`        | `4`                   | Gap between anchor and surface                                                                                                                                    |
+| `flip`            | `true`                | Flip when the preferred side is out of view                                                                                                                       |
+| `shift`           | `true`                | Shift to stay within the boundary                                                                                                                                 |
+| `shiftPadding`    | `4`                   | Minimum space kept from the boundary                                                                                                                              |
+| `scope`           | viewport              | Boundary element                                                                                                                                                  |
+| `mobile`          | `"auto"`              | `"auto"`, `"sheet"`, `"none"`, or `"anchored"` sheet behavior                                                                                                     |
+| `breakpoint`      | `768`                 | Max viewport width for an automatic sheet                                                                                                                         |
+| `autoClose`       | `"outside"`           | `"true"` closes for inside and outside clicks; `"inside"` and `"outside"` limit the side; `"false"` disables automatic click closing. Invalid values use `"true"` |
+| `dismissOnScroll` | `false`               | Close when scrolling outside the surface follows a new user input; opening/focus scroll is ignored                                                                |
+| `restoreFocusTo`  | `trigger` or `source` | Element focused on close                                                                                                                                          |
 
 The click policy belongs to the surface rather than to a particular menu
 anatomy. The generic primitive defaults to outside-click dismissal; flyout and
@@ -239,14 +242,14 @@ The runtime dispatches a small set of public `actual:*` events. All are
 listenable on the document; cancelable events veto the associated action when
 `preventDefault()` is called.
 
-| Event | Dispatch | Contract |
-|---|---|---|
-| `actual:surface-open` | `openSurface()`, before a surface opens | Cancelable. `detail: { surface, options }` |
-| `actual:context-menu` | context-menu, before its menu opens | Cancelable. `detail: { menu, context, origin, trigger }` |
-| `actual:status` | status module, or any code | Show or clear the status bar. `detail: { message, intent, duration }`; omit `message` to clear |
-| `actual:invalid` | validation, after a submit was blocked | `detail: { form, firstInvalid, message }` |
-| `actual:dialog-cancel` | dialog, before native cancel close | Cancelable. `detail: { dialog, sourceEvent }` |
-| `actual:dismiss` | `--dismiss` command, after hiding a target | `detail: { trigger }` |
+| Event                  | Dispatch                                   | Contract                                                                                       |
+|------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------|
+| `actual:surface-open`  | `openSurface()`, before a surface opens    | Cancelable. `detail: { surface, options }`                                                     |
+| `actual:context-menu`  | context-menu, before its menu opens        | Cancelable. `detail: { menu, context, origin, trigger }`                                       |
+| `actual:status`        | status module, or any code                 | Show or clear the status bar. `detail: { message, intent, duration }`; omit `message` to clear |
+| `actual:invalid`       | validation, after a submit was blocked     | `detail: { form, firstInvalid, message }`                                                      |
+| `actual:dialog-cancel` | dialog, before native cancel close         | Cancelable. `detail: { dialog, sourceEvent }`                                                  |
+| `actual:dismiss`       | `--dismiss` command, after hiding a target | `detail: { trigger }`                                                                          |
 
 ## Extending the runtime
 

package/docs/pages/guides/tailwind.md

@@ -25,14 +25,14 @@ The layered import is the cleanest way to keep both stylesheets during the
 migration:
 
 ```css
-/* Migration setup — Actual rules sit in @layer actual */
 @import "tailwind.css";        /* your compiled Tailwind output */
-@import "actual-css/css/layer";
+@layer actual;
+@import "actual-css/full" layer(actual);
 /* Unlayered project overrides stay on top */
 @import "app.css";
 ```
 
-`actual.layer.css` wraps every Actual rule in a single `@layer actual`, so
+The full import places every Actual rule in a single `actual` layer, so
 unlayered Tailwind output and project CSS keep precedence while the migration
 runs. See [Cascade layer strategy](https://github.com/lekoala/actual-css/blob/master/docs/design-notes/cascade-layer.md) for the
 limitations of the approach.
@@ -128,13 +128,11 @@ Actual:
 </div>
 ```
 
-If the grid should respond to its container:
+If these are independent items that should reflow with available space:
 
 ```html
-<div class="container-query">
-  <div class="grid-3">
-    ...
-  </div>
+<div class="grid" style="--grid-min: 16rem">
+  ...
 </div>
 ```
 

package/docs/pages/layout/app-layout.md

@@ -0,0 +1,57 @@
+# App Layout
+
+> Specialized application recipe with a topbar, independently scrolling content, and one adaptive primary navigation landmark.
+
+Use `.app-layout` only when all three direct regions are intentional:
+
+- `.topbar` is persistent application chrome;
+- `.app-main` is the page's independent scroll container;
+- `.app-nav` changes from bottom navigation to labelled side navigation.
+
+This is not a generic wrapper for a website, dashboard, or anything described
+as an "app." It fixes the shell to the dynamic viewport and hides overflow on
+that shell. A public, marketing, editorial, or normally scrolling page should
+use semantic landmarks, optionally `.app-shell` for full-height document flow,
+and `.navbar` for top-level site navigation.
+
+```html demo
+<div class="app-shell app-layout" style="block-size: 30rem">
+  <header class="topbar">
+    <strong>Tasks</strong>
+  </header>
+  <main class="app-main padding-context">
+    <div class="stack">
+      <h2>Today</h2>
+      <p>The main region scrolls without displacing the application chrome.</p>
+    </div>
+  </main>
+  <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>
+  <div class="fab">
+    <button class="btn primary circle icon-only" type="button" aria-label="Add task">+</button>
+  </div>
+</div>
+```
+
+The direct-child relationship is required, not illustrative: `.app-layout`
+assigns those children to named grid areas and changes `.app-nav` from a bottom
+bar to labelled side navigation. Missing, renamed, or wrapped regions mean a
+different layout contract should be used.
+
+A direct-child `.fab` overlays the end of the main grid area. It therefore
+clears both bottom and side navigation without copying the navigation size or
+bottom safe-area inset. When navigation moves aside, the layout applies the
+bottom inset at the viewport edge. Outside this recipe, FAB keeps its
+viewport-fixed placement.
+
+The recipe uses the dynamic viewport token and gives scrolling to `.app-main`,
+which avoids fixed-position offsets and keeps mobile keyboard resizing within
+the same layout contract. The topbar preserves its normal spacing below the
+top safe-area inset. The recipe provides no routing or page lifecycle.
+
+### Hooks
+
+- `--app-nav-side-size` controls the side navigation track.

package/docs/pages/layout/app-shell.md

@@ -1,16 +1,30 @@
 # App Shell
 
-Document landmarks for top and bottom regions, composed with layout primitives.
+Full-height, single-column document flow. Despite its historical name, this is
+the general shell for ordinary pages as well as simple applications.
 
 Header and footer are document landmarks, not required layout classes.
-
-Use semantic elements by default.
+Use semantic elements by default. `.app-shell` already supplies the outer
+column, so do not add a `.stack` solely to arrange the page landmarks.
 
 ```html demo
 <body class="app-shell">
-  <header>Actual CSS</header>
-  <main class="grow">Main content</main>
-  <footer>Footer links</footer>
+  <header>
+    <div class="center">
+      <nav class="navbar" aria-label="Main">
+        <a class="navbar-brand" href="/">Actual CSS</a>
+      </nav>
+    </div>
+  </header>
+  <main class="grow">
+    <div class="center stack">
+      <h1>Page title</h1>
+      <p>Main content</p>
+    </div>
+  </main>
+  <footer>
+    <div class="center">Footer links</div>
+  </footer>
 </body>
 ```
 
@@ -22,4 +36,11 @@ Use semantic elements by default.
 }
 ```
 
-Sticky header/footer behavior should be opt-in and documented only if it becomes part of the shipped layout API.
+Keep `.center` inside each full-width landmark when their backgrounds or
+borders should span the viewport. Sticky header/footer behavior remains an
+application choice.
+
+Do not upgrade this shell to `.app-layout` merely because the product is an
+application. Use App Layout only for its complete specialized contract: a
+direct-child `.topbar`, independently scrolling `.app-main`, and direct-child
+`.app-nav` that changes from a bottom bar to a labelled side menu.

package/docs/pages/layout/center.md

@@ -26,4 +26,15 @@ Tune width and side padding with local variables.
 
 `.center` intentionally uses `box-sizing: content-box`. The max inline size is
 the content measure, while inline padding is added outside that measure. This is
-deliberate even though the global reset uses `border-box`.
+deliberate even though the global reset uses `border-box`. Its explicit inline
+size subtracts that padding, so `.center` also keeps its available width as a
+flex or grid item instead of collapsing to its min-content width.
+
+Do not override it with `inline-size: 100%`: because the padding sits outside
+the content box, that would make its outer size exceed the available width by
+both padding edges.
+
+As a child of `.stack`, `.center` sizes to its content measure and centers via
+`margin-inline: auto` instead of stretching to the full row. For full-width page
+regions, keep `.center` regions in normal block flow rather than inside a
+`.stack` wrapper (see [stack](stack.md)).

package/docs/pages/layout/choosing.md

@@ -0,0 +1,54 @@
+# Choosing a layout
+
+Choose a primitive from the relationship between its children, not from the
+number of children visible in one mockup.
+
+## Page and application shells
+
+| Situation | Recipe |
+|---|---|
+| Public, marketing, editorial, or normally scrolling page | Semantic landmarks; optionally `.app-shell`, with `.navbar` for site navigation |
+| Persistent topbar + independently scrolling main + bottom-to-side primary navigation | `.app-layout` with its exact direct-child contract |
+
+Do not choose `.app-layout` from the word "app" or from the presence of a
+header. Its viewport-sized grid, hidden shell overflow, internal main scroll,
+and adaptive `.app-nav` are one indivisible behavior. If any of those is not
+wanted, compose the ordinary page from semantic landmarks and the primitives
+below.
+
+## Content relationships
+
+| Situation                                                    | Primitive         |
+|--------------------------------------------------------------|-------------------|
+| Vertical flow                                                | `.stack`          |
+| Inline actions, tags, or navigation that may wrap            | `.cluster`        |
+| Responsive collection; an incomplete final row is acceptable | `.grid`           |
+| Known structural density, at most N columns                 | `.grid-N`         |
+| Peer regions that must switch together                       | `.switcher`       |
+| Main content followed by a secondary region                  | `.sidebar-layout` |
+| Fixed media followed by flexible content                     | `.media`          |
+| Explicit region placement on a shared 12-column canvas       | `.column-layout`  |
+
+For cards, products, results, and galleries, start with `.grid`. Use a fixed
+`.grid-N` only when N columns remain part of the structure at every width. If
+all peers should move together rather than form a partial row, use `.switcher`.
+
+For a main region plus an aside, use `.sidebar-layout`.
+
+Use `.column-layout` when the placement of each region is itself part of the
+design — a 10-column article starting on column 2, regions in separate sibling
+sections that must share the same column lines, an editorial composition whose
+starts and spans are deliberately aligned across the page. It is the one layout
+primitive with no automatic responsive behavior: the canvas stays twelve
+columns and the application owns narrow-container recomposition. Choose it
+because placement is the design, not because a mockup happens to contain
+columns.
+
+Use `--grid-columns` for exact track templates that do not match a built-in
+layout contract: arbitrary structural counts such as seven calendar days,
+asymmetric fractional tracks, or mixed intrinsic/flexible tracks. Once set, the
+application owns narrow-container behavior.
+
+`.container-query` is a low-level opt-in for a component that changes its own
+representation according to allocated space. It does not enable responsive
+behavior for layout primitives and never changes their meaning.