actual-css 0.2.0 → 0.3.1

package/src/css/optional/aura.css

@@ -0,0 +1,93 @@
+/*
+ * Decorative intent-colored frame for one direct child.
+ *
+ * Public hooks:
+ * --aura-color
+ * --aura-width
+ * --aura-blur
+ * --aura-radius
+ * --aura-duration
+ */
+@property --aura-angle {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+
+/* Intent boundary — an outer intent does not tint nested aura frames. */
+:where(.aura) {
+  --intent: initial;
+  --intent-fg: initial;
+}
+
+.aura {
+  --aura-color: var(--intent, var(--primary));
+  --aura-width: 2px;
+  --aura-blur: 0.75rem;
+  --aura-radius: var(--radius-lg);
+  --aura-duration: 6s;
+
+  position: relative;
+  isolation: isolate;
+  display: inline-grid;
+  padding: var(--aura-width);
+  border-radius: calc(var(--aura-radius) + var(--aura-width));
+  background: var(--aura-color);
+  background: conic-gradient(from var(--aura-angle), transparent 0 65%, var(--aura-color));
+}
+
+.aura::before {
+  position: absolute;
+  z-index: -1;
+  inset: 0;
+  border-radius: inherit;
+  background: inherit;
+  filter: blur(var(--aura-blur));
+  opacity: 0.45;
+  pointer-events: none;
+  content: "";
+}
+
+.aura > * {
+  position: relative;
+}
+
+.aura-glow {
+  background: var(--aura-color);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .aura:not(.aura-glow) {
+    animation: aura-rotate var(--aura-duration) linear infinite;
+  }
+}
+
+@keyframes aura-rotate {
+  to {
+    --aura-angle: 360deg;
+  }
+}
+
+@supports selector(:has(*)) {
+  .aura:has(> .btn) {
+    --aura-radius: var(--radius);
+  }
+
+  .aura:has(> :is(.card, .alert)) {
+    --aura-radius: var(--radius-lg);
+  }
+
+  .aura:has(> .badge) {
+    --aura-radius: var(--radius-full);
+  }
+}
+
+@media (forced-colors: active) {
+  .aura {
+    background: CanvasText;
+  }
+
+  .aura::before {
+    display: none;
+  }
+}

package/src/css/optional/chat.css

@@ -0,0 +1,105 @@
+/*
+ * Message rows composed from an optional avatar, metadata, and bubble.
+ *
+ * Public hooks:
+ * --chat-gap
+ * --chat-max-size
+ *
+ * Internal:
+ * --chat-bubble-bg
+ * --chat-bubble-fg
+ * --chat-bubble-border
+ */
+.chat {
+  --chat-gap: var(--space-30);
+  --chat-max-size: min(85%, 40rem);
+
+  display: grid;
+  grid-auto-rows: min-content;
+  column-gap: var(--chat-gap);
+}
+
+.chat-start {
+  grid-template-columns: auto minmax(0, 1fr);
+  justify-items: start;
+}
+
+.chat-end {
+  grid-template-columns: minmax(0, 1fr) auto;
+  justify-items: end;
+}
+
+.chat-avatar {
+  grid-row: 1 / span 3;
+  align-self: end;
+}
+
+.chat-start > .chat-avatar {
+  grid-column: 1;
+}
+
+.chat-end > .chat-avatar {
+  grid-column: 2;
+}
+
+.chat-header,
+.chat-footer {
+  display: flex;
+  gap: var(--space-10);
+  color: var(--text-muted);
+  font-size: var(--font-size-xs);
+}
+
+.chat-start > :is(.chat-header, .chat-bubble, .chat-footer) {
+  grid-column: 2;
+}
+
+.chat-end > :is(.chat-header, .chat-bubble, .chat-footer) {
+  grid-column: 1;
+}
+
+/* Intent boundary — an outer intent does not tint nested messages. */
+:where(.chat-bubble) {
+  --intent: initial;
+  --intent-fg: initial;
+  --ui-bg: initial;
+  --ui-fg: initial;
+  --ui-border: initial;
+}
+
+.chat-bubble {
+  --chat-bubble-bg: var(--ui-bg, var(--intent, var(--surface-subtle)));
+  --chat-bubble-fg: var(--ui-fg, var(--intent-fg, var(--text)));
+  --chat-bubble-border: var(--ui-border, transparent);
+
+  inline-size: fit-content;
+  max-inline-size: var(--chat-max-size);
+  padding: var(--space-20) var(--space-30);
+  border: var(--border-width) solid var(--chat-bubble-border);
+  border-radius: var(--radius-lg);
+  background: var(--chat-bubble-bg);
+  color: var(--chat-bubble-fg);
+  overflow-wrap: anywhere;
+}
+
+.chat-start > .chat-bubble {
+  border-end-start-radius: var(--radius-sm);
+}
+
+.chat-end > .chat-bubble {
+  border-end-end-radius: var(--radius-sm);
+}
+
+/* Remove the reserved avatar gutter when a message has no avatar. This is a
+   cosmetic enhancement; the two-column baseline remains fully readable. */
+@supports selector(:has(*)) {
+  .chat:not(:has(> .chat-avatar)) {
+    column-gap: 0;
+  }
+}
+
+@media (forced-colors: active) {
+  .chat-bubble {
+    border-color: CanvasText;
+  }
+}

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;