actual-css 0.14.1 → 0.15.0

package/docs/pages/forms/combobox.md

@@ -16,15 +16,14 @@ properties onto Actual's tokens.
 
 The [combobox template](../../demo/templates/combobox.html) themes
 [`@lekoala/combobox`](https://github.com/lekoala/combobox) entirely with Actual
-tokens: the control mirrors `.input`, chips re-derive the `.badge` soft recipe,
-and the picker popover follows `--surface-raised` and `--shadow-popout`. No
-adapter, no compatibility layer — a handful of `--cb-*` assignments and shared
-mix tokens.
+tokens: the control mirrors `.input`, chips are real `.badge` elements, and the
+picker popover follows `--surface-raised` and `--shadow-popout`. No adapter, no
+compatibility layer — a handful of `--cb-*` assignments and shared mix tokens.
 
 ```html
 <label class="field actual-combobox">
   <span class="field-label">Skills</span>
-  <combo-box placeholder="Search or add a skill…">
+  <combo-box chip-class="badge primary" placeholder="Search or add a skill…">
     <select class="select" name="skills[]" multiple>
       <option value="design" selected>Design</option>
       <option value="css" selected>CSS</option>
@@ -34,6 +33,17 @@ mix tokens.
 </label>
 ```
 
+`chip-class` hands the chip skin to the host classes, so badge variants and
+theme rules on `.badge` apply; the widget keeps layout, removal and keyboard
+focus. Set the default before creating comboboxes, after loading the CDN script:
+
+```js
+customElements.get("combo-box").setDefaultChipClass("badge primary");
+```
+
+With a bundler, use `Combobox.setDefaultChipClass("badge primary")`.
+The `chip-class` attribute overrides the default for one element.
+
 The card in the template documents the full token map of this recipe.
 
 ## Bridge contract
@@ -60,14 +70,13 @@ contrast contracts apply to the combobox for free:
 
 ```css
 .actual-combobox {
-  --cb-bg: var(--surface);
+  --cb-bg: var(--control-default-bg, var(--surface));
   --cb-color: var(--text);
   --cb-border-color: var(--form-invalid-border, var(--border));
   --cb-border-radius: var(--radius);
   --cb-focus-color: var(--focus);
   --cb-muted-color: var(--text-muted);
   --cb-error-color: var(--danger);
-  --cb-chip-bg: transparent;
   --cb-control-height: var(--control-size);
   --cb-option-min-height: var(--control-size);
 }
@@ -76,7 +85,7 @@ contrast contracts apply to the combobox for free:
   border-color: var(--form-invalid-border, var(--cb-border-color));
   outline: var(--focus-ring-width) solid var(--form-invalid-border, var(--focus));
   outline-offset: calc(var(--focus-ring-width) * -1);
-  box-shadow: none;
+  box-shadow: var(--control-shadow, none);
 }
 
 .actual-combobox :is(.cb-text-control[aria-invalid="true"], .cb-control:has([aria-invalid="true"])) {
@@ -88,27 +97,33 @@ contrast contracts apply to the combobox for free:
 }
 
 .actual-combobox :is(.cb-control, .cb-text-control) {
+  border-width: var(--border-width);
   border-radius: inherit;
+  box-shadow: var(--control-shadow, none);
 }
 
-.actual-combobox .cb-chip {
-  border: var(--border-width) solid
-    color-mix(in oklab, var(--primary) calc(100% - var(--soft-border-mix, 100%)), transparent);
-  border-radius: var(--radius-full);
-  background: color-mix(in oklab, var(--primary) calc(100% - var(--soft-bg-mix)), transparent);
-  color: color-mix(in oklab, var(--primary) var(--soft-fg-mix), var(--text));
-  font-size: var(--font-size-xs);
-  font-weight: var(--font-weight-semibold);
+.actual-combobox :is(.cb-control, .cb-text-control):hover {
+  border-color: var(--form-invalid-border, var(--control-hover-border, var(--text-subtle)));
 }
 ```
 
-While the search input is focused, the control takes the same inset outline as
-`.input` in place of the library's accent border and outer halo; a focused chip
+The control reads the field geometry a theme gives `.input`: `--border-width`
+and the `--control-shadow` elevation, which focus keeps. Hover follows `.input`
+too (`--control-hover-border`), since the control is typed into, in place of
+the library's own border mix. While the search input
+is focused, the control takes the same inset outline as `.input` in place of
+the library's accent border and outer halo; a focused chip
 or remove × keeps the library's own inner ring. Being inset, the outline needs
 no adaptation inside `.join`: `combo-box` owns the radius at zero specificity,
 so the join gives it the group corners and the visible control inherits them. The invalid rule sets `--form-invalid-border`,
 the hook `.field.danger` and `aria-invalid` already use, so border and outline
 turn danger together.
 
+### Limits
+
+The bridge shares the inherited resting field fill through `--control-default-bg`.
+It follows tokens, not native-control selectors: local `--control-bg` overrides
+and theme-specific invalid or disabled fills need matching widget state rules.
+
 The same approach works for any widget that exposes a custom-property skin —
-keep the widget's behavior, restyle its tokens through the shared vocabulary.
+keep the widget's behavior, restyle its tokens through the shared vocabulary.

package/docs/pages/forms/controls.md

@@ -33,3 +33,5 @@ The filename area stays muted.
   <span class="field-help" id="file-help">JPG, PNG or WebP — max 2 MB</span>
 </label>
 ```
+
+For drag and drop, previews and upload progress, see [File upload](file-upload.md).

package/docs/pages/forms/date-picker.md

@@ -58,28 +58,49 @@ date-calendar {
   --dp-accent: var(--primary);
   --dp-accent-fg: var(--primary-fg);
   --dp-radius: var(--radius);
+  --dp-focus: var(--focus);
+  --dp-focus-width: var(--focus-ring-width);
   /* Trigger glyph on the select chevron axis. */
   --dp-picker-button-size: calc(var(--control-pad-x) * 2 + 1em + var(--border-width) * 2);
 }
 
-.dp-calendar-header :where(button, select, input):focus-visible {
-  border-color: var(--dp-border);
-  outline: var(--focus-ring-width) solid var(--focus);
-  outline-offset: calc(var(--focus-ring-width) * -1);
-  box-shadow: none;
-}
-
-.dp-picker-button:focus-visible,
-.dp-day:focus-visible {
-  outline-color: var(--focus);
+.dp-picker-panel[popover] {
+  box-shadow: var(--shadow-popout);
 }
 ```
 
-The field is a plain `.input`, so the core inset focus outline already outranks
-the library's halo; the calendar's own controls paint a `--dp-accent` halo, so
-the two focus rules map them onto the core outline. The calendar popup is its own
+The picker draws focus as an inset line, like the core, so `--dp-focus` and
+`--dp-focus-width` are the whole focus mapping; the field itself is a plain
+`.input` and keeps the core outline. The panel has no shadow token, so it takes
+`--shadow-popout` directly. It opens as a popover, in the top layer,
+so inside a modal, even in a scrolling body, it is neither clipped nor stacked
+under the dialog. The calendar popup is its own
 element, so the `--dp-*` map is declared on `date-picker`/`date-calendar` rather
 than inherited from a wrapper.
+
+The header month, year and arrows take host classes through `controlClasses`,
+so they render as real Actual controls:
+
+```js
+picker.controlClasses = { month: "select sm", year: "input sm", nav: "btn outline sm icon-only" };
+```
+
+Set the defaults once for every picker and inline calendar. With the CDN script,
+call the registered constructor after the deferred script has loaded:
+
+```js
+customElements.get("date-picker").setDefaultControlClasses({
+  month: "select sm",
+  year: "input sm",
+  nav: "btn outline sm icon-only",
+});
+```
+
+With a bundler, import `setDefaultControlClasses` from `@lekoala/date-picker`.
+An instance's `controlClasses` overrides only the supplied roles; omitted roles
+follow the current defaults. Day cells and the field trigger stay on the
+`--dp-*` tokens.
+
 As with the combobox, the bridge stays in docs/demo — it is a recipe, not package
 API, and pins no widget version.
 

package/docs/pages/forms/file-upload.md

@@ -0,0 +1,120 @@
+# File upload
+
+> An upload widget is not shipped by the framework — the native `.file` input stays the baseline. Compose Dropzone's rows from Actual components, or theme FilePond with Actual tokens.
+
+The native input is the default: it submits with the form and needs no
+JavaScript. Reach for an uploader when the product needs drag and drop,
+previews, progress, or asynchronous and chunked uploads.
+
+**Related terms:** file upload, uploader, file input, drag and drop, drop zone, dropzone, attachments, upload progress, file preview, FilePond.
+
+## Native baseline
+
+```html demo
+<label class="field">
+  <span class="field-label">Profile picture</span>
+  <input class="file" type="file" accept="image/*" />
+</label>
+```
+
+See [Controls](controls.md#file) for what `.file` styles.
+
+## Dropzone: rows from Actual components
+
+The [file upload template](../../demo/templates/file-upload.html) puts the
+native input, [Dropzone](https://docs.dropzone.dev/) and FilePond side by side.
+Dropzone owns drop, queue and requests; its stylesheet is not loaded. Its
+`previewTemplate` is plain markup, so each file renders as a `.list-item`, and
+Dropzone fills the `data-dz-*` slots:
+
+```html
+<template id="upload-row">
+  <li class="list-item">
+    <span class="avatar"><span data-dz-ext aria-hidden="true"></span><img data-dz-thumbnail alt="" hidden></span>
+    <span class="list-item-content">
+      <strong class="list-item-title truncate" data-dz-name></strong>
+      <span class="list-item-text" data-dz-size></span>
+      <span class="list-item-text"><span class="danger intent-color" data-dz-errormessage></span></span>
+      <progress class="progress" value="0" max="100" data-dz-uploadprogress></progress>
+    </span>
+    <button class="close" type="button" aria-label="Remove file" data-dz-remove></button>
+  </li>
+</template>
+```
+
+```js
+const dropzone = new Dropzone(zone, {
+  url: "/upload",
+  clickable: zone.querySelector("button"), // a real button, not the whole zone
+  previewsContainer: "#upload-list", // a <ul class="list">
+  previewTemplate: document.getElementById("upload-row").innerHTML,
+});
+dropzone.on("success", (file) => file.previewElement.querySelector("progress").classList.add("success"));
+```
+
+Dropzone sets the value of a `<progress>` slot, so `.progress` works as is.
+Outcomes take intent classes from event listeners rather than styling
+Dropzone's `dz-success` and `dz-error` classes. The thumbnail starts
+`hidden` and a `thumbnail` listener reveals it; until then the avatar shows
+the file extension.
+
+The drop target is the one piece left to draw: a dashed `--border-control`
+outline on `--surface-subtle`, with a `.dz-drag-hover` rule (Dropzone writes
+the class while files hover the zone). Put a native `.file` input in the zone
+for the no-JavaScript case and remove it at init, as the template does:
+Dropzone appends its own hidden input to `<body>`.
+
+## FilePond: theme bridge
+
+[FilePond v5](https://v5.filepond.com/) is a `<file-pond>` web component that
+wraps a native input and renders its own UI in a shadow root. Its
+`--default-*` properties inherit into that root, so the bridge is one rule:
+
+```html
+<div class="field">
+  <label class="field-label" for="attachments">Attachments</label>
+  <file-pond>
+    <input class="file" id="attachments" type="file" name="attachments" multiple>
+  </file-pond>
+</div>
+```
+
+```css
+file-pond {
+  --default-color: var(--text);
+  --default-background-color: var(--surface-subtle);
+  --default-accent-color: var(--primary);
+  --default-accent-color-text: var(--primary-fg);
+  --default-border: var(--border-width) solid var(--border-control);
+  --default-border-radius: var(--radius);
+  --default-padding: var(--space-40);
+  --outline: var(--focus-ring-width) solid var(--focus);
+  display: block;
+}
+```
+
+```js
+import { defineFilePond } from "filepond";
+import { locale } from "filepond/locales/en-gb.js";
+
+defineFilePond({ locale });
+```
+
+FilePond reads `color-scheme` for everything the map leaves out, so light,
+dark and `data-theme` islands need no second rule. Font and line height
+inherit from the page. `--outline` is not documented by FilePond: it is the
+property every focus-visible outline inside the component reads, and mapping
+it gives the browse button and entry buttons the framework focus line. The
+host is `inline-block` by default; `display: block` makes the drop area span
+its field. For deeper changes, FilePond exposes `::part()` hooks and a
+template API; the template does not need them.
+
+FilePond v5 is in beta: pin an exact version (`npm install filepond@beta`).
+
+Both bridges stay in docs/demo — they are recipes, not package API.
+
+## Which one?
+
+- A form that posts a few files: native `.file`.
+- Drag and drop, previews and progress in your own markup: Dropzone with an Actual `previewTemplate`.
+- A complete uploader UI (media previews, image editing, camera, chunked uploads): FilePond on the token bridge.

package/docs/pages/forms/overview.md

@@ -172,9 +172,17 @@ A full form using the control classes, field wrappers, and form actions:
 
 ## Hooks
 
+Set `--control-default-bg` on a theme or region for an inherited resting field
+background shared by `.input`, `.textarea`, `.select` and external widget bridges.
+Use `--control-bg` for a local field override; state rules still own readonly,
+disabled and validation fills.
+
 Set `--control-hover-border` to tune the hover border of `.input` and `.textarea`.
 Set `--control-hover-bg` to keep a `.select` background steady on hover, or give
 it a stronger fill.
+Set `--control-shadow` to give `.input`, `.textarea` and `.select` a resting
+elevation (unset by default). It inherits, so a theme can set it once on its
+root; keyboard focus and an open custom select keep it.
 
 ## Notes
 

package/docs/pages/foundations/philosophy.md

@@ -102,6 +102,12 @@ classes: `<article class="card pricing-plan pricing-plan--featured">`.
 
 Components are semantic boxes: `.btn`, `.badge`, `.alert`, `.card`, `.avatar`, etc. Each component owns its intrinsic layout and visual defaults.
 
+Components are replaceable implementations. If a built-in component does more
+than your application needs, omit its module and write your own. Keep the
+semantic markup, state conventions, and shared design tokens where they fit.
+See [Replace a component, keep the conventions](../guides/modular-import.md#replace-a-component-keep-the-conventions)
+for a minimal Steps implementation.
+
 ## Intents
 
 `.primary`, `.secondary`, `.success`, `.warning`, `.danger` do not style elements directly. They only expose `--intent` and `--intent-fg`. Components and variants decide how to consume them.

package/docs/pages/foundations/theming.md

@@ -64,6 +64,33 @@ Change `--switch-width`, `--switch-block-size`, and `--switch-knob-margin`; knob
 
 Set `--disabled-opacity`. All disabled-prone components — buttons, tabs, menu items, badges, avatars, choice cards, native inputs, and range sliders — read it for their dimmed state.
 
+### Customize focus beyond the ring / focus background, text and border
+
+Use an application class with `:focus-visible` to change a button's fill, text,
+and border while keeping its framework outline. Load the rule after Actual CSS:
+
+```css
+.settings-action.btn:focus-visible:not(:where(:disabled, [aria-disabled="true"])) {
+  background: var(--surface-solid);
+  color: var(--surface-solid-fg);
+  border-color: var(--focus);
+  /* Hover paints an inset shadow over the background. */
+  --btn-hover-overlay: transparent;
+}
+```
+
+```html
+<button class="btn primary settings-action" type="button">Settings</button>
+```
+
+Focus and hover can be active together. The selector takes precedence over the
+generic hover fill; `--btn-hover-overlay` removes its extra tint while
+preserving any `--btn-shadow` elevation. Check keyboard focus both with and
+without the pointer over the button, in each color scheme and in forced colors.
+Keep the outline visible against the surrounding surface when changing colors.
+
+→ [Button hooks](../components/button.md#css-hooks) · [Focus tokens](./tokens.md#color)
+
 ### Keep bare native controls on-theme / accent-color
 
 Native controls that no component class restyles — a bare checkbox, radio, range, or `<progress>` — follow the theme through `accent-color: var(--primary)`, declared on `:root` and every `[data-theme]` island so each island recomputes it from its own palette. Component classes (`.check`, `.radio`, `.range`) paint their own rendering and do not read it.
@@ -206,6 +233,27 @@ step per role rather than importing the scale.
 
 → Foundations · Tokens (theme contract) · Guides · Tailwind (Map the palette to theme roles)
 
+### Use a custom font / webfont / typeface with a theme
+
+A font belongs to the page, not to the theme. Load the face in the application
+stylesheet (`@font-face` or a font service) and set `--font-sans` (and
+`--font-mono`) on `:root`, never in a `[data-theme]` block: a theme switches at
+runtime and scopes to islands, so a font tied to it would change the text
+metrics of every island it touches. A display face for headings has no token:
+name it on the headings in application CSS.
+
+```css
+:root {
+  --font-sans: "Space Grotesk Variable", system-ui, sans-serif;
+}
+
+:is(h1, h2) {
+  font-family: "Archivo Black", var(--font-sans);
+}
+```
+
+→ Examples · Neo-brutalist
+
 ### Use or adapt a preset palette
 
 `src/css/themes/` holds example palettes (`ocean`, `spruce`, `neon`, `brutalist`, …) as
@@ -213,11 +261,15 @@ reference material to copy into your own `[data-theme]` island — they are demo
 assets, not package entrypoints. Each sets the intent/surface/text tokens and
 lets the core derive everything else.
 
-The `bootstrap-v6` example follows Bootstrap 6's blue palette, stronger subtle
-surfaces, filled badges, and steady select hover; its focus is the core solid
-line. Use `.badge.soft` for a subtle badge. It is a visual theme, not a
-Bootstrap compatibility layer. The `gradient` example keeps a Bootstrap 4 style
-outer halo on focused fields, for comparison. The `material` example restyles
+The `gradient` example keeps a Bootstrap 4 style outer halo on focused fields
+instead of the core inset line. The `neo-brutalist` example puts a hard offset
+shadow on every standalone framed object (`--btn-shadow` for buttons, which
+lift on hover and press flat), keeps pastel intents in fills with contrasting
+ink, and turns the accordion marker into a plus. It is an invasive page skin:
+its descendant rules and inherited component hooks cross nested `data-theme`
+boundaries, so use a separate page to show another theme. Its `.join` groups
+fit their contents so the shadow follows the controls.
+The `material` example restyles
 fields as filled underlines with pill buttons — tokens plus three small rules,
 and `.join` still needs no adaptation. The `glass` example paints translucent
 surfaces over its own backdrop: it sets `--surface-opaque` and

package/docs/pages/foundations/typography.md

@@ -97,6 +97,9 @@ The `.prose` fallback to `--primary` breaks down for a theme whose primary is a
 
 It is a color token only. There are still no `--link-decoration-thickness`, `--link-decoration-thickness-hover`, or `--link-underline-offset` tokens; no global rule consumes them. Prose and components set their own underline metrics inline.
 
+On `.card.solid`, links follow the surrounding text color in every state;
+the theme's `--link` ink remains for page surfaces. See [Card](../components/card.md).
+
 ## Type scale
 
 There is no exposed type scale.

package/docs/pages/guides/introduction.md

@@ -53,7 +53,7 @@ optimizing — the bare `actual-css` entrypoint and `actual-css/full` both resol
 to the complete compiled framework:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.14/dist/actual.full.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.15/dist/actual.full.min.css">
 ```
 
 The package does not maintain separate partial bundles. Modular entrypoints map

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

@@ -74,6 +74,130 @@ shared: keep `components/close` with modal, drawer, alert, or a removable
 badge; `components/bleed` with a `.bleed` child of card, drawer, or accordion;
 `components/spinner` with `components/busy`.
 
+## Replace a component, keep the conventions
+
+Actual CSS components are reference implementations, not mandatory dependencies.
+Omit a component's stylesheet and write a smaller implementation when your
+application needs fewer features. Keep its semantic markup, state conventions,
+and shared theme tokens where they fit.
+
+Choose the level of customization that matches the need:
+
+- Change a color, size, or spacing through the component's public hooks.
+- Give the component a different appearance with an application CSS variant.
+- Replace a component that does more than you need by omitting its module and
+  writing your own implementation.
+
+### Example: a simpler Steps component
+
+The built-in Steps component supports horizontal and vertical layouts,
+connectors, optional labels, responsive representations, scrolling, and focus
+for navigable labels. A static, horizontal progress indicator can use the same
+HTML with a smaller stylesheet.
+
+Import only the framework modules the application uses, followed by the
+replacement:
+
+```css
+/* app.css */
+@import "actual-css/css";
+@import "actual-css/css/components/button";
+@import "actual-css/css/components/card";
+@import "./steps.css";
+```
+
+Omit `actual-css/css/components/steps` and any entrypoint that includes it:
+`actual-css`, `actual-css/full`, `actual-css/css/full`, or
+`actual-css/css/components`. Loading the original and overriding it retains
+its weight and may introduce cascade conflicts.
+
+Keep the ordered list, `.step-complete` for completed steps, and
+`aria-current="step"` for the current step:
+
+```html
+<ol class="steps steps-horizontal" aria-label="Booking progress">
+  <li class="step-complete">
+    <span class="step-label">Details</span>
+  </li>
+  <li aria-current="step">
+    <span class="step-label">Payment</span>
+  </li>
+  <li>
+    <span class="step-label">Confirmation</span>
+  </li>
+</ol>
+```
+
+The application owns this replacement stylesheet:
+
+```css
+/* steps.css — static horizontal progress only */
+.steps-horizontal {
+  --step-size: 2rem;
+  counter-reset: app-step;
+  display: flex;
+  gap: var(--space-30);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.steps-horizontal > li {
+  counter-increment: app-step;
+  flex: 1 1 0;
+  min-inline-size: 0;
+  display: grid;
+  justify-items: center;
+  align-content: start;
+  gap: var(--space-20);
+  text-align: center;
+  color: var(--text-muted);
+}
+
+.steps-horizontal > li::before {
+  content: counter(app-step);
+  display: grid;
+  place-items: center;
+  box-sizing: border-box;
+  inline-size: var(--step-size);
+  block-size: var(--step-size);
+  border: 2px solid var(--border);
+  border-radius: var(--radius-full);
+  background: var(--surface-opaque);
+  color: var(--text-muted);
+  font-weight: var(--font-weight-semibold);
+}
+
+.steps-horizontal > .step-complete::before {
+  background: var(--state-selected);
+  border-color: var(--state-selected);
+  color: var(--state-selected-fg);
+}
+
+.steps-horizontal > [aria-current="step"] {
+  color: var(--text);
+}
+
+.steps-horizontal > [aria-current="step"]::before {
+  border-color: var(--state-selected-text, var(--state-selected));
+  color: var(--state-selected-text, var(--state-selected));
+}
+
+.steps-horizontal .step-label {
+  color: inherit;
+  font-size: var(--font-size-sm);
+  overflow-wrap: anywhere;
+}
+```
+
+The shared tokens supply theme colors, typography, and spacing without copying
+the palette. This recipe is for static labels: use the built-in
+[Steps](../components/steps.md) for navigable labels, connectors, vertical
+orientation, or responsive representations.
+
+If a replacement needs different markup or semantics, give it an
+application-specific component name.
+
 ## Family manifests
 
 Each family is one import. The contents are enumerations rather than table

package/docs/pages/guides/upgrading.md

@@ -7,6 +7,69 @@ sections in order when skipping a release.
 
 **Related terms:** migration, breaking changes, update, version.
 
+## 0.14 to 0.15
+
+No class or hook is removed: markup and application CSS keep working.
+
+### Rendering changes without an edit
+
+- `.badge > .close` is a disc inside the pill instead of overhanging its end;
+  a transparent hit area keeps the 24px target. Check CSS that overrides it or
+  sets `--close-size` on a badge.
+- `.card.solid` links take the card's text color at rest, hover and focus,
+  even when a theme sets `--link`.
+- `.skeleton` tracks and highlights are translucent ink tints.
+- A selected `.choice-card.chip` paints its check with `--state-selected-text`
+  even when it carries an intent class.
+- The `bootstrap-v6` demo theme is gone. Demo themes are not part of the
+  package, so this only affects a copy of it: keep the copy, or drop it since
+  the core focus line and fields now match it.
+- The combobox, date picker and data grid recipes target
+  `@lekoala/combobox` 0.7.1, `@lekoala/date-picker` 0.5.1 and
+  `data-grid-component` 3.7.0. Compare a copied bridge with the current one in
+  [Combobox](../forms/combobox.md) and [Date picker](../forms/date-picker.md).
+
+## 0.13 to 0.14
+
+### Soft border mix
+
+`--soft-border-mix` has no default. Search application CSS for
+`var(--soft-border-mix)` without a fallback and give it the one its treatment
+needs: `var(--soft-border-mix, 100%)` beside the translucent soft tint,
+`var(--soft-border-mix, 65%)` beside the opaque `.soft` mix. A theme that sets the property still drives both treatments.
+
+### Selected ink in themes
+
+`--state-selected-text` colors selected ink on a regular surface (current
+`.nav-link`, selected `.tab`, current step) and falls back to
+`--state-selected`. A theme whose primary is too light to read as text sets it
+to a darker ink; `actual-css contrast` reports the pair.
+
+### Placement values
+
+An unknown `data-tooltip-placement` or `data-flyout-placement` value logs a
+console warning and falls back to the default placement. Replace the values
+the console names.
+
+### Building from a clone
+
+`dist/`, `site/` and `demo/assets/` are no longer committed: run
+`bun run build:all` after cloning. npm and GitHub release downloads are
+unaffected.
+
+### Rendering changes without an edit
+
+- `.badge`, `.alert` and `.btn.soft` paint a translucent intent tint with no
+  rim; the shared `.soft` on `.card`, `.navbar`, `.app-nav` and `.chat-bubble`
+  stays opaque. Check custom themes on `--surface`, `--surface-raised` and
+  `--surface-subtle`.
+- `.alert.admonition` follows `.solid`, `.surface` and `.outline`; a solid
+  admonition frames its body with `--border`.
+- A `.list-item` moves its trailing region to a new line instead of breaking
+  the title mid-word.
+- `.topbar` and `.form-actions.sticky` turn opaque under
+  `prefers-reduced-transparency: reduce`.
+
 ## 0.12 to 0.13
 
 ### Layout hooks stop at each layout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actual-css",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Plain CSS component framework with semantic classes, universal variants, small tokens, theme hooks, and progressive enhancements.",
   "type": "module",
   "packageManager": "bun@1.4.3",
@@ -161,6 +161,6 @@
     "happy-dom": "^21.0.1"
   },
   "dependencies": {
-    "@lekoala/floating": "^0.3.0"
+    "@lekoala/floating": "^0.3.1"
   }
 }