actual-css 0.4.0 → 0.4.2

package/docs/pages/components/rating.md

@@ -0,0 +1,68 @@
+# Rating
+
+> Integer star rating built from native radio inputs.
+
+Each star is a real `input[type="radio"]`, so submission, `required`, disabled
+state, form reset, and keyboard navigation remain native. Keep values and DOM
+order ascending. The cumulative fill and hover preview use `:has()` as a
+progressive enhancement; older supported browsers show only the selected star
+filled while the control remains fully functional.
+
+## Class reference
+
+| Class         | Kind      | Description                         |
+|---------------|-----------|-------------------------------------|
+| `.rating`     | Component | Radio group presented as stars.     |
+| `.sm` / `.lg` | Size      | Smaller or larger star geometry.    |
+
+```html demo
+<fieldset class="field">
+  <legend class="field-label">Rate your experience</legend>
+  <div class="rating">
+    <input type="radio" name="experience" value="1" aria-label="1 star" />
+    <input type="radio" name="experience" value="2" aria-label="2 stars" />
+    <input type="radio" name="experience" value="3" aria-label="3 stars" checked />
+    <input type="radio" name="experience" value="4" aria-label="4 stars" />
+    <input type="radio" name="experience" value="5" aria-label="5 stars" />
+  </div>
+</fieldset>
+```
+
+Use a visible `<legend>` to name the group and an `aria-label` on every radio
+to name its value. Add `required` to the radios when the form must receive a
+rating. In forced-colors mode the stars deliberately return to native platform
+radios so checked and focus states remain unambiguous.
+
+Intent classes change the active color without changing the interaction model.
+
+```html demo
+<div class="cluster">
+  <fieldset class="field">
+    <legend class="field-label">Small rating</legend>
+    <div class="rating primary sm">
+      <input type="radio" name="small-rating" value="1" aria-label="1 star" />
+      <input type="radio" name="small-rating" value="2" aria-label="2 stars" checked />
+      <input type="radio" name="small-rating" value="3" aria-label="3 stars" />
+    </div>
+  </fieldset>
+
+  <fieldset class="field">
+    <legend class="field-label">Large rating</legend>
+    <div class="rating danger lg">
+      <input type="radio" name="large-rating" value="1" aria-label="1 star" />
+      <input type="radio" name="large-rating" value="2" aria-label="2 stars" />
+      <input type="radio" name="large-rating" value="3" aria-label="3 stars" />
+      <input type="radio" name="large-rating" value="4" aria-label="4 stars" checked />
+      <input type="radio" name="large-rating" value="5" aria-label="5 stars" />
+    </div>
+  </fieldset>
+</div>
+```
+
+### Hooks
+
+- `--rating-size` — size of each star; `.sm` and `.lg` set this hook.
+- `--rating-gap` — visual space between stars without creating inactive hover zones.
+- `--rating-color` — star color. Prefer an intent class for semantic color.
+- `--rating-empty` — color of unselected stars; use a surface or border token.
+- `--rating-star` — mask image used to draw a star; override it when a strict CSP disallows data URLs.

package/docs/pages/components/steps.md

@@ -0,0 +1,57 @@
+# Steps
+
+> Semantic ordered-list progression for a multi-step process.
+
+Use an `<ol>` because order is part of the meaning. Add `.complete` to finished
+steps and `aria-current="step"` to exactly one current step. Unmarked items are
+future steps. The component needs no JavaScript.
+
+## Class reference
+
+| Class                   | Kind      | Description                                |
+|-------------------------|-----------|--------------------------------------------|
+| `.steps`                | Component | Ordered progression with numbered markers. |
+| `.complete`             | State     | A finished step.                           |
+| `[aria-current="step"]` | State     | The current step.                          |
+
+```html demo
+<ol class="steps">
+  <li class="complete">Account</li>
+  <li aria-current="step">Payment</li>
+  <li>Confirm</li>
+</ol>
+```
+
+## Intrinsic responsiveness
+
+`.steps` fills its row when the steps fit and holds each item at `--step-min`
+otherwise, so the sequence scrolls horizontally only when it genuinely cannot
+fit — no breakpoint. The threshold is space-driven: how many steps fit depends
+on their number and the configurable minimum item width `--step-min`. Labels
+wrap inside their item when needed.
+
+Because `.steps` is an `<ol>` that can scroll horizontally, its overflow is not
+focusable by default in every browser. Prefer a `--step-min` that fits the
+common case, and only give a step flow `tabindex="0"` when your content
+genuinely needs keyboard access to the overflow — the framework adds neither
+JavaScript nor a tabindex automatically.
+
+Keep state classes aligned with the real process state; they are visual, while
+`aria-current="step"` also exposes the current position to assistive technology.
+Do not put links or buttons around a step unless the workflow genuinely allows
+the user to navigate to it.
+
+### Hooks
+
+- `--step-size` — marker diameter.
+- `--step-min` — minimum item width; below this the sequence scrolls instead of
+  squishing labels.
+- `--step-gap` — space between each marker and label.
+- `--step-line-size` — connector thickness.
+- `--step-marker-radius` — marker corner radius (round by default).
+- `--step-connector` — connector background; when set it overrides the color
+  (defaults to each step's own line, so a `.complete` step's connector follows
+  its selected color). A plain color by default, but any background (e.g. a
+  dashed `repeating-linear-gradient`) works.
+- `--step-complete-mark` — replaces the number on a `.complete` step with any
+  `content` value (e.g. `"✓"`); defaults to the step number.

package/docs/pages/enhancements/flyout.md

@@ -350,12 +350,12 @@ delay; a number sets the delay in milliseconds.
       More
     </button>
   </div>
-  <p class="text-sm text-muted">Right click a detail below, press the context-menu key, or use More.</p>
+  <p class="muted">Right click a detail below, press the context-menu key, or use More.</p>
   <div class="cluster">
     <span class="badge" data-context-item="File name">File.pdf</span>
     <span class="badge" data-context-item="Owner">Design team</span>
   </div>
-  <output id="context-result" class="text-sm text-muted" aria-live="polite">No context selected.</output>
+  <output id="context-result" class="muted" aria-live="polite">No context selected.</output>
 
   <menu class="flyout menu"
         id="file-actions"

package/docs/pages/enhancements/tabs.md

@@ -20,8 +20,7 @@
 - A `.tab` with an icon uses `--tab-gap` (default `0.375em`) for the space between icon and label.
 
 ```html demo
-<div class="tabset">
-  <div class="tabs" data-enhance="tabs" role="tablist" aria-label="Settings">
+<div class="tabs" data-enhance="tabs" role="tablist" aria-label="Settings">
     <button class="tab primary"
             type="button"
             role="tab"

package/docs/pages/examples/overview.md

@@ -26,6 +26,14 @@ and `actual.full.js` from `dist/`, plus the theme palettes bundle from
 
 Full sites demo living in `demo/sites`.
 
+### Mobile PWA
+
+[Actual Tasks](../../demo/sites/actual-tasks/index.html) is a mobile task demo
+with one bottom/side navigation landmark, application lists, tabs,
+dialog validation, project cards, an activity feed, loading and empty states,
+theme preferences, switches, and passive status feedback. Its local
+stylesheet includes a rule-by-rule framework friction audit.
+
 ### Admin application
 
 `demo/sites/admini/` is a complete admin interface: application shell, navigation,

package/docs/pages/forms/otp.md

@@ -40,6 +40,38 @@ The component follows shared `.sm` and `.lg` density through `--control-size`.
 Use `aria-invalid="true"` for explicit invalid state, or place it in the
 standard `.needs-validation.was-validated` form flow.
 
+The `<input>` must be the **first** direct child, with one `<span>` per
+character after it — the state rules (focus, invalid, disabled) select the
+cells as following siblings, so that order is part of the contract.
+
+## Disabled
+
+Set `disabled` on the input. The cells rest on `--surface-subtle` with a muted
+`--state-disabled` border at `--disabled-opacity`, the code glyph turns
+`--state-disabled`, and the cursor is `not-allowed` — a clearly distinct,
+non-interactive look that follows the shared disabled contract. A disabled
+`<fieldset>` disables it the same way.
+
+```html demo
+<div class="otp" aria-label="Disabled verification code">
+  <input
+    class="input"
+    type="text"
+    autocomplete="one-time-code"
+    inputmode="numeric"
+    maxlength="6"
+    disabled
+    aria-label="Disabled verification code"
+  />
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+  <span aria-hidden="true"></span>
+</div>
+```
+
 ## CSS hooks
 
 - `--otp-cell-size` — width and height of every cell; follows `--control-size`.

package/docs/pages/forms/states-and-sizes.md

@@ -96,7 +96,7 @@ type instead.
         </label>
       </div>
 
-      <div class="grid-5 items-start">
+      <div class="grid items-start">
         <label class="choice">
           <input class="check" type="checkbox" />
           <span>
@@ -133,7 +133,7 @@ type instead.
           <input class="check" type="checkbox" id="indet-demo" />
           <span>
             <span class="field-label">Indeterminate checkbox</span>
-            <span class="field-help">Partially selected — set via <code>element.indeterminate = true</code>. Try it: <button class="btn text sm" type="button" onclick="document.getElementById('indet-demo').indeterminate = !document.getElementById('indet-demo').indeterminate">toggle</button></span>
+            <span class="field-help">Partially selected — set via <code>element.indeterminate = true</code>. Try it: <button class="btn link sm" type="button" onclick="document.getElementById('indet-demo').indeterminate = !document.getElementById('indet-demo').indeterminate">toggle</button></span>
           </span>
         </label>
       </div>
@@ -291,7 +291,7 @@ type instead.
         </label>
         <label class="choice">
           <input class="check" type="checkbox" id="indet-size" />
-          <span>Indeterminate <button class="btn text sm" type="button" onclick="document.getElementById('indet-size').indeterminate = !document.getElementById('indet-size').indeterminate">toggle</button></span>
+          <span>Indeterminate <button class="btn link sm" type="button" onclick="document.getElementById('indet-size').indeterminate = !document.getElementById('indet-size').indeterminate">toggle</button></span>
         </label>
       </div>
 

package/docs/pages/guides/integrating-actual-css.md

@@ -4,6 +4,12 @@ Use Actual CSS as a vocabulary before writing application CSS.
 
 The goal is not to eliminate custom CSS. The goal is to keep framework concerns in the framework and application identity in the application.
 
+In short: **use Actual for generic structure and behavior; add product-specific
+classes for brand and compositions rather than forcing a generic primitive.** A
+local rule is not a failure of Actual — overfitting the framework to a
+product-specific look is. Reach for an Actual primitive first, and write
+application CSS when the need is genuinely product-specific (see §6–7).
+
 ## 1. Start with the theme
 
 Define palette values once, then derive decorative colors from them.

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

@@ -3,6 +3,21 @@
 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`          |

package/docs/pages/layout/grid.md

@@ -34,7 +34,7 @@ Tune the item minimum with `--grid-min`.
 own: it never exceeds N columns, never overflows, and every item keeps the same
 width.
 
-```html demo
+```html demo bare
 <div class="grid-4">
   <div class="card">Exercitation</div>
   <div class="card">Amet mollit</div>
@@ -55,8 +55,10 @@ density is `.grid-N`'s. Choose the preset that suits your item size:
 ## Balanced subdivision
 
 Left alone, a preset collapses one column at a time, so a six-item `.grid-6`
-can pass through five columns — five items and a lone sixth. Wrap it in
-`.container-query` and it only ever enters a **divisor of N**:
+can pass through five columns — five items and a lone sixth. The example above
+is that bare version. Placed inside a container named **`actual-grid`** — the
+`.container-query` helper, or a region of your own that declares
+`container: actual-grid / inline-size` — it only ever enters a **divisor of N**:
 
 ```text
 .grid-2   2 → 1
@@ -80,12 +82,43 @@ Every state splits the collection evenly, and all items keep the same width.
 </div>
 ```
 
-The wrapper is an opt-in for precision, never a prerequisite for responsive
-behavior — forgetting it costs you the exact chain, nothing else. It has to be
-an ancestor: an element cannot query its own size without taking inline-size
+### Container sizes
+
+The steps are read from the **container's content box** — not the viewport, and
+not the grid's own width. Padding and borders on the container come off before
+the query resolves.
+
+| Container content box | `.grid-2` | `.grid-3` | `.grid-4` | `.grid-6` |
+|-----------------------|-----------|-----------|-----------|-----------|
+| under `28rem`         | 1         | 1         | 1         | 1         |
+| `28rem` to `48rem`    | 2         | 1         | 2         | 2         |
+| `48rem` to `64rem`    | 2         | 3         | 2         | 3         |
+| `64rem` and up        | 2         | 3         | 4         | 6         |
+
+Size a region that hosts a `.grid-N` so it lands on the step you want, with room
+to spare. The step is a cliff, not a ramp: a container at `47rem` gives
+`.grid-3` a single column, the same as one at `20rem`. `.grid-3` has no
+intermediate state by design — it never shows `2 + 1`.
+
+Budget backwards from the content box. A region that must reach a step needs
+that width **plus its own padding and borders**:
+
+```text
+3 columns   48rem + 2 x 1rem padding  ~= 50rem outer
+4 or 6      64rem + 2 x 1rem padding  ~= 66rem outer
+```
+
+Round up past the figure rather than matching it exactly, so a later padding
+change cannot drop the region a state.
+
+Balanced subdivision is precision, never a prerequisite for responsive
+behavior — forgetting the container costs you the exact chain, nothing else.
+The grid responds only to a container named `actual-grid`, never to an
+incidental query container, so a region that sets `container-type: inline-size`
+for its own reasons leaves the grid untouched. The container has to be an
+ancestor: an element cannot query its own size without taking inline-size
 containment, which would collapse the grid inside a `.cluster`, a float, or any
-shrink-to-fit box. Put `.container-query` on a normal block-level wrapper for
-the same reason.
+shrink-to-fit box. Put it on a normal block-level wrapper for the same reason.
 
 The chain balances the **declared density**, not your actual item count. Eight
 items in `.grid-6` still give `6 + 2`. For a paginated collection, choose a page

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

@@ -22,6 +22,25 @@ otherwise stack. No `.container-query` ancestor is required.
 The first child is the flexible main region and the last child is the aside.
 Use a custom `.grid` template only when an exact editorial ratio is structural.
 
+To place the aside on the inline start instead, add `.reverse` and put the
+aside first in the DOM — visual, reading and keyboard order then all agree:
+
+```html demo
+<div class="sidebar-layout reverse">
+  <aside class="stack">
+    <h3>On this page</h3>
+    <ol class="list-reset"><li><a class="link-muted" href="#">Section</a></li></ol>
+  </aside>
+
+  <article class="stack">
+    <h1>Long-form article</h1>
+    <p>Article body that benefits from a related table of contents.</p>
+  </article>
+</div>
+```
+
+When the layout stacks (narrow space), the aside stays on top.
+
 ### Hooks
 
 - `--sidebar-layout-size` sets the aside's preferred width.

package/docs/pages/layout/stack.md

@@ -22,6 +22,23 @@ block margins are reset, so vertical rhythm always comes from `--gap`. Inline
 margins stay free — for example `margin-inline: auto` on a child centers it
 without fighting the primitive.
 
+## Don't wrap full-width regions with `.stack`
+
+`.stack` is a column flex container, so a `.center` child — which sets its own
+`inline-size` and `margin-inline: auto` — becomes a flex item that will not
+stretch across the full row; it sizes to its content measure and centers inside
+the flex line. For page-level full-width regions that each constrain their own
+content, keep them in normal block flow instead:
+
+```html
+<header class="center">…</header>
+<main class="center">…</main>
+<footer class="center">…</footer>
+```
+
+Use `.stack` for the vertical rhythm *between* related items inside one region,
+not as the wrapper that lays out independent full-width regions of a page.
+
 ## Choosing a density
 
 `--gap` is the primitive's channel, and the density variants set it at the point

package/docs/pages/patterns/icon-slot.md

@@ -0,0 +1,61 @@
+# Icon slot
+
+> Contained icon zones — a leading icon, an icon disc, a status marker — appear
+> across product UI: notifications, activity feeds, list actions, cards. There
+> is no dedicated primitive; the same small contract is composed from existing
+> pieces.
+
+A contained icon zone must be a **stable box** that never shrinks, always
+centers its glyph, and clips overflow:
+
+- fixed `inline-size` / `block-size` (or `aspect-ratio: 1` for a disc);
+- `display: grid; place-items: center;` for reliable centering;
+- `flex: 0 0 auto` so a flex row never compresses it;
+- `overflow: hidden`;
+- a child `svg` constrained to the box.
+
+## The contract
+
+```css
+.product-icon {
+  flex: 0 0 auto;
+  inline-size: 1.5rem;
+  block-size: 1.5rem;
+  display: grid;
+  place-items: center;
+  overflow: hidden;
+}
+
+.product-icon svg {
+  inline-size: 100%;
+  block-size: 100%;
+}
+```
+
+For a round disc, add the `.circle` utility — it supplies the `border-radius`:
+
+```css
+.product-icon.circle {
+  background: var(--surface-subtle);
+}
+```
+
+## Reuse the existing icon slots
+
+Several components already embody this slot — reach for them before composing
+your own:
+
+- `.alert-icon` — the leading icon in an alert.
+- `.avatar` — initials or image in a fixed circular box.
+- `.btn.icon-only` — a square icon button sized to the control height.
+- `.input-icon` — a leading icon in a search/filter input.
+
+```html demo
+<div class="media">
+  <span class="avatar primary"><abbr>AM</abbr></span>
+  <div class="stack">
+    <strong>Ada Meridian</strong>
+    <span class="muted">Senior designer.</span>
+  </div>
+</div>
+```