kiso 0.1.0.pre → 0.2.0.pre

data/lib/kiso/themes/field_set.rb

@@ -0,0 +1,32 @@
+module Kiso
+  module Themes
+    # Fieldset grouping for related form controls (e.g. checkbox/radio groups).
+    #
+    # Automatically tightens gap when containing checkbox or radio groups.
+    #
+    # @example
+    #   FieldSet.render
+    #
+    # Sub-parts: {FieldLegend}
+    FieldSet = ClassVariants.build(
+      base: "flex flex-col gap-6 " \
+            "has-[>[data-slot=checkbox-group]]:gap-3 " \
+            "has-[>[data-slot=radio-group]]:gap-3"
+    )
+
+    # Heading for a {FieldSet}.
+    #
+    # Variants:
+    # - +variant+ — :legend (default, larger text), :label (smaller, label-sized)
+    FieldLegend = ClassVariants.build(
+      base: "mb-3 font-medium",
+      variants: {
+        variant: {
+          legend: "text-base",
+          label: "text-sm"
+        }
+      },
+      defaults: {variant: :legend}
+    )
+  end
+end

data/lib/kiso/themes/input.rb

@@ -0,0 +1,33 @@
+module Kiso
+  module Themes
+    # Single-line text input field.
+    #
+    # @example
+    #   Input.render(variant: :outline, size: :md)
+    #
+    # Variants:
+    # - +variant+ — :outline (default), :soft, :ghost
+    # - +size+ — :sm, :md (default), :lg
+    Input = ClassVariants.build(
+      base: "text-foreground w-full min-w-0 rounded-md outline-none transition-[color,box-shadow] " \
+            "placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground " \
+            "file:text-foreground file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium " \
+            "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 " \
+            "focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary " \
+            "aria-invalid:ring-error aria-invalid:focus-visible:ring-error",
+      variants: {
+        variant: {
+          outline: "bg-background ring ring-inset ring-accented shadow-xs",
+          soft: "bg-elevated/50 hover:bg-elevated focus:bg-elevated",
+          ghost: "bg-transparent hover:bg-elevated focus:bg-elevated"
+        },
+        size: {
+          sm: "h-8 px-2.5 py-1 text-sm",
+          md: "h-9 px-3 py-1 text-base md:text-sm",
+          lg: "h-10 px-3 py-2 text-base"
+        }
+      },
+      defaults: {variant: :outline, size: :md}
+    )
+  end
+end

data/lib/kiso/themes/input_group.rb

@@ -0,0 +1,39 @@
+module Kiso
+  module Themes
+    # Wrapper that combines an input with leading/trailing addons (icons, text, buttons).
+    #
+    # Resets the inner input's ring/shadow so the group ring applies uniformly.
+    #
+    # @example
+    #   InputGroup.render
+    #
+    # Sub-parts: {InputGroupAddon}
+    InputGroup = ClassVariants.build(
+      base: "relative flex w-full items-center rounded-md text-foreground " \
+            "ring ring-inset ring-accented shadow-xs " \
+            "h-9 min-w-0 has-[>textarea]:h-auto " \
+            "has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-inset has-[:focus-visible]:ring-primary " \
+            "has-[[aria-invalid]]:ring-error " \
+            "[&_input]:flex-1 [&_input]:rounded-none [&_input]:border-0 [&_input]:shadow-none [&_input]:ring-0 [&_input]:bg-transparent [&_input]:focus-visible:ring-0 " \
+            "[&_textarea]:flex-1 [&_textarea]:rounded-none [&_textarea]:border-0 [&_textarea]:shadow-none [&_textarea]:ring-0 [&_textarea]:bg-transparent [&_textarea]:focus-visible:ring-0",
+      variants: {},
+      defaults: {}
+    )
+
+    # Leading or trailing addon element (icon, text, button) inside an {InputGroup}.
+    #
+    # Variants:
+    # - +align+ — :start (default, left side), :end (right side)
+    InputGroupAddon = ClassVariants.build(
+      base: "text-muted-foreground flex items-center justify-center gap-2 py-1.5 text-sm font-medium select-none " \
+            "[&_svg:not([class*='size-'])]:size-4",
+      variants: {
+        align: {
+          start: "ps-3",
+          end: "pe-3"
+        }
+      },
+      defaults: {align: :start}
+    )
+  end
+end

data/lib/kiso/themes/input_otp.rb

@@ -0,0 +1,46 @@
+module Kiso
+  module Themes
+    # OTP/PIN code input container. Positions a transparent real +<input>+
+    # over visual slot divs managed by the +kiso--input-otp+ Stimulus controller.
+    #
+    # @example
+    #   InputOtp.render
+    InputOtp = ClassVariants.build(
+      base: "relative text-foreground flex items-center gap-2 has-disabled:opacity-50"
+    )
+
+    # Groups adjacent slots visually (e.g., first 3 digits, last 3 digits).
+    InputOtpGroup = ClassVariants.build(
+      base: "flex items-center"
+    )
+
+    # Individual character display slot with connected borders.
+    # Content and active state managed by +kiso--input-otp+ controller.
+    #
+    # @example
+    #   InputOtpSlot.render(size: :md)
+    InputOtpSlot = ClassVariants.build(
+      base: "border-accented relative flex items-center justify-center " \
+            "border-y border-r shadow-xs transition-all outline-none " \
+            "first:rounded-l-md first:border-l last:rounded-r-md " \
+            "data-[active=true]:z-10 data-[active=true]:border-primary " \
+            "data-[active=true]:ring-[3px] data-[active=true]:ring-primary/50 " \
+            "aria-invalid:border-error " \
+            "data-[active=true]:aria-invalid:border-error " \
+            "data-[active=true]:aria-invalid:ring-error/20",
+      variants: {
+        size: {
+          sm: "size-8 text-xs",
+          md: "size-9 text-sm",
+          lg: "size-10 text-base"
+        }
+      },
+      defaults: {size: :md}
+    )
+
+    # Separator between groups (renders a minus icon by default).
+    InputOtpSeparator = ClassVariants.build(
+      base: "flex items-center text-muted-foreground [&>svg]:size-4"
+    )
+  end
+end

data/lib/kiso/themes/kbd.rb

@@ -0,0 +1,31 @@
+module Kiso
+  module Themes
+    # Keyboard shortcut indicator (e.g. +Ctrl+K+, +Cmd+S+).
+    #
+    # @example
+    #   Kbd.render(size: :md)
+    #
+    # Variants:
+    # - +size+ — :sm, :md (default), :lg
+    #
+    # Sub-parts: {KbdGroup}
+    Kbd = ClassVariants.build(
+      base: "bg-muted text-foreground pointer-events-none inline-flex items-center " \
+            "justify-center gap-1 rounded-sm font-sans font-medium select-none " \
+            "[&_svg:not([class*='size-'])]:size-3",
+      variants: {
+        size: {
+          sm: "h-4 min-w-4 px-0.5 text-xs",
+          md: "h-5 min-w-5 px-1 text-xs",
+          lg: "h-6 min-w-6 px-1.5 text-xs"
+        }
+      },
+      defaults: {size: :md}
+    )
+
+    # Inline container for multiple {Kbd} elements (e.g. +Ctrl+ + +K+).
+    KbdGroup = ClassVariants.build(
+      base: "inline-flex items-center gap-1"
+    )
+  end
+end

data/lib/kiso/themes/label.rb

@@ -0,0 +1,16 @@
+module Kiso
+  module Themes
+    # Standalone text label for form controls.
+    #
+    # Automatically dims when the associated control is disabled (via
+    # +group-data-[disabled]+ and +peer-disabled+ selectors).
+    #
+    # @example
+    #   Label.render
+    Label = ClassVariants.build(
+      base: "flex items-center gap-2 text-sm leading-none font-medium select-none " \
+            "group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 " \
+            "peer-disabled:cursor-not-allowed peer-disabled:opacity-50"
+    )
+  end
+end

data/lib/kiso/themes/nav.rb

@@ -0,0 +1,27 @@
+module Kiso
+  module Themes
+    Nav = ClassVariants.build(
+      base: "flex flex-col gap-2"
+    )
+
+    NavSection = ClassVariants.build(
+      base: "relative flex w-full min-w-0 flex-col gap-1 p-2"
+    )
+
+    NavSectionTitle = ClassVariants.build(
+      base: "flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-muted-foreground cursor-pointer select-none list-none [&::-webkit-details-marker]:hidden"
+    )
+
+    NavSectionContent = ClassVariants.build(
+      base: "flex w-full min-w-0 flex-col gap-1 text-sm"
+    )
+
+    NavItem = ClassVariants.build(
+      base: "group relative w-full flex items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm outline-hidden transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-accent-foreground [&>svg]:size-4 [&>svg]:shrink-0"
+    )
+
+    NavItemBadge = ClassVariants.build(
+      base: "ms-auto pointer-events-none flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium tabular-nums select-none"
+    )
+  end
+end

data/lib/kiso/themes/pagination.rb

@@ -0,0 +1,73 @@
+module Kiso
+  module Themes
+    # @return [String] shared base classes for all pagination link-type elements.
+    #   Matches shadcn's buttonVariants base (ghost/outline neutral).
+    PAGINATION_LINK_BASE = "inline-flex items-center justify-center whitespace-nowrap rounded-md " \
+                           "text-sm font-medium transition-all " \
+                           "focus-visible:outline-2 focus-visible:outline-offset-2 " \
+                           "disabled:pointer-events-none disabled:opacity-50 " \
+                           "aria-disabled:cursor-not-allowed aria-disabled:opacity-50 " \
+                           "#{Shared::SVG_BASE}"
+
+    # @return [Hash] shared active/inactive variants for pagination links.
+    #   +active: true+ renders outline neutral style, +active: false+ renders ghost.
+    PAGINATION_ACTIVE_VARIANTS = {
+      active: {
+        true => "ring ring-inset text-foreground bg-background ring-accented " \
+                "hover:bg-elevated focus-visible:ring-2 focus-visible:ring-inverted",
+        false => "text-foreground hover:bg-elevated active:bg-accented/75 focus-visible:outline-inverted"
+      }
+    }.freeze
+
+    # Page navigation with numbered links, prev/next buttons, and ellipsis.
+    #
+    # @example
+    #   Pagination.render
+    #
+    # Sub-parts: {PaginationContent}, {PaginationItem}, {PaginationLink},
+    # {PaginationPrevious}, {PaginationNext}, {PaginationEllipsis}
+    Pagination = ClassVariants.build(
+      base: "mx-auto flex w-full justify-center"
+    )
+
+    # Flex row container for pagination items.
+    PaginationContent = ClassVariants.build(
+      base: "flex flex-row items-center gap-1"
+    )
+
+    # Wrapper for a single pagination element (link, ellipsis, etc.).
+    PaginationItem = ClassVariants.build(
+      base: ""
+    )
+
+    # Square button for a page number. Switches between ghost and outline
+    # style based on the +active+ variant.
+    #
+    # Variants:
+    # - +active+ — +true+ (outline, current page), +false+ (default, ghost)
+    PaginationLink = ClassVariants.build(
+      base: "#{PAGINATION_LINK_BASE} size-9",
+      variants: PAGINATION_ACTIVE_VARIANTS,
+      defaults: {active: false}
+    )
+
+    # "Previous" navigation link with chevron icon.
+    PaginationPrevious = ClassVariants.build(
+      base: "#{PAGINATION_LINK_BASE} h-9 gap-1 px-2.5 sm:pl-2.5",
+      variants: PAGINATION_ACTIVE_VARIANTS,
+      defaults: {active: false}
+    )
+
+    # "Next" navigation link with chevron icon.
+    PaginationNext = ClassVariants.build(
+      base: "#{PAGINATION_LINK_BASE} h-9 gap-1 px-2.5 sm:pr-2.5",
+      variants: PAGINATION_ACTIVE_VARIANTS,
+      defaults: {active: false}
+    )
+
+    # Ellipsis indicator for skipped page ranges.
+    PaginationEllipsis = ClassVariants.build(
+      base: "pointer-events-none flex size-9 items-center justify-center text-muted-foreground"
+    )
+  end
+end

data/lib/kiso/themes/popover.rb

@@ -0,0 +1,32 @@
+module Kiso
+  module Themes
+    # Floating panel anchored to a trigger element.
+    #
+    # @example
+    #   PopoverContent.render
+    #
+    # Sub-parts: {PopoverContent}, {PopoverHeader}, {PopoverTitle},
+    # {PopoverDescription}
+
+    # The floating panel itself. Positioned via the Popover Stimulus controller.
+    PopoverContent = ClassVariants.build(
+      base: "bg-background text-foreground z-50 w-72 rounded-md " \
+            "ring ring-inset ring-border p-4 shadow-md outline-hidden"
+    )
+
+    # Header section with title and description.
+    PopoverHeader = ClassVariants.build(
+      base: "flex flex-col gap-1 text-sm"
+    )
+
+    # Popover heading text.
+    PopoverTitle = ClassVariants.build(
+      base: "font-medium"
+    )
+
+    # Popover body text.
+    PopoverDescription = ClassVariants.build(
+      base: "text-muted-foreground"
+    )
+  end
+end

data/lib/kiso/themes/radio_group.rb

@@ -0,0 +1,43 @@
+module Kiso
+  module Themes
+    # Grid container for a set of {RadioGroupItem} elements.
+    #
+    # @example
+    #   RadioGroup.render
+    #
+    # Sub-parts: {RadioGroupItem}
+    RadioGroup = ClassVariants.build(
+      base: "grid gap-3"
+    )
+
+    # Native +<input type="radio">+ styled with +appearance-none+ and semantic
+    # color tokens. Uses the same color compound variant pattern as {Checkbox}.
+    #
+    # @example
+    #   RadioGroupItem.render(color: :primary)
+    #
+    # Variants:
+    # - +color+ — :primary (default), :secondary, :success, :info, :warning, :error, :neutral
+    RadioGroupItem = ClassVariants.build(
+      base: "appearance-none aspect-square size-4 shrink-0 rounded-full " \
+            "ring ring-inset ring-accented shadow-xs " \
+            "transition-[color,box-shadow] outline-none " \
+            "disabled:cursor-not-allowed disabled:opacity-50 " \
+            "focus-visible:ring-[3px] " \
+            "aria-invalid:ring-error/30 aria-invalid:ring-2",
+      variants: {
+        color: COLORS.index_with { "" }
+      },
+      compound_variants: [
+        {color: :primary, class: "checked:bg-primary checked:ring-primary checked:text-primary-foreground focus-visible:ring-primary/50"},
+        {color: :secondary, class: "checked:bg-secondary checked:ring-secondary checked:text-secondary-foreground focus-visible:ring-secondary/50"},
+        {color: :success, class: "checked:bg-success checked:ring-success checked:text-success-foreground focus-visible:ring-success/50"},
+        {color: :info, class: "checked:bg-info checked:ring-info checked:text-info-foreground focus-visible:ring-info/50"},
+        {color: :warning, class: "checked:bg-warning checked:ring-warning checked:text-warning-foreground focus-visible:ring-warning/50"},
+        {color: :error, class: "checked:bg-error checked:ring-error checked:text-error-foreground focus-visible:ring-error/50"},
+        {color: :neutral, class: "checked:bg-inverted checked:ring-inverted checked:text-inverted-foreground focus-visible:ring-inverted/50"}
+      ],
+      defaults: {color: :primary}
+    )
+  end
+end

data/lib/kiso/themes/select.rb

@@ -0,0 +1,78 @@
+module Kiso
+  module Themes
+    # Native-like select dropdown with custom styling and keyboard navigation.
+    #
+    # @example
+    #   Select.render
+    #
+    # Sub-parts: {SelectTrigger}, {SelectValue}, {SelectContent}, {SelectGroup},
+    # {SelectLabel}, {SelectItem}, {SelectItemIndicator}, {SelectSeparator}
+    Select = ClassVariants.build(
+      base: "relative text-foreground"
+    )
+
+    # Button that displays the selected value and opens the dropdown.
+    #
+    # Variants:
+    # - +size+ — :sm, :md (default)
+    SelectTrigger = ClassVariants.build(
+      base: "text-foreground flex w-full items-center justify-between gap-2 rounded-md " \
+            "bg-background px-3 py-2 text-sm whitespace-nowrap shadow-xs " \
+            "ring ring-inset ring-accented " \
+            "outline-none transition-[color,box-shadow] " \
+            "focus-visible:ring-2 focus-visible:ring-primary " \
+            "aria-invalid:ring-error aria-invalid:focus-visible:ring-error " \
+            "disabled:cursor-not-allowed disabled:opacity-50 " \
+            "#{Shared::SVG_BASE} " \
+            "[&_svg:not([class*='text-'])]:text-muted-foreground",
+      variants: {
+        size: {
+          sm: "h-8",
+          md: "h-9"
+        }
+      },
+      defaults: {size: :md}
+    )
+
+    # Display area for the currently selected value inside {SelectTrigger}.
+    SelectValue = ClassVariants.build(
+      base: "line-clamp-1 flex items-center gap-2"
+    )
+
+    # Dropdown panel containing the selectable items.
+    SelectContent = ClassVariants.build(
+      base: "relative bg-background text-foreground z-50 max-h-60 min-w-32 " \
+            "overflow-x-hidden overflow-y-auto rounded-md shadow-md ring ring-inset ring-border p-1"
+    )
+
+    # Semantic grouping wrapper for related select items.
+    SelectGroup = ClassVariants.build(
+      base: ""
+    )
+
+    # Non-interactive heading for a {SelectGroup}.
+    SelectLabel = ClassVariants.build(
+      base: Shared::MENU_LABEL
+    )
+
+    # Selectable option within the dropdown.
+    SelectItem = ClassVariants.build(
+      base: "relative flex w-full cursor-default items-center gap-2 rounded-sm " \
+            "py-1.5 pr-8 pl-2 text-sm outline-none select-none " \
+            "data-[highlighted]:bg-elevated data-[highlighted]:text-foreground " \
+            "data-[disabled]:pointer-events-none data-[disabled]:opacity-50 " \
+            "#{Shared::SVG_BASE} " \
+            "[&_svg:not([class*='text-'])]:text-muted-foreground"
+    )
+
+    # Check mark indicator shown on the selected item.
+    SelectItemIndicator = ClassVariants.build(
+      base: "absolute right-2 flex size-3.5 items-center justify-center"
+    )
+
+    # Horizontal divider between select items or groups.
+    SelectSeparator = ClassVariants.build(
+      base: "bg-border pointer-events-none -mx-1 my-1 h-px"
+    )
+  end
+end

data/lib/kiso/themes/select_native.rb

@@ -0,0 +1,49 @@
+module Kiso
+  module Themes
+    # Wrapper for the select native element and its chevron icon overlay.
+    #
+    # @example
+    #   SelectNativeWrapper.render
+    SelectNativeWrapper = ClassVariants.build(
+      base: "relative w-full has-[select:disabled]:opacity-50"
+    )
+
+    # Native HTML `<select>` element with appearance-none and Kiso styling.
+    #
+    # @example
+    #   SelectNative.render(variant: :outline, size: :md)
+    #
+    # Variants:
+    # - +variant+ — :outline (default), :soft, :ghost
+    # - +size+ — :sm, :md (default), :lg
+    SelectNative = ClassVariants.build(
+      base: "text-foreground w-full min-w-0 appearance-none rounded-md pr-9 outline-none " \
+            "transition-[color,box-shadow] " \
+            "disabled:pointer-events-none disabled:cursor-not-allowed " \
+            "focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary " \
+            "aria-invalid:ring-error aria-invalid:focus-visible:ring-error",
+      variants: {
+        variant: {
+          outline: "bg-background ring ring-inset ring-accented shadow-xs",
+          soft: "bg-elevated/50 hover:bg-elevated focus:bg-elevated",
+          ghost: "bg-transparent hover:bg-elevated focus:bg-elevated"
+        },
+        size: {
+          sm: "h-8 px-2.5 py-1 text-sm",
+          md: "h-9 px-3 py-1 text-base md:text-sm",
+          lg: "h-10 px-3 py-2 text-base"
+        }
+      },
+      defaults: {variant: :outline, size: :md}
+    )
+
+    # Chevron icon overlay positioned inside the select native wrapper.
+    #
+    # @example
+    #   SelectNativeIcon.render
+    SelectNativeIcon = ClassVariants.build(
+      base: "text-muted-foreground pointer-events-none absolute top-1/2 right-3.5 " \
+            "size-4 -translate-y-1/2 opacity-50 select-none"
+    )
+  end
+end

data/lib/kiso/themes/separator.rb

@@ -1,8 +1,14 @@
 module Kiso
   module Themes
+    # Visual divider between content sections.
+    #
+    # @example
+    #   Separator.render(orientation: :horizontal)
+    #
+    # Variants:
+    # - +orientation+ — :horizontal (default), :vertical
+    #
     # shadcn base: bg-border shrink-0
-    # Horizontal: h-px w-full
-    # Vertical: h-full w-px
     Separator = ClassVariants.build(
       base: "bg-border shrink-0",
       variants: {

data/lib/kiso/themes/shared.rb

@@ -0,0 +1,51 @@
+module Kiso
+  # Theme definitions for all Kiso components.
+  #
+  # Each constant is a +ClassVariants+ instance that maps variant options
+  # to Tailwind CSS class strings. Call +.render+ with variant options to
+  # get the resolved class string:
+  #
+  #   Kiso::Themes::Badge.render(color: :success, variant: :soft, size: :md)
+  #   # => "inline-flex items-center ... bg-success/10 text-success ..."
+  #
+  # Compound components (Card, Table, Field, etc.) have multiple constants
+  # for the root and each sub-part (e.g. +Card+, +CardHeader+, +CardTitle+).
+  #
+  # @see project/design-system.md for compound variant formulas and token mapping
+  # @see project/component-strategy.md for architecture patterns
+  module Themes
+    # Shared class strings for patterns that are identical across multiple
+    # components. Using shared constants prevents drift when updating styles.
+    #
+    # Only extract constants that are byte-for-byte identical across components.
+    # Component-specific variations (e.g., CommandSeparator missing +my-1+,
+    # SelectSeparator with +pointer-events-none+) should remain inline to
+    # preserve shadcn fidelity.
+    module Shared
+      # Used by: Button, Toggle, ToggleGroupItem, SelectTrigger, SelectItem,
+      # ComboboxItem, CommandItem, DropdownMenuItem, DropdownMenuSubTrigger,
+      # DropdownMenuCheckboxItem, DropdownMenuRadioItem (via CHECKABLE_ITEM),
+      # PaginationLink/Previous/Next (via PAGINATION_LINK_BASE)
+      SVG_BASE = "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
+
+      # Used by: ComboboxSeparator, DropdownMenuSeparator
+      # (CommandSeparator omits my-1, SelectSeparator adds pointer-events-none — both per shadcn)
+      ITEM_SEPARATOR = "bg-border -mx-1 my-1 h-px"
+
+      # Used by: ComboboxLabel, SelectLabel
+      # (CommandGroupHeading adds font-medium — per shadcn)
+      MENU_LABEL = "text-muted-foreground px-2 py-1.5 text-xs"
+
+      # Used by: CommandShortcut, DropdownMenuShortcut
+      MENU_SHORTCUT = "text-muted-foreground ml-auto text-xs tracking-widest"
+
+      # Shared base for checkbox and radio items in DropdownMenu.
+      # These are structurally identical — same layout, same interactive states.
+      CHECKABLE_ITEM = "relative flex cursor-default items-center gap-2 rounded-sm " \
+                       "py-1.5 pr-2 pl-8 text-sm outline-none select-none " \
+                       "data-[highlighted]:bg-elevated data-[highlighted]:text-foreground " \
+                       "data-[disabled]:pointer-events-none data-[disabled]:opacity-50 " \
+                       "#{SVG_BASE}"
+    end
+  end
+end

data/lib/kiso/themes/stats_card.rb

@@ -1,9 +1,19 @@
 module Kiso
   module Themes
-    # Stats card — specialized Card layout for dashboard metrics.
-    # Same variant axis as Card (outline/soft/subtle) with tighter spacing.
-    # shadcn ref: section-cards.tsx (Card + CardDescription + CardTitle + CardAction)
-    # Maquina ref: stats/_stats_card.html.erb
+    # Compact card for displaying a single dashboard metric.
+    #
+    # Same variant axis as {Card} (outline/soft/subtle) with tighter spacing.
+    #
+    # @example
+    #   StatsCard.render(variant: :outline)
+    #
+    # Variants:
+    # - +variant+ — :outline (default), :soft, :subtle
+    #
+    # Sub-parts: {StatsCardHeader}, {StatsCardLabel}, {StatsCardValue},
+    # {StatsCardDescription}
+    #
+    # Related: {StatsGrid} for responsive grid layout of multiple stats cards.
     StatsCard = ClassVariants.build(
       base: "flex flex-col gap-2 rounded-xl p-4 text-foreground",
       variants: {
@@ -16,32 +26,34 @@ module Kiso
       defaults: {variant: :outline}
     )
 
-    # shadcn: CardHeader with CardDescription + CardAction in a row
-    # Flex row for label on left, optional icon/badge on right.
+    # Header row with label on the left and optional icon/badge on the right.
     StatsCardHeader = ClassVariants.build(
       base: "flex items-center justify-between gap-2"
     )
 
-    # shadcn: CardDescription — text-sm text-muted-foreground
-    # The metric name ("Total Revenue", "New Customers").
+    # The metric name (e.g. "Total Revenue", "New Customers").
     StatsCardLabel = ClassVariants.build(
       base: "text-sm font-medium text-muted-foreground"
     )
 
-    # shadcn: CardTitle overridden to text-2xl font-semibold tabular-nums
-    # The big metric number ("$1,250.00", "45,678").
+    # The prominent metric number (e.g. "$1,250.00", "45,678").
+    # Uses +tabular-nums+ for aligned digits.
     StatsCardValue = ClassVariants.build(
       base: "text-2xl font-semibold tabular-nums"
     )
 
-    # shadcn: CardFooter description — text-xs text-muted-foreground
-    # Trend text, subtitle, or additional context.
+    # Supplementary text below the value (e.g. trend info, subtitle).
     StatsCardDescription = ClassVariants.build(
       base: "text-xs text-muted-foreground"
     )
 
-    # Responsive grid wrapper for stats cards.
-    # Maquina ref: stats/_stats_grid.html.erb
+    # Responsive grid layout for arranging multiple {StatsCard} instances.
+    #
+    # @example
+    #   StatsGrid.render(columns: 4)
+    #
+    # Variants:
+    # - +columns+ — 2, 3, 4 (default)
     StatsGrid = ClassVariants.build(
       base: "grid grid-cols-1 gap-4",
       variants: {