actual-css 0.9.2 → 0.11.0

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

@@ -57,10 +57,11 @@ than the registration root, without crossing shadow boundaries.
 
 > `data-enhance` is a generic opt-in for when HTML does not already provide an unambiguous one.
 
-- **A token** is for a root controller — a behavior that owns a subtree and manages
-  descendants (tabs, flyout, scrollspy, validation).
-- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously the opt-in
-  and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
+- **A token** is for a named behavior whose opt-in carries no configuration,
+  whether it owns a subtree or enhances one leaf (tabs, flyout, range,
+  scrollspy, validation).
+- **A self-describing `data-*`** is for a leaf whose attribute is simultaneously
+  the opt-in and the configuration (`data-tooltip`, `data-mask`, `data-filter`,
   `data-context-menu`).
 - **Elements that are their own opt-in** need nothing (`<dialog>`).
 
@@ -72,6 +73,13 @@ than the registration root, without crossing shadow boundaries.
 on the same root throws; `disconnect()` releases the name; re-registration
 after disconnect is allowed; the same token on a different root is independent.
 
+Named registrations share one `[data-enhance]` discovery gate per root: however
+many behaviors are registered, the observer queries that single selector and
+each registration matches its own `[data-enhance~="name"]` against what it finds.
+`enhance()` records share the same observer and lifecycle with their arbitrary
+selectors. Behaviors on one element start in no guaranteed order and must not
+depend on each other.
+
 `enhance()` stays generic and unguarded — registering the same selector twice
 creates two independent records that both run.
 
@@ -95,8 +103,8 @@ those registrations explicitly.
 
 - Use a command for an immediate trigger-to-current-target action. Commands
   resolve the DOM at event time and do not own element lifecycle.
-- Use `registerEnhancement()` for an opted-in controller that owns listeners or
-  state for a subtree.
+- Use `registerEnhancement()` for a named, opted-in behavior that owns listeners
+  or state for a subtree or leaf.
 - Use `enhance()` for a self-describing leaf behavior that needs connection and
   cleanup lifecycle without a named token.
 - Prefer delegation when no persistent per-element state is required.
@@ -145,7 +153,8 @@ of the contract itself.
 | ------------ | ------------------------------------------------ | ------------------- |
 | `tabs`       | Tab panel switching, arrow-key navigation        | `.tabs`             |
 | `flyout`     | Trigger → panel positioning, open/close          | `.flyout`           |
+| `range`      | Fill share and named-value synchronization       | `.range`            |
 | `scrollspy`  | Scroll-driven nav highlighting                   | `.scrollspy`        |
 | `validation` | Form validation, focus management, server errors | `.needs-validation` |
 
-Four tokens. Everything else stays self-describing.
+Five tokens. Everything else stays self-describing.

package/docs/design-notes/forced-colors.md

@@ -30,6 +30,12 @@ an essential shape, state, or affordance.
 
 ## Pattern: custom property + single override
 
+The hook-only form below is fine until an application overrides the hook: the
+override sits at the same specificity, loads after the framework, and wins the
+variable — leaving a non-system fill the browser then remaps to `Canvas`. For
+a masked marker, write the forced value on the property itself so no hook
+override can take it away (accordion) — same for range track/thumb fills.
+
 ```css
 .component {
   --cmp-marker-color: var(--text-muted);
@@ -48,6 +54,11 @@ an essential shape, state, or affordance.
   .component {
     --cmp-marker-color: CanvasText;
   }
+
+  /* Masked markers: pin the property, not just the hook. */
+  .component::marker {
+    background-color: CanvasText;
+  }
 }
 ```
 
@@ -104,7 +115,7 @@ remapping is perfect:
 
 - `.card` — `background: Canvas`, `color: CanvasText` are already the defaults
 - `.flyout` / `.menu` — `Canvas`/`CanvasText` for content, `ButtonText` for borders
-- `.accordion` / `.breadcrumb` — pure remapping gets everything right
+- `.breadcrumb` — pure remapping gets everything right
 - `.status-bar` — `CanvasText` on `Canvas` background
 
 The only forced-colors rules that should remain after a full audit are the ones

package/docs/design-notes/naming.md

@@ -47,7 +47,7 @@ never about opting in.
 - **Base** (`utilities/base.css`) is a curated set of common ergonomic
   shortcuts (`.overflow-auto`, `.gap-none`, `.text-nowrap`, `.px`, `.py`).
 - **Extra** (`utilities/extra.css`) uses explicit property/value names
-  (`.overflow-hidden`, `.padding-context`, `.white-space-normal`).
+  (`.overflow-hidden`, `.padding-context`, `.flex-nowrap`).
 
 Call them base and extra, after the files. "Optional" is the wrong word for
 either: it reads as a layer an author has to opt into, which is true of every

package/docs/design-notes/platform-alignment.md

@@ -386,12 +386,16 @@ Prefer native controls and progressive styling.
 
 The concrete signal to watch is `appearance: base-slider` with `::slider-track`, `::slider-fill`, and `::slider-thumb`. Checked on Chrome 152: `CSS.supports('appearance', 'base-slider')` and `CSS.supports('selector(::slider-fill)')` are both false, so there is nothing to enhance against yet.
 
-Until then, `.range` intentionally omits filled tracks and tick marks. Both are reachable today only through techniques Actual should not take on:
+Until then, `.range` intentionally omits tick marks, and its filled track comes
+from the `range` enhancement (one `--range-progress` share driving a
+track gradient) rather than engine-specific pseudo-elements:
 
-- The Chromium filled-track trick needs `overflow: hidden` on the runnable track plus a large `box-shadow` on the thumb. It collides twice with `range.css`: the thumb is wider than the track and would be clipped, and the focus ring already owns the thumb's `box-shadow`.
-- CSS-only tick marks need a step count duplicated out of `min`/`max`/`step` into a custom property, so markup carries the same contract twice and the two can diverge. `datalist` cannot carry it either: its native ticks are part of the appearance that `appearance: none` removes, and no engine renders `<option label>` for a range.
+- The Chromium filled-track trick needs `overflow: hidden` on the runnable track plus a large `box-shadow` on the thumb. It collides twice with `range.css`: the thumb is wider than the track and would be clipped, and the thumb's `box-shadow` is already owned by the focus ring.
+- CSS-only tick marks need a step count duplicated out of `min`/`max`/`step` into a custom property, so markup carries the same contract twice and the two can diverge. `datalist` cannot carry it either: its native ticks are part of the appearance that `appearance: none` removes, and no engine renders `<option label>` for a range — Actual reads the datalist as data only.
 
-When the base-slider parts become interoperable, this becomes a `@supports` enhancement in the shape of `custom-select.css` — less engine-specific CSS, not more.
+When the base-slider parts become interoperable, the `--range-progress`
+calculation becomes a `@supports` enhancement in the shape of
+`custom-select.css` — less engine-specific CSS, not more.
 
 ### Navigation
 

package/docs/design-notes/rich-text.md

@@ -0,0 +1,61 @@
+# Rich text: three levels and why a package demos level 2
+
+Editing text and editing a document are different problems with different
+costs. Actual draws the line at the document boundary, in three levels:
+
+```text
+1. TEXTAREA (native)
+   text, autosize, actions row, plain-text caret helpers
+   → the composer pattern: demo/templates/composer.html
+
+2. HOSTED RICH-TEXT PACKAGE (integration)
+   bold / italic / lists / links / quote, undo, paste cleanup,
+   structured @mentions, / snippets
+   → the rich-text recipe: demo/templates/rich-text.html + @lekoala/rich-text
+
+3. STRUCTURED DOCUMENT ENGINE (integration, heavier)
+   custom document nodes, annotations, collaborative state
+   → no demo; the bridge contract from level 2 applies unchanged
+```
+
+Level 1 stays a real `<textarea>`: form value, IME, undo, mobile,
+accessibility, validation. `contenteditable="plaintext-only"` buys nothing over
+it and loses the native form control, so the framework does not use it. The
+Markdown round-trip some engines offer is still beta upstream and is not the
+storage contract.
+
+## Why a package for the level-2 demo
+
+The demo exists to prove the bridge (tokens, pressed states, focus, invalid,
+composer chrome), not the engine. Owning the toolbar, sanitizer, roving focus
+and lifecycle inside the demo meant Actual did involuntarily much of the
+editor's job. Extracting that into `@lekoala/rich-text` restored the boundary:
+
+```text
+Actual CSS         presentation, tokens, composer chrome, dialogs, validation
+@lekoala/rich-text textarea enhancement, Squire, sanitization, toolbar
+                   semantics + keyboard, links, mentions, suggestions,
+                   form/reset/readonly/disabled, lifecycle
+application        people lookup, templates, attachments, dictation, send
+```
+
+`@lekoala/rich-text` owns the editor UI semantics; Actual owns its visual
+language. Squire is an implementation detail of the integration package: it
+owns selection, editing, paste normalisation and undo/redo, while the package
+owns the product-facing contract around it (progressive enhancement of a real
+`<textarea>`, mandatory sanitization, accessible generated UI, lifecycle and
+cleanup). HTML stays the source of truth, which keeps the storage decoupled
+and the engine choice reversible.
+
+## What was deliberately not demoed
+
+- A second engine demo would prove nothing more about the bridge, and one
+  candidate changes fundamental choices between minor versions — a pinned demo
+  would rot. Spikes belong in `tmp/`, not `demo/`.
+- Plain-text caret helpers stay a textarea-level improvement at level 1.
+  Structured `@mentions` live at level 2 because they are sanitized, atomic
+  entities inserted as HTML — the demo's Snippet/Mention buttons reuse the
+  same suggestion seam as `/` and `@`, so one capability keeps two surfaces
+  without duplicating its logic.
+- Syntax highlighting inside inputs is a search-DSL concern, not a composer
+  concern; layering it onto a textarea rebuilds a fake rich editor.

package/docs/design-notes/steps.md

@@ -630,8 +630,8 @@ so an author who lowers `--step-min` below `--step-size` narrows the scroll
 budget without collapsing items behind their own markers.
 
 The cost of scrolling is that clipping happens at the padding edge, and a focus
-ring is drawn outside its element's border box — `--focus-outline` is two
-border-widths wide at `--focus-outline-offset`, so 4px past a label that sits
+ring is drawn outside its element's border box — `--focus-outline` is
+`--focus-ring-width` wide at `--focus-outline-offset`, so 4px past a label that sits
 flush with the bottom of a stacked row. A navigable row therefore reserves
 exactly that much `padding-block`, gated on `.steps-horizontal:has(a[href])`. An
 informational stepper — the common case, with no ring to protect — keeps its

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

@@ -20,8 +20,8 @@ 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
+Actual leans on inheritance deliberately: theme islands, density, and the
+custom properties an application scopes to its own containers all
 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.
 
@@ -30,13 +30,12 @@ many forms as there are inherited contexts.
 Chrome, one `.flyout` per scope, values read off the panel before and after the
 click that opens it:
 
-| Scope                     | Closed                                   | Open                 |
-| ------------------------- | ---------------------------------------- | -------------------- |
-| `[data-theme="dark"]`     | `background: rgb(30, 26, 35)`            | `rgb(255, 255, 255)` |
-| `.sm`                     | `--control-size: 2rem`                   | `2.375rem`           |
-| `.inverted`               | `--ui-fg: light-dark(hsl(0 0% 100%), …)` | *(unset)*            |
-| app-scoped `--app-accent` | `rgb(1, 2, 3)`                           | *(unset)*            |
-| `.sm` inside a `<dialog>` | `--control-size: 2rem`                   | `2.375rem`           |
+| Scope                     | Closed                        | Open                 |
+| ------------------------- | ----------------------------- | -------------------- |
+| `[data-theme="dark"]`     | `background: rgb(30, 26, 35)` | `rgb(255, 255, 255)` |
+| `.sm`                     | `--control-size: 2rem`        | `2.375rem`           |
+| app-scoped `--app-accent` | `rgb(1, 2, 3)`                | *(unset)*            |
+| `.sm` inside a `<dialog>` | `--control-size: 2rem`        | `2.375rem`           |
 
 Every context broke. Three consequences were worth stating plainly:
 

package/docs/navigation.json

@@ -49,10 +49,12 @@
         "aura",
         "avatar",
         "badge",
+        "bleed",
         "breadcrumb",
         "button",
         "card",
         "chat",
+        "close",
         "dialog",
         "drawer",
         "data-list",
@@ -65,6 +67,7 @@
         "pagination",
         "progress",
         "rating",
+        "shimmer",
         "skeleton",
         "spinner",
         "steps",
@@ -78,6 +81,7 @@
         "overview",
         "controls",
         "combobox",
+        "rich-text",
         "labels",
         "floating-field",
         "states-and-sizes",

package/docs/pages/components/accordion.md

@@ -116,4 +116,58 @@ 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; it reinforces to the summary text color on hover, and forced-colors mode overrides it to `CanvasText`.
+- `--accordion-pad` — inset of the summary row and the panel. The panel relays it as `--surface-pad`, so a direct `.bleed` child of the panel reaches the item's sides and bottom corners (never the summary); `.flush` drops the inline half and the relay with it.
+- `--accordion-marker-color` — color of the end marker; it reinforces to the summary text color on hover. In forced-colors mode the marker is pinned to `CanvasText` on the property itself, so an application override of the hook cannot leave a `Canvas`-remapped fill.
+- `--accordion-marker-size` — edge length of the end marker.
+
+### Replacing the marker
+
+The marker is a masked box: `--accordion-marker-color` fills it and the chevron
+mask clips it to the glyph. A background, ring, or shadow set on it is clipped
+to the same silhouette, so a decorated marker — a chevron inside a pill — has
+to be a real element: hide the built-in one and put a
+`<span class="marker" aria-hidden="true"></span>` at the end of the summary. The
+pill is the span; the chevron is its pseudo-element, which reads the same color
+hook, so the hover reinforcement carries over. The forced-colors pin does not
+carry over through the hook — an application hook override at the same
+specificity loads after the framework and would win the variable — so the
+recipe repeats it on its own property:
+
+```css
+.accordion.custom-marker summary::after {
+  display: none;
+}
+
+.accordion.custom-marker .marker {
+  display: grid;
+  place-items: center;
+  margin-inline-start: auto;
+  padding: var(--space-10);
+  border-radius: 50%;
+  background: var(--surface-subtle);
+  transition: transform var(--duration);
+}
+
+.accordion.custom-marker .marker::before {
+  content: "";
+  inline-size: var(--accordion-marker-size);
+  block-size: var(--accordion-marker-size);
+  background-color: var(--accordion-marker-color);
+  -webkit-mask: var(--icon-chevron) center / contain no-repeat;
+  mask: var(--icon-chevron) center / contain no-repeat;
+}
+
+.accordion.custom-marker summary:hover .marker {
+  --accordion-marker-color: currentColor;
+}
+
+.accordion.custom-marker details[open] .marker {
+  transform: rotate(180deg);
+}
+
+@media (forced-colors: active) {
+  .accordion.custom-marker .marker::before {
+    background-color: CanvasText;
+  }
+}
+```

package/docs/pages/components/alert.md

@@ -5,7 +5,7 @@
 - Supports intent colors.
 - Supports longer text and lists.
 - Links inherit alert color by default.
-- Alerts are soft by default. Use `.surface` for neutral chrome with the intent only in the ink, `.solid` or `.outline` when the message needs stronger or quieter emphasis, and `.inverted` for an inverse surface.
+- Alerts are soft by default. Use `.surface` for neutral chrome with the intent only in the ink, `.solid` or `.outline` when the message needs stronger or quieter emphasis.
 - Use `<menu class="actions cluster">` for alert action lists.
 - Use `role="alert"` only when the alert is injected dynamically and should be announced.
 - Not a toast.
@@ -13,7 +13,7 @@
 - A title and a description are plain siblings: the alert owns the small space between its direct content blocks, so neither needs a wrapper. Nested content keeps its own rhythm — wrap several paragraphs in `.prose`, or a differently spaced group in `.stack`, when the message needs a rhythm of its own.
 - Alerts may include a decorative leading icon. Use `.alert-icon` on the icon element; the rest of the content flows into the remaining text column.
 - Use `.compact` or `.spacious` for density changes. The inline padding stays stable.
-- Use `.alert-dismiss` for a compact dismiss button. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions. It uses the shared `--icon-close` mask and the `--dismiss` runtime command — no icon font or custom JS.
+- Use a [`.close`](close.md) button to make the alert dismissible. It is a direct trailing child in standard alerts and lives inside `.alert-title` in admonitions; the alert makes it compact.
 
 Because alerts are soft by default, adding `.soft` to an intent (`.alert.soft.primary`,
 `.alert.soft.danger`, …) is a no-op: it already resolves to a soft version of that
@@ -26,14 +26,13 @@ itself needs to change, not `.soft`.
 | ---------------- | ----------- | ----------------------------------------------- |
 | `.alert`         | Component   | Inline status surface; soft by default.         |
 | `.alert-icon`    | Composition | Decorative leading icon, in the first column.   |
-| `.alert-dismiss` | Modifier    | Compact dismiss button.                         |
+| `.close`         | Composition | Dismiss button, in the last column.             |
 | `.alert-title`   | Composition | Admonition title bar; hosts the dismiss button. |
 | `.alert-body`    | Composition | Admonition body on the page surface.            |
 | `.callout`       | Variant     | Leading-edge flag; owns the border geometry.    |
 | `.admonition`    | Variant     | Tinted title bar, body on the page surface.     |
 | Shared intents   | Intent      | `.primary`, `.secondary`, `.success`, …         |
 | Shared variants  | Variant     | `.solid`, `.outline`, `.surface`.               |
-| `.inverted`      | Surface     | Inverse surface, any intent.                    |
 | Density contexts | Density     | Descendant rhythm; inline padding stays stable. |
 
 ## Basic usage
@@ -101,7 +100,7 @@ intent treatment when the color itself carries the meaning.
 
 ## Trailing action
 
-The grid pins `.alert-icon` and `.alert-dismiss` to the outer columns. A
+The grid pins `.alert-icon` and `.close` to the outer columns. A
 trailing link or button is content, not anatomy, so it lives in the text column:
 wrap the row in a `.cluster` and push the two ends apart. Same recipe as any
 split / spread row — there is no `.alert-action` class.
@@ -129,10 +128,6 @@ center.
     I'm a surface alert — theme chrome, intent in the ink
   </div>
 
-  <div class="alert inverted" role="alert">
-    I'm an inverted alert <a href="#">with a link</a>
-  </div>
-
   <div class="alert danger compact" role="alert">
     I'm an error in a compact context
   </div>
@@ -153,7 +148,7 @@ center.
 
 ## Dismiss
 
-Use `.alert-dismiss` to let a user remove an inline alert. The button is transparent at rest with a muted glyph; it works with any intent because it uses `currentColor` and reduced opacity. It relies on the runtime `--dismiss` command — no custom script.
+Add a `.close` button to let a user remove an inline alert. Inside an alert it is compact and at reduced opacity, and it follows the alert's ink with any intent. The runtime `--dismiss` command removes the alert — no custom script.
 
 ```html demo
 <div class="alert warning" id="warning-alert">
@@ -162,7 +157,7 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
   <p>Something needs your attention.</p>
 
   <button
-    class="alert-dismiss"
+    class="close"
     type="button"
     commandfor="warning-alert"
     command="--dismiss"
@@ -171,14 +166,14 @@ Use `.alert-dismiss` to let a user remove an inline alert. The button is transpa
 </div>
 ```
 
-In an admonition, place `.alert-dismiss` inside `.alert-title`; it rides the inline end of the title bar:
+In an admonition, place `.close` inside `.alert-title`; it rides the inline end of the title bar:
 
 ```html
 <div class="alert admonition warning" id="notice">
   <div class="alert-title">
     <span>Warning</span>
     <button
-      class="alert-dismiss"
+      class="close"
       type="button"
       commandfor="notice"
       command="--dismiss"
@@ -261,8 +256,7 @@ An admonition is a structured box with a tinted title bar, an optional icon, and
 - `--alert-pad-block` — block padding.
 - `--alert-font-size` — base font size.
 - `--alert-icon-size` — size of a leading `.alert-icon`.
-- `--alert-dismiss-size` — inline and block size of the `.alert-dismiss` button.
-- `--alert-dismiss-icon-size` — size of the dismiss glyph.
+- `--close-size` / `--close-icon-size` — the alert declares compact values for its `.close`; set them on the alert to change them.
 - `--alert-radius` — corner radius, when the default `--radius-lg` does not fit.
 - `--alert-border-inline-start-color` / `--alert-border-inline-start-width` — extension points for a callout-style colored flag on the leading edge instead of a uniform border.
 

package/docs/pages/components/aura.md

@@ -84,22 +84,22 @@ The frame color comes from an intent such as `.primary`, `.success`, or
 a neutral intent produces a neutral aura. Use a chromatic intent when you want
 a visibly luminous effect.
 
-Two hooks tune how loud the effect is. `--aura-intensity` scales both halos at
-once, resting and breathing alike, so the breath stays proportional at every
-setting; `--aura-duration` sets one full rotation of the accent, or one breath
-of the glow.
+The default is a thin lit line with a faint halo. Three hooks tune how loud it
+is: `--aura-width` sets the line, `--aura-intensity` scales both halos at once,
+resting and breathing alike, and `--aura-duration` sets one full rotation of
+the accent, or one breath of the glow.
 
 ```html demo
 <div class="cluster" style="gap: 2rem">
-  <span class="aura aura-glow primary" style="--aura-intensity: 0.4">
-    <span class="card" style="inline-size: 8rem">Muted</span>
+  <span class="aura aura-glow primary" style="--aura-intensity: 0">
+    <span class="card" style="inline-size: 8rem">Line only</span>
   </span>
 
   <span class="aura aura-glow primary">
     <span class="card" style="inline-size: 8rem">Default</span>
   </span>
 
-  <span class="aura aura-glow primary" style="--aura-intensity: 2">
+  <span class="aura aura-glow primary" style="--aura-width: 3px; --aura-intensity: 1">
     <span class="card" style="inline-size: 8rem">Loud</span>
   </span>
 
@@ -113,11 +113,10 @@ Keep exactly one direct child and set `--aura-radius` when its shape differs
 from the common button, card, alert, and badge shapes detected as a visual
 enhancement.
 
-The child must be opaque. The frame paints across the whole box and relies on
-the child to cover all but its edge, so a transparent child — an `.outline`
-alert, a `.ghost` button — is filled edge to edge with the frame color instead
-of framed by it. Give such a child a surface, or move the aura to an opaque
-wrapper around it.
+A transparent or translucent child — an `.outline` alert, a `.ghost` button, a
+glass surface — shows `--surface-opaque` beneath it, the theme's opaque
+neutral, rather than the frame color. On a differently painted band, give the
+child its own surface so it matches the band.
 
 ## CSS hooks
 
@@ -125,7 +124,7 @@ wrapper around it.
 - `--aura-width` — frame thickness.
 - `--aura-blur` — near halo blur; the far halo derives its own blur and its
   spread beyond the frame from this value, so one hook scales both.
-- `--aura-intensity` — multiplies both halo opacities, resting and breathing.
+- `--aura-intensity` — multiplies both halo strengths, resting and breathing.
   It does not touch the frame itself, which stays a crisp line at any setting.
 - `--aura-radius` — child corner radius used to derive the outer radius.
 - `--aura-duration` — one rotation of the accent, or one breath of the glow.

package/docs/pages/components/badge.md

@@ -2,6 +2,12 @@
 
 > Compact label for counts, status, or category tags, with shared intents and variants.
 
+A badge is **information, never a control**: counts, status, categories. It is
+non-interactive by nature — for a selectable option use
+[`.choice-card.chip`](../forms/choice-cards.md#chips); for a value produced by
+a widget that can be removed (combobox multi-value), the widget owns the
+removable tag (see [combobox](../forms/combobox.md)).
+
 - Supports intent colors.
 - Soft by default. Use `.solid` for counters and notification badges, or `.outline` for quieter emphasis.
 - Empty badges are solid status dots: visual variants such as `.soft` and `.outline` do not change their fill.
@@ -177,21 +183,24 @@ Override the existing hooks when the three-step scale does not fit the content.
 
 ## Removable tag pattern
 
-Use `.badge soft` for tag visuals. Add a direct dismiss button only when the tag can actually be removed. There is no separate chip component.
+Use `.badge soft` for tag visuals. Add a direct [`.close`](close.md) button only when the tag can actually be removed. There is no separate chip component.
 For a compact action or filter, use `.btn.sm` instead; badges describe content
 and must not be turned into toggle controls merely to obtain a compact shape.
+Never put a `.close` inside a `.choice-card.chip` label: the label is already
+an interactive target driving its checkbox/radio, and a nested button would mix
+two interactive targets. A removable tag next to a selectable chip is a sibling
+(a widget tag or a `.badge` + `.close`), never a child of the label.
 
-Leave the dismiss button empty: it paints its own X, so the pattern needs no
-icon font and no text glyph. Put your own icon inside it and that content is
-used instead.
+Inside a badge the close follows the pill's size, keeps a 24px pointer target,
+and tucks into the padding.
 
 ```html demo
 <span class="badge primary soft">
   Design
-  <button type="button" aria-label="Remove Design"></button>
+  <button class="close" type="button" aria-label="Remove Design"></button>
 </span>
 <span class="badge primary soft">
-  <button type="button" aria-label="Remove Design"></button>
+  <button class="close" type="button" aria-label="Remove Design"></button>
   Design
 </span>
 ```
@@ -204,4 +213,4 @@ used instead.
 - `--badge-font-size` — label font size.
 - `--badge-icon-size` — decorative child size; `1em` follows the label by default.
 - `--badge-pad-x` — inline padding. Derived from `--badge-size`, so it stays proportional to the pill; set it to opt out.
-- `--badge-dismiss-icon-size` — size of the X painted by an empty dismiss button.
+- `--close-size` / `--close-icon-size` — the badge declares them for its `.close`; set them on the badge to change them.

package/docs/pages/components/bleed.md

@@ -0,0 +1,42 @@
+# Bleed
+
+`.bleed` lets a direct child of a padded surface reach its edges. Use it for a
+full-width image, a colored header or footer, or a notice band.
+
+It works inside `.card`, `.drawer`, and an accordion panel. The accordion panel
+owns the padding, so place `.bleed` directly inside the panel, after the summary.
+A deeper descendant stays within its wrapper. A modular build imports
+`actual-css/css/components/bleed` alongside the surface component.
+
+```html demo
+<article class="card stack" style="--card-max-inline-size: 24rem">
+  <img class="bleed" src="https://picsum.photos/seed/actual-css-card/600/300" alt="" />
+  <header><h3>Full-width image</h3></header>
+  <p>The image reaches the card edges.</p>
+  <footer class="bleed" style="background: var(--surface-subtle)">
+    <button type="button" class="btn outline">View</button>
+  </footer>
+</article>
+```
+
+An `<img>`, `<picture>`, `<video>`, `<canvas>`, or `<svg>` with `.bleed` expands
+to the surface width. For a responsive image, put `.bleed` on `<picture>`; its
+image fills the picture and is clipped by it.
+
+Structural `header`, `footer`, and `figure` bands keep the surface's inner
+padding while their background reaches the edge. Other bands can read the
+relayed inset with `--bleed-pad`:
+
+```css
+.status-row {
+  padding: var(--bleed-pad);
+}
+```
+
+The participating surface relays its inset to direct children only. Read
+`--bleed-pad` on one of those children when a custom band needs matching
+padding. An author-defined surface needs its own direct-child relay to join
+this contract.
+
+See [Card](card.md), [Drawer](drawer.md), and [Accordion](accordion.md) for
+surface examples.

package/docs/pages/components/button.md

@@ -61,10 +61,37 @@ Reach for `.surface` when a secondary action must sit on an opaque, neutral
 chip: `.outline` lets whatever is behind it show through, and `.soft` is the
 intent-tinted treatment (its baseline fallback uses `--surface-subtle`).
 
+None of the three gives an opaque fill *under* an intent-colored border —
+`.surface` keeps the neutral `--border`, and `.outline` has no fill. Set
+`--ui-bg` on the element for that combination; it is the variant relay every
+component with shared variants reads, so the same declaration works on a badge:
+
+```css
+.chip-on-tint {
+  --ui-bg: var(--surface);
+}
+```
+
+The rule ties with the variant's own `--ui-bg` on specificity, so load it after
+Actual CSS or import `actual.layer.css`.
+
 Transparent treatments (`.outline`, `.ghost`, `.link`) follow the surrounding
-foreground by default, including on a contrasting `.inverted` surface. A local
-intent class still wins: `.danger.outline` uses the danger color in either
-context. Filled buttons own their surface and keep their normal intent recipe.
+foreground by default, including on a band your application paints. A local
+intent class still wins: `.danger.outline` uses the danger color in any
+context, and nothing tunes that color for a surface you paint yourself. For
+intent ink on a dark band, use a `data-theme` island, whose palette is tuned
+for its surface. Filled buttons own their surface and keep their normal intent
+recipe.
+
+A dark button (inverse, contrast) is a custom intent on the button itself, so
+every variant keeps working — `.outline` and `.ghost` take the solid ink:
+
+```css
+.btn.app-dark {
+  --intent: var(--surface-solid);
+  --intent-fg: var(--surface-solid-fg);
+}
+```
 
 `.btn.link` is a link-style action: it keeps button behavior and states, but
 remains intrinsically sized like text instead of stretching with its layout
@@ -251,5 +278,4 @@ For exclusive groups, manage a single pressed button:
 ## CSS hooks
 
 - `--btn-radius` — corner radius.
-- `--btn-focus-color` — focus ring base color; the ring itself is derived from it.
 - `--btn-gap` — space between an icon and the label text (default `0.375em`).