luxen-ui 0.22.1 → 0.24.0

package/dist/css/preset.css

@@ -33,7 +33,6 @@ Negates a value (returns the negative).
 @returns {Number} The negated value.
 @example padding: --negate(1em);
 */
-
 @function --negate(--value) {
 	result: calc(-1 * var(--value));
 }
@@ -47,7 +46,6 @@ Linear interpolation between two values.
 @returns {Number} Interpolated value.
 @example width: --lerp(100px, 200px, 0.5);
 */
-
 @function --lerp(--from, --to, --progress) {
 	result: calc(var(--from) + (var(--to) - var(--from)) * var(--progress));
 }
@@ -63,7 +61,6 @@ Maps a value from one range to another.
 @returns {Number} Mapped value.
 @example font-size: --map-range(50vw, 320px, 1920px, 14px, 24px);
 */
-
 @function --map-range(--value, --in-min, --in-max, --out-min, --out-max) {
 	--progress: clamp(0, calc((var(--value) - var(--in-min)) / (var(--in-max) - var(--in-min))), 1);
 	result: calc(var(--out-min) + (var(--out-max) - var(--out-min)) * var(--progress));
@@ -77,7 +74,6 @@ Returns the ratio of two values. Supports values with different units, unlike re
 @returns {Number} The ratio between two values.
 @example scale: --ratio(16px, 1em);
 */
-
 @function --ratio(--value, --to-value) {
 	result: tan(atan2(var(--value), var(--to-value)));
 }
@@ -94,7 +90,6 @@ Returns a semi-transparent version of any color.
 @returns {Color} Color with opacity.
 @example background: --opacity(blue, 50%);
 */
-
 @function --opacity(--color, --opacity) {
 	result: rgb(from var(--color) r g b / var(--opacity));
 }
@@ -109,7 +104,6 @@ Uses OKLab color space for perceptually uniform mixing.
 @returns {Color} Lightened color.
 @example background: --tint(blue, 20%);
 */
-
 @function --tint(--color, --amount: 10%) {
 	result: color-mix(in oklab, var(--color), white var(--amount));
 }
@@ -124,7 +118,6 @@ Uses OKLab color space for perceptually uniform mixing.
 @returns {Color} Darkened color.
 @example background: --shade(blue, 20%);
 */
-
 @function --shade(--color, --amount: 10%) {
 	result: color-mix(in oklab, var(--color), black var(--amount));
 }
@@ -139,7 +132,6 @@ Uses OKLCH color space for perceptually uniform chroma adjustment. Chroma is cla
 @returns {Color} Adjusted color.
 @example color: --saturate(red, 1.5);
 */
-
 @function --saturate(--color, --amount: 1.2) {
 	result: oklch(from var(--color) l clamp(0, calc(c * var(--amount)), 0.4) h);
 }
@@ -154,7 +146,6 @@ Uses OKLCH color space for perceptually uniform lightness adjustment. Maintains
 @returns {Color} Adjusted color.
 @example background: --lighten(blue, 20%);
 */
-
 @function --lighten(--color, --amount: 10%) {
 	result: oklch(from var(--color) clamp(0, calc(l + var(--amount) / 100%), 1) c h);
 }
@@ -169,7 +160,6 @@ Uses OKLCH color space for perceptually uniform lightness adjustment. Unlike `--
 @returns {Color} Darkened color.
 @example background: --darken(blue, 20%);
 */
-
 @function --darken(--color, --amount: 10%) {
 	result: oklch(from var(--color) clamp(0, calc(l - var(--amount) / 100%), 1) c h);
 }
@@ -184,7 +174,6 @@ Uses OKLCH color space for perceptually uniform hue rotation.
 @returns {Color} Color with rotated hue.
 @example background: --rotate-hue(blue, 180deg);
 */
-
 @function --rotate-hue(--color, --degrees: 30deg) {
 	result: oklch(from var(--color) l c calc(h + var(--degrees)));
 }
@@ -198,7 +187,6 @@ Uses OKLCH color space for perceptually accurate complementary colors.
 @returns {Color} Complementary color.
 @example border-color: --complement(blue);
 */
-
 @function --complement(--color) {
 	result: oklch(from var(--color) l c calc(h + 180deg));
 }
@@ -210,7 +198,6 @@ Inverts a color.
 @returns {Color} Inverted color.
 @example background: --invert(white);
 */
-
 @function --invert(--color) {
 	result: rgb(from var(--color) calc(255 - r) calc(255 - g) calc(255 - b) / alpha);
 }
@@ -224,7 +211,6 @@ Uses OKLCH color space by setting chroma to 0.
 @returns {Color} Grayscale color.
 @example filter: --grayscale(var(--brand-color));
 */
-
 @function --grayscale(--color) {
 	result: oklch(from var(--color) l 0 h);
 }
@@ -232,7 +218,6 @@ Uses OKLCH color space by setting chroma to 0.
 /*
 Uses HWB color space trick: converts to grayscale in OKLCH, then uses HWB's blackness/whiteness values amplified by a large multiplier to create a binary black/white decision based on brightness. This provides excellent contrast decisions without needing numeric luminance extraction.
 */
-
 /**
 Returns black or white text color for optimal contrast on a background.
 
@@ -240,7 +225,6 @@ Returns black or white text color for optimal contrast on a background.
 @returns {Color} Black or white for optimal readability.
 @example color: --text-on(var(--bg-color));
 */
-
 @function --text-on(--bg) {
 	result: hwb(from oklch(from var(--bg) l 0 0) h calc((b - 50) * 999) calc((w - 50) * 999));
 }
@@ -252,7 +236,6 @@ Removes transparency from a color, making it fully opaque.
 @returns {Color} Fully opaque version of the color.
 @example background: --opaque(var(--semi-transparent-bg));
 */
-
 @function --opaque(--color) {
 	result: rgb(from var(--color) r g b / 1);
 }
@@ -268,7 +251,6 @@ Uses perceptually uniform OKLab color space for natural-looking color mixing.
 @returns {Color} Mixed color.
 @example background: --mix(red, blue, 30%);
 */
-
 @function --mix(--color1, --color2, --amount: 50%) {
 	result: color-mix(in oklab, var(--color1), var(--color2) var(--amount));
 }
@@ -283,7 +265,6 @@ Triadic colors are evenly spaced around the color wheel (120° apart).
 @returns {Color} Triadic color.
 @example color: --triadic(blue, 1);
 */
-
 @function --triadic(--color, --index: 1) {
 	result: oklch(from var(--color) l c calc(h + 120deg * var(--index)));
 }
@@ -298,7 +279,6 @@ Tetradic colors are evenly spaced around the color wheel (90° apart).
 @returns {Color} Tetradic color.
 @example color: --tetradic(blue, 2);
 */
-
 @function --tetradic(--color, --index: 1) {
 	result: oklch(from var(--color) l c calc(h + 90deg * var(--index)));
 }
@@ -310,7 +290,6 @@ Creates a semi-transparent black.
 @returns {Color} Semi-transparent black.
 @example box-shadow: 0 2px 4px --black(20%);
 */
-
 @function --black(--opacity: 50%) {
 	result: rgb(0 0 0 / var(--opacity));
 }
@@ -322,7 +301,6 @@ Creates a semi-transparent white.
 @returns {Color} Semi-transparent white.
 @example background: --white(90%);
 */
-
 @function --white(--opacity: 50%) {
 	result: rgb(255 255 255 / var(--opacity));
 }
@@ -343,7 +321,6 @@ NOTE: This function is mathematically equivalent to `--responsive-value()` but o
 @returns {Length} Fluid font size.
 @example font-size: --fluid-type(16px, 24px, 320px, 1280px);
 */
-
 @function --fluid-type(--min, --max, --min-viewport: 320px, --max-viewport: 1280px) {
 	--slope: calc((var(--max) - var(--min)) / (var(--max-viewport) - var(--min-viewport)));
 	--intercept: calc(var(--min) - var(--slope) * var(--min-viewport));
@@ -359,7 +336,6 @@ Creates a modular scale value.
 @returns {Length} Scaled value.
 @example font-size: --modular-scale(1rem, 1.25, 3);
 */
-
 @function --modular-scale(--base: 1rem, --ratio: 1.25, --step: 0) {
 	result: calc(var(--base) * pow(var(--ratio), var(--step)));
 }
@@ -374,7 +350,6 @@ Returns a length (e.g., 24px) rather than a unitless ratio. Use this when you ne
 @returns {Length} Line height as a length.
 @example line-height: --line-height-length(16px, 1.6);
 */
-
 @function --line-height-length(--font-size, --multiplier: 1.5) {
 	result: calc(var(--font-size) * var(--multiplier));
 }
@@ -389,7 +364,6 @@ Returns a number (e.g., 1.5) which is recommended for better inheritance in CSS.
 @returns {Number} Unitless line height ratio.
 @example line-height: --line-height-ratio(24px, 16px);
 */
-
 @function --line-height-ratio(--line-height, --font-size) {
 	result: calc(var(--line-height) / var(--font-size));
 }
@@ -404,7 +378,6 @@ NOTE: Only works correctly with pixel font sizes. For rem/em values, use `--line
 @returns {Number} Unitless line height.
 @example line-height: --line-height-unitless(16px, 1.5);
 */
-
 @function --line-height-unitless(--font-size: 16px, --multiplier: 1.5) {
 	result: calc(var(--font-size) * var(--multiplier) / 1px);
 }
@@ -421,7 +394,6 @@ Creates responsive sidebar layout columns.
 @returns {Length} Grid template columns value.
 @example grid-template-columns: --sidebar-layout(250px, 20ch);
 */
-
 @function --sidebar-layout(--sidebar-width: 20ch, --content-min: 20ch) {
 	result: minmax(var(--sidebar-width), 1fr) minmax(var(--content-min), 3fr);
 }
@@ -434,7 +406,6 @@ Conditional border radius that removes at viewport edges.
 @returns {Length} Computed border radius.
 @example border-radius: --conditional-radius(1rem, 8px);
 */
-
 @function --conditional-radius(--radius, --edge-dist: 4px) {
 	/* Multiply by large number to amplify small differences, creating binary 0/radius effect */
 	result: clamp(0px, ((100vw - var(--edge-dist)) - 100%) * 1e5, var(--radius));
@@ -452,7 +423,6 @@ NOTE: This function is mathematically equivalent to `--fluid-type()` but uses a
 @returns {Length} Responsive value.
 @example padding: --responsive-value(1rem, 2rem, 320px, 1200px);
 */
-
 @function --responsive-value(--small, --large, --viewport-min: 320px, --viewport-max: 1200px) {
 	--progress: calc((100vw - var(--viewport-min)) / (var(--viewport-max) - var(--viewport-min)));
 	--clamped-progress: clamp(0, var(--progress), 1);
@@ -468,7 +438,6 @@ Calculates height from aspect ratio and maximum constraints.
 @returns {Length} Computed height.
 @example height: --aspect-height(16/9, 100vw, 100vh);
 */
-
 @function --aspect-height(--ratio: 1, --max-width: 100%, --max-height: 100%) {
 	--computed-height: calc(var(--max-width) / var(--ratio));
 	result: min(var(--computed-height), var(--max-height));
@@ -483,7 +452,6 @@ Calculates width from aspect ratio and maximum constraints.
 @returns {Length} Computed width.
 @example width: --aspect-width(16/9, 100vh, 100vw);
 */
-
 @function --aspect-width(--ratio: 1, --max-height: 100%, --max-width: 100%) {
 	--computed-width: calc(var(--max-height) * var(--ratio));
 	result: min(var(--computed-width), var(--max-width));
@@ -503,7 +471,6 @@ Recommended range: 0-10. Higher values create exponentially larger spacing.
 @returns {Length} Computed spacing.
 @example margin: --spacing(3);
 */
-
 @function --spacing(--level: 1, --base: 0.25rem) {
 	result: calc(var(--base) * pow(2, var(--level)));
 }
@@ -516,7 +483,6 @@ Creates inset spacing for containers.
 @returns {Length} Responsive padding.
 @example padding: --container-padding(2rem, 1200px);
 */
-
 @function --container-padding(--padding: 1rem, --max-width: 1200px) {
 	--available: calc(100vw - var(--max-width));
 	--side-space: max(var(--padding), calc(var(--available) / 2));
@@ -534,7 +500,6 @@ Creates a simple easing curve value.
 @returns {Number} Eased value.
 @example transform: translateY(--ease-out(var(--progress)));
 */
-
 @function --ease-out(--progress) {
 	--inverse: calc(1 - var(--progress));
 	result: calc(1 - var(--inverse) * var(--inverse));
@@ -548,7 +513,6 @@ Creates elastic easing.
 @returns {Number} Eased value.
 @example transform: scale(--elastic-ease(var(--progress), 1.2));
 */
-
 @function --elastic-ease(--progress, --amplitude: 1) {
 	--p: calc(var(--progress) * 3.14159);
 	result: calc(var(--amplitude) * sin(var(--p) * 10) * exp(calc(-5 * var(--progress))));
@@ -566,7 +530,6 @@ Converts pixels to rem.
 @returns {Length} Rem value.
 @example font-size: --px-to-rem(24px);
 */
-
 @function --px-to-rem(--pixels, --base: 16px) {
 	result: calc(var(--pixels) / var(--base) * 1rem);
 }
@@ -579,7 +542,6 @@ Converts rem to pixels.
 @returns {Length} Pixel value.
 @example width: --rem-to-px(2rem);
 */
-
 @function --rem-to-px(--rems, --base: 16px) {
 	result: calc(var(--rems) / 1rem * var(--base));
 }
@@ -596,7 +558,6 @@ Creates responsive grid columns.
 @returns {Grid} Grid template columns value.
 @example grid-template-columns: --auto-grid(250px, 4);
 */
-
 @function --auto-grid(--min-width: 250px, --max-cols: 4) {
 	result: repeat(
 		auto-fit,
@@ -614,7 +575,6 @@ Ensures the span is an integer value.
 @returns {Span} Grid column span (rounded to integer).
 @example grid-column: --grid-span(3, 12);
 */
-
 @function --grid-span(--columns: 1, --total: 12) {
 	result: span round(clamp(1, var(--columns), var(--total)));
 }
@@ -634,7 +594,6 @@ Generates three shadow layers. The spread-factor controls how distributed the sh
 @returns {Shadow} Layered box shadow.
 @example box-shadow: --smooth-shadow(black, 20px, 3);
 */
-
 @function --smooth-shadow(--color: rgb(0 0 0 / 0.2), --size: 12px, --spread-factor: 3) {
 	--step: calc(var(--size) / var(--spread-factor));
 	result:
@@ -652,7 +611,6 @@ Creates a glow effect.
 @returns {Shadow} Glow shadow.
 @example box-shadow: --glow(cyan, 10px, 0.5);
 */
-
 @function --glow(--color: white, --size: 10px, --intensity: 0.5) {
 	result: 0 0 var(--size) rgb(from var(--color) r g b / var(--intensity));
 }
@@ -677,7 +635,6 @@ Works with ANY value type (colors, lengths, etc.), not just colors.
 @example background-image: --light-dark(url(light.svg), url(dark.svg));
 @example padding: --light-dark(0.75rem, 1rem);
 */
-
 @function --light-dark(--light, --dark) {
 	result: if(color-scheme(dark): var(--dark); else: var(--light));
 }
@@ -696,35 +653,43 @@ In dark mode, mixes the base color with black (default 15% black).
 @returns {Color} Theme-adjusted color.
 @example background: --theme-color(blue, 80%, 20%);
 */
-
 @function --theme-color(--base, --light-mix: 85%, --dark-mix: 15%) {
 	--light-result: color-mix(in oklab, white var(--light-mix), var(--base));
 	--dark-result: color-mix(in oklab, black var(--dark-mix), var(--base));
 	result: if(color-scheme(dark): var(--dark-result); else: var(--light-result));
 }
-
+/* `.l-visually-hidden`: shared with the shadow roots that need it. */
 @layer base {
-  .l-visually-hidden {
-    /* Visually hide this, but keep it accessible to keyboard,
-       screen reader and other assistive technologies.
-
-      Also know as CSS helper: `.visually-hidden` / `.sr-only`
-
-      References:
-        - https://www.tpgi.com/the-anatomy-of-visually-hidden/
-        - https://youtu.be/ob_M_qXeDVE?t=677
-    */
-    position: absolute;
-    width: 1px;
-    height: 1px;
-    padding: 0;
-    margin: -1px;
-    overflow: hidden;
-    clip: rect(0, 0, 0, 0); /* for IE only */
-    white-space: nowrap;
-    border: 0;
-  }
 
+/*
+ * `.l-visually-hidden` — hides content visually while keeping it available to
+ * screen readers and other assistive technologies (a.k.a. `.sr-only`).
+ * One source for both tiers, like button-core.css:
+ *   - `@import`ed (and layered) by src/css/base/_base.css, the global helper
+ *     consumers use in the light DOM, and
+ *   - imported `?inline` (through visually-hidden.styles.ts) into the shadow
+ *     roots that need it (l-select, l-combobox, l-stories-viewer), which the
+ *     global class cannot reach. Templates bind it through `cls('visually-hidden')`
+ *     so a renamed prefix keeps both in sync.
+ *
+ * References:
+ *   - https://www.tpgi.com/the-anatomy-of-visually-hidden/
+ *   - https://youtu.be/ob_M_qXeDVE?t=677
+ */
+
+.l-visually-hidden {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+}
+@layer base {
   /* Hide Shadow-DOM overlay elements until their custom element upgrades.
      Without this, slotted/inner content flashes inline before the upgrade. */
   l-dialog:not(:defined),
@@ -735,9 +700,7 @@ In dark mode, mixes the base color with black (default 15% black).
     display: none;
   }
 }
-
 /* Design tokens — primitives (palette + scales) and semantic aliases. */
-
 /* Luxen design tokens — primitives (core 5 color families + spacing + radius
    + text + …) and semantic aliases (text-primary, bg-fill-brand, …) in one
    import. Equivalent to combining:
@@ -745,9 +708,7 @@ In dark mode, mixes the base color with black (default 15% black).
      @import 'luxen-ui/css/tokens/primitives';
      @import 'luxen-ui/css/tokens/aliases';
 */
-
 /* Luxen design-tokens entry — imports primitives + semantic aliases. */
-
 /* Luxen design-tokens — primitives (palette). */
 
 :root {
@@ -983,7 +944,7 @@ In dark mode, mixes the base color with black (default 15% black).
   --l-size-control-xl: 2.75rem;
 }
 
-/* Form component tokens (--l-form-control-*, --l-form-field-*). */
+/* Form component tokens (--l-form-control-*). */
 
 /* Luxen design-tokens — form component tokens.
    Opt-in via `@import "luxen-ui/css/tokens/forms"` (already bundled in the
@@ -992,56 +953,62 @@ In dark mode, mixes the base color with black (default 15% black).
 :root {
   /* Color of a control when activated (checked checkbox, selected radio, on switch). Form-wide accent, akin to native `accent-color`. A stable, saturated color that does not invert between light and dark, so the baked white glyph stays legible in both modes — override per brand. */
   --l-form-control-activated-color: var(--l-color-blue-600);
-  /* Color of the glyph on the activated fill (checkmark, radio dot, switch thumb). Pairs with the stable accent. */
+  /* Color of the switch thumb on the activated (on) track. Pairs with the stable accent. The checkbox checkmark and the radio dot do not read it: they are baked-white SVGs (background-image cannot take a color), so on a light accent swap them through the elements' `--checkmark` / `--dot` properties. */
   --l-form-control-activated-content-color: var(--l-color-white);
-  /* Control background (input, textarea, select, unchecked toggle box). */
+  /* Background of every form control at rest: text fields (input, textarea, select) and the box of an unchecked checkbox or radio. */
   --l-form-control-background-color: var(--l-color-surface);
   /* Color of the user-entered value text. */
   --l-form-control-value-color: var(--l-color-text-primary);
   /* Placeholder text color. */
   --l-form-control-placeholder-color: var(--l-color-text-tertiary);
-  /* Control border color. */
+  /* Border color of every form control at rest: text fields and the box of a checkbox or radio. */
   --l-form-control-border-color: var(--l-color-border);
-  /* Control border width. */
+  /* Border width of text fields and of the checkbox and radio box. */
   --l-form-control-border-width: 1px;
-  /* Control border radius. */
+  /* Corner radius of text fields (input, textarea, select, input group). Toggles keep their own shape. */
   --l-form-control-border-radius: var(--l-radius-md);
-  /* Control border color on hover. */
+  /* Border color of a hovered form control (text fields, checkbox, radio). Also tints the hover halo of an unchecked checkbox or radio. */
   --l-form-control-border-color-hover: var(--l-color-text-tertiary);
-  /* Control border color when invalid. */
+  /* Border color of an invalid form control (text fields, checkbox, radio), and the ring around an invalid switch. */
   --l-form-control-border-color-invalid: var(--l-color-bg-fill-danger-strong);
-  /* Background of a disabled text control — a faint ink wash (reinforces non-interactivity, instead of fading the whole control with opacity). Translucent rather than a solid grey so it composites onto whatever sits behind: a disabled field reads the same on a card, an alert, or a dialog, where an opaque fill would show as a mismatched patch. On the default surface it lands within a step of the former solid --l-color-bg-disabled, in both light and dark. */
-  --l-form-control-disabled-background: color-mix(in oklab, var(--l-color-text-primary) 6%, transparent);
-  /* Border color of a disabled text control. Translucent for the same reason as --l-form-control-disabled-background, and derived from the same ink so fill and border stay in step under any theme. 20% is the alpha that reproduces the former solid --l-color-border-disabled on the default surface in both modes; 25% (the CSSWG default-UA proposal) drifts bright enough in dark mode to read as an enabled border. */
-  --l-form-control-disabled-border: color-mix(in oklab, var(--l-color-text-primary) 20%, transparent);
-  /* Value/placeholder text color of a disabled text control. Deliberately opaque, unlike the fill and border: text is the one layer that must not composite. An ink-derived alpha assumes the backdrop luminance matches the color scheme, so on a dark card in light mode a translucent value would fade dark-on-dark to nothing — a solid grey stays legible either way. */
-  --l-form-control-disabled-color: var(--l-color-text-disabled);
-  /* Mark on a disabled control that greys out through tokens rather than fading — currently the switch's thumb when it is off and disabled, sitting on the pale --l-form-control-disabled-background. A mid grey that holds in both light and dark, so the mark keeps past 3:1 against that fill either way; the lighter --l-form-control-disabled-color would drop below it. Decoupled from text tokens for the same reason as --l-form-control-track-off-color. Activated controls (checked checkbox, selected radio, on switch) do not use this — they fade instead, keeping their accent tint. */
-  --l-form-control-disabled-mark-color: var(--l-color-gray-500);
+  /* Background of a disabled form control: text fields, the box of an unchecked checkbox or radio, and the track of an off switch — a faint ink wash (reinforces non-interactivity, instead of fading the whole control with opacity). Translucent rather than a solid grey so it composites onto whatever sits behind: a disabled field reads the same on a card, an alert, or a dialog, where an opaque fill would show as a mismatched patch. On the default surface it lands within a step of the former solid --l-color-bg-disabled, in both light and dark. */
+  --l-form-control-background-color-disabled: color-mix(in oklab, var(--l-color-text-primary) 6%, transparent);
+  /* Border color of a disabled form control: text fields and the box of an unchecked checkbox or radio. Translucent for the same reason as --l-form-control-background-color-disabled, and derived from the same ink so fill and border stay in step under any theme. 20% is the alpha that reproduces the former solid --l-color-border-disabled on the default surface in both modes; 25% (the CSSWG default-UA proposal) drifts bright enough in dark mode to read as an enabled border. */
+  --l-form-control-border-color-disabled: color-mix(in oklab, var(--l-color-text-primary) 20%, transparent);
+  /* Text color of a disabled control and of its field: the value and placeholder, plus the label, hint and required indicator of a disabled `l-form-field` (and the legend and labels of a `fieldset:disabled`). Deliberately opaque, unlike the fill and border: text is the one layer that must not composite. An ink-derived alpha assumes the backdrop luminance matches the color scheme, so on a dark card in light mode a translucent value would fade dark-on-dark to nothing — a solid grey stays legible either way. */
+  --l-form-control-text-color-disabled: var(--l-color-text-disabled);
+  /* Mark on a disabled control that greys out through tokens rather than fading — currently the switch's thumb when it is off and disabled, sitting on the pale --l-form-control-background-color-disabled. A mid grey that holds in both light and dark, so the mark keeps past 3:1 against that fill either way; the lighter --l-form-control-text-color-disabled would drop below it. Decoupled from text tokens for the same reason as --l-form-control-track-color-off. Activated controls (checked checkbox, selected radio, on switch) do not use this — they fade instead, keeping their accent tint. */
+  --l-form-control-mark-color-disabled: var(--l-color-gray-500);
   /* Box size of toggle controls (checkbox, radio, switch). Relative to font size so it scales with the label. */
   --l-form-control-toggle-size: 1.25em;
   /* Thickness of the hover halo ring on toggle controls (checkbox, radio, switch), as a fraction of the toggle size. Single source for the shared toggle hover language. */
   --l-form-control-toggle-halo-ratio: 0.22;
   /* Off-state track fill of the switch. A mid grey that holds in both light and dark so the white thumb keeps ~5:1 contrast either way — decoupled from text tokens so re-theming body text never moves the track. */
-  --l-form-control-track-off-color: var(--l-color-gray-500);
-  /* Height of text controls (input, select, textarea). */
+  --l-form-control-track-color-off: var(--l-color-gray-500);
+  /* Height of text fields (input, textarea, select, input group, l-select, l-combobox). Checkbox, radio and switch are sized by --l-form-control-toggle-size instead. */
   --l-form-control-height: var(--l-size-control-md);
-  /* Horizontal padding of text controls. */
+  /* Horizontal padding of text fields (input, textarea, select, input group). */
   --l-form-control-padding-inline: var(--l-spacing-3);
-  /* Field label color. */
+  /* Glyph size of the actions and indicators at the end of a text control: the clear (×) and the chevron of l-select / l-combobox, the chevron of the native `.l-select`, the native search clear and date/time picker icon of an input, and the password toggle of l-input-group. Only the glyph — each action's hit area follows the control height. Relative to font size by default; set a length to enlarge the glyphs on taller controls. */
+  --l-form-control-icon-size: 1em;
+  /* Color of an `l-form-field` label (and of a radio group legend). */
   --l-form-control-label-color: var(--l-color-text-primary);
-  /* Helper/description text color (`l-hint`). */
+  /* Color of the helper text below a control (`.l-hint`). */
   --l-form-control-hint-color: var(--l-color-text-secondary);
-  /* Error message text color (`l-error`). */
-  --l-form-control-error-color: var(--l-color-text-danger);
-  /* Marker appended to a required field's label. */
+  /* Color of the error message text (`.l-error`) shown when the field is invalid. The message only — the invalid border is --l-form-control-border-color-invalid. */
+  --l-form-control-error-message-color: var(--l-color-text-danger);
+  /* Indicator appended to the label of a required field, as a CSS `content` value: a symbol (the default asterisk) or text, e.g. `" (required)"`. */
   --l-form-control-required-content: '*';
-  /* Color of the required marker. */
+  /* Color of the required indicator (--l-form-control-required-content). */
   --l-form-control-required-color: var(--l-color-text-danger);
-  /* Vertical gap between label, control, and messages in a stacked field. Tight, so the label and helper text sit close to the control. */
-  --l-form-field-gap: var(--l-spacing-1);
-  /* Horizontal gap between a toggle control and its label in an inline field. */
-  --l-form-field-choice-gap: var(--l-spacing-2);
+  /* Space between the parts inside one `l-form-field`: label, control, hint and error, stacked vertically (in an inline field, between the label and its messages). Tight, so the label and helper text sit close to the control. Not the space between two fields — the form layout owns that. */
+  --l-form-control-label-gap: var(--l-spacing-1);
+  /* Horizontal space between a toggle control (checkbox, radio, switch) and its label in an inline `l-form-field`. */
+  --l-form-control-choice-label-gap: var(--l-spacing-2);
+  /* Background of the `<mark>` wrapping the part of an option that matches the search query, in the listbox of `l-combobox` and searchable `l-select` (plain label, or a rich option's title and description). A soft marker tint, light enough to keep the option text readable on a hovered or active row. Setting it to `transparent` leaves only --l-form-control-match-font-weight to mark the match — pick a weight above the option text's then, since a rich `l-select` title is already semibold. */
+  --l-form-control-match-background-color: light-dark(var(--l-color-yellow-100), var(--l-color-yellow-900));
+  /* Font weight of the search-query match in `l-combobox` and searchable `l-select` options. Pairs with --l-form-control-match-background-color; set to `inherit` to mark the match with the background alone. */
+  --l-form-control-match-font-weight: var(--l-font-weight-semibold);
 }
 
 /* Tooltip component token (--l-tooltip-background-color). */
@@ -1055,3 +1022,34 @@ In dark mode, mixes the base color with black (default 15% black).
   /* Tooltip surface color — dark in light mode, light in dark mode. Neutral by design; not tied to --l-color-bg-fill-brand, so changing the brand color does not recolor tooltips. Override globally to re-skin every tooltip, or use the per-instance --background-color custom property on a single `<l-tooltip>`. */
   --l-tooltip-background-color: light-dark(var(--l-color-gray-900), var(--l-color-gray-50));
 }
+
+/* Popover and menu-item tokens (--l-popover-*, --l-menu-item-*): panels
+   anchored to a trigger and their rows. */
+
+/* Luxen design-tokens — popover and menu-item component tokens.
+   Bundled in the Luxen preset via `luxen-ui/css/tokens`. Geometry and type of
+   the panels anchored to a trigger (dropdown, popover, listbox, select picker)
+   and of the rows inside them. */
+
+:root {
+  /* Corner radius of a panel anchored to a trigger (dropdown menu, popover, listbox, select picker). Each element still exposes its own `--border-radius` knob for a one-off override. Not for dialogs or drawers. */
+  --l-popover-border-radius: var(--l-radius-md);
+  /* Inset between a menu or listbox panel's border and its rows. Also the vertical margin of an `<hr>` separator, which bleeds through it to the panel edges. Not applied to `l-popover`, whose content brings its own spacing. */
+  --l-popover-padding: var(--l-spacing-1);
+  /* Elevation of a panel anchored to a trigger. Aliases --l-shadow-md so popovers can be re-elevated without moving every medium shadow. Modal surfaces use their own, higher elevation. */
+  --l-popover-shadow: var(--l-shadow-md);
+  /* Text size inside an anchored panel — menu items, listbox options, popover body. */
+  --l-popover-font-size: var(--l-text-sm);
+  /* Line height inside an anchored panel. Pairs with --l-popover-font-size; a row's first line box (font-size × line-height) is what checkmarks and suffixes centre on. */
+  --l-popover-line-height: 1.5;
+  /* Minimum height of a row in a menu or listbox — `l-dropdown-item`, `l-select` / `l-combobox` options, native `.l-select` options (36px). A comfortable pointer and touch target, well above the WCAG 2.5.8 24px floor. Rich rows (description, media) grow past it. */
+  --l-menu-item-min-height: 2.25rem;
+  /* Vertical padding of a menu item or listbox option. Select rows never go below it, and centre a single line on --l-menu-item-min-height. */
+  --l-menu-item-padding-block: var(--l-spacing-1_5);
+  /* Horizontal padding of a menu item or listbox option. Section labels (`l-dropdown-label`) use it too, so they line up with the rows below them. */
+  --l-menu-item-padding-inline: var(--l-spacing-2);
+  /* Gap between the parts of a menu item or option — check, icon, label, suffix. */
+  --l-menu-item-gap: var(--l-spacing-2);
+  /* Corner radius of a row's hover / active tint, inset inside the popover's own radius. */
+  --l-menu-item-border-radius: var(--l-radius-sm);
+}

package/dist/css/tokens/aliases.css

@@ -1,9 +1,7 @@
 /* Luxen semantic aliases only — text-primary, bg-fill-brand, border-interactive, …
    Each one references a primitive via `var(--l-color-*)`, so primitives must be
    defined (either via 'luxen-ui/css/tokens/primitives' or by your own mapping).
-*/
-
-/* Luxen design-tokens — semantic aliases. */
+*//* Luxen design-tokens — semantic aliases. */
 
 :root {
   /* Main body text, headings, and high-emphasis content. Use as the default text color throughout the UI. */