actual-css 0.2.0 → 0.3.0

package/docs/pages/components/accordion.md

@@ -0,0 +1,80 @@
+# Accordion
+
+> Collapsible regions built on native details and summary, with optional exclusive groups via the name attribute.
+
+- 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.
+
+```html demo
+<div class="accordion">
+  <details open>
+    <summary>A paragraph body that is opened</summary>
+    <p>This is a paragraph.</p>
+  </details>
+
+  <details>
+    <summary>With a list</summary>
+    <ul>
+      <li>First item</li>
+      <li>Second item</li>
+    </ul>
+  </details>
+
+  <details>
+    <summary>
+      <i class="ti ti-settings" aria-hidden="true"></i>
+      <span>With a custom icon</span>
+    </summary>
+    <div>
+      <p>Any valid flow content can be used here.</p>
+    </div>
+  </details>
+</div>
+```
+
+## Exclusive groups
+
+```html demo
+<div class="accordion">
+  <details name="settings">
+    <summary>This is grouped with the next one</summary>
+    <p>Using the <code>name</code> attribute groups items like radio buttons.</p>
+  </details>
+
+  <details name="settings">
+    <summary>This is grouped with the previous one</summary>
+    <p>Only one item in the same named group can be open.</p>
+  </details>
+</div>
+```
+
+## Custom markers
+
+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.
+
+```html
+<div class="accordion accordion-demo">
+  <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>
+  </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>
+  </details>
+</div>
+```
+
+## CSS hooks
+
+- `--accordion-radius` — outer corner radius.
+- `--accordion-marker-color` — color of the end marker; forced-colors mode overrides it to `CanvasText`.

package/docs/pages/components/alert.md

@@ -0,0 +1,203 @@
+# Alert
+
+> Inline status messages for confirmations, warnings, and errors, with intents, icons, and action lists.
+
+- Supports intent colors.
+- Supports longer text and lists.
+- Links inherit alert color by default.
+- Alerts are soft by default. Use `.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.
+- Could have simple or complex html content.
+- 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 `.sm` or `.lg` 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.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.alert` | Component | Inline status surface; soft by default. |
+| `.alert-icon` | Composition | Decorative leading icon; pins to the first grid column. |
+| `.alert-dismiss` | Modifier | Compact dismiss button using the `--icon-close` mask and the `--dismiss` command. |
+| `.callout` | Variant | Neutral panel with a thick accent border on the leading edge. |
+| `.admonition` | Variant | Structured box with a tinted title bar and body on the page surface. |
+| `.alert-title` | Composition | Admonition title bar; hosts the dismiss button. |
+| `.alert-body` | Composition | Admonition body resting on the page surface. |
+| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
+| Shared variants | Variant | `.solid` and `.outline` emphasis. |
+| `.sm` / `.lg` | Size | Density; inline padding stays stable. |
+
+## Basic usage
+
+```html demo
+<div class="stack">
+  <div class="alert success">
+    <i class="ti ti-circle-check alert-icon" aria-hidden="true"></i>
+    <div>Your changes have been saved. <a href="#">View activity</a>.</div>
+  </div>
+
+  <div class="alert warning" role="alert">
+    <svg class="alert-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0Z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
+    <div>Please review the <a href="#">failed checks</a> before continuing.</div>
+  </div>
+
+  <div class="alert">
+    <svg class="alert-icon" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M5.255 5.786a.237.237 0 0 0 .241.247h.825c.138 0 .248-.113.266-.25.09-.656.54-1.134 1.342-1.134.686 0 1.314.343 1.314 1.168 0 .635-.374.927-.965 1.371-.673.489-1.206 1.06-1.168 1.987l.003.217a.25.25 0 0 0 .25.246h.811a.25.25 0 0 0 .25-.25v-.105c0-.718.273-.927 1.01-1.486.609-.463 1.244-.977 1.244-2.056 0-1.511-1.276-2.241-2.673-2.241-1.267 0-2.655.59-2.75 2.286m1.557 5.763c0 .533.425.927 1.01.927.609 0 1.028-.394 1.028-.927 0-.552-.42-.94-1.029-.94-.584 0-1.009.388-1.009.94"/></svg>
+    <div>This is a default alert message.</div>
+  </div>
+
+  <div class="alert danger" role="alert">
+    <strong>Error!</strong>
+    <div>Something went wrong.</div>
+  </div>
+
+  <div class="alert danger" role="alert">
+    I'm a simple error
+  </div>
+
+  <div class="alert danger" role="alert">
+    I'm a simple error <a href="#">with a link and no joke</a>
+  </div>
+</div>
+```
+
+## Content and actions
+
+```html demo
+<div class="alert danger" role="alert">
+  <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
+
+  <div class="stack">
+    <strong>Payment failed.</strong>
+    <p>Check your billing details or try another card.</p>
+
+    <menu class="actions cluster">
+      <li><a class="btn danger sm" href="/billing">Update billing</a></li>
+      <li><a href="/support">Contact support</a></li>
+    </menu>
+  </div>
+</div>
+```
+
+## Variants
+
+```html demo
+<div class="stack">
+  <div class="alert danger sm" role="alert">
+    I'm a small error
+  </div>
+
+  <div class="alert danger lg" role="alert">
+    I'm a large error
+  </div>
+
+  <div class="alert danger outline" role="alert">
+    I'm an outline error <a href="#">with a link</a>
+  </div>
+
+  <div class="alert danger solid" role="alert">
+    I'm a solid error <a href="#">with a link</a>
+  </div>
+</div>
+```
+
+## 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.
+
+```html demo
+<div class="alert warning" id="warning-alert">
+  <i class="ti ti-alert-triangle alert-icon" aria-hidden="true"></i>
+  <div>
+    <strong>Warning</strong>
+    <p>Something needs your attention.</p>
+  </div>
+  <button
+    class="alert-dismiss"
+    type="button"
+    commandfor="warning-alert"
+    command="--dismiss"
+    aria-label="Dismiss alert"
+  ></button>
+</div>
+```
+
+In an admonition, place `.alert-dismiss` 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"
+      type="button"
+      commandfor="notice"
+      command="--dismiss"
+      aria-label="Dismiss alert"
+    ></button>
+  </div>
+  <div class="alert-body">...</div>
+</div>
+```
+
+## Callout
+
+Use `.callout` for a neutral panel with a thick accent border on the leading edge. Intent classes tint the border color.
+
+```html demo
+<div class="stack">
+  <div class="alert callout">
+    <strong>Note</strong>
+    <p>This is a callout — a neutral panel with a thick accent border on the leading edge.</p>
+  </div>
+
+  <div class="alert warning callout" role="alert">
+    <strong>Heads up</strong>
+    <p>The border color follows the intent. No other borders are drawn.</p>
+  </div>
+</div>
+```
+
+## Admonition
+
+An admonition is a structured box with a tinted title bar, an optional icon, and body content on the page surface — like the `!!! note` callouts in mkdocs. Use `.alert-title` for the header and `.alert-body` for the content. Intent classes tint the title bar background and the border.
+
+```html demo
+<div class="stack">
+  <div class="alert admonition">
+    <div class="alert-title">
+      <i class="ti ti-info-circle" aria-hidden="true"></i>
+      Note
+    </div>
+    <div class="alert-body">
+      <p>An admonition with a tinted title bar. The body rests on the page background.</p>
+    </div>
+  </div>
+
+  <div class="alert warning admonition">
+    <div class="alert-title">
+      <i class="ti ti-alert-triangle" aria-hidden="true"></i>
+      Warning
+    </div>
+    <div class="alert-body">
+      <p>The intent tints the title bar, the border, and the body uses <code>var(--surface)</code>.</p>
+    </div>
+  </div>
+</div>
+```
+
+## CSS hooks
+
+- `--alert-pad-inline` — inline padding. Stays stable across `.sm`/`.lg`.
+- `--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.
+- `--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.
+
+Prefer intents and shared variants for alert colors rather than overriding the
+internal color plumbing directly.

package/docs/pages/components/aura.md

@@ -0,0 +1,35 @@
+# Aura
+
+> **Optional** — import `actual-css/css/optional/aura` or `actual-css/css/optional/index`.
+
+Aura adds a decorative intent-colored border and halo around one direct child.
+It is visual emphasis only and does not change the child's semantics.
+
+```html demo
+<div class="cluster">
+  <span class="aura primary">
+    <button class="btn" type="button">Publish</button>
+  </span>
+
+  <span class="aura aura-glow secondary">
+    <span class="badge">New</span>
+  </span>
+</div>
+```
+
+The animated conic frame runs only when the user has not requested reduced
+motion. Add `.aura-glow` for a static, solid frame. The component uses an
+intent such as `.primary`, `.success`, or `.danger`; it does not introduce
+separate aura color variants.
+
+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.
+
+## CSS hooks
+
+- `--aura-color` — frame and halo color; follows the local intent.
+- `--aura-width` — frame thickness.
+- `--aura-blur` — halo blur radius.
+- `--aura-radius` — child corner radius used to derive the outer radius.
+- `--aura-duration` — rotation duration when motion is allowed.

package/docs/pages/components/avatar.md

@@ -0,0 +1,95 @@
+# Avatar
+
+> Initials or image representing a person or entity, composable with a status dot.
+
+- Supports initials and images.
+- 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.
+- 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`).
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.avatar` | Component | Initials or image in a circular box; works on `div`, `a`, and `button`. |
+| `.avatar-stack` | Composition | Overlapping avatar group. |
+| `.badge:empty` (inside `.avatar`) | Composition | Status dot at the bottom-end corner; give it an `aria-label`. |
+| `.sm` / `.lg` | Size | Density; also rescales the whole `.avatar-stack`. |
+
+## Basic usage
+
+```html demo
+<div class="avatar" role="img" aria-label="John Doe, online">
+  <span aria-hidden="true">JD</span>
+  <span class="badge success" aria-label="Online"></span>
+</div>
+
+<div class="avatar lg" role="img" aria-label="John Doe, online">
+  <span aria-hidden="true">JD</span>
+  <span class="badge success" aria-label="Online"></span>
+</div>
+
+<div class="avatar sm" role="img" aria-label="John Doe, errors">
+  <span aria-hidden="true">JD</span>
+  <span class="badge danger" aria-label="2 errors"></span>
+</div>
+```
+
+The avatar keeps the same visual box across semantics — as a link or button it
+gains hover and pressed feedback.
+
+```html demo
+<a href="#" class="avatar">
+  <img src="https://mockmind-api.uifaces.co/content/human/219.jpg" alt="Jane Doe" />
+</a>
+
+<div class="flyout-trigger">
+  <button type="button"
+          class="avatar"
+          data-enhance="flyout"
+          aria-haspopup="menu"
+          aria-expanded="false"
+          aria-controls="profile-menu"
+          id="profile-trigger"
+          aria-label="Jane Doe, open profile menu">
+    <img src="https://mockmind-api.uifaces.co/content/human/219.jpg" alt="" />
+  </button>
+  <menu class="flyout menu" id="profile-menu" aria-labelledby="profile-trigger" hidden>
+    <li><a class="menu-item" href="#profile">View profile</a></li>
+    <li><button class="menu-item" type="button">Sign out</button></li>
+  </menu>
+</div>
+```
+
+## Avatar stack
+
+```html demo
+<div class="avatar-stack" role="group" aria-label="Team members">
+  <div class="avatar" role="img" aria-label="John Doe" style="--avatar-bg:#E5EEE4">
+    <span aria-hidden="true">JD</span>
+  </div>
+  <div class="avatar" role="img" aria-label="Jane Doe" style="--avatar-bg:#F6F4E8">
+    <span aria-hidden="true">JD</span>
+  </div>
+  <div class="avatar" role="img" aria-label="99 more team members" style="--avatar-bg:#744577;" data-tone="dark">
+    <span aria-hidden="true">+99</span>
+  </div>
+</div>
+```
+
+## CSS hooks
+
+- `--avatar-size` — inline and block size.
+- `--avatar-radius` — corner radius; set a smaller value for squared avatars.
+- `--avatar-bg` — background; `data-tone` adjusts the derived foreground.
+- `--avatar-stack-size` — stack-scoped size that each avatar falls back to.
+- `--avatar-stack-overlap` — how far stacked avatars overlap.
+- `--avatar-stack-ring` — separating ring width inside `.avatar-stack`.
+
+Prefer intents for avatar colors. Inside `.avatar-stack`, `--avatar-size` falls
+back to a stack-scoped value so the whole group resizes together with `.sm`/`.lg`;
+set `--avatar-size` on an individual avatar to opt one out.
+`--avatar-stack-overlap` is derived from `--avatar-stack-size`, not `--avatar-size`.

package/docs/pages/components/badge.md

@@ -0,0 +1,102 @@
+# Badge
+
+> Compact label for counts, status, or category tags, with shared intents and variants.
+
+- Supports intent colors.
+- Soft by default. Use `.solid` for counters and notification badges, or `.outline` for quieter emphasis.
+- Dots stay solid regardless of variant.
+- Use `.sm` or `.lg` for compact density changes.
+- Can be used inline in headings.
+- Can be used as a count badge.
+- Can be used as a stable dot badge when empty and given an accessible name.
+- Empty badges render as dots. The element must be truly empty: no text and no whitespace.
+
+A badge is **content-sized**: it never stretches to fill its container, even as a
+direct child of `.stack` (where flex children otherwise stretch). Use
+`inline-size: 100%` — or the optional `.inline-size-full` utility — when a
+full-width badge is intentional.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.badge` | Component | Compact label; soft by default. |
+| `.badge:empty` | Composition | Truly-empty badge renders as a solid dot. |
+| Shared intents | Intent | `.primary`, `.secondary`, `.success`, `.warning`, `.danger`. |
+| Shared variants | Variant | `.solid` (filled) and `.outline` (bordered) emphasis. |
+| `.sm` / `.lg` | Size | Compact density. |
+
+## Basic usage
+
+```html demo
+<span class="badge">Default</span>
+<span class="badge secondary">Secondary</span>
+<span class="badge success">Success</span>
+<span class="badge warning">Warning</span>
+<span class="badge danger">Danger</span>
+<span class="badge success outline">Outline success</span>
+<span class="badge warning soft">Soft warning</span>
+```
+
+## In a title
+
+```html demo
+<h2>New features <span class="badge success soft">New</span></h2>
+```
+
+## Composed
+
+```html demo
+<button type="button" class="btn ghost" aria-label="Notifications">
+  <i class="ti ti-bell" aria-hidden="true"></i>
+  <span class="badge danger solid" aria-label="12 unread notifications">12</span>
+</button>
+
+<button type="button" class="btn secondary soft" aria-label="Notifications">
+  <i class="ti ti-bell" aria-hidden="true"></i>
+  <span class="badge danger" aria-label="Errors!"></span>
+</button>
+```
+
+## Empty badge dot
+
+```html demo
+<span class="badge success" aria-label="Online"></span>
+```
+
+The dot conveys no text, so an `aria-label` is required for it to mean anything.
+
+## Size variants
+
+```html demo
+<span class="badge success sm">Small Success</span>
+<span class="badge success">Regular Success</span>
+<span class="badge success lg">Large Success</span>
+```
+
+## 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.
+
+```html demo
+<span class="badge primary soft">
+  Design
+  <button type="button" aria-label="Remove Design">
+    <i class="ti ti-x" aria-hidden="true"></i>
+  </button>
+</span>
+<span class="badge primary soft">
+  <button type="button" aria-label="Remove Design">
+    <i class="ti ti-x" aria-hidden="true"></i>
+  </button>
+  Design
+</span>
+```
+
+## CSS hooks
+
+- `--badge-radius` — corner radius.
+- `--badge-size` — minimum block size; also the square size of an `:empty` dot badge.
+- `--badge-dot-size` — size of an `:empty` dot badge.
+- `--badge-font-size` — label font size.
+- `--badge-pad-x` — inline padding.

package/docs/pages/components/breadcrumb.md

@@ -0,0 +1,19 @@
+# Breadcrumb
+
+> Trail of links showing the current page's location in a hierarchy.
+
+- Use a semantic `<nav>` landmark.
+- Put `.breadcrumb` on the ordered list.
+- Use `aria-current="page"` for the current page.
+- Separators are generated with CSS (`li + li::before`).
+
+```html demo
+<nav aria-label="Breadcrumb">
+  <ol class="breadcrumb">
+    <li><a href="/home">Home</a></li>
+    <li><a href="/projects">Projects</a></li>
+    <li><a href="/projects/docs">Docs</a></li>
+    <li><a href="/current" aria-current="page">Breadcrumb</a></li>
+  </ol>
+</nav>
+```