actual-css 0.14.1 → 0.15.0

package/docs/navigation.json

@@ -60,6 +60,7 @@
         "dialog",
         "drawer",
         "data-list",
+        "diagrams",
         "fab",
         "indicator",
         "key",
@@ -74,7 +75,8 @@
         "skeleton",
         "spinner",
         "steps",
-        "table"
+        "table",
+        "timeline"
       ]
     },
     {
@@ -85,6 +87,7 @@
         "controls",
         "combobox",
         "date-picker",
+        "file-upload",
         "rich-text",
         "labels",
         "floating-field",

package/docs/pages/components/accordion.md

@@ -6,7 +6,7 @@
 - Use the `name` attribute for exclusive accordions.
 - Supports any valid body element (`div`, `p`, `ul`, ...).
 - 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.
+- The end marker is a chevron that turns when open; its glyph, turn, color, and size are hooks.
 
 ```html demo
 <div class="accordion">
@@ -89,26 +89,21 @@ The accordion owns its disclosure marker; the trigger content belongs to the mar
 </div>
 ```
 
-## Custom markers
+## Plus / close marker
 
-The end marker is a shared token-based chevron; swapping it for a local icon is a demo concern, not part of the base API.
+Swap the glyph and the turn: a plus turned 45° reads as a close cross (plus
+minus, expand collapse, + / ×).
 
-```html
-<div class="accordion accordion-demo">
+```html demo
+<div class="accordion" style="--accordion-marker-icon: var(--icon-plus); --accordion-marker-open-rotate: 45deg">
   <details open>
-    <summary>
-      <span class="accordion-demo-icon" aria-hidden="true"></span>
-      <span>Custom marker at the start</span>
-    </summary>
-    <p>This demo swaps the default end marker for a local plus/minus icon.</p>
+    <summary>Open: the plus has turned into a cross</summary>
+    <p>The turn animates with the open state.</p>
   </details>
 
   <details>
-    <summary>
-      <span class="accordion-demo-icon" aria-hidden="true"></span>
-      <span>Another item</span>
-    </summary>
-    <p>The icon belongs to the example, not the base accordion API.</p>
+    <summary>Closed: a plus</summary>
+    <p>Any mask-ready icon token works as the glyph.</p>
   </details>
 </div>
 ```
@@ -119,6 +114,8 @@ The end marker is a shared token-based chevron; swapping it for a local icon is
 - `--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.
+- `--accordion-marker-icon` — the marker glyph, any mask image (`--icon-chevron`, `--icon-plus`, …).
+- `--accordion-marker-open-rotate` — the marker's turn when open.
 
 ### Replacing the marker
 
@@ -153,8 +150,8 @@ recipe repeats it on its own property:
   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;
+  -webkit-mask: var(--accordion-marker-icon) center / contain no-repeat;
+  mask: var(--accordion-marker-icon) center / contain no-repeat;
 }
 
 .accordion.custom-marker summary:hover .marker {
@@ -162,7 +159,7 @@ recipe repeats it on its own property:
 }
 
 .accordion.custom-marker details[open] .marker {
-  transform: rotate(180deg);
+  transform: rotate(var(--accordion-marker-open-rotate));
 }
 
 @media (forced-colors: active) {

package/docs/pages/components/avatar.md

@@ -6,6 +6,7 @@
 - Can be an inert element, link, or button when the link/button has a real destination or action.
 - Stack avatars with `.avatar-stack` for overlapping group displays.
 - A status dot attaches as an empty `.badge` child; the badge carries an `aria-label` so the dot conveys its meaning to assistive tech.
+- For a person chip (mention, assignee), put the avatar first in a `.badge`; see [Badge](badge.md#with-an-avatar).
 - Does not support shape modifiers as public API. Shape is theme-level.
 - Sizes can be adjusted with CSS variables and optional `.sm` or `.lg`.
 - Background is an exposed css variable (and can use `data-tone`).

package/docs/pages/components/badge.md

@@ -23,7 +23,7 @@ direct child of `.stack` (where flex children otherwise stretch), and a flex
 parent never compresses it (`flex: none`). Use `inline-size: 100%` — or the
 optional `.inline-size-full` utility — when a full-width badge is intentional.
 
-**Related terms:** chip, tag, pill, removable tag.
+**Related terms:** chip, tag, pill, removable tag, user chip, mention, assignee.
 
 ## Class reference
 
@@ -32,6 +32,7 @@ optional `.inline-size-full` utility — when a full-width badge is intentional.
 | `.badge`        | Component   | Compact label; soft by default.           |
 | `.badge:empty`  | Composition | Truly-empty badge renders as a solid dot. |
 | `.dot`          | Composition | Status dot inside a badge.                |
+| `.avatar`       | Composition | Leading avatar sized to the badge.        |
 | Shared intents  | Intent      | `.primary`, `.secondary`, `.success`, …   |
 | Shared variants | Variant     | `.solid`, `.outline`, `.surface`.         |
 | `.sm` / `.lg`   | Size        | Smaller or larger optical scale.          |
@@ -133,7 +134,7 @@ badge.
 ## With an icon
 
 Decorative SVG, image, or `[aria-hidden="true"]` children follow
-`--badge-icon-size`.
+`--badge-icon-size`. An `.avatar` keeps its own sizing (see below).
 
 ```html demo
 <span class="badge success">
@@ -150,6 +151,36 @@ Decorative SVG, image, or `[aria-hidden="true"]` children follow
 </span>
 ```
 
+## With an avatar
+
+Put an [`.avatar`](avatar.md) first in the badge for a person chip: mention,
+assignee, contributor, author. The avatar follows the badge size, so the pill
+keeps its height and `.sm` / `.lg` scale both together. Wrap the chips in a
+[`.cluster`](../layout/cluster.md) to let them wrap.
+
+```html demo
+<div class="cluster tight">
+  <a href="#" class="badge lg">
+    <span class="avatar">
+      <img src="https://mockmind-api.uifaces.co/content/human/219.jpg" alt="" />
+    </span>
+    @jane-doe
+  </a>
+  <a href="#" class="badge lg">
+    <span class="avatar success"><abbr>RM</abbr></span>
+    @rin-moreau
+  </a>
+  <span class="badge primary">
+    <span class="avatar"><abbr>AM</abbr></span>
+    Ada Morgan
+    <button class="close" type="button" aria-label="Remove Ada Morgan"></button>
+  </span>
+</div>
+```
+
+Keep `alt=""` when the handle or name sits next to the image. Initials fit
+the default and `.lg` sizes; use an image on `.sm`.
+
 ## Loading status
 
 A decorative spinner follows the badge color and optical size.
@@ -185,17 +216,22 @@ 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.
 
-Inside a badge the close follows the pill's size, keeps a 24px pointer target,
-and tucks into the padding.
+Put the close last. It mirrors a leading avatar: a disc inside the pill at the
+same inset, so a fill or the hover wash never leaves the pill. On small badges
+the disc is small; an invisible hit area keeps the pointer target at 24px.
 
 ```html demo
-<span class="badge primary soft">
+<span class="badge primary soft sm">
   Design
   <button class="close" type="button" aria-label="Remove Design"></button>
 </span>
 <span class="badge primary soft">
+  Design
   <button class="close" type="button" aria-label="Remove Design"></button>
+</span>
+<span class="badge primary soft lg">
   Design
+  <button class="close" type="button" aria-label="Remove Design"></button>
 </span>
 ```
 

package/docs/pages/components/button.md

@@ -280,3 +280,8 @@ For exclusive groups, manage a single pressed button:
 
 - `--btn-radius` — corner radius.
 - `--btn-gap` — space between an icon and the label text (default `0.375em`).
+- `--btn-shadow` — resting elevation (unset by default). It inherits, so a
+  theme can set it once on its root; the solid hover overlay composes with it.
+  Change it in `:hover`/`:active` rules for a lift and press.
+  Supply shadow-list items; use `0 0 #0000` for no elevation. `none` cannot
+  compose with the inset hover overlay and invalidates the whole shadow list.

package/docs/pages/components/card.md

@@ -16,6 +16,13 @@ Flexible content container with optional header, body, and footer regions.
 `--surface-raised` and leaves the intent to the text. For a dark card on a
 light page (or the reverse), put `data-theme="dark"` on the card.
 
+Shared `.soft` with an intent class gives the card a tone: an opaque surface
+tinted by the intent, with the soft ink. See [Tones](#tones).
+
+On `.card.solid`, bare and `.prose` links follow the surrounding text color,
+including hover and keyboard focus, instead of the theme's `--link` ink.
+Nested cards and `data-theme` islands establish their own link context.
+
 ## Basic usage
 
 Use semantic elements inside the card. A direct `<header>` or `<footer>` is the
@@ -126,6 +133,33 @@ all footers in the row line up regardless of body length.
 </section>
 ```
 
+## Tones
+
+A toned, tinted, or colored card (accent card, highlight card) is `.soft` plus
+an intent class. The tint is opaque, so it holds over an image, and the ink
+follows the soft recipe, so muted text and links stay readable on it.
+
+```html demo
+<section class="grid">
+  <article class="card soft primary">
+    <h3>Primary</h3>
+    <p class="muted">A highlighted plan or feature.</p>
+  </article>
+  <article class="card soft success">
+    <h3>Success</h3>
+    <p class="muted">A completed step.</p>
+  </article>
+  <article class="card soft warning">
+    <h3>Warning</h3>
+    <p class="muted">Something to check.</p>
+  </article>
+</section>
+```
+
+For a fully colored card, use a `data-theme` island rather than `.solid`: the
+island recomputes muted text, links, and fields for the new surface, where
+`.solid` only repaints the fill and the main ink.
+
 ## Surfaces
 
 A card is a surface-owning component: inside a painted band it keeps its own

package/docs/pages/components/diagrams.md

@@ -0,0 +1,96 @@
+# Diagrams
+
+> The framework draws no diagrams. Render Mermaid text with an external engine such as Pele and theme it with Actual tokens.
+
+A diagram is a drawing to look at: a chronology, a schedule, a process. For
+content a reader scans, follows links from or acts on, stay in HTML.
+
+- Events with links or actions in them: [Timeline](timeline.md).
+- Progress through the steps of a flow: [Steps](steps.md).
+- A timeline chart, Gantt chart, flowchart or any other Mermaid diagram: an
+  external engine on the token bridge below.
+
+**Related terms:** chart, Mermaid, Gantt, flowchart, sequence diagram, mind
+map, roadmap, timeline chart, org chart, diagram library.
+
+## Pele on Actual tokens
+
+[Pele](https://pele.run/) renders Mermaid text to SVG with no runtime
+dependency, and reads its colors, fonts and radius from `--pele-*` custom
+properties on the SVG or any ancestor. The
+[diagrams template](../../demo/templates/diagrams.html) wraps it in a small
+`<pele-diagram>` web component:
+
+```html
+<pele-diagram>
+  <script type="text/plain">
+    flowchart LR
+      A[Request] --> B{Slot free?}
+      B -- Yes --> C[Confirm]
+  </script>
+</pele-diagram>
+```
+
+The component, in
+[`demo/scripts/pele-diagram.js`](../../demo/scripts/pele-diagram.js), is an
+example to copy, not Actual CSS API. It loads `pele/lazy` from a CDN, which
+fetches each diagram type on first use, and mounts the source found in its
+`text/plain` script. Zoom is off; the boolean `zoom` attribute turns on
+Pele's automatic zoom controls for one diagram.
+
+```css
+pele-diagram {
+  --pele-bg: var(--surface-opaque);
+  --pele-fg: var(--text);
+  --pele-muted: var(--text-muted);
+  --pele-line: var(--text-muted);
+  --pele-surface: var(--surface-subtle);
+  --pele-surface-alt: var(--surface-raised);
+  --pele-border: var(--border);
+  --pele-accent: var(--primary);
+  --pele-critical: var(--danger);
+  --pele-error: var(--danger);
+  --pele-font: var(--font-sans);
+  --pele-font-mono: var(--font-mono);
+  --pele-radius: var(--radius);
+
+  display: block;
+  min-inline-size: 0;
+}
+
+@supports (color: oklch(from red l c h)) {
+  pele-diagram {
+    --diagram-series: var(
+      --primary-soft-fg,
+      color-mix(in oklab, var(--text), var(--primary) var(--soft-fg-mix))
+    );
+    --pele-series-1: var(--diagram-series);
+    --pele-series-2: oklch(from var(--diagram-series) l c calc(h + 135));
+    --pele-series-3: oklch(from var(--diagram-series) l c calc(h + 270));
+    --pele-series-4: oklch(from var(--diagram-series) l c calc(h + 45));
+    --pele-series-5: oklch(from var(--diagram-series) l c calc(h + 180));
+    --pele-series-6: oklch(from var(--diagram-series) l c calc(h + 315));
+    --pele-series-7: oklch(from var(--diagram-series) l c calc(h + 90));
+    --pele-series-8: oklch(from var(--diagram-series) l c calc(h + 225));
+  }
+}
+```
+
+Colors resolve at paint time, so a theme or light/dark switch restyles a
+mounted diagram without a re-render; a font change needs the mounted
+diagram's `refresh()`.
+
+- `--pele-bg` is opaque because Pele also writes series labels and edge-label
+  plates in it.
+- Series colors (timeline sections, pie slices, kanban lanes) are categories,
+  so they turn one hue rather than borrow intents, which would read as
+  status. The base is the soft primary ink, readable against the surface, and
+  Pele writes the series labels in `--pele-bg`.
+- The `@supports` guard is required: a custom property accepts any value, so
+  an engine without relative colors would receive an invalid fill. Without
+  it, Pele keeps its own series palette.
+
+The bridge stays in docs and the demo, like the
+[combobox](../forms/combobox.md) and [date picker](../forms/date-picker.md)
+ones: Actual CSS does not depend on Pele. The template pins the version the
+bridge was checked against.

package/docs/pages/components/steps.md

@@ -4,7 +4,7 @@
 
 Use an `<ol>` because the order is part of the meaning. Add `.step-complete` to
 finished steps and `aria-current="step"` to the current one. Unmarked steps are
-upcoming.
+upcoming. For a history of past events, use [Timeline](timeline.md).
 
 Orientation and labels are two independent choices.
 

package/docs/pages/components/table.md

@@ -141,3 +141,7 @@ a duplication.
 
 - `--table-cell-pad` — cell padding; `.compact` re-declares it tighter.
 - `--table-min` — minimum table width before `.table-wrap` scrolls horizontally.
+- `--table-header-bg`, `--table-header-fg` — header band fill and ink. Set
+  them on a theme root rather than on `.table`: a data grid bridge reads the
+  same pair, so the table and the grid share one header (see the
+  [data grid template](../../demo/templates/data-grid.html)).

package/docs/pages/components/timeline.md

@@ -0,0 +1,111 @@
+# Timeline
+
+> Vertical history of dated events: activity feed, audit log, order tracking.
+
+Use an `<ol>` of events, most recent first or oldest first. Each event gets a
+dot on a rail; a direct `<time>` child is its dateline. The content is plain
+HTML in block flow, so a sentence that mixes text and links stays one
+sentence.
+
+**Related terms:** activity feed, activity log, history, audit trail, event
+log, changelog, order tracking.
+
+For progress through a process (checkout, onboarding), use
+[Steps](steps.md): a timeline records what happened, steps show where you
+are. For a horizontal, alternating or time-scaled chronology, or a Gantt
+chart, render a diagram: see [Diagrams](diagrams.md).
+
+## Basic usage
+
+```html demo
+<ol class="timeline">
+  <li>
+    <time datetime="2026-10-18T09:30">Today, 09:30</time>
+    <strong>Appointment confirmed</strong>
+    <p class="muted">The patient received a confirmation email.</p>
+  </li>
+  <li>
+    <time datetime="2026-10-17T14:00">Yesterday, 14:00</time>
+    <strong>Appointment requested</strong>
+    <p class="muted">The booking was submitted online.</p>
+  </li>
+  <li>
+    <time datetime="2026-10-15">October 15</time>
+    <strong>Patient registered</strong>
+  </li>
+</ol>
+```
+
+The dot lines up with the first line of the event, whether it opens with the
+`<time>` or with text. Block children drop their margins; wrap the content in
+a [`.stack`](../layout/stack.md) when an event needs more spacing.
+
+## Intents
+
+An intent class on the `<li>` colors its dot.
+
+```html demo
+<ol class="timeline">
+  <li class="success">
+    <time datetime="2026-10-18">October 18</time>
+    Order delivered
+  </li>
+  <li class="warning">
+    <time datetime="2026-10-17">October 17</time>
+    Delivery delayed
+  </li>
+  <li class="primary">
+    <time datetime="2026-10-16">October 16</time>
+    Order shipped
+  </li>
+</ol>
+```
+
+The color is decoration: write the state in the text too.
+
+## Avatars and icons
+
+An [`.avatar`](avatar.md) or an `aria-hidden` icon written first in the `<li>`
+replaces the dot. One such event widens the rail for the whole list, so dots
+and slots stay aligned. An icon sits in a disc colored by the event's intent.
+
+```html demo
+<ol class="timeline">
+  <li>
+    <span class="avatar primary"><abbr>AM</abbr></span>
+    <time datetime="2026-10-18T09:30">Today, 09:30</time>
+    <a href="#">Ada Morgan</a> approved the security terms.
+  </li>
+  <li class="success">
+    <i class="ti ti-check" aria-hidden="true"></i>
+    <time datetime="2026-10-17">Yesterday</time>
+    Contract signed
+  </li>
+  <li>
+    <time datetime="2026-10-15">October 15</time>
+    Account created
+  </li>
+</ol>
+```
+
+## Density
+
+The gap between events follows the density context: `.compact` and
+`.spacious` on the list or an ancestor tighten or loosen it.
+
+```html demo
+<ol class="timeline compact">
+  <li><time datetime="2026-10-18">Today</time>Build passed</li>
+  <li><time datetime="2026-10-17">Yesterday</time>Build failed</li>
+  <li><time datetime="2026-10-16">October 16</time>Build passed</li>
+</ol>
+```
+
+## Hooks
+
+- `--timeline-dot-size` — dot diameter.
+- `--timeline-slot-size` — avatar and icon diameter; the rail takes this width
+  as soon as one event has a slot.
+- `--timeline-gap` — space between events; follows `--density-space`.
+- `--timeline-inline-gap` — space between the rail and the content.
+- `--timeline-line-size` — rail line thickness.

package/docs/pages/enhancements/tabs.md

@@ -4,11 +4,13 @@
 
 ## 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. |
+| `.tabs-attached` | Component | Joins a horizontal tablist to its panels.    |
+| `.tab-panel`     | Part      | Framed panel inside `.tabs-attached`.        |
 
 ## Usage
 
@@ -89,6 +91,43 @@ JavaScript involved:
 </nav>
 ```
 
+## Attached panels
+
+For attached tabs (folder tabs, connected or enclosed panels), wrap the
+horizontal tablist and its panels as direct children of `.tabs-attached`.
+Put `.tab` buttons directly in the strip and `.tab-panel` on each panel.
+The selected tab and panel share one surface; selection uses the open edge
+instead of an underline.
+The selected tab uses the panel fill and text color; intent classes such as
+`.primary` do not tint it. `.tab-panel` receives its frame only as a direct
+child of `.tabs-attached`.
+Keep the wrapper free of layout gaps and panel background overrides.
+
+```html demo
+<div class="tabs-attached">
+  <div class="tabs" role="tablist" aria-label="Traffic" data-enhance="tabs">
+    <button class="tab" type="button" role="tab" id="traffic-overview-tab"
+            aria-selected="true" aria-controls="traffic-overview">Overview</button>
+    <button class="tab" type="button" role="tab" id="traffic-activity-tab"
+            aria-selected="false" aria-controls="traffic-activity" tabindex="-1">Activity</button>
+  </div>
+  <section class="tab-panel" role="tabpanel" id="traffic-overview"
+           aria-labelledby="traffic-overview-tab" tabindex="-1">
+    Traffic is up 12% week over week, led by organic search.
+  </section>
+  <section class="tab-panel" role="tabpanel" id="traffic-activity"
+           aria-labelledby="traffic-activity-tab" tabindex="-1" hidden>
+    Recent activity appears here.
+  </section>
+</div>
+```
+
+Set `--tab-panel-bg`, `--tab-panel-pad`, and `--tab-panel-shadow` on
+`.tabs-attached` to customize the shared fill, panel padding and elevation.
+The neo-brutalist demo theme supplies the panel shadow. Use ordinary `.tabs`
+for vertical rails or navigation links; attached tabs are a horizontal panel
+switcher. Long strips retain horizontal scrolling and keyboard navigation.
+
 ## Equal-width tabs
 
 To make a few tabs share the strip's width (full-width, fill), set
@@ -160,8 +199,11 @@ the current item of the strip. This is the only place a `.tab` takes `true`.
 Do not put a flyout trigger in a `role="tablist"`: a tablist holds only
 `role="tab"` items, and the arrow keys of the two widgets collide.
 
-## CSS hooks
+### Hooks
 
 - `--tab-flex` — flex of each item; set `1 1 0` on the strip for equal-width tabs
   (fill the width). A strip that cannot fit its labels still scrolls.
 - `--tab-gap` — space between an icon and the label text (default `0.375em`).
+- `--tab-panel-bg` — shared fill for the attached panel and selected tab.
+- `--tab-panel-pad` — attached panel padding.
+- `--tab-panel-shadow` — attached panel elevation; the strip casts no shadow.

package/docs/pages/examples/overview.md

@@ -33,6 +33,7 @@ Whole pages, composed the way a real product would.
 - [Workspace settings](../../demo/templates/settings-pricing.html) - plans with visible native choices, preferences and segmented tabs
 - [iOS-style settings](../../demo/templates/settings-ios.html) - iOS-like controls and grouped settings from unchanged framework markup, a local theme, and its findings listed rule by rule
 - [Card compositions](../../demo/templates/card-compositions.html) - editorial, team, sign-in and horizontal cards composed from existing primitives
+- [Neo-brutalist](../../demo/templates/neo-brutalist.html) - a risograph print studio on the `neo-brutalist` theme (order alerts, plus-marker FAQ, ruled testimonial grid, docked cookie banner) with the page loading its own fonts
 - [Register form](../../demo/templates/register-form.html) - registration page with choice cards, masks, the password toggle, `tel-prefix` validation, an OTP verification dialog, and status feedback
 
 ### Layout references
@@ -63,6 +64,8 @@ extension points.
 - [Data grid](../../demo/templates/data-grid.html) - an external data grid component themed with Actual tokens (sort, filter, search, selection)
 - [Combobox](../../demo/templates/combobox.html) - an external combobox themed with Actual tokens (search, tags, autocomplete)
 - [Date fields](../../demo/templates/date-fields.html) - a native date input, a masked text field and an external date picker on Actual tokens, side by side
+- [File upload](../../demo/templates/file-upload.html) - the native file input, Dropzone rendering its file rows as Actual components, and FilePond on Actual tokens
+- [Diagrams](../../demo/templates/diagrams.html) - Mermaid timelines, Gantt charts and flowcharts drawn by Pele through a small web component, on Actual tokens
 
 ## Sites
 

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

@@ -197,6 +197,9 @@ The dot is `::before`: a full-chip layer clipped to a `circle()` centred on
 the check slot (`--choice-chip-dot`). A theme can grow it into a selected fill
 by widening the clip, as the `material` theme does.
 
+The check uses `--state-selected-text` when the theme sets it, including on
+chips with an explicit intent. Otherwise it follows the chip's intent.
+
 ## CSS hooks
 
 - `--choice-card-pad` — inner padding.