actual-css 0.2.0 → 0.3.0

package/docs/pages/patterns/navigation-list.md

@@ -0,0 +1,235 @@
+# Navigation List
+
+Use `.nav-list` for a semantic list of navigation links.
+
+It removes native list chrome but does not force a direction. Combine it with layout primitives depending on context.
+
+```html demo
+<div class="stack">
+  <h2>Navigation</h2>
+  <nav aria-label="Main navigation">
+    <ul class="nav-list cluster">
+      <li><a href="/docs">Docs</a></li>
+      <li><a href="/components">Components</a></li>
+      <li><a href="/examples">Examples</a></li>
+    </ul>
+  </nav>
+  <h2>Documentation</h2>
+  <nav aria-label="Documentation">
+    <ul class="nav-list stack">
+      <li><a href="/docs/getting-started" aria-current="page">Getting started</a></li>
+      <li><a href="/docs/tokens">Tokens</a></li>
+      <li><a href="/docs/layout">Layout</a></li>
+      <li><a href="/docs/components">Components</a></li>
+    </ul>
+  </nav>
+</div>
+```
+
+Use `.nav-list` for:
+
+- header navigation
+- side navigation
+- footer navigation
+- tab-like navigation lists
+- documentation navigation
+
+Do not reset every list inside `nav`.
+
+```css
+/* Avoid */
+nav ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+```
+
+This is too broad and removes native list behavior from every navigation context, including nested documentation trees or rich content.
+
+Prefer an explicit pattern class.
+
+```html demo
+<nav aria-label="Footer">
+  <ul class="nav-list cluster">
+    <li><a href="/privacy">Privacy</a></li>
+    <li><a href="/terms">Terms</a></li>
+    <li><a href="/contact">Contact</a></li>
+  </ul>
+</nav>
+```
+
+### Header Navigation
+
+Header navigation is usually a composition of landmarks, layout primitives, and patterns.
+
+```html demo
+<header class="site-header">
+  <div class="center cluster" style="--cluster-justify: space-between">
+    <a class="brand" href="/">Actual CSS</a>
+
+    <nav aria-label="Main navigation">
+      <ul class="nav-list cluster">
+        <li><a href="/docs">Docs</a></li>
+        <li><a href="/components">Components</a></li>
+        <li><a href="/examples">Examples</a></li>
+      </ul>
+    </nav>
+  </div>
+</header>
+```
+
+In this example:
+
+- `header` provides the document landmark.
+- `.center` constrains the content.
+- `.cluster` arranges the brand and navigation.
+- `nav` provides navigation semantics.
+- `.nav-list` normalizes the navigation list.
+- the inner `.cluster` arranges navigation items horizontally.
+
+A project may add `.site-header` when it needs a visual shell.
+
+```css
+.site-header {
+  border-block-end: 1px solid var(--border);
+  background: var(--surface);
+}
+```
+
+### App Shell With Sidebar
+
+`.app-shell` (see Layout App Shell) covers the simple case: a single column stacked `header`/`main`/`footer`. A persistent-sidebar app — a dashboard, an admin panel — needs a second, distinct shape: a two-column grid where the sidebar collapses below a breakpoint. These are not the same primitive solving the same problem two ways; `.app-shell` has no sidebar at all.
+
+```html
+<div class="shell-sidebar">
+  <aside class="shell-sidebar-nav" aria-label="Primary">
+    <a class="navbar-brand" href="#"><span class="avatar primary"><abbr>AC</abbr></span> Product</a>
+    <nav aria-label="Primary">
+      <ul class="nav-list stack">
+        <li><a class="nav-link" href="#" aria-current="page">Overview</a></li>
+        <li><a class="nav-link" href="#">Settings</a></li>
+      </ul>
+    </nav>
+  </aside>
+
+  <div class="shell-sidebar-main">
+    <header class="topbar">...</header>
+    <main class="center">...</main>
+  </div>
+</div>
+```
+
+```css
+.shell-sidebar {
+  display: grid;
+  grid-template-columns: 1fr;
+  min-block-size: var(--viewport-block);
+}
+
+.shell-sidebar-nav {
+  display: none;
+  flex-direction: column;
+  gap: var(--gap);
+  inline-size: var(--shell-sidebar-size, 16rem);
+  padding: var(--space-40);
+  border-inline-end: var(--border-width) solid var(--border);
+  background: var(--surface-raised);
+}
+
+.shell-sidebar-main {
+  min-inline-size: 0;
+}
+
+@media (min-width: 64rem) {
+  .shell-sidebar {
+    grid-template-columns: auto minmax(0, 1fr);
+  }
+
+  .shell-sidebar-nav {
+    display: flex;
+    position: sticky;
+    inset-block-start: 0;
+    block-size: var(--viewport-block);
+    overflow-y: auto;
+  }
+}
+```
+
+The sidebar width is the one tunable a project reaches for often, so it is exposed as `--shell-sidebar-size` rather than hard-coded — override it locally (`style="--shell-sidebar-size: 18rem"` or in a project stylesheet) instead of forking the rule. The breakpoint stays a literal `64rem` in the media query: custom properties cannot be substituted into a media condition, so a project that genuinely needs a different one copies the rule rather than fighting the token.
+
+Below the breakpoint, mirror the sidebar into a `.drawer` (see Components Drawer) for mobile access — the two are separate elements, not a responsive transform of one.
+
+### Side Navigation
+
+Side navigation is usually a `.nav-list` composed with `.stack`.
+
+```html demo
+<aside>
+  <nav aria-label="Documentation">
+    <ul class="nav-list stack">
+      <li><a href="/docs/getting-started" aria-current="page">Getting started</a></li>
+      <li><a href="/docs/tokens">Tokens</a></li>
+      <li><a href="/docs/layout">Layout</a></li>
+      <li><a href="/docs/components">Components</a></li>
+    </ul>
+  </nav>
+</aside>
+```
+
+A project may add `.side-nav` only when it needs specific visual behavior such as indentation, sticky positioning, section labels, or active states.
+
+```html demo
+<aside class="side-nav">
+  <nav aria-label="Documentation">
+    <ul class="nav-list stack">
+      <li><a href="/docs/getting-started" aria-current="page">Getting started</a></li>
+      <li><a href="/docs/tokens">Tokens</a></li>
+      <li><a href="/docs/layout">Layout</a></li>
+    </ul>
+  </nav>
+</aside>
+```
+
+```css
+.side-nav {
+  font-size: var(--font-size-sm);
+}
+
+.side-nav a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.side-nav a[aria-current="page"] {
+  font-weight: 600;
+}
+```
+
+### Optional Navigation Link Styling
+
+`.nav-list` can stay purely structural. If the framework wants navigation links to have a default hit area and active state, this can be added as a lightweight visual pattern.
+
+```css
+.nav-list a {
+  display: flex;
+  align-items: center;
+  gap: var(--space-20);
+  min-block-size: 2rem;
+  padding-inline: var(--space-20);
+  border-radius: var(--radius-sm);
+  color: inherit;
+  text-decoration: none;
+}
+
+.nav-list a:hover {
+  background: var(--surface-subtle);
+}
+
+.nav-list a[aria-current="page"] {
+  background: var(--surface-subtle);
+  font-weight: 600;
+}
+```
+
+Keep this separate from layout primitives. `.cluster` and `.stack` should not style links.

package/docs/pages/patterns/overview.md

@@ -0,0 +1,58 @@
+# Patterns
+
+> Small structural helpers for recurring semantic HTML shapes, between layout primitives and full components.
+
+Patterns are small structural helpers for recurring semantic HTML shapes. They sit between layout primitives and full components.
+
+They do not define page layout like `.stack`, `.cluster`, or `.grid`, and they do not provide a strong visual identity like `.alert`, `.card`, or `.btn`.
+
+Use patterns when a semantic element needs a small amount of normalization before being composed with layout primitives or components.
+
+## Principles
+
+- Layout primitives control spatial behavior.
+- Patterns normalize recurring semantic structures.
+- Components provide visual identity, states, and interaction styling.
+- Prefer composition over one-off component CSS.
+- Avoid broad element selectors such as `nav ul` or `.alert menu`.
+- A pattern should be useful in more than one component or context.
+
+## Relationship With Layout
+
+Patterns often compose with layout primitives.
+
+```html
+<menu class="actions cluster">...</menu>
+<ul class="nav-list cluster">...</ul>
+<ul class="nav-list stack">...</ul>
+<section class="grid">...</section>
+```
+
+Avoid putting semantic resets into layout primitives.
+
+```css
+/* Avoid */
+.stack {
+  padding: 0;
+  list-style: none;
+}
+```
+
+`.stack` should remain useful for real content lists where markers are expected.
+
+```html demo
+<ul class="stack">
+  <li>First important point</li>
+  <li>Second important point</li>
+  <li>Third important point</li>
+</ul>
+```
+
+If list chrome should be removed, use an explicit pattern.
+
+```html demo
+<ul class="nav-list stack">
+  <li><a href="/docs">Docs</a></li>
+  <li><a href="/components">Components</a></li>
+</ul>
+```

package/docs/pages/patterns/structured-lists.md

@@ -0,0 +1,47 @@
+# Structured Lists
+
+Use native lists plus layout primitives for rich content rows. Reset list chrome only when markers are not part of the content.
+
+```html demo
+<figure class="stack">
+  <figcaption><strong>Most played songs this week</strong></figcaption>
+
+  <ul class="list-reset stack gap-none">
+    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
+      <div class="avatar">
+        <img src="https://i.pravatar.cc/48?img=5" alt="Dio Lupa" />
+      </div>
+      <div class="cluster">
+        <div class="stack grow" style="--gap: var(--space-10)">
+          <strong>Dio Lupa</strong>
+          <span class="muted">Remaining Reason</span>
+        </div>
+        <span class="muted">3:45</span>
+        <button class="btn ghost" type="button" aria-label="Play">
+          <i class="ti ti-player-play" aria-hidden="true"></i>
+        </button>
+      </div>
+    </li>
+
+    <li class="media items-center py" style="border-block-end: var(--border-width) solid var(--border)">
+      <div class="avatar">
+        <img src="https://i.pravatar.cc/48?img=10" alt="Astral Planes" />
+      </div>
+      <div class="cluster">
+        <div class="stack grow" style="--gap: var(--space-10)">
+          <strong>Astral Planes</strong>
+          <span class="muted">Neon Drift</span>
+        </div>
+        <span class="muted">4:12</span>
+        <button class="btn ghost" type="button" aria-label="Play">
+          <i class="ti ti-player-play" aria-hidden="true"></i>
+        </button>
+      </div>
+    </li>
+  </ul>
+</figure>
+```
+
+Use `.actions` for action controls and `.nav-list` for navigation links. For structured content items, compose `.list-reset`, `.stack`, `.cluster`, `.media`, and components directly.
+
+`.media` is a two-slot object: it lays out exactly two children — the leading element and one content column. Trailing metadata and actions belong inside the content column (nest a `.cluster` and put `.grow` on the flexible part), never as extra row children: additional children silently wrap onto a second grid row.

package/docs/pages/utilities/accessibility.md

@@ -0,0 +1,34 @@
+# Accessibility
+
+Text hidden visually but still available to assistive technology.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.sr-only` | Utility | Visually hides text while keeping it in the accessibility tree. |
+
+## Screen reader only
+
+Use `.sr-only` for text that should be available to assistive technology but visually hidden.
+
+```html demo
+<button class="btn ghost" type="button">
+  <i class="ti ti-menu-2" aria-hidden="true"></i>
+  <span class="sr-only">Open navigation</span>
+</button>
+```
+
+```css
+.sr-only {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```

package/docs/pages/utilities/flex.md

@@ -0,0 +1,105 @@
+# Flex Helpers
+
+Small flex helpers for grow behavior and other one-line needs.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.grow` | Utility | Makes an item take available flex space without overflowing. |
+| `.items-start` | Utility | Aligns children to the block-start edge; sets `--items-align`. |
+| `.items-center` | Utility | Centers children on the cross axis; sets `--items-align`. |
+| `.items-end` | Utility | Aligns children to the block-end edge; sets `--items-align`. |
+| `.dot` | Utility | Inline separator dot for metadata rows. |
+| `.justify-content-start` | Utility | `justify-content: flex-start` and `--cluster-justify`. Optional layer. |
+| `.justify-content-center` | Utility | `justify-content: center` and `--cluster-justify`. Optional layer. |
+| `.justify-content-end` | Utility | `justify-content: flex-end` and `--cluster-justify`. Optional layer. |
+| `.justify-content-space-between` | Utility | `justify-content: space-between` and `--cluster-justify`. Optional layer. |
+| `.flex-wrap` | Utility | `flex-wrap: wrap` on any flex container. Optional layer. |
+| `.flex-nowrap` | Utility | `flex-wrap: nowrap` on any flex container. Optional layer. |
+
+## Grow
+
+Use `.grow` when one item in a flex layout should take available space without overflowing.
+
+```html demo
+<header class="cluster">
+  <strong>Actual CSS</strong>
+  <nav class="grow" aria-label="Main navigation">
+    <a href="#">Docs</a>
+    <a href="#">Components</a>
+  </nav>
+  <button class="btn ghost" type="button">Menu</button>
+</header>
+```
+
+```css
+.grow {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+}
+```
+
+## Item alignment
+
+Use `.items-start` on flex or grid layouts when children should keep their natural height and align to the block-start edge. This is especially useful for form fields in a grid, where the default grid stretch would make short fields as tall as taller neighbors.
+
+```html demo
+<div class="grid items-start">
+  <label class="field">
+    <span class="field-label">Name</span>
+    <input class="input" type="text" />
+  </label>
+  <label class="field">
+    <span class="field-label">Notes</span>
+    <textarea class="textarea"></textarea>
+  </label>
+</div>
+```
+
+Use `.items-center` when a flex or grid layout should center its children on the cross axis. Use `.items-end` when children should align to the block-end edge.
+
+These helpers work by setting a custom property that participating components read,
+so they also apply inside a component's own grid anatomy rather than only on plain
+flex containers:
+
+- `.items-start` / `.items-center` / `.items-end` set `--items-align`, read by `.alert` and `.card`.
+- `.text-start` / `.text-center` / `.text-end` set `--text-align`, read by `.table` cells.
+- `.justify-content-*` (optional layer) set `--cluster-justify`, read by `.cluster`.
+- `.flex-wrap` / `.flex-nowrap` (optional layer) set `flex-wrap` directly on any flex container.
+
+Set the property directly when you need a value the helpers do not ship.
+
+## Metadata separator
+
+> A small inline dot for separating facts in a metadata row.
+
+Use `.dot` between short facts in a byline, timestamp row, or breadcrumb-like list of details — anywhere a plain `·` character would otherwise be typed as text (which screen readers announce awkwardly).
+
+```html demo
+<p class="cluster" style="--cluster-justify: flex-start;">
+  <span>Ada Meridian</span>
+  <span class="dot" aria-hidden="true"></span>
+  <time datetime="2026-06-12">June 12, 2026</time>
+  <span class="dot" aria-hidden="true"></span>
+  <span>8 min read</span>
+</p>
+```
+
+```css
+.dot {
+  flex: none;
+  inline-size: 0.25rem;
+  block-size: 0.25rem;
+  border-radius: var(--radius-full);
+  background: var(--text-subtle);
+}
+```
+
+Always mark it `aria-hidden="true"` — it is a visual separator, not content.
+
+## CSS hooks
+
+- `--items-align` — cross-axis alignment, set by `.items-start` / `.items-center` / `.items-end`.
+- `--text-align` — text alignment, set by `.text-start` / `.text-center` / `.text-end`.
+- `--cluster-justify` — main-axis distribution, set by the optional `.justify-content-*` helpers and read by `.cluster`.

package/docs/pages/utilities/links.md

@@ -0,0 +1,18 @@
+# Link Variants
+
+Link styling for chrome that is conceptually a link but should not look like prose.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.link-plain` | Utility | Removes the underline and inherits the surrounding color. |
+| `.link-muted` | Utility | Muted link that shifts to the full text color on hover. |
+
+## Plain
+
+`.link-plain` removes the link's underline and inherits the surrounding color. Use for chrome that is conceptually a link (a card title, a table row action, a tag, a breadcrumb segment) but should not look like prose.
+
+## Muted
+
+`.link-muted` is a `.link-plain` that starts in the muted text color and shifts to the full text color on hover. Use for navigation lists, table of contents, and other secondary navigation surfaces.

package/docs/pages/utilities/list.md

@@ -0,0 +1,31 @@
+# List Helpers
+
+Utilities for list chrome reset, readable measure, and editorial kicker labels.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.list-reset` | Utility | Removes native list margin, padding, and markers. |
+| `.measure` | Utility | Caps a block at a readable width via `--prose-measure`. |
+| `.overline` | Component | Small editorial kicker label: muted, uppercase, letterspaced. |
+
+## List reset
+
+`.list-reset` removes the native list chrome (margin, padding, markers) from any list. It is the generic version of `.nav-list` — use `.nav-list` when the list is a navigation list for semantic intent, and `.list-reset` for everything else (tag clouds, footer columns, related items, comment threads, embedded controls).
+
+## Measure
+
+`.measure` caps a block at a readable width using `--prose-measure`. It does not center — combine with `.center` for the common centered reading column, or with `margin-inline: auto` for a one-off centered block.
+
+Use it for any content that needs a comfortable measure: prose articles, TOC lists, form fields, callouts. Avoid using it for full-bleed surfaces.
+
+## Editorial labels
+
+`.overline` is a small editorial label: muted color, smaller size, uppercase, slight letter-spacing. It does not impose a shape by itself. Add `.pill` for a bordered rounded chip, and combine with an intent class (`.primary`, `.success`, etc.) to tint the chip's text, border, and background.
+
+The overline exists because categories, kicker labels, and section markers recur across editorial surfaces, and `.badge` is the wrong shape for them. `.badge` is a status indicator; `.overline` is metadata.
+
+## CSS hooks
+
+- `--prose-measure` — the readable measure `.measure` caps at; defaults to `70ch`.

package/docs/pages/utilities/overflow.md

@@ -0,0 +1,43 @@
+# Overflow
+
+Explicit overflow handling for content that may exceed its container.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.overflow-auto` | Utility | Enables scrolling when content exceeds the container. |
+| `.overflow-hidden` | Utility | Clips overflowing content. Optional layer. |
+| `.overflow-clip` | Utility | Clips overflowing content without a scroll container. Optional layer. |
+| `.overflow-x-auto` | Utility | Horizontal scrolling only. Optional layer. |
+| `.overflow-y-auto` | Utility | Vertical scrolling only. Optional layer. |
+
+Use `.overflow-auto` when content may overflow its container, especially tables and code-like regions.
+
+```html demo
+<div class="overflow-auto">
+  <table class="table">
+    <caption>Team members</caption>
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Role</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Alice Johnson</td>
+        <td>Admin</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+```css
+.overflow-auto {
+  overflow: auto;
+}
+```
+
+The optional layer extends the same concern with axis-specific and clipping variants. For quiet, custom scrollbar chrome instead of the native OS scrollbar, pair `.overflow-auto` with `.scroller` on the Sizing And Wrapping page.

package/docs/pages/utilities/overview.md

@@ -0,0 +1,18 @@
+# Utilities
+
+Utilities are a small escape hatch for common single-purpose needs. They should support composition, not become the primary way to build UI.
+
+- Prefer semantic HTML, components, and layout primitives first.
+- Add utilities only when the rule is broadly useful and unlikely to become a component.
+- Keep utility names stable, boring, and few.
+- Utilities should use logical properties where relevant.
+
+## Non-Goals
+
+> Utilities deliberately excluded to keep the surface small and intentional.
+
+- No display scale such as `.block`, `.flex`, `.grid` — use layout primitives.
+- No color scales such as `.text-primary` or `.bg-success` — intent colors belong to components and state.
+- No breakpoint utility variants — use container queries or layout primitives.
+- No utility variants for hover, focus, dark mode, or arbitrary selectors — use component states.
+- No full spacing scale with every step and direction — the 17 spacing helpers across the core and optional layers cover the most common escape hatches.

package/docs/pages/utilities/shape.md

@@ -0,0 +1,25 @@
+# Shape Helpers
+
+Rare shape utilities for cases that must be perfectly round or square.
+
+## Class reference
+
+| Class | Kind | Description |
+|---|---|---|
+| `.circle` | Utility | Forces a perfectly round shape via `--radius-full`. |
+
+Shape utilities should be rare because shape is mostly theme-level.
+
+Use `.circle` only when an element must be perfectly round.
+
+```html demo
+<img class="circle" src="https://i.pravatar.cc/48?img=5" alt="Jane Doe" width="48" height="48" />
+```
+
+```css
+.circle {
+  border-radius: var(--radius-full);
+}
+```
+
+Do not add `.rounded-sm`, `.rounded-lg`, `.square`, or `.pill` unless repeated real use proves they are needed.