RubyGems - kiso - Versions diffs - 0.5.2.pre → 0.6.0.pre - Mend

kiso 0.5.2.pre → 0.6.0.pre

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

data/app/assets/tailwind/kiso/engine.css CHANGED Viewed

@@ -1,7 +1,23 @@
-/* Kiso Engine CSS — imported by host apps via tailwindcss-rails engine bundling.
-   Component CSS files go here for transitions, animations, and pseudo-states
-   that are awkward to express in ERB. Most styling lives in Ruby theme modules
-   (lib/kiso/themes/) as computed Tailwind classes. */
+/* ── Kiso Engine CSS ──────────────────────────────────────────────────────────
+   Main entry point for Kiso's CSS, imported by host apps via tailwindcss-rails
+   engine bundling. This file aggregates:
+   1. Per-component CSS for transitions, animations, pseudo-states, and layout
+      mechanics that ERB partials cannot express (most styling lives in Ruby
+      theme modules at lib/kiso/themes/ as computed Tailwind classes).
+   2. Tailwind @source directives so the engine's own class references are
+      scanned during the host app's Tailwind build.
+   3. @font-face declarations for the Geist typeface family.
+   4. @theme blocks defining structural tokens (radius, container) and the full
+      semantic color system (light + dark mode via .dark class).
+   5. @layer base defaults for <body>.
+   ──────────────────────────────────────────────────────────────────────────── */
+/* === Component CSS Imports ===
+   Each file handles CSS-only concerns for a specific component or component
+   family: animations, pseudo-element indicators, popover overrides, layout
+   grid mechanics, etc. If a component needs no CSS beyond Tailwind utilities,
+   it does not have a file here. */
 @import "./button.css";
 @import "./checkbox.css";
@@ -13,18 +29,22 @@
 @import "./slider.css";
 @import "./tooltip.css";
-/* Scan Kiso's own files so host apps don't need to know the gem's internals.
+/* === Tailwind Source Scanning ===
+   Tell Tailwind v4 to scan Kiso's own source files for class references.
+   Without these, utility classes referenced in ERB partials, helpers, theme
+   modules, and presets would not be generated in the host app's CSS output.
    Paths are relative to THIS file (app/assets/tailwind/kiso/engine.css).
-   Count carefully — wrong paths fail SILENTLY (classes just won't generate). */
+   WARNING: wrong paths fail SILENTLY — classes simply won't generate. */
 @source "../../../views";              /* → app/views              */
 @source "../../../helpers";            /* → app/helpers            */
 @source "../../../../lib/kiso/themes";  /* → lib/kiso/themes        */
 @source "../../../../lib/kiso/presets"; /* → lib/kiso/presets       */
 /* === Geist Font (by Vercel) ===
-   Self-hosted variable fonts — no CDN dependency.
-   Licensed under the SIL Open Font License (see OFL.txt).
-   Host apps can override --font-sans / --font-mono in their own @theme block. */
+   Self-hosted variable fonts loaded from the engine's asset pipeline — no CDN
+   dependency. Licensed under the SIL Open Font License (see OFL.txt in the
+   fonts directory). Host apps can override --font-sans / --font-mono in their
+   own @theme block to use a different typeface. */
 @font-face {
   font-family: "Geist";
@@ -42,20 +62,61 @@
   src: url("/kiso/GeistMonoVF.woff2") format("woff2");
 }
-/* Set Geist as the default sans and mono fonts.
-   Host apps can override by redefining --font-sans / --font-mono. */
+/* Register Geist as the default sans and mono font stacks.
+   Using @theme inline so these values are inlined into the generated CSS
+   rather than emitted as separate custom properties (reduces output size).
+   Host apps can override by redefining --font-sans / --font-mono in their
+   own @theme block — Tailwind v4 merges @theme blocks, last definition wins. */
 @theme inline {
   --font-sans: "Geist", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
 }
+/* === Structural Tokens ===
+   Framework-level layout primitives that host apps can tune. These are
+   namespaced with --kiso- to avoid collisions with Tailwind's own variables.
+   Override in the host app's own @theme block:
+     @theme { --kiso-radius: 0.5rem; --kiso-container: 64rem; } */
+@theme {
+  /* Base radius unit — the single knob that controls the entire border-radius
+     scale. Namespaced as --kiso-radius (our variable) vs --radius-* (Tailwind's
+     built-in scale that we override below). */
+  --kiso-radius: 0.25rem;
+  /* Maximum content width, used by the Container component. */
+  --kiso-container: 80rem;
+  /* Computed radius scale — overrides Tailwind's built-in --radius-* variables
+     with values derived from --kiso-radius using the same multiplier system as
+     Nuxt UI's --ui-radius. This wires rounded-sm, rounded-md, rounded-lg, etc.
+     through our base variable so changing --kiso-radius shifts every component's
+     border-radius proportionally.
+     At the default 0.25rem, computed values match Tailwind's defaults exactly,
+     making this invisible until a host app changes --kiso-radius. */
+  --radius-xs:  calc(var(--kiso-radius) * 0.5);   /* 0.125rem */
+  --radius-sm:  var(--kiso-radius);                /* 0.25rem  */
+  --radius-md:  calc(var(--kiso-radius) * 1.5);    /* 0.375rem */
+  --radius-lg:  calc(var(--kiso-radius) * 2);      /* 0.5rem   */
+  --radius-xl:  calc(var(--kiso-radius) * 3);      /* 0.75rem  */
+  --radius-2xl: calc(var(--kiso-radius) * 4);      /* 1rem     */
+  --radius-3xl: calc(var(--kiso-radius) * 6);      /* 1.5rem   */
+  --radius-4xl: calc(var(--kiso-radius) * 8);      /* 2rem     */
+}
 /* === Semantic Color Tokens ===
-   Purpose-named tokens that flip in dark mode. Components use bg-primary,
-   text-foreground, etc. — never raw palette shades or dark: prefixes.
+   Purpose-named CSS custom properties that flip automatically in dark mode
+   (via the .dark class below). Components reference these tokens through
+   Tailwind utilities — bg-primary, text-foreground, border-border, etc. —
+   and never use raw palette shades or Tailwind dark: prefixes.
-   Two ways to customize brand colors:
+   Each semantic color has a -foreground companion for accessible text pairing:
+   bg-primary + text-primary-foreground is always readable.
-   1. Define a shade scale (Tailwind-native):
+   Host apps can customize brand colors in two ways:
+   1. Define a shade scale (Tailwind-native approach):
         @theme {
           --color-primary-50:  oklch(...);
           --color-primary-500: oklch(...);
@@ -66,10 +127,15 @@
    2. Override the semantic token directly:
         @theme { --color-primary: oklch(0.55 0.10 237); }
+   See project/design-system.md for the full token table and compound variant
+   formulas that use these tokens.
 */
 @theme {
-  /* Brand / action colors — auto-wire from shade scale, fall back to defaults */
+  /* ── Brand / Action Colors ──
+     Auto-wire from shade scale (if host defines --color-*-500 etc.),
+     falling back to Tailwind's built-in palette colors as defaults. */
   --color-primary: var(--color-primary-500, var(--color-rose-500));
   --color-primary-foreground: var(--color-primary-50, white);
@@ -88,31 +154,40 @@
   --color-error: var(--color-error-500, var(--color-red-600));
   --color-error-foreground: var(--color-error-50, white);
-  /* Surface tokens */
-  --color-background: white;
-  --color-foreground: var(--color-zinc-950);
+  /* ── Surface Tokens ──
+     Neutral tokens for page backgrounds, text, borders, and UI chrome.
+     These map to Tailwind's zinc scale by default. */
+  --color-background: white;               /* Page background */
+  --color-foreground: var(--color-zinc-950); /* Default text color */
-  --color-muted: var(--color-zinc-100);
-  --color-muted-foreground: var(--color-zinc-500);
+  --color-muted: var(--color-zinc-100);           /* Subdued backgrounds (e.g., table headers) */
+  --color-muted-foreground: var(--color-zinc-500); /* Secondary/helper text */
-  --color-accent: var(--color-zinc-100);
-  --color-accent-foreground: var(--color-zinc-900);
+  --color-accent: var(--color-zinc-100);           /* Interactive hover backgrounds */
+  --color-accent-foreground: var(--color-zinc-900); /* Text on accent backgrounds */
-  --color-inverted: var(--color-zinc-900);
-  --color-inverted-foreground: white;
-  --color-elevated: var(--color-zinc-100);
-  --color-accented: var(--color-zinc-300);
+  --color-inverted: var(--color-zinc-900);    /* Inverse surface (solid neutral variant bg) */
+  --color-inverted-foreground: white;         /* Text on inverted surface */
+  --color-elevated: var(--color-zinc-100);    /* Soft/subtle neutral variant background */
+  --color-accented: var(--color-zinc-300);    /* Subtle neutral variant ring color */
-  --color-border: var(--color-zinc-200);
-  --color-border-accented: var(--color-zinc-300);
+  --color-border: var(--color-zinc-200);          /* Default borders (cards, inputs) */
+  --color-border-accented: var(--color-zinc-300); /* Emphasized borders */
-  --color-ring: var(--color-zinc-400);
+  --color-ring: var(--color-zinc-400);  /* Focus rings */
 }
 /* === Dark Mode ===
-   Redefine tokens under .dark — components never use dark: prefixes. */
+   Redefine every semantic token under .dark so components never need Tailwind
+   dark: prefixes. The .dark class is set on <html> by kiso_theme_script (a
+   blocking inline script that runs before first paint to avoid FOUC).
+   Brand colors shift from shade 500 → 400 (brighter on dark backgrounds).
+   Foreground companions shift from shade 50 → 950 (dark text on bright bg).
+   Surface tokens invert: light grays become dark grays, white becomes near-black. */
 .dark {
+  /* ── Brand / Action Colors (dark) ── */
   --color-primary: var(--color-primary-400, var(--color-rose-400));
   --color-primary-foreground: var(--color-primary-950, var(--color-zinc-950));
@@ -131,6 +206,7 @@
   --color-error: var(--color-error-400, var(--color-red-400));
   --color-error-foreground: var(--color-error-950, var(--color-zinc-950));
+  /* ── Surface Tokens (dark) ── */
   --color-background: var(--color-zinc-950);
   --color-foreground: var(--color-zinc-50);
@@ -152,9 +228,16 @@
 }
 /* === Page Defaults ===
-   Kiso automatically applies sensible base styles to <body> so host apps
-   start with the correct colors and rendering. Uses @layer base (lowest
-   Tailwind priority) — utility classes on <body> override automatically. */
+   Apply sensible base styles to <body> so host apps start with the correct
+   semantic colors and font rendering. Uses @layer base (lowest Tailwind
+   priority) so any utility classes on <body> override automatically.
+   - bg-background / text-foreground: wires semantic tokens, auto-flips in
+     dark mode without host app doing anything
+   - antialiased: subpixel rendering for crisp text
+   - font-synthesis-weight: none: prevents browsers from synthesizing bold
+     weights for the variable font (Geist handles all weights natively)
+   - text-rendering: optimizeLegibility: enables kerning and ligatures */
 @layer base {
   body {

data/app/assets/tailwind/kiso/input-otp.css CHANGED Viewed

@@ -1,4 +1,17 @@
-/* InputOTP caret blink animation — the blinking cursor in the active empty slot. */
+/* ── Input OTP ───────────────────────────────────────────────────────────────
+   Caret animation and separator-adjacent border-radius for the OTP input
+   component (kui(:input_otp)).
+   Why CSS instead of ERB?
+   1. The blinking caret requires a @keyframes animation.
+   2. Separator-adjacent slot rounding requires :has() and adjacent-sibling
+      selectors, which cannot be expressed as Tailwind utility classes.
+   ──────────────────────────────────────────────────────────────────────────── */
+/* ── Caret blink animation ─────────────────────────────────────────────────
+   A blinking cursor shown in the active (focused, empty) OTP slot. Registered
+   as a Tailwind animation token via @theme inline so it can be applied with
+   the `animate-caret-blink` utility class in the theme module. */
 @theme inline {
   --animate-caret-blink: caret-blink 1s ease-out infinite;
@@ -9,9 +22,16 @@
   20%, 50% { opacity: 0; }
 }
-/* Separator-adjacent rounding — when a separator sits inside a group,
-   round the slot edges next to it so each visual cluster has proper corners.
-   Also reset the negative margin so the slot after a separator starts fresh. */
+/* ── Separator-adjacent slot rounding ──────────────────────────────────────
+   OTP slots are visually joined (negative margin, no individual rounding) to
+   form a continuous row. When a separator element sits between slots, the
+   slots on either side of it need rounded corners to form distinct visual
+   groups. The :has() selector rounds the right edge of the slot before a
+   separator, and the adjacent-sibling selector rounds the left edge of the
+   slot after a separator (and resets its negative margin).
+   Uses @layer utilities so these rules participate in Tailwind's specificity
+   layer, matching the border-radius utilities used on the first/last slots. */
 @layer utilities {
   [data-slot="input-otp-slot"]:has(+ [data-slot="input-otp-separator"]) {

data/app/assets/tailwind/kiso/palettes/blue.css CHANGED Viewed

@@ -1,21 +1,29 @@
-/* Kiso Color Palette: Blue
+/* ── Kiso Color Palette: Blue ─────────────────────────────────────────────────
    A professional blue palette — classic SaaS/enterprise feel.
    Based on shadcn/ui's Blue theme with OKLCH color values.
+   Palettes override Kiso's default semantic color tokens (defined in engine.css)
+   using a [data-palette] attribute selector. This lets host apps switch color
+   schemes without redefining @theme variables.
    Usage:
-     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/blue.css";
+     1. Import in your Tailwind CSS: @import "kiso/palettes/blue.css";
      2. Add to your HTML: <html data-palette="blue"> or <body data-palette="blue">
-*/
+   Dark mode is handled by a companion rule below that targets either
+   `.dark [data-palette="blue"]` (dark class on an ancestor) or
+   `[data-palette="blue"].dark` (dark class on the same element).
+   ──────────────────────────────────────────────────────────────────────────── */
 [data-palette="blue"] {
-  /* Brand / action colors — vibrant blue */
+  /* ── Brand / action colors — vibrant blue ── */
   --color-primary: oklch(0.488 0.243 264.376);
   --color-primary-foreground: oklch(0.97 0.014 254.604);
   --color-secondary: oklch(0.967 0.001 286.375);
   --color-secondary-foreground: oklch(0.21 0.006 285.885);
-  /* Surface tokens — slate-tinted neutrals */
+  /* ── Surface tokens — slate-tinted neutrals ── */
   --color-background: oklch(1 0 0);
   --color-foreground: oklch(0.13 0.028 261.692);
@@ -36,6 +44,7 @@
   --color-ring: oklch(0.488 0.243 264.376);
 }
+/* Dark mode overrides */
 .dark [data-palette="blue"],
 [data-palette="blue"].dark {
   --color-primary: oklch(0.42 0.18 266);

data/app/assets/tailwind/kiso/palettes/green.css CHANGED Viewed

@@ -1,21 +1,24 @@
-/* Kiso Color Palette: Green
+/* ── Kiso Color Palette: Green ────────────────────────────────────────────────
    A fresh, natural green palette — great for eco, health, or finance apps.
    Based on shadcn/ui's Green theme with OKLCH color values.
+   Palettes override Kiso's default semantic color tokens (defined in engine.css)
+   using a [data-palette] attribute selector. See blue.css for full documentation.
    Usage:
-     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/green.css";
+     1. Import in your Tailwind CSS: @import "kiso/palettes/green.css";
      2. Add to your HTML: <html data-palette="green"> or <body data-palette="green">
-*/
+   ──────────────────────────────────────────────────────────────────────────── */
 [data-palette="green"] {
-  /* Brand / action colors — vivid green */
+  /* ── Brand / action colors — vivid green ── */
   --color-primary: oklch(0.648 0.2 131.684);
   --color-primary-foreground: oklch(0.986 0.031 120.757);
   --color-secondary: oklch(0.967 0.001 286.375);
   --color-secondary-foreground: oklch(0.21 0.006 285.885);
-  /* Surface tokens — zinc neutrals */
+  /* ── Surface tokens — zinc neutrals ── */
   --color-background: oklch(1 0 0);
   --color-foreground: oklch(0.141 0.005 285.823);
@@ -36,6 +39,7 @@
   --color-ring: oklch(0.648 0.2 131.684);
 }
+/* Dark mode overrides */
 .dark [data-palette="green"],
 [data-palette="green"].dark {
   --color-primary: oklch(0.648 0.2 131.684);

data/app/assets/tailwind/kiso/palettes/orange.css CHANGED Viewed

@@ -1,21 +1,24 @@
-/* Kiso Color Palette: Orange
+/* ── Kiso Color Palette: Orange ───────────────────────────────────────────────
    A warm, energetic palette — great for creative, food, or community apps.
    Based on shadcn/ui's Orange theme with OKLCH color values.
+   Palettes override Kiso's default semantic color tokens (defined in engine.css)
+   using a [data-palette] attribute selector. See blue.css for full documentation.
    Usage:
-     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/orange.css";
+     1. Import in your Tailwind CSS: @import "kiso/palettes/orange.css";
      2. Add to your HTML: <html data-palette="orange"> or <body data-palette="orange">
-*/
+   ──────────────────────────────────────────────────────────────────────────── */
 [data-palette="orange"] {
-  /* Brand / action colors — warm orange */
+  /* ── Brand / action colors — warm orange ── */
   --color-primary: oklch(0.646 0.222 41.116);
   --color-primary-foreground: oklch(0.98 0.016 73.684);
   --color-secondary: oklch(0.97 0.001 106.424);
   --color-secondary-foreground: oklch(0.216 0.006 56.043);
-  /* Surface tokens — warm stone neutrals */
+  /* ── Surface tokens — warm stone neutrals ── */
   --color-background: oklch(1 0 0);
   --color-foreground: oklch(0.147 0.004 49.25);
@@ -36,6 +39,7 @@
   --color-ring: oklch(0.646 0.222 41.116);
 }
+/* Dark mode overrides */
 .dark [data-palette="orange"],
 [data-palette="orange"].dark {
   --color-primary: oklch(0.705 0.213 47.604);

data/app/assets/tailwind/kiso/palettes/violet.css CHANGED Viewed

@@ -1,21 +1,24 @@
-/* Kiso Color Palette: Violet
+/* ── Kiso Color Palette: Violet ───────────────────────────────────────────────
    A rich, creative purple palette — great for design tools or premium brands.
    Based on shadcn/ui's Violet theme with OKLCH color values.
+   Palettes override Kiso's default semantic color tokens (defined in engine.css)
+   using a [data-palette] attribute selector. See blue.css for full documentation.
    Usage:
-     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/violet.css";
+     1. Import in your Tailwind CSS: @import "kiso/palettes/violet.css";
      2. Add to your HTML: <html data-palette="violet"> or <body data-palette="violet">
-*/
+   ──────────────────────────────────────────────────────────────────────────── */
 [data-palette="violet"] {
-  /* Brand / action colors — vivid violet */
+  /* ── Brand / action colors — vivid violet ── */
   --color-primary: oklch(0.541 0.281 293.009);
   --color-primary-foreground: oklch(0.969 0.016 293.756);
   --color-secondary: oklch(0.967 0.001 286.375);
   --color-secondary-foreground: oklch(0.21 0.006 285.885);
-  /* Surface tokens — gray neutrals */
+  /* ── Surface tokens — gray neutrals ── */
   --color-background: oklch(1 0 0);
   --color-foreground: oklch(0.13 0.028 261.692);
@@ -36,6 +39,7 @@
   --color-ring: oklch(0.541 0.281 293.009);
 }
+/* Dark mode overrides */
 .dark [data-palette="violet"],
 [data-palette="violet"].dark {
   --color-primary: oklch(0.606 0.25 292.717);

data/app/assets/tailwind/kiso/palettes/zinc.css CHANGED Viewed

@@ -1,21 +1,24 @@
-/* Kiso Color Palette: Zinc
-   A neutral, cool-toned palette using the Zinc scale.
-   Based on shadcn/ui's Zinc theme with OKLCH color values.
+/* ── Kiso Color Palette: Zinc ─────────────────────────────────────────────────
+   A neutral, cool-toned palette using the Zinc scale — minimal color,
+   maximum content focus. Based on shadcn/ui's Zinc theme with OKLCH values.
+   Palettes override Kiso's default semantic color tokens (defined in engine.css)
+   using a [data-palette] attribute selector. See blue.css for full documentation.
    Usage:
-     1. Import in your CSS: @import "../builds/tailwind/kiso/palettes/zinc.css";
+     1. Import in your Tailwind CSS: @import "kiso/palettes/zinc.css";
      2. Add to your HTML: <html data-palette="zinc"> or <body data-palette="zinc">
-*/
+   ──────────────────────────────────────────────────────────────────────────── */
 [data-palette="zinc"] {
-  /* Brand / action colors — zinc primary (near-black in light, near-white in dark) */
+  /* ── Brand / action colors — near-black primary (inverts in dark mode) ── */
   --color-primary: oklch(0.21 0.006 285.885);
   --color-primary-foreground: oklch(0.985 0 0);
   --color-secondary: oklch(0.967 0.001 286.375);
   --color-secondary-foreground: oklch(0.21 0.006 285.885);
-  /* Surface tokens */
+  /* ── Surface tokens ── */
   --color-background: oklch(1 0 0);
   --color-foreground: oklch(0.141 0.005 285.823);
@@ -36,6 +39,7 @@
   --color-ring: oklch(0.705 0.015 286.067);
 }
+/* Dark mode overrides */
 .dark [data-palette="zinc"],
 [data-palette="zinc"].dark {
   --color-primary: oklch(0.92 0.004 286.32);

data/app/assets/tailwind/kiso/radio-group.css CHANGED Viewed

@@ -1,7 +1,14 @@
-/* RadioGroupItem indicator — CSS ::after for the filled circle dot since
-   native <input type="radio"> can't contain child elements. Uses currentColor
-   which inherits from checked:text-{color}-foreground set by compound variants.
-   Follows the same pattern as Checkbox (mask-image with currentColor). */
+/* ── Radio Group ─────────────────────────────────────────────────────────────
+   Filled-circle indicator via CSS ::after pseudo-element for radio inputs.
+   Why CSS instead of ERB?
+   Native <input type="radio"> cannot contain child elements, so the selected
+   indicator dot must be rendered as a pseudo-element. Same pattern as
+   Checkbox — uses currentColor for the fill, which inherits the text color
+   set by compound variants (e.g., checked:text-primary-foreground).
+   The grid + place-content: center pattern centers the ::after dot within
+   the radio circle regardless of its size variant. */
 [data-radio-group-part="item"] {
   display: grid;

data/app/assets/tailwind/kiso/slider.css CHANGED Viewed

@@ -1,25 +1,44 @@
+/* ── Slider ──────────────────────────────────────────────────────────────────
+   Thumb positioning and disabled state for the custom Slider component.
+   Why CSS instead of ERB?
+   The slider thumb is positioned via inline `left: N%` styles set by the
+   kiso--slider Stimulus controller. CSS handles the centering transform
+   (translateX(-50%)) and vertical alignment that must work in concert with
+   that dynamic inline style. The disabled state uses :has(input:disabled)
+   which cannot be expressed as a Tailwind utility.
+   Uses @layer components so utility classes can override if needed.
+   ──────────────────────────────────────────────────────────────────────────── */
 @layer components {
-  /* Center the thumb over its left % position */
+  /* Center the thumb horizontally over its left % position, and vertically
+     within the track. The negative margin-top pulls the thumb up by half
+     its own height (--thumb-offset) so it sits centered on the track line. */
   [data-slot="slider-thumb"] {
     transform: translateX(-50%);
     top: 50%;
     margin-top: calc(-1 * var(--thumb-offset, 0.5rem));
   }
-  /* Size-specific thumb offsets (half the thumb size) */
+  /* Size-specific thumb offsets — each size variant has a different thumb
+     diameter, so the vertical centering offset must match. Uses :where()
+     to keep specificity low (0,0,0 for the class selector), allowing
+     the theme module's size classes to remain the authority on thumb size. */
   [data-slot="slider"] :where([data-slot="slider-thumb"].size-3) {
-    --thumb-offset: 0.375rem;
+    --thumb-offset: 0.375rem;  /* half of 0.75rem (size-3) */
   }
   [data-slot="slider"] :where([data-slot="slider-thumb"].size-4) {
-    --thumb-offset: 0.5rem;
+    --thumb-offset: 0.5rem;    /* half of 1rem (size-4) */
   }
   [data-slot="slider"] :where([data-slot="slider-thumb"].size-5) {
-    --thumb-offset: 0.625rem;
+    --thumb-offset: 0.625rem;  /* half of 1.25rem (size-5) */
   }
-  /* Disabled state */
+  /* Disabled state — dim the entire slider and prevent interaction.
+     Uses :has(input:disabled) to detect the hidden range input's state. */
   [data-slot="slider"]:has(input:disabled) {
     opacity: 0.5;
     pointer-events: none;

data/app/assets/tailwind/kiso/tooltip.css CHANGED Viewed

@@ -1,33 +1,57 @@
-/* Tooltip entry/exit animations and arrow positioning. */
+/* ── Tooltip ─────────────────────────────────────────────────────────────────
+   Display overrides, popover UA stylesheet resets, entry/exit animations,
+   and reduced-motion support for the Tooltip component.
-/* Tooltip root — inline-flex via @layer components so utilities can override */
+   Why CSS instead of ERB?
+   Tooltips use [popover="manual"] for positioning (via Floating UI) and need
+   CSS to work around browser UA stylesheet conflicts, animate entry/exit,
+   and handle the :popover-open pseudo-class. None of this can be expressed
+   as Tailwind utility classes.
+   Key browser issue: the UA stylesheet hides [popover]:not(:popover-open)
+   with display: none in the UA layer. But Tailwind's `flex` utility class
+   (in the author layer) has higher specificity and overrides it, making
+   non-open popovers visible. We fix this with an explicit author-layer rule.
+   See MEMORY.md for the full explanation.
+   ──────────────────────────────────────────────────────────────────────────── */
+/* ── Root display ──────────────────────────────────────────────────────────
+   Same pattern as Button: @layer components so utility classes can override. */
 @layer components {
   [data-slot="tooltip"] {
     display: inline-flex;
   }
 }
-/* The browser UA stylesheet hides [popover]:not(:popover-open) with
-   display: none, but Tailwind's `flex` utility (author layer) overrides it.
-   Explicitly enforce hidden state for non-open popovers. */
+/* ── Popover UA stylesheet overrides ──────────────────────────────────────
+   Two browser UA stylesheet behaviors must be explicitly overridden:
+   1. Hidden state: the UA hides non-open popovers with display: none, but
+      Tailwind's `flex` utility (author layer) overrides the UA layer. This
+      rule enforces hidden state in the author layer to match the UA intent.
+   2. Positioning reset: browsers apply inset: 0, margin: auto, and
+      width/height: fit-content to :popover-open elements, which fights
+      Floating UI's inline positioning styles. We reset inset and margin
+      so Floating UI has full control over placement. */
 [data-slot="tooltip-content"]:not(:popover-open) {
   display: none;
 }
-/* Reset UA popover styles — browsers apply inset: 0, margin: auto, and
-   width/height: fit-content to [popover]:popover-open, which overrides
-   Floating UI's inline-style positioning. */
 [data-slot="tooltip-content"] {
   inset: unset;
   margin: 0;
 }
-/* Entry animation — fade + scale from 95% */
+/* ── Entry/exit animations ────────────────────────────────────────────────
+   data-state is set by the kiso--tooltip Stimulus controller:
+   - "open" on show (after showPopover()) → fade in + scale up from 95%
+   - "closed" on hide (before hidePopover()) → fade out + scale down to 95%
+     with `forwards` fill to hold opacity: 0 until hidePopover() removes it */
 [data-slot="tooltip-content"][data-state="open"] {
   animation: kiso-tooltip-in 150ms ease-out;
 }
-/* Exit animation — fade out + scale to 95% */
 [data-slot="tooltip-content"][data-state="closed"] {
   animation: kiso-tooltip-out 100ms ease-in forwards;
 }
@@ -39,7 +63,9 @@
   to { opacity: 0; transform: scale(0.95); }
 }
-/* Respect reduced motion */
+/* ── Reduced motion ───────────────────────────────────────────────────────
+   Disable animations for users who prefer reduced motion. The tooltip will
+   still appear/disappear, just without the fade/scale transition. */
 @media (prefers-reduced-motion: reduce) {
   [data-slot="tooltip-content"][data-state="open"],
   [data-slot="tooltip-content"][data-state="closed"] {