actual-css 0.2.0 → 0.3.1

package/docs/pages/components/button.md

@@ -0,0 +1,210 @@
+# Button
+
+Actions and navigation with shared intents, variants, sizes, and loading, pressed, and disabled states.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.btn` | Component | Base button. Solid by default; works on `<button>`, `<a href>`, and button-like `<input>`. |
+| `.primary` | Intent | Primary action. |
+| `.secondary` | Intent | Secondary action. |
+| `.success` | Intent | Positive outcome. |
+| `.warning` | Intent | Caution. |
+| `.danger` | Intent | Destructive action. |
+| `.neutral` | Intent | Neutral tone (the `.btn` default). |
+| `.soft` | Variant | Muted intent-tinted surface. |
+| `.outline` | Variant | Transparent with an intent-colored border. |
+| `.solid` | Variant | Filled intent background — the `.btn` default. |
+| `.ghost` | Variant | Borderless text button (button-only). |
+| `.link` | Variant | Underlined text button (button-only). |
+| `.sm` / `.lg` | Size | Compact or large control height. |
+| `.icon-only` | Variant | Square icon button sized to the control height. |
+
+## Basic usage
+
+Use `.btn` on actionable elements: `<button>`, `<a href>`, or
+`input[type="button"|"submit"|"reset"]`. Use a real `<button>` for actions and
+`<a class="btn">` for navigation.
+
+```html demo
+<div class="cluster">
+  <button class="btn" type="button">Default</button>
+  <button class="btn primary" type="button">Primary</button>
+  <a class="btn primary" href="#">Account</a>
+  <input class="btn" type="button" value="Input button" />
+</div>
+```
+
+## Intents
+
+Shared intent classes set color meaning. They compose with every variant.
+
+```html demo
+<div class="cluster">
+  <button class="btn primary" type="button">Primary</button>
+  <button class="btn secondary" type="button">Secondary</button>
+  <button class="btn success" type="button">Success</button>
+  <button class="btn warning" type="button">Warning</button>
+  <button class="btn danger" type="button">Danger</button>
+  <button class="btn neutral" type="button">Neutral</button>
+</div>
+```
+
+## Variants
+
+`.ghost` and `.link` are button-only; `.soft`, `.outline`, and `.solid` are
+shared with other components.
+
+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.
+
+```html demo
+<div class="cluster">
+  <button class="btn outline" type="button">Outline</button>
+  <button class="btn danger outline" type="button">Danger outline</button>
+  <button class="btn soft" type="button">Soft</button>
+  <button class="btn danger soft" type="button">Danger soft</button>
+  <button class="btn ghost" type="button">Ghost</button>
+  <button class="btn link" type="button">Button as link</button>
+</div>
+```
+
+### Icon and icon-only buttons
+
+```html demo
+<div class="cluster">
+  <button class="btn" type="button"><i class="ti ti-star" aria-hidden="true"></i> With an icon</button>
+  <button class="btn icon-only" type="button" aria-label="Add">
+    <i class="ti ti-plus" aria-hidden="true"></i>
+  </button>
+  <button class="btn primary icon-only" type="button" aria-label="Search">
+    <i class="ti ti-search" aria-hidden="true"></i>
+  </button>
+</div>
+```
+
+Use `.btn.icon-only` for a square icon button sized to the control height.
+Always name it with an `aria-label` since there is no visible text.
+
+### Button groups
+
+Join adjacent buttons with `.join`. The joined group is not a new component —
+the buttons keep their own variants.
+
+```html demo
+<div class="join" role="group" aria-label="Text alignment">
+  <button class="btn" type="button">Left</button>
+  <button class="btn outline" type="button">Center</button>
+  <button class="btn soft" type="button">Right</button>
+</div>
+```
+
+## Sizes
+
+Prefer `.sm` and `.lg` over setting sizes directly. Density variants never
+change typography.
+
+```html demo
+<div class="cluster">
+  <button class="btn sm" type="button">Small</button>
+  <button class="btn" type="button">Regular</button>
+  <button class="btn lg" type="button">Large</button>
+</div>
+```
+
+## States
+
+### Disabled
+
+Disable a `<button>` or `<input>` with the native `disabled` attribute. Anchors
+have no native disabled state, so `<a class="btn" aria-disabled="true">` is the
+supported way to style a disabled link button; application code must also
+prevent the click since `aria-disabled` does not stop navigation on its own.
+
+```html demo
+<div class="cluster">
+  <button class="btn primary" type="button" disabled>Disabled</button>
+  <button class="btn outline" type="button" disabled>Disabled outline</button>
+  <a class="btn outline" href="#" aria-disabled="true">Disabled link</a>
+</div>
+```
+
+### Loading
+
+Set `aria-busy="true"` on the button and add a `.spinner`. The spinner inherits
+the button size.
+
+```html demo
+<div class="cluster">
+  <button class="btn primary" type="button" aria-busy="true" disabled>
+    <span class="spinner" aria-hidden="true"></span>
+    Saving…
+  </button>
+</div>
+```
+
+### Toggle
+
+Use `aria-pressed` for toggle buttons. Actual styles the pressed state;
+application code owns changing the attribute. The example scopes its script to
+its own preview so repeated demos on a page cannot cross-bind.
+
+```html demo
+<div class="cluster">
+  <button class="btn" type="button" aria-pressed="false">Bold</button>
+  <button class="btn" type="button" aria-pressed="false">Italic</button>
+</div>
+<script>
+  (() => {
+    const preview = document.currentScript.closest(".docs-preview");
+    for (const button of preview.querySelectorAll("button")) {
+      button.addEventListener("click", () => {
+        const pressed = button.getAttribute("aria-pressed") === "true";
+        button.setAttribute("aria-pressed", String(!pressed));
+      });
+    }
+  })();
+</script>
+```
+
+For exclusive groups, manage a single pressed button:
+
+```html demo
+<div class="join" role="group" aria-label="Text alignment" data-docs-toggle-group>
+  <button class="btn" type="button" aria-pressed="true">Left</button>
+  <button class="btn outline" type="button" aria-pressed="false">Center</button>
+  <button class="btn outline" type="button" aria-pressed="false">Right</button>
+</div>
+<script>
+  (() => {
+    const preview = document.currentScript.closest(".docs-preview");
+    const group = preview.querySelector("[data-docs-toggle-group]");
+    group.addEventListener("click", (event) => {
+      const button = event.target.closest("button[aria-pressed]");
+      if (!button || !group.contains(button)) return;
+      for (const item of group.querySelectorAll("button[aria-pressed]")) {
+        item.setAttribute("aria-pressed", String(item === button));
+      }
+    });
+  })();
+</script>
+```
+
+## Accessibility
+
+- Always set `type="button"` when a button is not submitting a form.
+- Use a real `<button>` for actions and `<a class="btn">` for navigation.
+- Toggle buttons expose their state with `aria-pressed`; the component styles
+  the pressed state but application code owns toggling the attribute.
+- Disabled `<button>` and `<input>` use the native `disabled` attribute;
+  disabled link buttons use `aria-disabled="true"` plus an app-side
+  activation guard.
+
+## 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`).

package/docs/pages/components/card.md

@@ -0,0 +1,195 @@
+# Card
+
+Flexible content container with optional header, body, and footer regions, plus full-bleed children.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.card` | Component | Neutral raised surface for grouped content. |
+| `.raised` | Variant | Elevated surface with a soft shadow. |
+| `.subtle` | Variant | Lower contrast against the page surface. |
+| `.inverted` | Surface modifier | Inverse surface treatment: paints `--surface-solid` and swaps the foreground to `--surface`, so it inverts in dark themes instead of always reading as dark. Apply as `class="card inverted"`, or on any block. |
+| `.compact` | Variant | Tighter padding for dense contexts. |
+
+## Basic usage
+
+Use semantic elements inside the card. A direct `<header>` or `<footer>` is the
+card's structural slot. Cards do not own page spacing — compose them with
+layout primitives like `.grid`.
+
+```html demo
+<div style="max-inline-size: 32rem">
+  <article class="card stack">
+    <header>
+      <hgroup>
+        <h3>Understanding Semantic HTML</h3>
+        <p class="muted">A quick primer for new contributors</p>
+      </hgroup>
+    </header>
+
+    <p>Using the right HTML tags improves both SEO and accessibility. Lean on landmarks and live lists.</p>
+
+    <ul class="cluster" style="list-style: none; padding: 0; margin: 0; gap: 0.5rem" aria-label="Tags">
+      <li><span class="badge primary soft secondary">HTML</span></li>
+      <li><span class="badge soft primary">Accessibility</span></li>
+      <li><span class="badge outline">5 min read</span></li>
+    </ul>
+
+    <footer>
+      <time datetime="2026-06-12" class="muted">June 12, 2026</time>
+      <button type="button" class="btn outline">Read more</button>
+    </footer>
+  </article>
+</div>
+```
+
+## Bleed
+
+Use `.bleed` on a direct child to escape the card padding — full-width images,
+colored headers, or footers.
+
+```html demo
+<div style="max-inline-size: 32rem">
+  <article class="card stack">
+    <img class="bleed" src="https://picsum.photos/seed/actual-css-card/600/300" alt="Coastal cliffs at dusk" />
+    <header>
+      <h3>Coastal cliffs at dusk</h3>
+    </header>
+    <section class="stack" aria-label="Summary">
+      <p>A short caption that wraps across a few lines. The image bleeds to the card edges.</p>
+    </section>
+    <footer>
+      <span class="badge primary soft">Photo</span>
+      <button type="button" class="btn outline">View</button>
+    </footer>
+  </article>
+</div>
+```
+
+```html demo
+<article class="card stack" style="--card-max-inline-size: 24rem">
+  <header class="bleed stack items-center text-center" style="background: var(--surface-subtle)">
+    <hgroup>
+      <h3>Team</h3>
+      <p class="muted">For growing products</p>
+    </hgroup>
+    <p>
+      <span style="font-size: 2rem; font-weight: var(--font-weight-strong); line-height: 1">$24</span>
+      <span class="muted">/ user / month</span>
+    </p>
+  </header>
+
+  <ul class="stack items-center" style="list-style: none; padding: 0">
+    <li>Unlimited projects</li>
+    <li>Up to 25 seats</li>
+    <li>Shared workspaces</li>
+    <li>Priority support</li>
+  </ul>
+
+  <footer class="bleed" style="background: var(--surface-subtle); justify-content: center">
+    <a class="btn primary" href="#">Upgrade</a>
+  </footer>
+</article>
+```
+
+## In grids
+
+Cards display nicely in grids with equal-height behavior.
+
+```html demo
+<section class="grid">
+  <article class="card">
+    <header>
+      <h3>Components</h3>
+    </header>
+    <p>Buttons, alerts, dialogs — all opt-in.</p>
+    <footer>
+      <a class="btn outline" href="#">Browse</a>
+    </footer>
+  </article>
+
+  <article class="card">
+    <header>
+      <h3>Layout</h3>
+    </header>
+    <p>Stack, cluster, grid, switcher, sidebar.</p>
+    <footer>
+      <a class="btn outline" href="#">Browse</a>
+    </footer>
+  </article>
+
+  <article class="card">
+    <header>
+      <h3>Patterns</h3>
+    </header>
+    <p>Actions, nav-list — small structural helpers.</p>
+    <footer>
+      <a class="btn outline" href="#">Browse</a>
+    </footer>
+  </article>
+</section>
+```
+
+## Surfaces
+
+`.inverted` creates a contrasting surface context, not a complete theme island.
+On a bare block (`<header class="inverted">`, `<section class="inverted">`) it
+paints the surface directly; contextual content and transparent treatments such
+as `.btn.outline`, `.btn.ghost`, and `.btn.link` follow its foreground.
+
+Apply it directly to a component that consumes the shared `--ui-*` surface
+contract (`.card`, `.navbar`, `.alert`, `.badge`) to treat that component as the
+contrasting surface. A surface-owning component nested inside an inverted block
+keeps its own surface and establishes a new context for its descendants. Use a
+`data-theme` island when every component and form control in a subtree must use
+another theme.
+
+More specific component states or explicit surface variants still take
+precedence: `.card.inverted.subtle` keeps the `.subtle` background while the
+foreground stays inverted.
+
+`.inverted` and `.subtle` are competing surface treatments — do not combine
+them. `.subtle` paints the card's background directly while `.inverted` swaps
+the surface tokens, so `.card.subtle.inverted` renders a subtle background with
+inverted foreground. Treat them as mutually exclusive, like two competing
+variants.
+
+```html demo
+<section class="grid">
+  <article class="card raised">
+    <hgroup>
+      <h3>Raised</h3>
+      <p class="muted">Elevated surface with a soft shadow.</p>
+    </hgroup>
+  </article>
+
+  <article class="card subtle">
+    <hgroup>
+      <h3>Subtle</h3>
+      <p class="muted">Lower contrast against the page surface.</p>
+    </hgroup>
+  </article>
+
+  <article class="card inverted stack">
+    <hgroup>
+      <h3>Inverted</h3>
+      <p>Inverse surface for emphasis. Text inherits the contrasting surface color.</p>
+    </hgroup>
+    <button type="button" class="btn">Action</button>
+  </article>
+
+  <article class="card compact">
+    <hgroup>
+      <h3>Compact</h3>
+      <p class="muted">Tighter padding for dense contexts.</p>
+    </hgroup>
+  </article>
+</section>
+```
+
+## CSS hooks
+
+- `--card-radius` — corner radius.
+- `--card-max-inline-size` — maximum width.
+- `--card-pad` — inner padding; also drives the negative offsets that let a `.bleed` child reach the card edge. `.compact` lowers it.

package/docs/pages/components/chat.md

@@ -0,0 +1,50 @@
+# Chat
+
+> **Optional** — import `actual-css/css/optional/chat` or `actual-css/css/optional/index`.
+
+Chat lays out message metadata, an optional avatar, and a content-sized bubble
+at either edge of a conversation.
+
+```html demo
+<div class="stack" aria-label="Conversation">
+  <div class="chat chat-start">
+    <div class="chat-avatar avatar sm" role="img" aria-label="Thomas">
+      <span aria-hidden="true">T</span>
+    </div>
+    <div class="chat-header">
+      Thomas <time datetime="2026-08-18T21:30">21:30</time>
+    </div>
+    <div class="chat-bubble">Are we still shipping today?</div>
+    <div class="chat-footer">Delivered</div>
+  </div>
+
+  <div class="chat chat-end">
+    <div class="chat-header">You</div>
+    <div class="chat-bubble primary">Yes, the checks are green.</div>
+  </div>
+</div>
+```
+
+Use `.chat-start` and `.chat-end` for logical inline placement, so the layout
+also follows right-to-left writing direction. The avatar is optional. Bubble
+colors compose with intents and shared variants: `.primary`, `.primary.soft`,
+and `.primary.outline` all work without chat-specific color classes.
+
+For a live conversation, put an appropriate live-region or `role="log"` on the
+conversation container according to the product's announcement needs. Do not
+put `role="log"` on individual messages.
+
+## Class reference
+
+| Class | Description |
+|---|---|
+| `.chat` | Message row grid. |
+| `.chat-start` / `.chat-end` | Logical inline placement. |
+| `.chat-avatar` | Avatar grid slot; compose it with `.avatar`. |
+| `.chat-header` / `.chat-footer` | Muted message metadata. |
+| `.chat-bubble` | Content-sized message surface. |
+
+## CSS hooks
+
+- `--chat-gap` — gap between the avatar and message content.
+- `--chat-max-size` — maximum inline size of a bubble.