actual-css 0.2.0 → 0.3.0

package/src/css/optional/fab.css

@@ -0,0 +1,104 @@
+/*
+ * Fixed floating action placement and a native-details speed dial.
+ * Button owns the action's size, shape, and intent; FAB only owns placement.
+ *
+ * Public hooks:
+ * --fab-offset
+ * --fab-gap
+ */
+.fab {
+  --fab-offset: var(--space-40);
+  --fab-gap: var(--space-20);
+
+  position: fixed;
+  z-index: var(--z-menu);
+  inset-block-end: max(var(--fab-offset), env(safe-area-inset-bottom));
+  inset-inline-end: var(--fab-offset);
+}
+
+.fab > summary {
+  list-style: none;
+  cursor: pointer;
+}
+
+.fab > summary::-webkit-details-marker {
+  display: none;
+}
+
+/* A lone decorative plus can communicate the open/close state without
+   requiring a second icon or JavaScript-managed content. */
+.fab > summary > [aria-hidden="true"]:only-child {
+  display: inline-block;
+  transition: transform var(--duration);
+}
+
+.fab-actions {
+  position: absolute;
+  inset-inline-end: 0;
+  inset-block-end: calc(100% + var(--fab-gap));
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--fab-gap);
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(var(--space-10));
+  transition:
+    opacity var(--duration),
+    transform var(--duration),
+    visibility 0s linear var(--duration);
+}
+
+/* One action is one compact row. Keeping this relationship inside FAB avoids
+   wrapping and prevents labels from becoming visually associated with the
+   preceding or following button. */
+.fab-action {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--fab-gap);
+  inline-size: max-content;
+  max-inline-size: calc(var(--viewport-inline) - var(--fab-offset) - var(--fab-offset));
+}
+
+.fab-label {
+  flex: 0 1 auto;
+  overflow: hidden;
+  max-inline-size: 16rem;
+  padding: var(--space-10) var(--space-20);
+  border-radius: var(--radius);
+  background: var(--surface);
+  color: var(--text);
+  box-shadow: var(--shadow);
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--line-height-tight);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.fab[open] > .fab-actions {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+  transform: translateY(0);
+  transition-delay: 0s;
+}
+
+.fab[open] > summary > [aria-hidden="true"]:only-child {
+  transform: rotate(45deg);
+}
+
+@media (forced-colors: active) {
+  .fab-label {
+    border: var(--border-width) solid CanvasText;
+    box-shadow: none;
+  }
+}
+
+@media print {
+  .fab {
+    display: none;
+  }
+}

package/src/css/optional/floating-field.css

@@ -0,0 +1,87 @@
+/*
+ * Floating labels — optional composition over the text controls
+ * (.input, .textarea, .select) and .field-label.
+ *
+ * The cell owns a control plus its label; the label overlays the control and
+ * floats to the top when the control is focused or non-empty. Help and error
+ * messages stay in the surrounding .field, not inside the cell, so the
+ * resting label can center on the control alone.
+ *
+ * The control must precede the label: the float is driven by the sibling
+ * combinator and :placeholder-shown. Every .input/.textarea needs
+ * placeholder=" " to expose a reliable empty state — without it the label
+ * only reacts to focus.
+ *
+ * Density flows through --control-size: .sm/.lg shrink the control geometry
+ * and the reserved headroom with it, leaving typography untouched.
+ *
+ * Public hooks:
+ * --floating-pad-block-start
+ */
+.floating-field {
+  --floating-pad-block-start: calc(var(--control-size) / 2 + var(--space-20));
+
+  /* Grid blockifies the control, removing the inline descender gap a textarea
+     would otherwise leave under itself. */
+  position: relative;
+  display: grid;
+}
+
+.floating-field > :is(.input, .textarea, .select) {
+  /* Headroom for the floated label is always reserved, so the value never
+     jumps when the label floats. Half the control centers the resting label;
+     the extra step clears the floated label's bottom edge. */
+  padding-block-start: var(--floating-pad-block-start);
+  padding-block-end: var(--space-10);
+}
+
+.floating-field > .field-label {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: calc(var(--space-30) + var(--border-width));
+  transform: translateY(-50%);
+  color: var(--text-muted);
+  font-size: var(--control-font-size);
+  font-weight: var(--font-weight);
+  pointer-events: none;
+  transition:
+    inset-block-start var(--duration),
+    transform var(--duration),
+    font-size var(--duration),
+    color var(--duration);
+}
+
+/* A textarea's resting label aligns with the first text line instead of
+   centering in the (tall) control. */
+.floating-field > .textarea + .field-label {
+  inset-block-start: var(--floating-pad-block-start);
+  transform: none;
+}
+
+/* :autofill covers prefilled values before interaction, when the browser may
+   not have propagated the value to the placeholder state yet. */
+.floating-field
+  > :is(.input, .textarea):is(:focus, :autofill, :not(:placeholder-shown))
+  + .field-label {
+  inset-block-start: var(--space-10);
+  transform: none;
+  font-size: var(--font-size-xs);
+}
+
+/* Controls without a dependable :placeholder-shown empty state stay floated:
+   select always, and date/time inputs whose placeholder rendering is
+   inconsistent across engines (Firefox shows none). */
+.floating-field
+  > :is(
+    .select,
+    .input[type="date"],
+    .input[type="time"],
+    .input[type="datetime-local"],
+    .input[type="month"],
+    .input[type="week"]
+  )
+  + .field-label {
+  inset-block-start: var(--space-10);
+  transform: none;
+  font-size: var(--font-size-xs);
+}

package/src/css/optional/index.css

@@ -1,3 +1,8 @@
+@import "otp.css";
+@import "chat.css";
+@import "aura.css";
+@import "fab.css";
+@import "floating-field.css";
 @import "scroller.css";
 @import "scroll-snap.css";
 @import "typography-fluid.css";

package/src/css/optional/layout-extra.css

@@ -2,6 +2,9 @@
  * Additional layout primitives not included in the core bundle.
  *
  * Import this file explicitly when a project needs these patterns.
+ *
+ * Public hooks:
+ * --switcher-threshold
  */
 .switcher {
   display: flex;
@@ -22,8 +25,8 @@
  * to the page.
  *
  * Not for marketing/editorial site headers — those are one-off visual
- * identity per page; see docs/patterns.md's Header Navigation section.
- * This is for the structural app-shell topbar, which recurs unchanged
+ * identity per page; see docs/pages/patterns/overview.md's Header Navigation
+ * section. This is for the structural app-shell topbar, which recurs unchanged
  * across app UIs regardless of brand.
  */
 .topbar {
@@ -34,8 +37,8 @@
   display: flex;
   align-items: center;
   gap: var(--gap);
-  padding-block: var(--space-3);
-  padding-inline: var(--space-4);
+  padding-block: var(--space-30);
+  padding-inline: var(--space-40);
   border-block-end: var(--border-width) solid var(--border);
   background: var(--surface);
 }

package/src/css/optional/otp.css

@@ -0,0 +1,115 @@
+/*
+ * One-time code input with visual cells and one native input.
+ *
+ * Add one direct span per accepted character. The cells determine the
+ * component width; the overlaid input remains the only interactive control.
+ *
+ * Public hooks:
+ * --otp-cell-size
+ * --otp-gap
+ * --otp-font-size
+ *
+ * Internal:
+ * --otp-cell-border
+ * --otp-cell-bg
+ */
+.otp {
+  --otp-cell-size: var(--control-size);
+  --otp-gap: var(--space-10);
+  --otp-font-size: 1.5rem;
+  --otp-cell-border: var(--border);
+  --otp-cell-bg: var(--surface);
+
+  position: relative;
+  display: inline-grid;
+  grid-auto-flow: column;
+  grid-auto-columns: var(--otp-cell-size);
+  inline-size: fit-content;
+  max-inline-size: 100%;
+  gap: var(--otp-gap);
+  border-radius: var(--radius);
+  direction: ltr;
+}
+
+.otp > span {
+  inline-size: var(--otp-cell-size);
+  block-size: var(--otp-cell-size);
+  border: var(--border-width) solid var(--otp-cell-border);
+  border-radius: var(--radius);
+  background: var(--otp-cell-bg);
+  transition:
+    border-color var(--duration),
+    background-color var(--duration),
+    box-shadow var(--duration);
+}
+
+/* The native input owns focus, selection, autofill, paste, and one-time-code
+   integration. Its spacing aligns monospace glyphs with the visual cells. */
+.otp > input {
+  position: absolute;
+  z-index: 1;
+  inset: 0;
+  inline-size: 100%;
+  block-size: 100%;
+  margin: 0;
+  padding: 0 calc((var(--otp-cell-size) - 1ch) / 2);
+  border: 0;
+  outline: 2px solid transparent;
+  box-shadow: none;
+  background: transparent;
+  color: var(--text);
+  font-family: var(--font-mono);
+  font-size: var(--otp-font-size);
+  font-variant-numeric: tabular-nums;
+  line-height: var(--otp-cell-size);
+  letter-spacing: calc(var(--otp-cell-size) + var(--otp-gap) - 1ch);
+  text-align: start;
+  appearance: none;
+}
+
+.otp:focus-within {
+  box-shadow: var(--focus-ring-shadow);
+}
+
+.otp > input:focus ~ span {
+  --otp-cell-border: var(--focus);
+}
+
+.otp > input[aria-invalid="true"] ~ span,
+.needs-validation.was-validated .otp > input:invalid ~ span {
+  --otp-cell-border: var(--danger);
+}
+
+@supports selector(:user-invalid) {
+  .needs-validation .otp > input:user-invalid ~ span {
+    --otp-cell-border: var(--danger);
+  }
+}
+
+.otp > input:disabled {
+  color: var(--state-disabled);
+  cursor: not-allowed;
+}
+
+.otp > input:disabled ~ span {
+  --otp-cell-bg: var(--surface-subtle);
+
+  opacity: var(--disabled-opacity);
+}
+
+@media (forced-colors: active) {
+  .otp:focus-within {
+    outline: var(--focus-outline);
+    outline-offset: var(--focus-outline-offset);
+    box-shadow: none;
+  }
+
+  .otp > input:focus ~ span {
+    --otp-cell-border: Highlight;
+  }
+
+  .otp > input[aria-invalid="true"] ~ span,
+  .needs-validation.was-validated .otp > input:invalid ~ span {
+    --otp-cell-border: Mark;
+  }
+}

package/src/css/optional/scroll-snap.css

@@ -5,6 +5,12 @@
  * This is not a full carousel. For previous/next controls, pagination,
  * active state, drag behavior, looping, or robust desktop mouse interaction,
  * use a dedicated carousel library.
+ *
+ * Public hooks:
+ * --scroll-snap-gap
+ * --scroll-snap-align
+ * --scroll-snap-item-size
+ * --scroll-snap-padding
  */
 .scroll-snap {
   --scroll-snap-gap: var(--gap);

package/src/css/optional/scroller.css

@@ -2,8 +2,16 @@
  * Scroller — optional custom scrollbar styling for overflow regions.
  *
  * Apply to any scroll container (.overflow-auto, sidebars, long tables). Both
- * stable-color (Firefox) and ::-webkit-scrollbar (Safari/Chromium) are styled;
- * the thumb lands as a thin, theme-aware affordance with a hover state.
+ * scrollbar-color (Firefox) and ::-webkit-scrollbar (Safari/Chromium) are
+ * styled; the thumb lands as a thin, theme-aware affordance with a hover
+ * state.
+ *
+ * Public hooks:
+ * --scroller-size
+ * --scroller-padding
+ * --scroller-track
+ * --scroller-thumb
+ * --scroller-thumb-hover
  */
 .scroller {
   --scroller-size: 0.625rem;
@@ -38,11 +46,9 @@
   background-clip: content-box;
 }
 
-@media (hover: hover) {
-  .scroller::-webkit-scrollbar-thumb:hover {
-    background: var(--scroller-thumb-hover);
-    background-clip: content-box;
-  }
+.scroller::-webkit-scrollbar-thumb:hover {
+  background: var(--scroller-thumb-hover);
+  background-clip: content-box;
 }
 
 .scroller::-webkit-scrollbar-corner {

package/src/css/optional/typography-fluid.css

@@ -14,6 +14,11 @@
  *   --fluid-display, --fluid-title, --fluid-lead  (size tokens, clamp())
  *   .text-display, .text-title, .text-lead        (composed classes)
  *
+ * Public hooks:
+ * --fluid-display
+ * --fluid-title
+ * --fluid-lead
+ *
  * Values are generated from scripts/rfs.ts over the 360px -> 1440px range.
  */
 :root {

package/src/css/optional/utilities-extra.css

@@ -5,10 +5,13 @@
  * They are escape hatches for layout nudges, not a full atomic scale.
  *
  * Core principle:
- * - .sm / .lg provide local rhythm through --gap and --variant-space.
+ * - .sm / .lg provide local rhythm through --gap and --density-space.
  * - utilities consume the current context instead of defining their own -sm/-lg scale.
  * - optional utilities extend core utilities, they do not re-express them.
  * - follow verbose .{property}-{value} naming.
+ *
+ * Internal:
+ * --cluster-justify (local relay consumed by .cluster)
  */
 
 /* Display */
@@ -83,6 +86,18 @@
   flex-wrap: nowrap;
 }
 
+.gap-sm {
+  gap: var(--space-20);
+}
+
+.gap-md {
+  gap: var(--space-40);
+}
+
+.gap-lg {
+  gap: var(--space-50);
+}
+
 .justify-content-start {
   --cluster-justify: flex-start;
   justify-content: flex-start;
@@ -117,7 +132,7 @@
 
 /* Spacing */
 .padding-context {
-  padding: var(--variant-space);
+  padding: var(--density-space);
 }
 
 .margin-inline-auto {

package/src/css/prose.css

@@ -3,6 +3,17 @@
  *
  * Global element styles stay mild so app UI is not shaped accidentally. Page
  * layout, forms, cards, navigation, and app tables remain outside this scope.
+ *
+ * Public hooks:
+ * --prose-size
+ * --prose-line-height
+ * --prose-measure
+ * --prose-flow
+ * --prose-heading-line-height
+ * --prose-h1
+ * --prose-h2
+ * --prose-h3
+ * --prose-h4
  */
 
 .prose {
@@ -66,15 +77,13 @@
   text-underline-offset: 0.18em;
 }
 
-@media (hover: hover) {
-  .prose a:hover {
-    text-decoration-thickness: 0.12em;
-  }
+.prose a:hover {
+  text-decoration-thickness: 0.12em;
+}
 
-  @supports (color: color-mix(in oklch, red, white)) {
-    .prose a:hover {
-      color: color-mix(in oklch, var(--primary), var(--text) 15%);
-    }
+@supports (color: color-mix(in oklch, red, white)) {
+  .prose a:hover {
+    color: color-mix(in oklch, var(--primary), var(--text) 15%);
   }
 }
 
@@ -94,6 +103,7 @@
   font-size: 0.875em;
 }
 
+/* Visual twin of .key (components/key.css) — keep the two recipes in sync. */
 .prose kbd {
   display: inline-flex;
   align-items: center;

package/src/css/reset.css

@@ -24,16 +24,6 @@ select {
   display: none !important;
 }
 
-/* Legacy dialog fallback only. Modern dialogs keep the browser's native closed
-   state so display/overlay transitions are not flattened by the reset.
-   The presentation for the dialog-fallback.js shim lives in the separate
-   dialog-fallback.css, so it can be dropped from custom bundles. */
-@supports not (selector(dialog:modal)) {
-  dialog:not([open]) {
-    display: none;
-  }
-}
-
 :where(img, svg, video) {
   max-inline-size: 100%;
   block-size: auto;

package/src/css/theme.css

@@ -1,3 +1,14 @@
+/*
+ * Theme tokens — the palette, surfaces, text, borders, radius and shadow
+ * color. Named themes (themes/*.css) override this file; authors can set the
+ * same tokens on :root or on [data-theme="…"] islands.
+ *
+ * Public: Intent colors, Surfaces, Text, Lines and focus, Radius scale,
+ * Shadow color, Focus ring derivation.
+ * Derived: "Theme-derived aliases", Tone subsystem, Backdrop fill — reference
+ * other tokens; hard-coded overrides on a custom theme will break the intent.
+ * Internal: --hgroup-gap.
+ */
 :root {
   color-scheme: light dark;
 }
@@ -65,7 +76,6 @@
   /* Pre-color-mix fallback only — superseded below by a derivation from
      --focus so overriding --neutral/--focus never leaves a stale ring. */
   --focus-ring: hsl(258 7% 43% / 0.3);
-  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
   --hover-overlay: hsl(260 20% 10% / 0.04);
 
   /* Radius scale — themes may override the whole scale (e.g. [data-theme="square"]) */
@@ -76,13 +86,19 @@
   /* Shadow color — consumed by --shadow / --shadow-popout in tokens.css */
   --shadow-color: hsl(260 25% 10%);
 
-  /* Heading and selection — derived from theme color tokens */
+  /* hgroup internal gap */
+  --hgroup-gap: 0.25em;
+}
+
+/* Theme-derived aliases — re-declared on every theme boundary (see tokens.css
+   for the custom-property resolution rationale): islands recompute these from
+   their own tokens instead of inheriting :root's resolved values. */
+:root,
+[data-theme] {
   --heading: var(--text);
   --selection-bg: var(--primary);
   --selection-fg: var(--primary-fg);
-
-  /* hgroup internal gap */
-  --hgroup-gap: 0.25em;
+  --focus-ring-shadow: 0 0 0 var(--focus-ring-width) var(--focus-ring);
 }
 
 /* Tone subsystem — fixed-backdrop foreground for components placed over media

package/src/css/themes/cyberpunk.css

@@ -1,5 +1,5 @@
 /* Cyberpunk — light-only stress-test theme (single block, color-scheme: light,
- * same shape as dark.css). Illustrative rather than production: it exists to
+ * same shape as indigo.css). Illustrative rather than production: it exists to
  * prove the token contract survives an extreme spec — a saturated yellow
  * canvas, near-black text and borders, dark-on-bright intent pairs, zero
  * radius, 2px strokes, and hard offset shadows — without touching a single

package/src/css/themes/dim.css

@@ -1,7 +1,7 @@
 /* Dim — a dark theme variant that lifts the surface tones up a few percentage
- * points. Same shape as dark.css (dark-only, single block) so authors can drop
- * it in when the canonical dark is too dense. Demonstrates how a theme can
- * recolor the same token set without changing structure. */
+ * points. Same shape as indigo.css (dark-only, single block) so authors can
+ * drop it in when the canonical dark is too dense. Demonstrates how a theme
+ * can recolor the same token set without changing structure. */
 [data-theme="dim"] {
   color-scheme: dark;
 

package/src/css/themes/edge.css

@@ -3,9 +3,9 @@
  * intent-colored lower edge (.solid remains available when an action needs a
  * filled treatment), text controls (input/textarea/select) pick up the same
  * lower-edge accent via --control-border-block-end-*, alerts get an
- * intent-colored leading flag via --alert-border-inline-start-*, and text
- * controls and buttons both get a thinner, tighter focus outline than the
- * shared recipe. */
+ * intent-colored leading flag via --alert-border-inline-start-*. The focus
+ * ring keeps the shared width — edge only drops the border-color flip so the
+ * intent-colored lower edge stays dominant. */
 [data-theme="edge"] {
   color-scheme: light dark;
 
@@ -61,13 +61,11 @@
   --ui-hover-bg: var(--surface-raised);
 }
 
-@media (hover: hover) {
-  [data-theme="edge"]
-    .btn:not(
-      :where(:disabled, [aria-disabled="true"], .solid, .soft, .outline, .ghost, .link)
-    ):hover {
-    box-shadow: none;
-  }
+[data-theme="edge"]
+  .btn:not(
+    :where(:disabled, [aria-disabled="true"], .solid, .soft, .outline, .ghost, .link)
+  ):hover {
+  box-shadow: none;
 }
 
 /* Intent-dependent alert token, same reasoning as the button rule above:

package/src/css/themes/index.css

@@ -5,7 +5,7 @@
  * The themes are illustrative: each one demonstrates a different set of knobs
  * the token contract exposes, beyond recoloring.
  *
- *   dark       — canonical dark (single block, color-scheme: dark only)
+ *   indigo     — deep blue/violet dark palette (single block)
  *   dim        — dark variant with lifted surface tones
  *   corporate  — reference paired light/dark recolor via light-dark()
  *   forest     — paired recolor + scaled-up radius tokens
@@ -24,9 +24,9 @@
  *   gradient   — paired recolor + Bootstrap 4 style gradient on solid buttons
  *                via component-local button tokens
  *
- * Single-block themes (dark, dim, cyberpunk, neon) pin one color-scheme and
+ * Single-block themes (indigo, dim, cyberpunk, neon) pin one color-scheme and
  * cannot adapt to prefers-color-scheme; the paired ones follow the OS. */
-@import "./dark.css";
+@import "./indigo.css";
 @import "./dim.css";
 @import "./corporate.css";
 @import "./forest.css";

package/src/css/themes/{dark.css → indigo.css}

@@ -1,7 +1,8 @@
-/* Canonical dark theme. Single-block shape (color-scheme: dark only) — it
- * does not adapt to prefers-color-scheme; opt in via [data-theme="dark"].
- * dim.css is a darker variant with lifted surface tones. */
-[data-theme="dark"] {
+/* Indigo — deep blue/violet palette, dark-only. Single-block shape
+ * (color-scheme: dark only) — it does not adapt to prefers-color-scheme;
+ * opt in via [data-theme="indigo"]. dim.css is a darker variant with
+ * lifted surface tones. */
+[data-theme="indigo"] {
   color-scheme: dark;
 
   --primary: hsl(220 90% 66%);

package/src/css/themes/neon.css

@@ -1,9 +1,9 @@
 /* Neon — dark-only theme (single block, color-scheme: dark, same shape as
- * dark.css) that demonstrates wide-gamut progressive enhancement. The baseline
- * block uses sRGB-safe hsl() and works everywhere dark.css works; on P3
- * displays with oklch() support the intents are re-declared with chroma beyond
- * sRGB. This is the pattern for shipping colors sRGB cannot express without
- * breaking older screens or browsers. Also demonstrates the soft-variant
+ * indigo.css) that demonstrates wide-gamut progressive enhancement. The
+ * baseline block uses sRGB-safe hsl() and works everywhere indigo.css works;
+ * on P3 displays with oklch() support the intents are re-declared with chroma
+ * beyond sRGB. This is the pattern for shipping colors sRGB cannot express
+ * without breaking older screens or browsers. Also demonstrates the soft-variant
  * tuning knobs and glow shadows on popovers. */
 [data-theme="neon"] {
   color-scheme: dark;

package/src/css/themes/square.css

@@ -34,9 +34,6 @@
 }
 
 @supports (color: light-dark(red, blue)) {
-  /* Square — paired light/dark theme that demonstrates overriding the full
- * --radius scale to 0 for sharp-cornered applications. The recolor is close to
- * the default blue palette; the radius override is the point. */
   [data-theme="square"] {
     --primary: light-dark(hsl(220 90% 56%), hsl(220 75% 80%));
     --primary-fg: light-dark(white, hsl(220 30% 12%));