actual-css 0.3.1 → 0.4.1

package/docs/pages/components/navbar.md

@@ -8,19 +8,23 @@
 - `.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.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.navbar` | Component | Horizontal bar shell. |
-| `.navbar-brand` | Composition | Brand link at the inline start. |
-| `.navbar-nav` | Composition | Horizontal link list. |
-| `.nav-link` | Component | A link item; current page via `aria-current="page"`. |
-| `.nav-list` | Component | Shared vertical navigation list, reused by `.drawer`. |
+| Class           | Kind        | Description                                           |
+|-----------------|-------------|-------------------------------------------------------|
+| `.navbar`       | Component   | Horizontal bar shell.                                 |
+| `.navbar-brand` | Composition | Brand link at the inline start.                       |
+| `.navbar-nav`   | Composition | Horizontal link list.                                 |
+| `.nav-link`     | Component   | A link item; current page via `aria-current="page"`.  |
+| `.nav-list`     | Component   | Shared vertical navigation list, reused by `.drawer`. |
 
 ## Basic usage
 
@@ -36,13 +40,16 @@ 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
 
 There is no collapse/toggler mechanism. For a responsive navigation, keep the
 horizontal `.navbar` for the desktop bar and compose the mobile experience from
 a `.drawer` with a vertical `.nav-list`, opened by a `command="show-modal"` /
-`commandfor` trigger.
+`commandfor` trigger. Keep that trigger outside the `<nav>` subtree you hide at
+narrow widths, or hiding the nav hides the control that opens it.
 
 ```html demo
 <nav class="navbar" aria-label="Main">

package/docs/pages/components/pagination.md

@@ -9,14 +9,15 @@
 - Numeric links may use `aria-label="Page N"` for clearer screen reader output.
 - Prefer text labels for Previous and Next. Icon-only controls need an accessible name.
 - Page links can compose with `.btn` for button-like hit targets.
+- Arrows, page numbers, and truncation ellipses share one geometric system: every item gets the same minimum footprint, and wider content (100, 1000, text labels) grows past it naturally.
 - Truncated ranges are plain text with `.muted` and `aria-hidden="true"`, not `.btn` — they are decorative, not actionable.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
+| Class         | Kind      | Description                    |
+|---------------|-----------|--------------------------------|
 | `.pagination` | Component | Ordered list of page controls. |
-| `.sm` / `.lg` | Size | Control density. |
+| `.sm` / `.lg` | Size      | Control density.               |
 
 ## Basic usage
 

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/skeleton.md

@@ -10,10 +10,10 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.skeleton` | Component | Animated placeholder shape. |
-| `data-shape` | Modifier | Geometry presets: `text`, `title`, `avatar`, `box`. |
+| Class        | Kind      | Description                                         |
+|--------------|-----------|-----------------------------------------------------|
+| `.skeleton`  | Component | Animated placeholder shape.                         |
+| `data-shape` | Modifier  | Geometry presets: `text`, `title`, `avatar`, `box`. |
 
 ## Basic usage
 

package/docs/pages/components/spinner.md

@@ -12,11 +12,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.spinner` | Component | Circular loading indicator using `currentColor`. |
-| `.sm` / `.lg` | Size | Smaller (`0.75em`) or larger (`2rem`) spinner. |
-| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger` color. |
+| Class          | Kind      | Description                                                        |
+|----------------|-----------|--------------------------------------------------------------------|
+| `.spinner`     | Component | Circular loading indicator using `currentColor`.                   |
+| `.sm` / `.lg`  | Size      | Smaller (`0.75em`) or larger (`2rem`) spinner.                     |
+| Shared intents | Intent    | `.primary`, `.secondary`, `.success`, `.warning`, `.danger` color. |
 
 ## Basic usage
 

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/components/table.md

@@ -11,10 +11,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.table-wrap` | Component | Scroll container and outer chrome (surface, border, radius). |
-| `.table` | Component | The table itself; row and cell rules. |
+| Class           | Kind      | Description                                                  |
+|-----------------|-----------|--------------------------------------------------------------|
+| `.table-wrap`   | Component | Scroll container and outer chrome (surface, border, radius). |
+| `.table`        | Component | The table itself; row and cell rules.                        |
+| `.table.compact`| Density   | Tighter cell padding; typography is unchanged.               |
 
 ## Basic usage
 
@@ -96,7 +97,31 @@ table width before the wrapper scrolls horizontally.
 </div>
 ```
 
+## Compact tables
+
+`.compact` lowers the cell padding only — density never changes typography.
+It is the same vocabulary as `.card.compact`.
+
+```html demo
+<div class="table-wrap">
+  <table class="table compact">
+    <caption>Standings by position</caption>
+    <thead>
+      <tr>
+        <th scope="col">Pos</th>
+        <th scope="col">Name</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td>1</td><td>John Nemo</td></tr>
+      <tr><td>2</td><td>Jane Doe</td></tr>
+      <tr><td>3</td><td>Ada Morgan</td></tr>
+    </tbody>
+  </table>
+</div>
+```
+
 ## CSS hooks
 
-- `--table-cell-pad` — cell padding.
+- `--table-cell-pad` — cell padding; `.compact` re-declares it tighter.
 - `--table-min` — minimum table width before `.table-wrap` scrolls horizontally.

package/docs/pages/enhancements/flyout.md

@@ -4,19 +4,19 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.flyout-trigger` | Composition | Positioning wrapper for a trigger and its panel; gives the flyout a local absolute-position fallback before JavaScript positions it. |
-| `.stretch` | Modifier | Stretches a `.flyout-trigger` to span its container, e.g. the last row of a full-width sidebar nav list. |
-| `.flyout` | Component | Floating action or nav surface, positioned by JavaScript. |
-| `.menu` | Component | Action-list primitive with strict `.menu > li > .menu-item` anatomy. |
-| `.menu-item` | Component | One action row; participates in roving focus. |
-| `.menu-item-icon` | Slot | Fixed leading column for a decorative icon. |
-| `.menu-item-text` | Slot | Flexible label column; truncates when the row is constrained. |
-| `.menu-item-end` | Slot | Trailing metadata such as a shortcut, badge, or status. |
-| `.menu-label` | Variant | Muted section heading inside a menu; not interactive. |
-| `.menu-separator` | Variant | Divider between menu groups (`<hr role="separator">`). |
-| `.sm` / `.lg` | Variant | Compact or large density. |
+| Class             | Kind        | Description                                                          |
+|-------------------|-------------|----------------------------------------------------------------------|
+| `.flyout-trigger` | Composition | Positioning wrapper for a trigger and its panel.                     |
+| `.stretch`        | Modifier    | Stretches a `.flyout-trigger` to span its container.                 |
+| `.flyout`         | Component   | Floating action or nav surface, positioned by JavaScript.            |
+| `.menu`           | Component   | Action-list primitive with strict `.menu > li > .menu-item` anatomy. |
+| `.menu-item`      | Component   | One action row; participates in roving focus.                        |
+| `.menu-item-icon` | Slot        | Fixed leading column for a decorative icon.                          |
+| `.menu-item-text` | Slot        | Flexible label column; truncates when the row is constrained.        |
+| `.menu-item-end`  | Slot        | Trailing metadata such as a shortcut, badge, or status.              |
+| `.menu-label`     | Variant     | Muted section heading inside a menu; not interactive.                |
+| `.menu-separator` | Variant     | Divider between menu groups (`<hr role="separator">`).               |
+| `.sm` / `.lg`     | Variant     | Compact or large density.                                            |
 
 ## Usage
 
@@ -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/overview.md

@@ -33,4 +33,4 @@ is a no-op until the module is loaded again with a DOM.
 Each interactive component has its own page documenting the exact markup its
 enhancement expects: Dialog, Drawer, Flyout, Tooltip, Tabs, Scrollspy, and
 Status Bar. The default runtime is loaded on the docs pages, so the examples
-work with the documented markup alone.
+work with the documented markup alone.

package/docs/pages/enhancements/scrollspy.md

@@ -8,11 +8,11 @@ or style `[aria-current]` yourself.
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.scrollspy` | Component | Marks the nav region for the enhancer; adds no visual styles. |
-| `.nav-list` | Composition | Vertical list of navigation links. |
-| `.nav-link` | Component | Navigation link whose active state comes from `[aria-current]`. |
+| Class        | Kind        | Description                                                     |
+|--------------|-------------|-----------------------------------------------------------------|
+| `.scrollspy` | Component   | Marks the nav region for the enhancer; adds no visual styles.   |
+| `.nav-list`  | Composition | Vertical list of navigation links.                              |
+| `.nav-link`  | Component   | Navigation link whose active state comes from `[aria-current]`. |
 
 ## Usage
 
@@ -68,4 +68,4 @@ without JavaScript.
 ```
 
 Keep this as progressive enhancement. The JavaScript enhancement remains the
-portable fallback — the same markup serves both paths.
+portable fallback — the same markup serves both paths.

package/docs/pages/enhancements/status-bar.md

@@ -2,6 +2,10 @@
 
 > Singleton floating area for short, non-critical, transient feedback.
 
+`status-bar` is for transient feedback, not persistent application status. For
+persistent status, metrics, or operational state, compose regular content
+primitives such as cards, badges, and clusters.
+
 A status bar is a single live region, not a stacked toaster. New messages
 replace the previous one. Keep one element in the HTML, styled with
 `.status-bar` and carrying the `[data-status][role="status"]` contract that the
@@ -69,4 +73,4 @@ document.dispatchEvent(new CustomEvent("actual:status", {
 - `--status-bg` — bar background.
 - `--status-fg` — bar text color.
 
-Prefer an intent class over setting these directly.
+Prefer an intent class over setting these directly.

package/docs/pages/enhancements/tabs.md

@@ -4,11 +4,11 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.tabs` | Component | Tab strip; pairs with `role="tablist"`. |
-| `.tab` | Component | One tab trigger; pairs with `role="tab"`. |
-| `.primary` | Intent | Tints the selected tab's indicator and text. |
+| Class      | Kind      | Description                                  |
+|------------|-----------|----------------------------------------------|
+| `.tabs`    | Component | Tab strip; pairs with `role="tablist"`.      |
+| `.tab`     | Component | One tab trigger; pairs with `role="tab"`.    |
+| `.primary` | Intent    | Tints the selected tab's indicator and text. |
 
 ## Usage
 
@@ -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"
@@ -77,4 +76,4 @@ JavaScript involved:
 
 ## CSS hooks
 
-- `--tab-gap` — space between an icon and the label text (default `0.375em`).
+- `--tab-gap` — space between an icon and the label text (default `0.375em`).

package/docs/pages/enhancements/tooltip.md

@@ -127,4 +127,4 @@ and solid colors both work.
 - `--tooltip-arrow-size` — arrow size.
 
 `--arrow-x` and `--arrow-y` are written by the positioner at runtime, not set by
-the author. See the JavaScript runtime documentation.
+the author. See the JavaScript runtime documentation.

package/docs/pages/examples/overview.md

@@ -1,28 +1,10 @@
 # Examples
 
-> Real pages built with Actual CSS - an admin application and a set of standalone templates - to see the primitives, components, and patterns composed the way they are meant to be used.
+> Real pages built with Actual CSS to see the primitives, components, and patterns composed the way they are meant to be used.
 
-The examples live in the repository under `demo/` and load the shipped bundles
-from `dist/` (`actual.css`, `optional.css`, `actual-themes.min.css`,
-`actual.js`), referenced with stable URLs.
-
-## Admin application
-
-`demo/admini/` is a complete admin interface: application shell, navigation,
-tables, forms, dialogs, and feedback states.
-
-- [Dashboard](../../demo/admini/index.html) - app shell, navbar, stat cards, charts, recent activity
-- [Login](../../demo/admini/login.html) - centered auth card with social actions
-- [Forms](../../demo/admini/forms.html) - inputs, choice cards, validation, joined controls, sticky actions
-- [Tables](../../demo/admini/tables.html) - data tables, status badges, bulk actions
-- [Kanban](../../demo/admini/kanban.html) - drag-free column layout with cards
-- [Chat](../../demo/admini/chat.html) - conversation list, message thread, composer
-- [Calendar](../../demo/admini/calendar.html) - month grid with event cards
-- [Invoice](../../demo/admini/invoice.html) - structured document layout
-- [Profile](../../demo/admini/profile.html) - avatar, tabs, settings rows
-- [Settings](../../demo/admini/settings.html) - grouped settings with switches
-- [User grid](../../demo/admini/user-grid.html) - avatar grid, filters, pagination
-- [404](../../demo/admini/404.html) - empty state
+The examples live in the repository under `demo/` and load `actual.full.css`
+and `actual.full.js` from `dist/`, plus the theme palettes bundle from
+`demo/assets/` (`bun run build:themes`).
 
 ## Templates
 
@@ -37,7 +19,50 @@ tables, forms, dialogs, and feedback states.
 - [Blog](../../demo/templates/blog.html) - article page with prose
 - [Blocks](../../demo/templates/blocks.html) - layout building blocks
 - [Layout reference](../../demo/templates/layouts.html) - canonical compositions built only with the layout primitives
+- [Grid density](../../demo/templates/grid.html) - the grid contracts on resizable stages, with the pitfalls called out
 - [Density](../../demo/templates/density.html) - compact control density
 
+## Sites
+
+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,
+tables, forms, dialogs, and feedback states.
+
+- [Dashboard](../../demo/sites/admini/index.html) - app shell, navbar, stat cards, quota meter, recent activity
+- [Login](../../demo/sites/admini/login.html) - centered auth card with social actions
+- [Forms](../../demo/sites/admini/forms.html) - inputs, choice cards, validation, joined controls
+- [Tables](../../demo/sites/admini/tables.html) - data tables, status badges, right-click row actions
+- [Kanban](../../demo/sites/admini/kanban.html) - drag-and-drop columns with card context menus
+- [Chat](../../demo/sites/admini/chat.html) - conversation list, message thread, composer
+- [Calendar](../../demo/sites/admini/calendar.html) - month grid with event chips and month navigation
+- [Invoice](../../demo/sites/admini/invoice.html) - structured document layout, print styles
+- [Profile](../../demo/sites/admini/profile.html) - avatar header, tabs, activity feed
+- [Settings](../../demo/sites/admini/settings.html) - vertical tabs, validation, confirmation dialog
+- [User grid](../../demo/sites/admini/user-grid.html) - avatar grid with live search and role filter
+- [404](../../demo/sites/admini/404.html) - error state
+
+### Neon ramen
+
+`demo/sites/neon-ramen/` is a complete restaurant storefront: campaign home,
+menu browsing, item customization, locations, and checkout validation flow.
+
+- [Home](../../demo/sites/neon-ramen/index.html) - campaign landing, hero story, live cart summary
+- [Menu](../../demo/sites/neon-ramen/menu.html) - tabbed categories with equal-height product cards
+- [Item](../../demo/sites/neon-ramen/item.html) - product configurator with choice cards and form controls
+- [Locations](../../demo/sites/neon-ramen/locations.html) - responsive shop list with practical location metadata
+- [Order](../../demo/sites/neon-ramen/order.html) - checkout form with validation feedback states
+
+
 > Note: the examples reference the repository's source files, so they open from
 > the checkout, not from a standalone copy of `site`.

package/docs/pages/forms/choice-cards.md

@@ -4,10 +4,10 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.choice-card` | Component | Card-style `<label>` wrapping a native radio or checkbox; the whole card is the click target. |
-| `.primary` / `.secondary` | Intent | Intent accent for the selected state (supported on the card). |
+| Class                     | Kind      | Description                                                   |
+|---------------------------|-----------|---------------------------------------------------------------|
+| `.choice-card`            | Component | Card-style `<label>` wrapping a native radio or checkbox.     |
+| `.primary` / `.secondary` | Intent    | Intent accent for the selected state (supported on the card). |
 
 - Use `.choice-card` on a `<label>` wrapping a native `<input type="radio">` or `<input type="checkbox">`. The input is visually hidden; in browsers without `:has()` it stays visible so selection state never disappears.
 - Selected items show a primary border, subtle background tint, and a checkmark badge at the top-right corner — round for radio, rounded square for checkbox.
@@ -96,7 +96,12 @@ Sizes follow the shared `.sm` and `.lg` modifiers. Intent classes (`.primary`, `
 - `--choice-card-radius` — corner radius.
 - `--choice-card-check-size` — size of the check indicator.
 
-Plain `.check` / `.radio` controls expose one hook:
+Plain `.check` / `.radio` controls expose two hooks:
 
+- `--choice-control-size` — the control's own size, in `em` off the surrounding
+  type. The switch track derives from it too, so a checkbox and a switch on the
+  same line stay proportionate. `.sm` / `.lg` do not touch it.
 - `--choice-control-offset` — top offset that aligns the control with the first
-  line of a multi-line label.
+  line of a multi-line label. Left unset, each control derives its own offset
+  from its height and the line box, which keeps a checkbox and a taller switch
+  level with each other. Setting one constant applies it to both.

package/docs/pages/forms/controls.md

@@ -29,4 +29,4 @@ The filename area stays muted.
   <input class="file" type="file" accept="image/*" aria-describedby="file-help" />
   <span class="field-help" id="file-help">JPG, PNG or WebP — max 2 MB</span>
 </label>
-```
+```

package/docs/pages/forms/detached-actions.md

@@ -56,4 +56,4 @@ For multiple submit intents, pair the `form` attribute with `formaction`. The fo
     Publish
   </button>
 </div>
-```
+```

package/docs/pages/forms/floating-field.md

@@ -1,6 +1,6 @@
 # Floating labels
 
-> **Optional** — import `actual-css/css/optional/floating-field` or `actual-css/css/optional`.
+> **Module** — import `actual-css/css/forms/floating-field` or `actual-css/css/forms/all`.
 
 `.floating-field` turns a control and its label into a floating-label cell:
 the label rests inside the control and floats to the top when the control is
@@ -28,8 +28,9 @@ prefills a field still lifts the label.
 
 ## Textarea
 
-A textarea's resting label aligns with the first text line instead of centering
-in the tall control.
+A textarea's empty label starts at the control's normal first-line position,
+then floats to the same top anchor as the other controls when focused or
+filled. The control still reserves headroom so its text position never jumps.
 
 ```html demo
 <div class="field">
@@ -75,8 +76,12 @@ line on top of the control's minimum size.
 
 ## CSS hooks
 
+- `--floating-label-top` — shared top anchor for floated labels.
+- `--floating-label-opacity` — resting label opacity; floated labels return to
+  full opacity.
 - `--floating-pad-block-start` — headroom reserved above the control for the
-  floated label; defaults to half the control height plus one spacing step.
+  floated label; it also anchors an empty textarea label to its first text
+  line.
 
 Validation and focus come from the existing form contracts: the control's
 border and focus ring flip through `--form-invalid-border` and the shared
@@ -85,4 +90,4 @@ left to the surrounding recipe — the joined floating form in the
 [blocks demo](../../demo/templates/blocks.html) shows one such recipe.
 
 > Not currently compatible with `.input-icon`; use standard labels when an
-> embedded leading icon is required.
+> embedded leading icon is required.

package/docs/pages/forms/form-actions.md

@@ -53,4 +53,4 @@ container to apply one arrangement to every `.form-actions` inside it.
 > The sticky variant adds `--form-actions-sticky-block-offset`,
 > `--form-actions-sticky-padding`, and `--form-actions-sticky-inline-offset` —
 > see Sticky Actions. `.form-actions` is class-only and works inside or
-> outside the form — see Detached Actions.
+> outside the form — see Detached Actions.

package/docs/pages/forms/input-policy.md

@@ -88,4 +88,4 @@ Use `data-mask` when the input has a fixed shape. Tokens are `9` for a digit,
 ```
 
 Masks enforce shape, not domain validity. Use application validation when a date
-must reject impossible values such as `2026-13-40`.
+must reject impossible values such as `2026-13-40`.

package/docs/pages/forms/joined-controls.md

@@ -4,9 +4,9 @@
 
 ## Class reference
 
-| Class | Kind | Description |
-|---|---|---|
-| `.join` | Composition | Visually joins adjacent controls into a single unit. |
+| Class         | Kind        | Description                                                                     |
+|---------------|-------------|---------------------------------------------------------------------------------|
+| `.join`       | Composition | Visually joins adjacent controls into a single unit.                            |
 | `.join-addon` | Composition | Static prefix/suffix content such as currency symbols, units, or protocol text. |
 
 Add `.join` to the wrapper that groups the controls. Use `.join-addon` for static prefix/suffix content such as currency symbols, units, or protocol text. Action buttons inside the group should use `.btn`. The wrapper should still carry `role="group"` with a label for accessibility.
@@ -34,4 +34,4 @@ identifiable.
 ## CSS hooks
 
 - `--join-radius` — outer corner radius of the joined group. The per-corner
-  values of each child are derived from it.
+  values of each child are derived from it.