actual-css 0.7.0 → 0.9.0

package/docs/design-notes/popover-manual-poc.md

@@ -7,9 +7,10 @@ negative, which are the ones a future attempt would otherwise repeat.
 Question asked: can `popover="manual"` replace the DOM reparenting in
 `surface.js` without changing anything else?
 
-Answer: yes, and the branch demonstrates it. What blocks shipping is not the
-architecture; it is the browser contract. See
-[browser-support](browser-support.md).
+Answer: yes. The branch demonstrated it, the WebKit gate below closed it, and
+the migration checklist at the end has been executed — so this note is now also
+the record of what the checklist got wrong. The cost was a browser floor, not
+an architecture change; see [browser-support](browser-support.md).
 
 ## Branch
 
@@ -138,14 +139,13 @@ pass, it is no longer a transport swap and the claim does not hold.
 
 ## Go / no-go: WebKit verification
 
-Every measurement in this note was taken on Chromium — the browser test harness
+The measurements above were taken on Chromium — the browser test harness
 hardcodes `backend: "chrome"`. The floor's most notable step is Safari 17, so
-the transport has no measured evidence on the engine the raise actually buys.
-This is the one open technical gate on the migration, and the only item on the
-checklist below that is not already demonstrated.
+the transport needed evidence on the engine the raise actually buys. That was
+the one open technical gate on the migration. It is now closed.
 
-A permanent WebKit matrix is disproportionate for a decision taken once. One
-manual pass on a real Safari at the chosen floor, recorded here, is enough:
+A permanent WebKit matrix was disproportionate for a decision taken once. One
+manual pass on a real Safari at the chosen floor:
 
 ```text
 1. showPopover() / hidePopover() in manual mode
@@ -158,24 +158,66 @@ manual pass on a real Safari at the chosen floor, recorded here, is enough:
 8. the sheet scrim covers and intercepts the click
 ```
 
-Record the result in this section:
+`demo/templates/popover-transport.html` is that pass, scored by the page. It
+loads no Actual JavaScript and measures the platform subset above, so it
+answers on `master` without checking the branch out. Scenarios 1–6 run
+unattended; 7 and 8 need a real gesture. It scores 8/8 on Chromium and
+reproduces the findings above, `::backdrop` included — so a deviation on WebKit
+is the engine, not the bench.
+
+### Result — gate passed
 
 ```text
 Verified manually on:
-  Safari __._ / macOS __
-  iOS Safari __._ / iOS __      (if reachable)
-Date: ____-__-__
-Scenarios: _/8 passed
+  iOS Safari 17.0 / iOS 17.0        8/8 passed
+  Safari 17.3 / macOS unrecorded    8/8 passed
+Date: 2026-09-04
 ```
 
-Scenario 5 deserves the most attention. On Chromium the native top layer solved
-cleanly the problem that motivated `getSurfaceRoot()` in the first place — a
-modal dialog inerts the rest of the document — and that result is what makes
-the transport worth making mandatory. Scenario 2 is the second: the old
-transport used `[hidden]`, which `isElementVisible()` reads in its first
-branch, and the migration shifts the guard onto `checkVisibility()` with
-`getClientRects()` behind it. Which branch actually runs depends on what the
-bottom of the new floor implements, and the third has never been exercised.
+iOS 17.0 is the bottom of the proposed floor, measured rather than inferred.
+The desktop score is the union of two page loads on one engine, the iOS score a
+single session at 390×745; a second iOS pass at 341×651 reproduced everything
+but scenario 7, whose assertion the bench has since corrected — see below.
+Safari freezes its macOS UA token at `10_15_7`, so the desktop host version is
+not recoverable from a report. macOS Safari 17.0–17.2 stay inferred, on the
+same WebKit that iOS 17.0 exercised.
+
+Scenario 7 ran through the synthetic fallback on both iOS passes: iOS fires no
+`contextmenu` from a long press, so that event path is unexercised on the port
+where it matters most, and the scenario attests placement only.
+
+Both ports report the same subset: the four runtime primitives and
+`selector(:popover-open)` present; `checkVisibility()`, `overlay`,
+`transition-behavior: allow-discrete` and `@starting-style` absent. That
+matches WebKit's published timeline — Popover in 17.0, the rest in 17.4 and
+17.5 — which is corroboration that the bench measures rather than guesses.
+
+Four results carry consequences:
+
+**Scenario 5 passes on both ports**, which is what makes the transport worth
+making mandatory: the native top layer solves on WebKit the problem that
+motivated `getSurfaceRoot()` in the first place, on a 390px phone included.
+
+**Scenario 2 passes on the fallback branch.** `checkVisibility()` does not
+exist below Safari 17.4, so `isElementVisible()` runs its `getClientRects()`
+branch at the floor — the branch that had never been exercised. It works, and
+it is load-bearing rather than dead.
+
+**`::backdrop` is weaker on WebKit, not stronger.** Author `pointer-events` on
+an open popover's backdrop still computes to `none`, the native backdrop still
+lets the pointer through, and an Actual scrim element still absorbs it,
+confirmed with a real tap. The one thing `::backdrop` did well on Chromium —
+resolving a custom property scoped to an ancestor of the panel — resolves to
+nothing on WebKit. The scrim stays an Actual element on both engines, and not
+by Chromium's accident.
+
+**An overflowing top-layer box is adjusted differently.** Asked to place a
+panel at a point that would push it past the right edge of a 341px viewport,
+iOS Safari 17.0 offset it by 11px; Chromium at the identical viewport and
+overflow offset it by 0. Not a gate: `surface.js` positions through floating's
+`shift` middleware with `shiftPadding: 4`, so it never asks for such a point
+and measures the rendered rect afterwards. The bench now picks a point that
+fits, so scenario 7 measures placement rather than the UA's correction.
 
 ## Changelog framing for the raise
 
@@ -202,7 +244,7 @@ For the release that raises Minimal. Items 4–7 are scaffolding built for a flo
 that will no longer exist; a gate outliving its reason is silent dead weight, so
 they belong here rather than being found later.
 
-1. Pass the WebKit verification above and record it. This is the go/no-go.
+1. WebKit verification — done, 8/8 on Safari 17.3, recorded above. Cleared.
 2. Raise Minimal to the required subset above. The justification is the defect
    and the transparent migration, not a download count: npm figures conflate
    CI, bots, caches and the author, and say nothing about the end browser.
@@ -213,11 +255,16 @@ they belong here rather than being found later.
    `scrollbar-gutter`, `scrollbar-width`, `scrollbar-color`) as Minimal
    baseline and drop their `check-compat` entries.
 5. Remove the `@supports selector(:popover-open)` gates in `flyout.css` and
-   `tooltip.css`.
+   `tooltip.css`. Those only: the `@supports (transition-behavior:
+   allow-discrete)` gate and the `@starting-style` blocks stay, since neither
+   is in the floor — Safari 17.4 and 17.5.
 6. Remove the two `popover` entries from `check-compat`'s feature table.
 7. Remove the associated `compat-ok:` pragmas, and `hasPragma()` itself if
    nothing else consumes it.
-8. Move `surface.js` to the manual transport, with no fallback branch.
+8. Move `surface.js` to the manual transport, with no fallback branch. This
+   does not reach `isElementVisible()` in `focus.js`: `checkVisibility()` is
+   Safari 17.4, so its `getClientRects()` fallback is the branch that runs at
+   the floor and must stay.
 9. Drop `test.failing` from the reparenting tests in
    `tests/browser/surface-inherited-context.test.js`, keeping the assertions.
 10. Update [surface-reparenting](surface-reparenting.md) from a known limitation
@@ -229,6 +276,39 @@ the transport changes — but nothing forces step 9. The test file points at the
 note, and the note points back here; that is as far as documentation can close
 the loop.
 
+### Executed — where the checklist was wrong
+
+All ten items are done. Three needed correcting on contact, and the corrections
+are worth more than the items were.
+
+**Item 4 rested on a false premise.** Raising Minimal does not make a CSS
+capability baseline, because Minimal is the *JavaScript* floor: a Degraded
+browser runs no supported runtime and still receives every stylesheet, so CSS
+owes its fallbacks that far down. `check:compat` now states the Degraded floor
+and keeps the entries, relabelled — dropping them would have removed the only
+machine check that keeps those fallbacks honest. Two of the six features were
+also mistagged before the migration: `scrollbar-gutter`, `scrollbar-width` and
+`scrollbar-color` land in Safari 18.2, above every tier including Recommended,
+so they are `optional` rather than absorbed. The same relabelling moved `:has()`
+and `@container` to `minimal` — the new floor genuinely does absorb them, which
+the checklist missed because it enumerated the Intermediate tier's features
+instead of reading the new floor.
+
+**Item 7 cost more than it removed.** `hasPragma()` had no consumer left once
+the popover entries went, so it is gone — and with it five tests, including the
+one recording that prose must not excuse an optional structural use. The
+discovery is now a comment in `check-compat.js` naming the pragma to reinstate.
+Deleting a guard whose only proof of value was its own test is the trade this
+item asked for; it should be re-read before the next optional structural
+capability arrives.
+
+**Item 8 left one author-facing decision open.** The POC preserved an author's
+own `popover` value and only defaulted a missing one. `prepareSurface()` now
+writes `manual` unconditionally: any other mode hands the UA a dismissal policy,
+and native light dismiss closes on outside clicks only — which silently defeats
+`data-flyout-auto-close="false"`. The old `[popover]` conflict warning had
+caught that case; overwriting the attribute is what replaces it.
+
 ## What was deliberately left out
 
 Not attempted, and not because it looked hard:

package/docs/design-notes/surface-reparenting.md

@@ -1,12 +1,12 @@
-# Surface reparenting breaks inherited presentation context
+# Surface reparenting broke inherited presentation context
 
-Known defect, present on the current Minimal floor. Tracked separately from
-Popover adoption on purpose: Popover is the likely cure, but the defect exists
-now and needs to be understood on its own terms.
+Resolved. The record is kept because the defect had no generic repair, three of
+the obvious ones look right and are wrong, and the transport that fixed it is
+the reason the JavaScript floor sits where it does.
 
-## What happens
+## What used to happen
 
-`surface.js` moves an open surface out of its place in the document:
+`surface.js` moved an open surface out of its place in the document:
 
 ```text
 getSurfaceRoot()   → nearest <dialog>, else body
@@ -14,15 +14,15 @@ mountSurface()     → root.append(panel)
 restoreSurface()   → put it back once the exit transition ends
 ```
 
-The move exists for good reasons — it escapes `overflow` clipping on any
-ancestor and sidesteps `z-index` stacking. But it also takes the panel out of
-every scope that reached it *by inheritance*. The panel is styled by one set of
-ancestors while it is closed, and by a different set from the moment it becomes
+The move existed for good reasons — it escaped `overflow` clipping on any
+ancestor and sidestepped `z-index` stacking. But it also took the panel out of
+every scope that reached it *by inheritance*. The panel was styled by one set of
+ancestors while closed, and by a different set from the moment it became
 visible.
 
 Actual leans on inheritance deliberately: theme islands, density, `.inverted`,
 and the custom properties an application scopes to its own containers all
-travel that way. So this is not one bug about themes. It is the same bug in as
+travel that way. So this was not one bug about themes. It was the same bug in as
 many forms as there are inherited contexts.
 
 ## Measured
@@ -38,23 +38,24 @@ click that opens it:
 | app-scoped `--app-accent` | `rgb(1, 2, 3)`                           | *(unset)*            |
 | `.sm` inside a `<dialog>` | `--control-size: 2rem`                   | `2.375rem`           |
 
-Every context breaks. Three consequences are worth stating plainly:
+Every context broke. Three consequences were worth stating plainly:
 
-- The theme case is visible, not theoretical: a flyout inside a dark island
-  turns light at the moment it opens.
-- The density case is measurable: menu rows render 38px instead of the 32px the
-  scope asked for.
-- The dialog case shows the `getSurfaceRoot()` special case does not help. The
-  panel does land inside the dialog, and still loses any scope sitting between
+- The theme case was visible, not theoretical: a flyout inside a dark island
+  turned light at the moment it opened.
+- The density case was measurable: menu rows rendered 38px instead of the 32px
+  the scope asked for.
+- The dialog case showed the `getSurfaceRoot()` special case did not help. The
+  panel did land inside the dialog, and still lost any scope sitting between
   that dialog and its trigger. Choosing a nearer root loses less context; it
   does not preserve it.
 
-Locked by `tests/browser/surface-inherited-context.test.js`, whose assertions
-describe the contract Actual owes and are marked `test.failing` until the
-transport stops reparenting.
+`tests/browser/surface-inherited-context.test.js` holds those assertions and
+now passes against the shipped transport.
 
 ## Why the obvious repairs are wrong
 
+Still wrong, and still tempting — this section is the reason the note is kept.
+
 **Copying `data-theme` onto the moved panel.** Fixes the one symptom that was
 noticed and leaves the other four broken. It also turns an inherited contract
 into an enumerated one, so every future scope has to be added to a list.
@@ -67,13 +68,13 @@ would also freeze values that should stay live.
 **Mounting to a nearer root.** The dialog row above is the experiment: it
 reduces the damage without addressing the cause.
 
-The cause is that the panel is moved at all. The repair is a transport that
+The cause was that the panel was moved at all. The repair is a transport that
 promotes the element without relocating it.
 
-## The actual repair
+## The repair, as shipped
 
 A native popover renders in the top layer while staying exactly where the
-author put it in the DOM. That removes the reason to reparent, and with it the
+author put it in the DOM. That removed the reason to reparent, and with it the
 whole mechanism:
 
 ```text
@@ -86,37 +87,45 @@ restoreSurface()
 `popover="manual"` is the mode that fits: it supplies the top layer and nothing
 else, so `surface.js` keeps its dismissal policy, Escape ordering, focus
 restoration and placement orchestration unchanged. See
-[platform-alignment](platform-alignment.md) for the responsibility split and
-the criteria a component must meet before adopting Popover, and
-[browser-support](browser-support.md) for which tier guarantees it.
+[platform-alignment](platform-alignment.md) for the responsibility split, and
+[browser-support](browser-support.md) for the floor it requires.
+
+Adopting it behind a capability branch was rejected rather than overlooked: the
+fallback path *is* the defect, so a branch would have kept the bug alive for
+exactly the browsers it was written to serve. Raising the floor was the cheaper
+half of the decision.
 
-That change is gated on Popover being available across Minimal. It is not
-available there today, and adopting it behind a capability branch would keep
-the reparenting code alive for the fallback path — so the defect would remain
-for exactly the browsers the branch was written to serve.
+## The contract now
 
-## Until then
+> A surface managed by `surface.js` is presented in its trigger's context. A
+> scoped theme, density, or custom property reaches an anchored surface through
+> inheritance, open or closed.
 
-The honest interim position is a documented limitation, not a patch:
+The two workarounds this note used to recommend — declaring the scope on `body`
+or on the panel itself — are no longer needed and can be removed from
+application code.
 
-> A surface managed by `surface.js` is presented in the document's own context,
-> not its trigger's. Do not rely on a scoped theme, density, or custom property
-> reaching an anchored surface through inheritance.
+`tooltip.js` reached the same contract later, and for the same reason: it moved
+an explicit tooltip to the dialog or the body on first hover, which is this
+defect in a second component. An explicit tooltip now stays where it was
+written and inherits accordingly.
 
-Applications that need a scoped surface today have two workarounds, both of
-which put the scope where the panel lands rather than where it starts: declare
-the scope on an ancestor that survives the move (`body`, or the dialog), or
-carry the scope on the panel element itself.
+A generated tooltip (`data-tooltip="text"`) is deliberately outside the
+contract. Actual creates that element, so Actual places it, and it goes to
+document level rather than beside the trigger — a generated sibling would take
+`.join > :last-child` from a trigger that ends a group, since structural
+pseudo-classes are DOM-based and `position: fixed` does not exempt an element
+from them. The shorthand therefore promises no inheritance; the explicit form
+is the one to use when local context matters.
 
 ## Experiment
 
-A branch has demonstrated the repair without changing any other contract:
-[popover-manual-poc](popover-manual-poc.md) records what it measured, what it
-refuted, and the checklist for the release that adopts it. Read that before
-attempting this again — it also holds the negative results.
+[popover-manual-poc](popover-manual-poc.md) records what the branch measured,
+what it refuted, and the checklist the migration followed. Read that before
+touching the transport again — it holds the negative results, `::backdrop`
+included.
 
 ## Review trigger
 
-Revisit when Popover is guaranteed across Minimal, when a further inherited
-context is found to break, or if a transport that preserves DOM ancestry
-becomes available by another route.
+Revisit if a further inherited context is found to break, or if a transport
+that promotes without the top layer becomes available by another route.

package/docs/design-notes/tooltip-coordinate-space.md

@@ -0,0 +1,132 @@
+# Tooltip coordinate space, and what an unpositionable tip means
+
+Two changes to `tooltip.js`, both consequences of one question: what a floating
+element's coordinates are relative to, and what it means when there are none.
+
+## The lag
+
+Scrolling is asynchronous. The compositor can move the page before any script
+runs, so a `position: fixed` element written from JavaScript is always one frame
+behind the content it is attached to. `autoUpdate()` coalesces to a frame by
+design, which is correct for the work and still visible as a wobble on touch
+devices, where scrolling is driven off the main thread.
+
+`@lekoala/floating` 0.2.0 adds `coordinateSpace: "document"`: the same viewport
+measurement, written as `left`/`top` plus the page scroll, for an absolutely
+positioned box whose containing block is the initial one. The browser then
+carries the element with the page and there is nothing to correct.
+
+Two candidates were rejected before this one:
+
+- **Popper's `strategy: "absolute"`.** Relative to a *containing block*, not to
+  the reference — which means resolving the offset parent, its borders, its
+  scroll offsets, its transforms, and its own nested scrollers. That is the
+  machinery `floating` exists without.
+- **Repositioning synchronously on scroll** instead of at the next frame.
+  Cheaper to write, and it only shortens the lag; it cannot remove it, because
+  the scroll that moved the page never reached the main thread in time.
+
+## The containing block is not a problem here
+
+Document coordinates assume the initial containing block. A tip is an open
+popover, so it is in the top layer, where an absolutely positioned box resolves
+against the initial containing block whatever its ancestors do. Measured in
+Chrome, writing viewport point `(200, 300)` in document coordinates at
+`scrollY: 640` and reading the resulting rect back:
+
+| Ancestor of the tip  | Rect      |
+| -------------------- | --------- |
+| `position: relative` | `200,300` |
+| `transform`          | `200,300` |
+| `filter`             | `200,300` |
+| `contain: paint`     | `200,300` |
+| `dialog` (`show()`)  | `200,300` |
+| `dialog` (modal)     | `200,300` |
+
+So where the tip lives never enters into it, and the placement contract — an
+explicit tip stays where the author wrote it, a generated one goes to the
+dialog subtree or the body — is untouched.
+
+## The trigger is the problem
+
+Document coordinates are only right while the *trigger* scrolls with the page.
+Against a trigger that does not, the browser carries the tip away on every
+scroll and the next frame snaps it back: a worse artefact than the lag it
+removes, and a real one — `.fab`, `.status-bar` and `.drawer` are fixed,
+`.navbar`, `.topbar`, `.app-nav` and `.form-actions` are sticky.
+
+`isViewportAnchored()` therefore walks up from the trigger for a computed
+`fixed` or `sticky`, and separately asks for `dialog:modal, :popover-open`,
+which the walk cannot see: a modal dialog computes `position: absolute` and is
+laid out against the viewport by the top layer. Sticky counts even while
+unstuck, because nothing in the DOM changes when it becomes stuck.
+
+The modal case is the one worth naming, because a modal dialog does **not**
+stop the page from scrolling behind it — measured, wheel included. A trigger
+inside one is as viewport-anchored as a fixed bar, and keeps `position: fixed`.
+
+## The scrollable overflow case
+
+An absolutely positioned box in the top layer joins the document's scrollable
+overflow; a fixed one never does. The scrollable height becomes the greater of
+the content's own bottom and the tip's, and the threshold is exact: walking a
+20px tip down a 2000px document in Chrome, `scrollHeight` reads 2000 for every
+tip bottom through 2000, and the tip's own bottom from 2001 on.
+
+A tip past the end of the content therefore raises the scroll maximum while it
+is up, and hiding it clamps back any position only that tip made reachable —
+the page appears to jump upwards.
+
+Placement is what prevents this, not anything in `tooltip.js`. Flip and shift
+put the tip inside the viewport, which at any scroll position is inside the
+document, so only overflow the engine explicitly accepts — a tip it could not
+fit anywhere — reaches past the end of the content. Nor does the demote and
+promote path add a case: the coordinates are a document point, so a tip that
+was inside the document when it went down is still inside it when it comes
+back up, exit fade included.
+
+It is a failure mode to test for, then, not a standing cost of document
+coordinates. If the page ever does jump, `documentElement.scrollHeight` across
+a show and a hide separates this from everything else that moves a page: it
+moves with the tip here, and holds steady for anything else.
+
+## `false` is a geometry answer
+
+`reposition()` returns `false` when it cannot place the element, an anchor
+outside the boundary included. `tooltip.js` used to read that as the end of the
+interaction and call `hideTip()`, which stopped position tracking.
+
+On a touch device that loses the tooltip for good: tap a trigger, it takes
+focus and the tip appears; scroll the trigger past the boundary and the tip is
+torn down; scroll back and nothing is watching any more. Tapping again does not
+help either — the trigger is already focused, so no `focusin` fires, and a
+repeat tap on the same element fires no `mouseover`.
+
+So the runtime now keeps two states. `wanted` is what the interaction asks for
+and only `hideTip()` clears it; `visible` is what is promoted. An
+unpositionable tip is demoted and stays tracked, and the next tick that can
+place it brings it back up.
+
+`floating` was deliberately left out of this: no `{ positioned, reason }`
+return, no option. Its README already documents the pattern — a failed
+positioning may be temporary without `autoUpdate()` being stopped.
+
+## Surfaces share geometry, not lifecycle
+
+Element-anchored surfaces use the same coupled coordinate and CSS position mode
+as tooltips. Point-positioned surfaces stay fixed because their `x` and `y` are
+client coordinates. A nested scroll container remains a separate boundary:
+document coordinates move natively with page scroll, while container scroll
+still waits for `autoUpdate()` to correct the placement.
+
+A surface that fits inside its boundary must not create scrollable overflow
+merely because it uses document coordinates. This is not a guarantee for an
+arbitrarily large custom surface: the positioner deliberately accepts overflow
+when no placement can physically contain it.
+
+`surface.js` still closes on `false`, and that stays a separate decision. A
+flyout close restores focus, fires an event and releases an Escape entry;
+hiding one while its trigger is off-boundary would leave a panel the user
+cannot see holding all three. The prerequisite named in
+[css-anchor](css-anchor.md) — "an out-of-view surface hides instead of closing"
+— is a component decision, and it has been taken for tooltips only.

package/docs/design-notes/widget-primitives.md

@@ -9,7 +9,7 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 | Discovery, lifecycle, cleanup      | `enhance`     | `actual-css/js/enhance`     |
 | Per-document LIFO Escape dismissal | `escape`      | `actual-css/js/escape`      |
 | Positioning, flip and shift        | `floating`    | `@lekoala/floating`         |
-| Open/close, sheet, backdrop, focus | `surface`     | `actual-css/js/surface`     |
+| Open/close, dismissal, focus       | `surface`     | `actual-css/js/surface`     |
 | Directional item lookup            | `keys`        | `actual-css/js/keys`        |
 | Menu-item vocabulary               | `menu`        | `actual-css/js/menu`        |
 | Focusable lookup, visibility       | `focus`       | `actual-css/js/focus`       |
@@ -22,7 +22,7 @@ The JS runtime doubles as a primitive kit for building custom widgets.
 
 The named exports each module carries:
 
-- `enhance` — `enhance`, `registerEnhancement`
+- `enhance` — `enhance`, `registerEnhancement`, `applyEnhancement`
 - `escape` — `registerEscapeDismissal`
 - `floating` — `autoUpdate`, `reposition`, `repositionAt`, plus
   `--available-height` and `data-placement`
@@ -89,12 +89,12 @@ an inline autocomplete that should survive an outside click).
 
 ```
 enhance
-surface   (Escape, outside click, focus restore, sheet mode)
+surface   (Escape, outside click, focus restore)
 floating
 keys
 ```
 
-Less code. Inherits the runtime's dismissal semantics and mobile sheet. Use for
+Less code. Inherits the runtime's dismissal semantics. Use for
 anything that behaves like a popup.
 
 > A `[role="listbox"]` surface with `[role="option"]` children gets no key handling and
@@ -130,6 +130,9 @@ state to style or ignore.
 
 ## Honest gaps
 
+- No nested surfaces — one Actual surface is open per document, and opening one
+  closes the rest. A widget that needs a second level owns its own popup
+  (composition A above).
 - No typeahead helper — filter, debounce, render are author concerns.
 - No `aria-activedescendant` helper — the author manages the composite-widget pattern.
 - No virtual-list support.

package/docs/pages/components/accordion.md

@@ -5,7 +5,8 @@
 - Use native `<details>` and `<summary>` for collapsible content.
 - Use the `name` attribute for exclusive accordions.
 - Supports any valid body element (`div`, `p`, `ul`, ...).
-- The toggle marker color is customizable with `--accordion-marker-color`; the marker icon comes from the shared `--icon-chevron` token.
+- Three container treatments: the default common shell, `.flush` (bare separators, for embedding inside an existing surface), and `.separated` (independent items).
+- The toggle marker color is customizable with `--accordion-marker-color`; it reinforces to the summary text color on hover, and the marker icon comes from the shared `--icon-chevron` token.
 
 ```html demo
 <div class="accordion">
@@ -34,6 +35,44 @@
 </div>
 ```
 
+## Variants
+
+The default builds one raised shell around the whole group. `.flush` and `.separated` only change that chrome — they are integration modes between the component and its container, not decorative skins.
+
+- **`flush`** — the ambient box disappears and only the item separators remain, so the group sits edge to edge inside a surface that already exists: a card, a drawer, a page section. A FAQ list without a box inside a box.
+
+```html demo
+<div class="accordion flush">
+  <details open>
+    <summary>Flush keeps just the separators</summary>
+    <p>No shell: embed the group in a card, drawer, or page section.</p>
+  </details>
+
+  <details>
+    <summary>Edge to edge</summary>
+    <p>The summary and panel follow the surrounding surface's own gutter.</p>
+  </details>
+</div>
+```
+
+- **`separated`** — each `<details>` becomes its own card, for groups of standalone items.
+
+```html demo
+<div class="accordion separated">
+  <details open>
+    <summary>Each item is its own card</summary>
+    <p>Standalone items share the same gap, border, radius, and raised surface.</p>
+  </details>
+
+  <details>
+    <summary>Still native details</summary>
+    <p>Exclusive <code>name</code> groups and per-item icons work exactly as in the base component.</p>
+  </details>
+</div>
+```
+
+The accordion owns its disclosure marker; the trigger content belongs to the markup. Item accents, per-item shadows, an underlined trigger label, and alternative markers stay application recipes, not framework variants.
+
 ## Exclusive groups
 
 ```html demo
@@ -77,4 +116,4 @@ The end marker is a shared token-based chevron; swapping it for a local icon is
 ## CSS hooks
 
 - `--accordion-radius` — outer corner radius.
-- `--accordion-marker-color` — color of the end marker; forced-colors mode overrides it to `CanvasText`.
+- `--accordion-marker-color` — color of the end marker; it reinforces to the summary text color on hover, and forced-colors mode overrides it to `CanvasText`.