kiso 0.1.0.pre → 0.2.0.pre

data/lib/kiso/themes/breadcrumb.rb

@@ -0,0 +1,44 @@
+module Kiso
+  module Themes
+    # Navigation breadcrumb trail rendered as a +<nav>+ element.
+    #
+    # @example
+    #   Breadcrumb.render
+    #
+    # Sub-parts: {BreadcrumbList}, {BreadcrumbItem}, {BreadcrumbLink},
+    # {BreadcrumbPage}, {BreadcrumbSeparator}, {BreadcrumbEllipsis}
+    Breadcrumb = ClassVariants.build(
+      base: ""
+    )
+
+    # Ordered list (+<ol>+) containing breadcrumb items.
+    BreadcrumbList = ClassVariants.build(
+      base: "text-muted-foreground flex flex-wrap items-center gap-1.5 text-sm break-words sm:gap-2.5"
+    )
+
+    # List item (+<li>+) wrapping a link or page indicator.
+    BreadcrumbItem = ClassVariants.build(
+      base: "inline-flex items-center gap-1.5"
+    )
+
+    # Clickable link to an ancestor page.
+    BreadcrumbLink = ClassVariants.build(
+      base: "hover:text-foreground transition-colors"
+    )
+
+    # Current page indicator (non-interactive, +aria-current="page"+).
+    BreadcrumbPage = ClassVariants.build(
+      base: "text-foreground font-normal"
+    )
+
+    # Chevron or custom separator between breadcrumb items.
+    BreadcrumbSeparator = ClassVariants.build(
+      base: "[&>svg]:size-3.5"
+    )
+
+    # Ellipsis indicator for collapsed breadcrumb levels.
+    BreadcrumbEllipsis = ClassVariants.build(
+      base: "flex size-9 items-center justify-center"
+    )
+  end
+end

data/lib/kiso/themes/button.rb

@@ -1,12 +1,25 @@
 module Kiso
   module Themes
+    # Clickable button with color, variant, and size axes.
+    #
+    # Renders as a +<button>+ by default; the partial switches to +<a>+ when
+    # +href:+ is provided (smart tag).
+    #
+    # @example
+    #   Button.render(color: :primary, variant: :solid, size: :md)
+    #
+    # Variants:
+    # - +color+ — :primary (default), :secondary, :success, :info, :warning, :error, :neutral
+    # - +variant+ — :solid (default), :outline, :soft, :subtle, :ghost, :link
+    # - +size+ — :xs, :sm, :md (default), :lg, :xl
+    # - +block+ — +true+ for full-width, +false+ (default)
     Button = ClassVariants.build(
       base: "inline-flex items-center justify-center gap-2 font-medium whitespace-nowrap shrink-0 " \
             "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 " \
-            "[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+            "#{Shared::SVG_BASE}",
       variants: {
         variant: {
           solid: "",
@@ -21,7 +34,7 @@ module Kiso
           sm: "h-8 px-3 py-1.5 text-xs rounded-md gap-1.5 has-[>svg]:px-2.5",
           md: "h-9 px-4 py-2 text-sm rounded-md gap-2 has-[>svg]:px-3",
           lg: "h-10 px-5 py-2.5 text-sm rounded-md gap-2 has-[>svg]:px-4",
-          xl: "h-11 px-6 py-3 text-base rounded-lg gap-2.5 has-[>svg]:px-5 [&_svg:not([class*='size-'])]:size-5"
+          xl: "h-11 px-6 py-3 text-base rounded-md gap-2.5 has-[>svg]:px-5 [&_svg:not([class*='size-'])]:size-5"
         },
         color: COLORS.index_with { "" },
         block: {

data/lib/kiso/themes/card.rb

@@ -1,5 +1,16 @@
 module Kiso
   module Themes
+    # Container card with header, content, and footer sections.
+    #
+    # @example
+    #   Card.render(variant: :outline)
+    #
+    # Variants:
+    # - +variant+ — :outline (default), :soft, :subtle
+    #
+    # Sub-parts: {CardHeader}, {CardTitle}, {CardDescription}, {CardAction},
+    # {CardContent}, {CardFooter}
+    #
     # shadcn base: bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm
     # We use variant: instead of hardcoded border + shadow, and our semantic tokens.
     Card = ClassVariants.build(
@@ -16,9 +27,9 @@ module Kiso
 
     # shadcn: @container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6
     #         has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6
-    # Simplified: we don't have CardAction yet, so flex-col instead of grid.
     CardHeader = ClassVariants.build(
-      base: "flex flex-col gap-1.5 px-6"
+      base: "grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 " \
+            "has-[>[data-card-part=action]]:grid-cols-[1fr_auto]"
     )
 
     # shadcn: leading-none font-semibold
@@ -31,6 +42,11 @@ module Kiso
       base: "text-sm text-muted-foreground"
     )
 
+    # shadcn: col-start-2 row-span-2 row-start-1 self-start justify-self-end
+    CardAction = ClassVariants.build(
+      base: "col-start-2 row-span-2 row-start-1 self-start justify-self-end"
+    )
+
     # shadcn: px-6
     CardContent = ClassVariants.build(
       base: "px-6"

data/lib/kiso/themes/checkbox.rb

@@ -0,0 +1,33 @@
+module Kiso
+  module Themes
+    # Native +<input type="checkbox">+ styled with +appearance-none+ and
+    # semantic color tokens.
+    #
+    # @example
+    #   Checkbox.render(color: :primary)
+    #
+    # Variants:
+    # - +color+ — :primary (default), :secondary, :success, :info, :warning, :error, :neutral
+    Checkbox = ClassVariants.build(
+      base: "appearance-none size-4 shrink-0 rounded-[4px] " \
+            "ring ring-inset ring-accented shadow-xs " \
+            "transition-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/color_mode_button.rb

@@ -0,0 +1,15 @@
+module Kiso
+  module Themes
+    ColorModeButton = ClassVariants.build(
+      base: "inline-flex items-center justify-center rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 cursor-pointer",
+      variants: {
+        size: {
+          sm: "w-7 h-7 [&>svg]:size-3.5",
+          md: "w-8 h-8 [&>svg]:size-4",
+          lg: "w-9 h-9 [&>svg]:size-5"
+        }
+      },
+      defaults: {size: :md}
+    )
+  end
+end

data/lib/kiso/themes/color_mode_select.rb

@@ -0,0 +1,7 @@
+module Kiso
+  module Themes
+    ColorModeSelect = ClassVariants.build(
+      base: ""
+    )
+  end
+end

data/lib/kiso/themes/combobox.rb

@@ -0,0 +1,97 @@
+module Kiso
+  module Themes
+    # Searchable dropdown (autocomplete) with keyboard navigation.
+    #
+    # @example
+    #   Combobox.render
+    #
+    # Sub-parts: {ComboboxInput}, {ComboboxContent}, {ComboboxList},
+    # {ComboboxItem}, {ComboboxItemIndicator}, {ComboboxGroup}, {ComboboxLabel},
+    # {ComboboxEmpty}, {ComboboxSeparator}, {ComboboxChips}, {ComboboxChip},
+    # {ComboboxChipsInput}
+    Combobox = ClassVariants.build(
+      base: "relative text-foreground"
+    )
+
+    # Input wrapper (replicates {InputGroup} pattern with embedded text input).
+    ComboboxInput = ClassVariants.build(
+      base: "text-foreground flex w-full items-center rounded-md " \
+            "bg-background ring ring-inset ring-accented shadow-xs " \
+            "h-9 min-w-0 " \
+            "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 " \
+            "[&_input]:h-full [&_input]:px-3 [&_input]:py-1 [&_input]:text-base [&_input]:md:text-sm " \
+            "[&_input]:outline-none [&_input]:placeholder:text-muted-foreground " \
+            "[&_input]:disabled:cursor-not-allowed [&_input]:disabled:opacity-50"
+    )
+
+    # Dropdown panel containing the filtered list of items.
+    ComboboxContent = ClassVariants.build(
+      base: "bg-background text-foreground z-50 max-h-96 min-w-32 " \
+            "overflow-hidden rounded-md shadow-md ring ring-inset ring-border"
+    )
+
+    # Scrollable list container inside {ComboboxContent}.
+    ComboboxList = ClassVariants.build(
+      base: "scroll-py-1 overflow-y-auto p-1"
+    )
+
+    # Selectable option within the combobox dropdown.
+    ComboboxItem = 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}"
+    )
+
+    # Check mark indicator on the selected item.
+    ComboboxItemIndicator = ClassVariants.build(
+      base: "pointer-events-none absolute right-2 flex size-4 items-center justify-center"
+    )
+
+    # Semantic grouping wrapper for related combobox items.
+    ComboboxGroup = ClassVariants.build(
+      base: ""
+    )
+
+    # Non-interactive heading for a {ComboboxGroup}.
+    ComboboxLabel = ClassVariants.build(
+      base: Shared::MENU_LABEL
+    )
+
+    # "No results" message shown when the filter matches nothing.
+    ComboboxEmpty = ClassVariants.build(
+      base: "text-muted-foreground flex w-full justify-center py-2 text-center text-sm"
+    )
+
+    # Horizontal divider between combobox items or groups.
+    ComboboxSeparator = ClassVariants.build(
+      base: Shared::ITEM_SEPARATOR
+    )
+
+    # Multi-select input container displaying selected values as chips.
+    ComboboxChips = ClassVariants.build(
+      base: "text-foreground flex min-h-9 flex-wrap items-center gap-1.5 rounded-md " \
+            "bg-background ring ring-inset ring-accented shadow-xs " \
+            "px-2.5 py-1.5 text-sm transition-[color,box-shadow] " \
+            "focus-within:ring-2 focus-within:ring-inset focus-within:ring-primary " \
+            "has-[[aria-invalid]]:ring-error"
+    )
+
+    # Individual chip representing a selected value in {ComboboxChips}.
+    ComboboxChip = ClassVariants.build(
+      base: "bg-muted text-foreground flex h-5.5 w-fit items-center " \
+            "justify-center gap-1 rounded-sm px-1.5 text-xs font-medium whitespace-nowrap"
+    )
+
+    # Inline text input within the {ComboboxChips} container.
+    ComboboxChipsInput = ClassVariants.build(
+      base: "min-w-16 flex-1 bg-transparent outline-none text-base md:text-sm " \
+            "placeholder:text-muted-foreground " \
+            "disabled:cursor-not-allowed disabled:opacity-50"
+    )
+  end
+end

data/lib/kiso/themes/command.rb

@@ -0,0 +1,79 @@
+module Kiso
+  module Themes
+    # Command palette (cmdk-style) with search input, grouped items, and
+    # keyboard navigation.
+    #
+    # @example
+    #   Command.render
+    #
+    # Sub-parts: {CommandInputWrapper}, {CommandInput}, {CommandList},
+    # {CommandEmpty}, {CommandGroup}, {CommandGroupHeading}, {CommandItem},
+    # {CommandSeparator}, {CommandShortcut}, {CommandDialog}, {CommandDialogContent}
+    Command = ClassVariants.build(
+      base: "bg-background text-foreground flex h-full w-full flex-col overflow-hidden rounded-md"
+    )
+
+    # Container for the search icon and input, separated from the list by a border.
+    CommandInputWrapper = ClassVariants.build(
+      base: "flex h-9 items-center gap-2 border-b border-border px-3"
+    )
+
+    # The search text input element.
+    CommandInput = ClassVariants.build(
+      base: "placeholder:text-muted-foreground flex h-10 w-full rounded-md bg-transparent " \
+            "py-3 text-sm outline-none " \
+            "disabled:cursor-not-allowed disabled:opacity-50"
+    )
+
+    # Scrollable results container.
+    CommandList = ClassVariants.build(
+      base: "max-h-72 scroll-py-1 overflow-x-hidden overflow-y-auto"
+    )
+
+    # "No results" message shown when the search matches nothing.
+    CommandEmpty = ClassVariants.build(
+      base: "py-6 text-center text-sm"
+    )
+
+    # Logical group of related command items.
+    CommandGroup = ClassVariants.build(
+      base: "text-foreground overflow-hidden p-1"
+    )
+
+    # Label text displayed above a {CommandGroup}.
+    CommandGroupHeading = ClassVariants.build(
+      base: "text-muted-foreground px-2 py-1.5 text-xs font-medium"
+    )
+
+    # Selectable action item within the command palette.
+    CommandItem = ClassVariants.build(
+      base: "data-[selected]:bg-elevated data-[selected]:text-foreground " \
+            "[&_svg:not([class*='text-'])]:text-muted-foreground " \
+            "relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm " \
+            "outline-none select-none " \
+            "data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 " \
+            "#{Shared::SVG_BASE}"
+    )
+
+    # Horizontal divider between command groups.
+    CommandSeparator = ClassVariants.build(
+      base: "bg-border -mx-1 h-px"
+    )
+
+    # Keyboard shortcut hint displayed on the right side of a {CommandItem}.
+    CommandShortcut = ClassVariants.build(
+      base: Shared::MENU_SHORTCUT
+    )
+
+    # The native +<dialog>+ element for modal command palette usage.
+    CommandDialog = ClassVariants.build(
+      base: "fixed inset-0 z-50 m-0 h-full w-full max-w-none max-h-none bg-black/50 p-0 " \
+            "flex items-center justify-center backdrop:bg-transparent open:flex"
+    )
+
+    # Inner content wrapper inside the {CommandDialog}.
+    CommandDialogContent = ClassVariants.build(
+      base: "bg-background text-foreground overflow-hidden rounded-lg ring ring-inset ring-border shadow-lg w-full max-w-lg"
+    )
+  end
+end

data/lib/kiso/themes/dashboard.rb

@@ -0,0 +1,51 @@
+module Kiso
+  module Themes
+    DashboardGroup = ClassVariants.build(
+      base: "grid h-dvh overflow-hidden bg-background text-foreground antialiased"
+    )
+
+    DashboardNavbar = ClassVariants.build(
+      base: "flex items-center gap-3 px-4 border-b border-border bg-background shrink-0 z-[--z-topbar]"
+    )
+
+    DashboardNavbarToggle = ClassVariants.build(
+      base: "flex items-center justify-center w-8 h-8 rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0"
+    )
+
+    DashboardSidebar = ClassVariants.build(
+      base: "overflow-hidden"
+    )
+
+    DashboardPanel = ClassVariants.build(
+      base: "min-w-0 overflow-y-auto bg-background"
+    )
+
+    DashboardSidebarHeader = ClassVariants.build(
+      base: "shrink-0 flex items-center gap-1.5 px-4"
+    )
+
+    DashboardSidebarFooter = ClassVariants.build(
+      base: "shrink-0 flex items-center gap-1.5 px-4 py-2"
+    )
+
+    DashboardSidebarToggle = ClassVariants.build(
+      base: "lg:hidden flex items-center justify-center w-8 h-8 rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 cursor-pointer"
+    )
+
+    DashboardSidebarCollapse = ClassVariants.build(
+      base: "hidden lg:flex items-center justify-center w-8 h-8 rounded-md text-foreground/50 hover:text-foreground hover:bg-accent transition-colors duration-150 shrink-0 cursor-pointer"
+    )
+
+    DashboardToolbar = ClassVariants.build(
+      base: "shrink-0 flex items-center justify-between border-b border-border px-4 sm:px-6 gap-1.5 overflow-x-auto h-(--topbar-height)"
+    )
+
+    DashboardToolbarLeft = ClassVariants.build(
+      base: "flex items-center gap-1.5"
+    )
+
+    DashboardToolbarRight = ClassVariants.build(
+      base: "flex items-center gap-1.5"
+    )
+  end
+end

data/lib/kiso/themes/dropdown_menu.rb

@@ -0,0 +1,108 @@
+module Kiso
+  module Themes
+    # Context menu or action menu triggered by a button click.
+    #
+    # @example
+    #   DropdownMenu.render
+    #
+    # Sub-parts: {DropdownMenuTrigger}, {DropdownMenuContent}, {DropdownMenuItem},
+    # {DropdownMenuCheckboxItem}, {DropdownMenuRadioGroup}, {DropdownMenuRadioItem},
+    # {DropdownMenuLabel}, {DropdownMenuSeparator}, {DropdownMenuShortcut},
+    # {DropdownMenuGroup}, {DropdownMenuSub}, {DropdownMenuSubTrigger},
+    # {DropdownMenuSubContent}
+    DropdownMenu = ClassVariants.build(
+      base: "relative inline-block text-foreground"
+    )
+
+    # Wrapper for the button that opens the menu.
+    DropdownMenuTrigger = ClassVariants.build(
+      base: "inline-flex"
+    )
+
+    # The dropdown panel containing menu items.
+    DropdownMenuContent = ClassVariants.build(
+      base: "bg-background text-foreground z-50 min-w-32 " \
+            "overflow-x-hidden overflow-y-auto rounded-md ring ring-inset ring-border p-1 shadow-md"
+    )
+
+    # Clickable menu action. Supports a +destructive+ variant for
+    # dangerous actions (delete, remove, etc.).
+    #
+    # Variants:
+    # - +variant+ — :default, :destructive
+    DropdownMenuItem = ClassVariants.build(
+      base: "relative flex cursor-default items-center gap-2 rounded-sm " \
+            "px-2 py-1.5 text-sm outline-none select-none " \
+            "data-[highlighted]:bg-elevated data-[highlighted]:text-foreground " \
+            "data-[disabled]:pointer-events-none data-[disabled]:opacity-50 " \
+            "data-[inset]:pl-8 " \
+            "#{Shared::SVG_BASE} " \
+            "[&_svg:not([class*='text-'])]:text-muted-foreground",
+      variants: {
+        variant: {
+          default: "",
+          destructive: "text-error data-[highlighted]:bg-error/10 data-[highlighted]:text-error " \
+                       "[&_svg:not([class*='text-'])]:text-error"
+        }
+      },
+      defaults: {variant: :default}
+    )
+
+    # Menu item with a checkbox indicator. Uses {Shared::CHECKABLE_ITEM} base.
+    DropdownMenuCheckboxItem = ClassVariants.build(
+      base: Shared::CHECKABLE_ITEM
+    )
+
+    # Wrapper for a set of mutually exclusive {DropdownMenuRadioItem} elements.
+    DropdownMenuRadioGroup = ClassVariants.build(
+      base: ""
+    )
+
+    # Menu item with a radio indicator. Uses {Shared::CHECKABLE_ITEM} base.
+    DropdownMenuRadioItem = ClassVariants.build(
+      base: Shared::CHECKABLE_ITEM
+    )
+
+    # Non-interactive heading within the menu.
+    DropdownMenuLabel = ClassVariants.build(
+      base: "px-2 py-1.5 text-sm font-medium data-[inset]:pl-8"
+    )
+
+    # Horizontal divider between menu sections.
+    DropdownMenuSeparator = ClassVariants.build(
+      base: Shared::ITEM_SEPARATOR
+    )
+
+    # Keyboard shortcut hint on the right side of a {DropdownMenuItem}.
+    DropdownMenuShortcut = ClassVariants.build(
+      base: Shared::MENU_SHORTCUT
+    )
+
+    # Semantic grouping wrapper for related menu items.
+    DropdownMenuGroup = ClassVariants.build(
+      base: ""
+    )
+
+    # Wrapper for a nested sub-menu (trigger + content pair).
+    DropdownMenuSub = ClassVariants.build(
+      base: "relative"
+    )
+
+    # Menu item that opens a nested {DropdownMenuSubContent} on hover.
+    DropdownMenuSubTrigger = ClassVariants.build(
+      base: "flex cursor-default items-center gap-2 rounded-sm " \
+            "px-2 py-1.5 text-sm outline-none select-none " \
+            "data-[highlighted]:bg-elevated data-[highlighted]:text-foreground " \
+            "data-[state=open]:bg-elevated data-[state=open]:text-foreground " \
+            "data-[inset]:pl-8 " \
+            "#{Shared::SVG_BASE} " \
+            "[&_svg:not([class*='text-'])]:text-muted-foreground"
+    )
+
+    # Panel for nested sub-menu items (same as {DropdownMenuContent} but +shadow-lg+).
+    DropdownMenuSubContent = ClassVariants.build(
+      base: "bg-background text-foreground z-50 min-w-32 " \
+            "overflow-hidden rounded-md ring ring-inset ring-border p-1 shadow-lg"
+    )
+  end
+end

data/lib/kiso/themes/empty.rb

@@ -0,0 +1,54 @@
+module Kiso
+  module Themes
+    # Empty state placeholder for when there's no content to display.
+    #
+    # Centered layout with dashed border (border becomes visible when the user
+    # adds +border+ via +css_classes:+).
+    #
+    # @example
+    #   Empty.render
+    #
+    # Sub-parts: {EmptyHeader}, {EmptyMedia}, {EmptyTitle}, {EmptyDescription},
+    # {EmptyContent}
+    #
+    # shadcn base: flex min-w-0 flex-1 flex-col ... border-dashed p-6 ... md:p-12
+    Empty = ClassVariants.build(
+      base: "flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance text-foreground md:p-12"
+    )
+
+    # Container for the empty state's title and description.
+    EmptyHeader = ClassVariants.build(
+      base: "flex max-w-sm flex-col items-center gap-2 text-center"
+    )
+
+    # Media container for an illustration or icon above the title.
+    #
+    # Variants:
+    # - +variant+ — :default (transparent), :icon (muted background + rounded container)
+    EmptyMedia = ClassVariants.build(
+      base: "flex shrink-0 items-center justify-center mb-2 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+      variants: {
+        variant: {
+          default: "bg-transparent",
+          icon: "bg-muted text-foreground size-10 rounded-lg [&_svg:not([class*='size-'])]:size-6"
+        }
+      },
+      defaults: {variant: :default}
+    )
+
+    # Empty state heading text.
+    EmptyTitle = ClassVariants.build(
+      base: "text-lg font-medium tracking-tight"
+    )
+
+    # Empty state body text with automatic link styling.
+    EmptyDescription = ClassVariants.build(
+      base: "text-muted-foreground text-sm/relaxed [&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4"
+    )
+
+    # Container for action buttons or other interactive content.
+    EmptyContent = ClassVariants.build(
+      base: "flex w-full max-w-sm min-w-0 flex-col items-center gap-4 text-sm text-balance"
+    )
+  end
+end

data/lib/kiso/themes/field.rb

@@ -0,0 +1,76 @@
+module Kiso
+  module Themes
+    # Form field wrapper that groups a label, input, description, and error message.
+    #
+    # @example
+    #   Field.render(orientation: :vertical)
+    #
+    # Variants:
+    # - +orientation+ — :vertical (default), :horizontal, :responsive
+    #
+    # Sub-parts: {FieldContent}, {FieldLabel}, {FieldTitle}, {FieldDescription},
+    # {FieldError}, {FieldSeparator}, {FieldSeparatorText}
+    Field = ClassVariants.build(
+      base: "group/field flex w-full gap-3 text-foreground data-[invalid=true]:text-error",
+      variants: {
+        orientation: {
+          vertical: "flex-col [&>*]:w-full [&>.sr-only]:w-auto",
+          horizontal: "flex-row items-center " \
+                      "[&>[data-slot=field-label]]:flex-auto " \
+                      "has-[>[data-slot=field-content]]:items-start " \
+                      "has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+          responsive: "flex-col [&>*]:w-full [&>.sr-only]:w-auto " \
+                      "@md/field-group:flex-row @md/field-group:items-center @md/field-group:[&>*]:w-auto " \
+                      "@md/field-group:[&>[data-slot=field-label]]:flex-auto " \
+                      "@md/field-group:has-[>[data-slot=field-content]]:items-start " \
+                      "@md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px"
+        }
+      },
+      defaults: {orientation: :vertical}
+    )
+
+    # Wrapper for the input element plus description/error text within a {Field}.
+    FieldContent = ClassVariants.build(
+      base: "group/field-content flex flex-1 flex-col gap-1.5 leading-snug"
+    )
+
+    # Label container within a {Field}. Supports nested field layouts for
+    # checkbox/radio card patterns.
+    FieldLabel = ClassVariants.build(
+      base: "group/field-label peer/field-label flex w-fit gap-2 leading-snug " \
+            "group-data-[disabled=true]/field:opacity-50 " \
+            "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col " \
+            "has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border " \
+            "[&>*[data-slot=field]]:p-4"
+    )
+
+    # Title text within a {FieldLabel}.
+    FieldTitle = ClassVariants.build(
+      base: "flex w-fit items-center gap-2 text-sm leading-snug font-medium " \
+            "group-data-[disabled=true]/field:opacity-50"
+    )
+
+    # Help text below the input. Includes automatic link styling.
+    FieldDescription = ClassVariants.build(
+      base: "text-muted-foreground text-sm leading-normal font-normal " \
+            "group-has-[[data-orientation=horizontal]]/field:text-balance " \
+            "last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5 " \
+            "[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4"
+    )
+
+    # Validation error message displayed below the input.
+    FieldError = ClassVariants.build(
+      base: "text-error text-sm font-normal"
+    )
+
+    # Horizontal rule between fields (e.g. "or" divider).
+    FieldSeparator = ClassVariants.build(
+      base: "relative -my-2 h-5 text-sm"
+    )
+
+    # Text label centered on the {FieldSeparator} line.
+    FieldSeparatorText = ClassVariants.build(
+      base: "bg-background text-muted-foreground relative mx-auto block w-fit px-2"
+    )
+  end
+end

data/lib/kiso/themes/field_group.rb

@@ -0,0 +1,15 @@
+module Kiso
+  module Themes
+    # Groups multiple {Field} elements with consistent vertical spacing.
+    #
+    # Supports nesting — inner field groups use tighter +gap-4+ spacing.
+    # Uses +@container/field-group+ for responsive field orientation queries.
+    #
+    # @example
+    #   FieldGroup.render
+    FieldGroup = ClassVariants.build(
+      base: "group/field-group @container/field-group flex w-full flex-col gap-7 " \
+            "[&>[data-slot=field-group]]:gap-4"
+    )
+  end
+end