actual-css 0.2.0 → 0.3.1

package/src/css/forms/form-actions.css

@@ -4,13 +4,24 @@
  * A flex cluster of buttons/actions that closes a form. The sticky variant
  * docks to the viewport bottom with a translucent blur where supported; at
  * rest it stays visually neutral so it does not double as a separator.
+ *
+ * Public hooks:
+ * --form-actions-align
+ * --form-actions-justify
+ * --form-actions-margin-block-start
+ *
+ * Internal:
+ * --form-actions-sticky-block-offset (owned by .form-actions.sticky)
+ * --form-actions-sticky-inline-offset (owned by .form-actions.sticky)
+ * --form-actions-sticky-padding (owned by .form-actions.sticky)
  */
 .form-actions {
   display: flex;
   flex-wrap: wrap;
   gap: var(--gap);
-  align-items: center;
-  margin-block-start: var(--form-actions-margin-block-start, var(--space-5));
+  align-items: var(--form-actions-align, center);
+  justify-content: var(--form-actions-justify, flex-start);
+  margin-block-start: var(--form-actions-margin-block-start, var(--space-50));
 }
 
 /* Opt-in sticky variant. When the bar is not stuck (at rest) the translucent
@@ -24,7 +35,7 @@
   isolation: isolate;
 
   margin-inline: calc(var(--form-actions-sticky-inline-offset, 0px) * -1);
-  padding: var(--form-actions-sticky-padding, var(--space-3));
+  padding: var(--form-actions-sticky-padding, var(--space-30));
 
   border-block-start: var(--border-width) solid var(--border);
   background: var(--surface);

package/src/css/forms/form.css

@@ -6,23 +6,26 @@
  *
  * Public API: .field, .field-label, .field-help, .field-error, .field-group,
  * .required-mark.
+ *
+ * Public hooks:
+ * --fieldset-legend-padding-inline
  */
 .field {
   display: grid;
-  gap: var(--space-1);
+  gap: var(--space-10);
   color: var(--text);
 }
 
 .field-group {
   min-inline-size: 0;
   margin: 0;
-  padding: var(--space-3);
+  padding: var(--space-30);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius);
 }
 
 .field-group + .field-group {
-  margin-block-start: var(--space-4);
+  margin-block-start: var(--space-40);
 }
 
 .field-label,
@@ -33,7 +36,7 @@
 
 .field-group > legend {
   padding-block: 0;
-  padding-inline: var(--fieldset-legend-padding-inline, var(--space-1));
+  padding-inline: var(--fieldset-legend-padding-inline, var(--space-10));
   font-size: var(--font-size-xs);
 }
 

package/src/css/forms/index.css

@@ -1,7 +1,7 @@
-/* Forms — import order matters: switch.css must follow choice.css so its
-   :not([role="switch"]) exclusion in choice.css still applies.
-   validation.css is part of the default forms bundle, but custom builds may
-   omit it when validation styling is app-owned. */
+/* Forms — import order matters: switch.css follows choice.css so its rules
+   land after the shared choice recipe. validation.css is part of the default
+   forms bundle, but custom builds may omit it when validation styling is
+   app-owned. */
 @import "./form.css";
 @import "./control.css";
 @import "./input-icon.css";

package/src/css/forms/input-icon.css

@@ -1,36 +1,54 @@
 /*
- * Input Icon — leading decorative icon inside a relative wrapper.
+ * Input Icon — decorative icon inside a relative wrapper, leading or trailing.
  *
- * Icon-library agnostic: selects the wrapper's first child rather than a
- * specific tag, so it works with an <i> webfont icon, an inline <svg>, or a
- * <span>. Sizes with --variant-icon-size (variants.css) so .sm/.lg pick up
- * the same icon scale used elsewhere (alert.css); the input's start padding
- * grows to match so text never runs under the icon.
+ * Icon-library agnostic: detects position by DOM order. First child that is
+ * not .input = leading icon; icon after .input = trailing. The icon keeps a
+ * fixed size; density contexts shrink the control geometry around it, not
+ * the pictogram.
+ *
+ * Public hooks:
+ * --input-icon-size
  */
 .input-icon {
-  --input-icon-size: var(--variant-icon-size, 1.25rem);
+  --input-icon-size: 1.25rem;
 
   display: block;
   position: relative;
 }
 
-.input-icon > :first-child {
+/* Icon — shared by leading and trailing */
+.input-icon > :where(:not(.input)) {
   position: absolute;
   inset-block-start: 50%;
-  inset-inline-start: var(--space-3);
   transform: translateY(-50%);
   font-size: var(--input-icon-size);
   color: var(--text-muted);
   pointer-events: none;
 }
 
+/* Leading: icon is the first child */
+.input-icon > :first-child:where(:not(.input)) {
+  inset-inline-start: var(--space-30);
+}
+
+/* Trailing: input is the first child, icon follows */
+.input-icon > .input:first-child ~ :where(:not(.input)) {
+  inset-inline-end: var(--space-30);
+}
+
 /* font-size only sizes text-metric icons (webfont <i>, <span>). An inline
    <svg> with just a viewBox ignores it, so give it explicit dimensions. */
-.input-icon > svg:first-child {
+.input-icon > svg:where(:not(.input)) {
   inline-size: var(--input-icon-size);
   block-size: var(--input-icon-size);
 }
 
-.input-icon > .input {
-  padding-inline-start: calc(var(--space-3) * 2 + var(--input-icon-size));
+/* Leading: input gets start padding to clear the icon */
+.input-icon > :first-child:where(:not(.input)) ~ .input {
+  padding-inline-start: calc(var(--space-30) * 2 + var(--input-icon-size));
+}
+
+/* Trailing: input is first child and has a sibling → end padding */
+.input-icon > .input:first-child:where(:not(:last-child)) {
+  padding-inline-end: calc(var(--space-30) * 2 + var(--input-icon-size));
 }

package/src/css/forms/native.css

@@ -1,7 +1,7 @@
 /*
- * Native-only control polish: file input that mostly defeats custom styling,
- * so the framework stays out of the way and just keeps it readable and
- * theme-aware.
+ * Native-only control polish: the file input and color picker mostly defeat
+ * custom styling, so the framework stays out of the way and just keeps them
+ * readable and theme-aware.
  *
  * Range has its own custom-styled file (range.css) so the focus ring can
  * target the thumb pseudo-element rather than the rectangular CSS box.
@@ -11,9 +11,9 @@
 }
 
 .file::file-selector-button {
-  margin-inline-end: var(--space-3);
-  padding-block: var(--space-1);
-  padding-inline: var(--space-2);
+  margin-inline-end: var(--space-30);
+  padding-block: var(--space-10);
+  padding-inline: var(--space-20);
   border: var(--border-width) solid var(--border);
   border-radius: var(--radius-sm);
   background: var(--surface-subtle);
@@ -32,13 +32,52 @@
   cursor: not-allowed;
 }
 
-@media (hover: hover) {
-  .file:not(:disabled)::file-selector-button:hover {
-    background: var(--border);
-  }
+.file:not(:disabled)::file-selector-button:hover {
+  background: var(--border);
 }
 
 .file:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
+  box-shadow: var(--focus-ring-shadow);
+}
+
+/* Native color picker — keep the browser's dialog and selected-color UI. */
+.color {
+  inline-size: var(--control-size);
+  block-size: var(--control-size);
+  padding: var(--space-10);
+  border: var(--border-width) solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  cursor: pointer;
+}
+
+.color::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+.color::-webkit-color-swatch {
+  border: 0;
+}
+
+.color::-moz-color-swatch {
+  border: 0;
+}
+
+.color:disabled {
+  cursor: not-allowed;
+  opacity: var(--disabled-opacity);
+}
+
+.color:focus-visible {
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
+
+@media (forced-colors: active) {
+  .color {
+    border-color: ButtonText;
+    background: ButtonFace;
+    forced-color-adjust: none;
+  }
+}

package/src/css/forms/range.css

@@ -5,19 +5,18 @@
  * appearance: none gives us full control over track and thumb; without it,
  * pseudo-element rules for ::-webkit-slider-thumb and ::-moz-range-thumb
  * are not reliably applied across browsers.
+ *
+ * Public hooks:
+ * --range-thumb-size
+ * --range-track-height
+ * --range-thumb-bg
+ * --range-track-bg
  */
 
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.range) {
-  /* @sync intent-boundary */
   --intent: initial;
-  --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .range {
@@ -68,7 +67,7 @@
 }
 
 .range:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
 }
 
 /*
@@ -89,7 +88,16 @@
 }
 
 .range:disabled {
-  --range-thumb-bg: var(--text-subtle);
+  --range-thumb-bg: var(--state-disabled);
   cursor: not-allowed;
   opacity: var(--disabled-opacity);
 }
+
+/* Forced colors: map the custom thumb/track to system colors. The focus
+   indicator stays visible through the transparent outline on :focus-visible. */
+@media (forced-colors: active) {
+  .range {
+    --range-thumb-bg: ButtonText;
+    --range-track-bg: Canvas;
+  }
+}

package/src/css/forms/select.css

@@ -8,19 +8,19 @@
  * custom-select.css can be opted out independently. Add .native to a specific
  * select to opt out of the enhancement.
  */
-.select:is(:not([multiple], [size]), :not([multiple])[size="1"]) {
+.select:not([multiple], [size]:not([size="1"])) {
   appearance: none;
-  padding-inline-end: calc(var(--space-3) + var(--space-6));
-  background-image: var(--icon-chevron-image);
-  background-position: center right var(--space-3);
+  padding-inline-end: calc(var(--space-30) + var(--space-60));
+  background-image: var(--icon-chevron);
+  background-position: center right var(--space-30);
   background-size: 1rem auto;
   background-repeat: no-repeat;
 }
 
 /* The chevron sits on the inline-end side; flip it in RTL so it follows
    the padding-inline-end space reserved for it. */
-.select:is(:not([multiple], [size]), :not([multiple])[size="1"]):dir(rtl) {
-  background-position: center left var(--space-3);
+.select:not([multiple], [size]:not([size="1"])):dir(rtl) {
+  background-position: center left var(--space-30);
 }
 
 /* Both forced-colors and prefers-contrast hand the arrow back to the
@@ -28,9 +28,9 @@
    simpler than maintaining contrast variants, and native rendering already
    matches whatever contrast mode the user picked. */
 @media (forced-colors: active), (prefers-contrast: more) {
-  .select:is(:not([multiple], [size]), :not([multiple])[size="1"]) {
+  .select:not([multiple], [size]:not([size="1"])) {
     appearance: auto;
     background-image: none;
-    padding-inline-end: var(--space-3);
+    padding-inline-end: var(--space-30);
   }
 }

package/src/css/forms/switch.css

@@ -3,18 +3,22 @@
  *
  * The switch remains an input control, not a decorative toggle. Checked, hover,
  * focus-visible, and disabled states stay clear.
+ *
+ * Public hooks:
+ * --switch-bg
+ * --switch-border
+ * --switch-knob
+ * --switch-width
+ * --switch-block-size
+ * --switch-knob-margin
+ * --switch-knob-size
+ * --switch-travel
  */
 /* Intent boundary — inherited intents do not tint this component.
    Local intent classes still win because :where() has zero specificity. */
 :where(.switch) {
-  /* @sync intent-boundary */
   --intent: initial;
   --intent-fg: initial;
-  --ui-bg: initial;
-  --ui-fg: initial;
-  --ui-border: initial;
-  --ui-hover-bg: initial;
-  /* @sync intent-boundary */
 }
 
 .switch {
@@ -62,10 +66,8 @@
     box-shadow var(--duration);
 }
 
-@media (hover: hover) {
-  .switch:hover:not(:disabled) {
-    --switch-border: var(--intent, var(--primary));
-  }
+.switch:hover:not(:disabled) {
+  --switch-border: var(--intent, var(--primary));
 }
 
 .switch:checked {
@@ -86,14 +88,14 @@
 
 .switch:focus-visible {
   --switch-border: var(--focus);
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--focus-ring-shadow);
 }
 
 .switch:disabled {
   --switch-bg: var(--surface-subtle);
   --switch-border: var(--border);
-  --switch-knob: var(--text-subtle);
+  --switch-knob: var(--state-disabled);
   opacity: 1;
   cursor: not-allowed;
 }

package/src/css/forms/validation.css

@@ -3,6 +3,17 @@
  *
  * Imported by default through forms/index.css. Custom builds may omit this
  * file when an app wants to own validation styling completely.
+ *
+ * State coverage (which states each component ships) is audited in
+ * tests/validation.test.js and summarized in docs/pages/forms/validation.md —
+ * not kept as a source comment that can drift from the implementation.
+ *
+ * Public hooks:
+ * --form-invalid-border
+ *
+ * Internal:
+ * --choice-bg
+ * --switch-bg
  */
 
 .field.danger {
@@ -25,17 +36,33 @@
   --form-invalid-border: var(--danger);
 }
 
-/* Override checked/indeterminate background so both border and fill signal
-   danger instead of showing a red border around a primary-colored control. */
-.check[aria-invalid="true"]:is(:checked, :indeterminate),
-.radio[aria-invalid="true"]:checked {
+/* Override checked/indeterminate fill so both border and fill signal danger
+   instead of a red border around a primary-colored control. All three
+   invalid routes must converge: aria-invalid, was-validated :invalid, and
+   :user-invalid. */
+.check:is(:checked, :indeterminate)[aria-invalid="true"],
+.needs-validation.was-validated .check:is(:checked, :indeterminate):invalid,
+.radio:checked[aria-invalid="true"],
+.needs-validation.was-validated .radio:checked:invalid {
   --choice-bg: var(--danger);
 }
 
-.switch[aria-invalid="true"]:checked {
+.switch:checked[aria-invalid="true"],
+.needs-validation.was-validated .switch:checked:invalid {
   --switch-bg: var(--danger);
 }
 
+@supports selector(:user-invalid) {
+  .needs-validation .check:is(:checked, :indeterminate):user-invalid,
+  .needs-validation .radio:checked:user-invalid {
+    --choice-bg: var(--danger);
+  }
+
+  .needs-validation .switch:checked:user-invalid {
+    --switch-bg: var(--danger);
+  }
+}
+
 /* Choice cards hide their native input, so invalid state must surface on the
    card itself. Sets the same --form-invalid-border hook the card's border
    consumes. */

package/src/css/grid.css

@@ -1,26 +1,37 @@
+/*
+ * Responsive equal-width grids, with fixed-column presets below.
+ *
+ * Public hooks:
+ * --grid-min
+ * --grid-columns
+ */
+
+/* --grid-columns replaces the intrinsic auto-fit template: once set, the
+   grid no longer collapses on its own — the author owns narrow-container
+   collapse. Prefer .sidebar-layout inside .container-query for content +
+   aside layouts; reserve --grid-columns for genuinely fixed or asymmetric
+   templates. */
+
+/* Recipe:
+   - N equal cards that collapse when narrow -> .grid (auto-fit, tune
+     --grid-min) or .grid-2/3/4/6 inside .container-query
+   - content + aside -> .sidebar-layout inside .container-query
+   - fixed or asymmetric columns -> --grid-columns with an explicit collapse
+     rule of your own */
 .grid {
   display: grid;
   gap: var(--gap);
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr));
+  grid-template-columns: var(
+      --grid-columns,
+      repeat(auto-fit, minmax(min(100%, var(--grid-min, 16rem)), 1fr))
+    );
 }
 
-/* Query-container wrapper that opts .grid-2/3/4/6 into responsive
- * collapse. Wrap a .grid-2/3/4/6 inside .container-query to make the
- * column count collapse on narrow wrappers. Without this wrapper,
- * .grid-2/3/4/6 stay at their full column count. */
-/* Fixed-column grids at their full count by default.
- *   .grid-2: 2 cols
- *   .grid-3: 3 cols
- *   .grid-4: 4 cols
- *   .grid-6: 6 cols
- * When placed inside .container-query, the column count collapses
- * on narrow wrappers. The intermediate 2-col step applies to
- * .grid-3/.grid-4; .grid-6 starts at 2 columns because it is meant
- * for compact items that do not need a full single-column stack.
- *   .grid-2: 1 col -> 2 cols
- *   .grid-3: 1 col -> 2 cols -> 3 cols
- *   .grid-4: 1 col -> 2 cols -> 4 cols
- *   .grid-6: 2 cols -> 3 cols -> 6 cols */
+/* Fixed-column grids at their full count by default: .grid-2/3/4/6 stay at
+   2/3/4/6 columns unless wrapped in .container-query, which collapses the
+   column count on narrow wrappers (a 2-col intermediate step for
+   .grid-3/.grid-4; .grid-6 starts at 2 columns because it is meant for
+   compact items that do not need a full single-column stack). */
 .grid-2,
 .grid-3,
 .grid-4,
@@ -42,6 +53,9 @@
   grid-template-columns: repeat(6, minmax(0, 1fr));
 }
 
+/* Container queries are the preferred responsive path; browsers without them
+   ignore these rules and get the equivalent @media rules from the
+   @supports not (container-type) block below — same columns, same breakpoints. */
 @container (width < 28rem) {
   .container-query .grid-2,
   .container-query .grid-3,

package/src/css/intents.css

@@ -2,8 +2,8 @@
  * Intent classes do not style elements directly.
  * They only expose --intent and --intent-fg.
  * Components and variants decide how to consume them. Each component that
- * consumes --intent or --ui-* must open a local intent boundary in a :where()
- * block that resets --intent / --intent-fg / --ui-* to initial. Parent intents
+ * consumes --intent or --ui-* opens a local intent boundary in a :where()
+ * block that resets exactly the tokens it consumes to initial. Parent intents
  * do not leak into nested components. Local intent classes (.primary, .danger,
  * etc.) still apply because they have higher specificity than :where().
  */

package/src/css/layout.css

@@ -1,3 +1,38 @@
+/*
+ * Core layout primitives: stack, cluster, center, frame, app-shell, media,
+ * sidebar-layout. Each primitive owns a single, readable behavior; they are
+ * meant to compose in markup.
+ *
+ * Public hooks:
+ * --cluster-align
+ * --cluster-justify
+ * --cluster-wrap
+ * --center-size
+ * --center-pad
+ * --frame-ratio
+ * --sidebar-layout-size
+ *
+ * Child contracts:
+ * .stack owns vertical rhythm: direct-child block-axis margins are reset,
+ *   spacing comes from --gap, inline margins stay free.
+ * .cluster owns inline rhythm: direct-child margins are reset, spacing comes
+ *   from --gap.
+ * .frame sizes direct media children (img/video/iframe/canvas/svg) to fill the
+ *   frame.
+ */
+
+/* Responsive recipes:
+   - avatar/icon + flexible content -> .media
+   - inline items that wrap when space runs out -> .cluster (keep wrapping)
+   - content + aside -> .sidebar-layout inside .container-query
+   - row that becomes a column when constrained -> .switcher (optional module)
+
+   Anti-patterns:
+   - viewport breakpoints for ordinary composition
+   - fixed grid templates (--grid-columns) where .grid/.sidebar-layout express
+     the layout
+   - nowrap on page-level compositions; prefer wrapping and container-aware
+     primitives */
 .container-query {
   container-type: inline-size;
 }
@@ -8,18 +43,24 @@
   gap: var(--gap);
 }
 
+/* .stack owns the block axis only: block margins reset, inline margins stay
+   free (self-centering children via margin-inline: auto keep working). */
 .stack > * {
-  margin: 0;
+  margin-block: 0;
 }
 
 .cluster {
   display: flex;
-  flex-wrap: wrap;
+  flex-wrap: var(--cluster-wrap, wrap);
   align-items: var(--cluster-align, center);
   justify-content: var(--cluster-justify, flex-start);
   gap: var(--gap);
 }
 
+.cluster > * {
+  margin: 0;
+}
+
 .center {
   box-sizing: content-box;
   max-inline-size: var(--center-size, 72rem);
@@ -63,6 +104,8 @@
   grid-template-columns: minmax(0, 1fr);
 }
 
+/* Container queries are the preferred path; without them the @supports not
+   block below restores the same columns at the same viewport breakpoint. */
 @container (width >= 64rem) {
   .container-query .sidebar-layout {
     grid-template-columns: minmax(0, 1fr) var(--sidebar-layout-size, 18rem);