kiso 0.1.0.pre → 0.2.0.pre

data/app/views/kiso/components/table/_header.html.erb

@@ -1,7 +1,7 @@
 <%# locals: (css_classes: "", **component_options) %>
 <%= content_tag :thead,
     class: Kiso::Themes::TableHeader.render(class: css_classes),
-    data: { component: :table, table_part: :header },
+    data: kiso_prepare_options(component_options, slot: "table-header"),
     **component_options do %>
   <%= yield %>
 <% end %>

data/app/views/kiso/components/table/_row.html.erb

@@ -1,7 +1,7 @@
 <%# locals: (css_classes: "", **component_options) %>
 <%= content_tag :tr,
     class: Kiso::Themes::TableRow.render(class: css_classes),
-    data: { component: :table, table_part: :row },
+    data: kiso_prepare_options(component_options, slot: "table-row"),
     **component_options do %>
   <%= yield %>
 <% end %>

data/app/views/kiso/components/toggle_group/_item.html.erb

@@ -0,0 +1,13 @@
+<%# locals: (value: nil, variant: :default, size: :default, pressed: false, css_classes: "", **component_options) %>
+<% component_options[:type] ||= :button
+   component_options[:"aria-pressed"] = pressed %>
+<%= content_tag :button,
+    class: Kiso::Themes::ToggleGroupItem.render(variant: variant, size: size, class: css_classes),
+    data: kiso_prepare_options(component_options, slot: "toggle-group-item",
+      state: pressed ? "on" : "off",
+      value: value,
+      kiso__toggle_group_target: "item",
+      action: "click->kiso--toggle-group#toggle"),
+    **component_options do %>
+  <%= yield %>
+<% end %>

data/config/deploy.docs.yml

@@ -0,0 +1,31 @@
+service: kiso-docs
+image: steveclarke/kiso-docs
+
+servers:
+  web:
+    hosts:
+      - <%= ENV["DEPLOY_HOST"] %>
+
+proxy:
+  ssl: true
+  host: kisoui.com
+  app_port: 80
+
+registry:
+  server: localhost:5555
+
+env:
+  clear: {}
+  secret: []
+
+builder:
+  arch: amd64
+  context: docs
+  dockerfile: docs/Dockerfile
+
+ssh:
+  user: deploy
+
+aliases:
+  shell: app exec --interactive --reuse "sh"
+  logs: app logs -f

data/config/deploy.yml

@@ -0,0 +1,34 @@
+service: kiso-lookbook
+image: steveclarke/kiso-lookbook
+
+servers:
+  web:
+    hosts:
+      - <%= ENV["DEPLOY_HOST"] %>
+
+proxy:
+  ssl: true
+  host: lookbook.kisoui.com
+  app_port: 3000
+
+registry:
+  server: localhost:5555
+
+env:
+  clear:
+    RAILS_ENV: production
+    RAILS_LOG_TO_STDOUT: true
+    RAILS_SERVE_STATIC_FILES: true
+  secret:
+    - RAILS_MASTER_KEY
+
+builder:
+  arch: amd64
+
+ssh:
+  user: deploy
+
+aliases:
+  console: app exec --interactive --reuse "cd lookbook && bin/rails console"
+  shell: app exec --interactive --reuse "bash"
+  logs: app logs -f

data/config/importmap.rb

@@ -0,0 +1,10 @@
+pin_all_from Kiso::Engine.root.join("app/javascript/controllers"),
+  under: "controllers"
+
+pin_all_from Kiso::Engine.root.join("app/javascript/kiso/utils"),
+  under: "kiso-ui/utils",
+  to: "kiso/utils"
+
+# Floating UI — vendored browser ESM builds for smart positioning
+pin "@floating-ui/core", to: "kiso/vendor/floating-ui-core.js"
+pin "@floating-ui/dom", to: "kiso/vendor/floating-ui-dom.js"

data/lib/kiso/cli/base.rb

@@ -2,15 +2,25 @@
 
 require "fileutils"
 
+# Base class for all Kiso CLI commands.
+#
+# Provides file generation helpers used by subcommands like {Make}.
 class Kiso::Cli::Base < Thor
   def self.exit_on_failure? = true
 
   private
 
+  # @return [String] absolute path to the kiso gem root directory
   def gem_root
     File.expand_path("../../..", __dir__)
   end
 
+  # Creates a file at +path+ (relative to gem root) with +content+.
+  # Skips if the file already exists.
+  #
+  # @param path [String] relative path from gem root
+  # @param content [String] file contents to write
+  # @return [Boolean] +true+ if created, +false+ if skipped
   def write_file(path, content)
     full_path = File.join(gem_root, path)
 
@@ -25,6 +35,11 @@ class Kiso::Cli::Base < Thor
     true
   end
 
+  # Appends +line+ to an existing file unless it already contains that line.
+  #
+  # @param path [String] relative path from gem root
+  # @param line [String] the line to append
+  # @return [void]
   def append_to_file(path, line)
     full_path = File.join(gem_root, path)
     content = File.read(full_path)

data/lib/kiso/cli/icons.rb

@@ -2,5 +2,6 @@
 
 require "kiso/icons/commands"
 
-# Delegate bin/kiso icons → kiso-icons gem's Commands class
+# Delegates +bin/kiso icons+ subcommands to the kiso-icons gem's Commands class.
+# @see https://github.com/steveclarke/kiso-icons
 Kiso::Cli::Icons = Kiso::Icons::Commands

data/lib/kiso/cli/main.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Top-level CLI entry point. Routes to subcommands ({Icons}, {Make}).
+#
+# @example
+#   $ bin/kiso version
+#   $ bin/kiso make component alert
+#   $ bin/kiso icons list
 class Kiso::Cli::Main < Kiso::Cli::Base
   desc "version", "Show Kiso version"
   def version

data/lib/kiso/cli/make.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# Generates scaffolding for new Kiso components.
+#
+# Creates theme module, ERB partial, Lookbook preview, and updates
+# the require list and skill reference docs.
+#
+# @example
+#   $ bin/kiso make component alert
+#   $ bin/kiso make component toggle_group --no-colored
 class Kiso::Cli::Make < Kiso::Cli::Base
   desc "component NAME", "Generate a new Kiso component"
   long_desc <<~DESC
@@ -99,7 +107,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
         **Defaults:** `color: :primary, variant: :soft, size: :md`
 
         ```erb
-        <%%= kiso(:#{@name}, color: :primary, variant: :soft) { "Label" } %>
+        <%%= kui(:#{@name}, color: :primary, variant: :soft) { "Label" } %>
         ```
 
         **Theme module:** `Kiso::Themes::#{@class_name}` (`lib/kiso/themes/#{@name}.rb`)
@@ -114,7 +122,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
         **Defaults:** `variant: :default, size: :md`
 
         ```erb
-        <%%= kiso(:#{@name}) { "Label" } %>
+        <%%= kui(:#{@name}) { "Label" } %>
         ```
 
         **Theme module:** `Kiso::Themes::#{@class_name}` (`lib/kiso/themes/#{@name}.rb`)
@@ -155,7 +163,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
               { color: :info, variant: :solid, class: "bg-info text-info-foreground" },
               { color: :warning, variant: :solid, class: "bg-warning text-warning-foreground" },
               { color: :error, variant: :solid, class: "bg-error text-error-foreground" },
-              { color: :neutral, variant: :solid, class: "bg-inverted text-inverted" },
+              { color: :neutral, variant: :solid, class: "bg-inverted text-inverted-foreground" },
 
               # -- outline --
               { color: :primary, variant: :outline, class: "text-primary ring-primary/50" },
@@ -173,7 +181,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
               { color: :info, variant: :soft, class: "bg-info/10 text-info" },
               { color: :warning, variant: :soft, class: "bg-warning/10 text-warning" },
               { color: :error, variant: :soft, class: "bg-error/10 text-error" },
-              { color: :neutral, variant: :soft, class: "text-foreground bg-muted" },
+              { color: :neutral, variant: :soft, class: "text-foreground bg-elevated" },
 
               # -- subtle --
               { color: :primary, variant: :subtle, class: "bg-primary/10 text-primary ring-primary/25" },
@@ -182,7 +190,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
               { color: :info, variant: :subtle, class: "bg-info/10 text-info ring-info/25" },
               { color: :warning, variant: :subtle, class: "bg-warning/10 text-warning ring-warning/25" },
               { color: :error, variant: :subtle, class: "bg-error/10 text-error ring-error/25" },
-              { color: :neutral, variant: :subtle, class: "ring-accented text-foreground bg-muted" }
+              { color: :neutral, variant: :subtle, class: "text-foreground bg-elevated ring-accented" }
             ],
             defaults: { color: :primary, variant: :soft, size: :md }
           )
@@ -217,11 +225,12 @@ class Kiso::Cli::Make < Kiso::Cli::Base
   # -- Partial templates --
 
   def colored_partial_template
+    slot = @name.tr("_", "-")
     <<~ERB
       <%# locals: (color: :primary, variant: :soft, size: :md, css_classes: "", **component_options) %>
       <%= content_tag :div,
           class: Kiso::Themes::#{@class_name}.render(color: color, variant: variant, size: size, class: css_classes),
-          data: { component: :#{@name} },
+          data: kiso_prepare_options(component_options, slot: "#{slot}"),
           **component_options do %>
         <%= yield %>
       <% end %>
@@ -229,11 +238,12 @@ class Kiso::Cli::Make < Kiso::Cli::Base
   end
 
   def simple_partial_template
+    slot = @name.tr("_", "-")
     <<~ERB
       <%# locals: (variant: :default, size: :md, css_classes: "", **component_options) %>
       <%= content_tag :div,
           class: Kiso::Themes::#{@class_name}.render(variant: variant, size: size, class: css_classes),
-          data: { component: :#{@name} },
+          data: kiso_prepare_options(component_options, slot: "#{slot}"),
           **component_options do %>
         <%= yield %>
       <% end %>
@@ -310,13 +320,13 @@ class Kiso::Cli::Make < Kiso::Cli::Base
     if @colored
       <<~ERB
         <div class="flex gap-4 items-center p-8">
-          <%%= kiso(:#{@name}, color: color, variant: variant, size: size) { text } %>
+          <%%= kui(:#{@name}, color: color, variant: variant, size: size) { text } %>
         </div>
       ERB
     else
       <<~ERB
         <div class="flex gap-4 items-center p-8">
-          <%%= kiso(:#{@name}, variant: variant, size: size) { text } %>
+          <%%= kui(:#{@name}, variant: variant, size: size) { text } %>
         </div>
       ERB
     end
@@ -324,7 +334,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
 
   def colors_template
     colors = %w[primary secondary success info warning error neutral]
-    lines = colors.map { |c| "  <%%= kiso(:#{@name}, color: :#{c}) { \"#{c.capitalize}\" } %>" }
+    lines = colors.map { |c| "  <%%= kui(:#{@name}, color: :#{c}) { \"#{c.capitalize}\" } %>" }
 
     <<~ERB
       <div class="flex flex-wrap gap-3 items-center p-8">
@@ -338,7 +348,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
     colors = %w[primary secondary success info warning error neutral]
 
     sections = variants.map do |v|
-      lines = colors.map { |c| "    <%%= kiso(:#{@name}, color: :#{c}, variant: :#{v}) { \"#{c.capitalize}\" } %>" }
+      lines = colors.map { |c| "    <%%= kui(:#{@name}, color: :#{c}, variant: :#{v}) { \"#{c.capitalize}\" } %>" }
       <<~SECTION
         <div>
           <p class="text-sm text-muted-foreground mb-2">#{v.capitalize}</p>
@@ -358,7 +368,7 @@ class Kiso::Cli::Make < Kiso::Cli::Base
 
   def sizes_template
     sizes = %w[sm md lg]
-    lines = sizes.map { |s| "  <%%= kiso(:#{@name}, size: :#{s}) { \"#{s.capitalize}\" } %>" }
+    lines = sizes.map { |s| "  <%%= kui(:#{@name}, size: :#{s}) { \"#{s.capitalize}\" } %>" }
 
     <<~ERB
       <div class="flex gap-4 items-center p-8">

data/lib/kiso/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Kiso
+  # Global configuration for the Kiso engine.
+  #
+  # Access via {Kiso.config} or set values in an initializer:
+  #
+  #   # config/initializers/kiso.rb
+  #   Kiso.configure do |config|
+  #     config.icons[:chevron_right] = "heroicons:chevron-right"
+  #     config.theme[:button] = { base: "rounded-full" }
+  #   end
+  class Configuration
+    # @return [Hash{Symbol => String}] semantic icon name to icon identifier mapping.
+    #   Keys are semantic names used by components (e.g. +:chevron_right+),
+    #   values are icon identifiers passed to +kiso_icon+ (e.g. +"heroicons:chevron-right"+).
+    attr_reader :icons
+
+    # @return [Hash{Symbol => Hash}] global theme overrides keyed by component name.
+    #   Keys are snake_case component names (e.g. +:button+, +:card_header+),
+    #   values are hashes accepted by +ClassVariants::Instance#merge+:
+    #   +base:+, +variants:+, +compound_variants:+, +defaults:+.
+    #   Applied once at boot by {ThemeOverrides.apply!}.
+    attr_reader :theme
+
+    def initialize
+      @icons = default_icons
+      @theme = {}
+    end
+
+    private
+
+    # @return [Hash{Symbol => String}] the default icon mapping using Lucide icon names
+    def default_icons
+      {
+        chevron_right: "chevron-right",
+        chevron_left: "chevron-left",
+        chevron_down: "chevron-down",
+        check: "check",
+        ellipsis: "ellipsis",
+        x: "x",
+        search: "search",
+        circle: "circle",
+        sun: "sun",
+        moon: "moon",
+        monitor: "monitor",
+        menu: "menu",
+        minus: "minus",
+        panel_left_close: "panel-left-close",
+        panel_left_open: "panel-left-open"
+      }
+    end
+  end
+end

data/lib/kiso/engine.rb

@@ -1,8 +1,18 @@
 module Kiso
+  # Rails engine that integrates Kiso into host applications.
+  #
+  # Registers initializers for:
+  # - ClassVariants merger (TailwindMerge for class deduplication)
+  # - Global theme overrides ({ThemeOverrides})
+  # - View helpers ({ComponentHelper}, {IconHelper})
+  # - Importmap and asset pipeline paths
+  # - Lookbook preview path registration
   class Engine < ::Rails::Engine
     isolate_namespace Kiso
-    engine_name "kiso_engine"
 
+    # Configures ClassVariants to use TailwindMerge for class deduplication.
+    # This ensures conflicting Tailwind utilities are resolved correctly
+    # when merging base, variant, and override classes.
     initializer "kiso.class_variants" do
       ClassVariants.configure do |config|
         merger = TailwindMerge::Merger.new
@@ -10,13 +20,38 @@ module Kiso
       end
     end
 
+    # Applies global theme overrides from {Configuration#theme} to
+    # theme constants. Runs after app initializers so the host app's
+    # +config/initializers/kiso.rb+ has populated +config.theme+.
+    initializer "kiso.theme_overrides", after: :load_config_initializers do
+      Kiso::ThemeOverrides.apply!
+    end
+
+    # Makes {ComponentHelper} and {IconHelper} available in all views.
     initializer "kiso.helpers" do
       ActiveSupport.on_load(:action_view) do
         include Kiso::ComponentHelper
         include Kiso::IconHelper
+        include Kiso::ThemeHelper
+      end
+    end
+
+    # Appends Kiso's importmap config and JavaScript assets for importmap-rails apps.
+    initializer "kiso.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    # Appends Kiso's JavaScript directory to the asset pipeline (Propshaft/Sprockets).
+    initializer "kiso.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/javascript")
       end
     end
 
+    # Registers Kiso's component previews with Lookbook when available.
     initializer "kiso.lookbook", after: :load_config_initializers do
       if defined?(Lookbook)
         Lookbook.config.preview_paths << root.join("test/components/previews").to_s

data/lib/kiso/theme_overrides.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Kiso
+  # Applies global theme overrides from {Configuration#theme} to
+  # the corresponding {Themes} constants at boot time.
+  #
+  # Each override hash is passed to +ClassVariants::Instance#merge+,
+  # which appends base/variant classes (TailwindMerge resolves conflicts
+  # at render time) and replaces defaults via +Hash#merge!+.
+  #
+  # @example Overriding button defaults
+  #   Kiso.configure do |config|
+  #     config.theme[:button] = { base: "rounded-full", defaults: { variant: :outline } }
+  #   end
+  #   # At boot, ThemeOverrides.apply! merges these into Kiso::Themes::Button
+  #
+  # @see Configuration#theme
+  module ThemeOverrides
+    class << self
+      # Apply all theme overrides to theme constants.
+      # Called once during the +kiso.theme_overrides+ engine initializer.
+      # Guarded against double application.
+      #
+      # @raise [ArgumentError] if any key does not map to a valid theme constant
+      # @return [void]
+      def apply!
+        return if @applied
+
+        overrides = Kiso.config.theme
+        return if overrides.empty?
+
+        validate_keys!(overrides.keys)
+
+        overrides.each do |key, options|
+          resolve_constant(key).merge(**options)
+        end
+
+        @applied = true
+      end
+
+      # Clears the applied flag so {.apply!} can run again.
+      # Used in test teardown.
+      #
+      # @return [void]
+      def reset!
+        @applied = false
+      end
+
+      private
+
+      # Maps a snake_case symbol to its PascalCase theme constant.
+      #
+      # @param key [Symbol] e.g. +:card_header+
+      # @return [ClassVariants::Instance] e.g. +Kiso::Themes::CardHeader+
+      def resolve_constant(key)
+        Kiso::Themes.const_get(camelize(key))
+      end
+
+      # Validates that all keys map to ClassVariants::Instance constants.
+      #
+      # @param keys [Array<Symbol>]
+      # @raise [ArgumentError] with typo suggestion for invalid keys
+      def validate_keys!(keys)
+        keys.each do |key|
+          name = camelize(key)
+          unless Kiso::Themes.const_defined?(name) &&
+              Kiso::Themes.const_get(name).is_a?(ClassVariants::Instance)
+            suggestion = find_closest(key)
+            msg = "Unknown theme key :#{key}."
+            msg += " Did you mean :#{suggestion}?" if suggestion
+            raise ArgumentError, msg
+          end
+        end
+      end
+
+      # Converts a snake_case symbol to PascalCase string.
+      #
+      # @param key [Symbol]
+      # @return [String]
+      def camelize(key)
+        key.to_s.split("_").map(&:capitalize).join
+      end
+
+      # Finds the closest valid theme key by edit distance.
+      #
+      # @param key [Symbol]
+      # @return [Symbol, nil] closest match within distance 3, or nil
+      def find_closest(key)
+        valid = valid_theme_keys
+        closest = valid.min_by { |vk| levenshtein(key.to_s, vk.to_s) }
+        closest if closest && levenshtein(key.to_s, closest.to_s) <= 3
+      end
+
+      # Lists all valid snake_case theme keys.
+      #
+      # @return [Array<Symbol>]
+      def valid_theme_keys
+        Kiso::Themes.constants
+          .select { |name| Kiso::Themes.const_get(name).is_a?(ClassVariants::Instance) }
+          .map { |name| name.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym }
+          .sort
+      end
+
+      # Minimal Levenshtein distance for typo detection.
+      #
+      # @param a [String]
+      # @param b [String]
+      # @return [Integer]
+      def levenshtein(a, b)
+        m = a.length
+        n = b.length
+        d = Array.new(m + 1) { |i| i }
+        (1..n).each do |j|
+          prev = d[0]
+          d[0] = j
+          (1..m).each do |i|
+            temp = d[i]
+            d[i] = if a[i - 1] == b[j - 1]
+              prev
+            else
+              [d[i] + 1, d[i - 1] + 1, prev + 1].min
+            end
+            prev = temp
+          end
+        end
+        d[m]
+      end
+    end
+  end
+end

data/lib/kiso/themes/alert.rb

@@ -1,5 +1,18 @@
 module Kiso
   module Themes
+    # Contextual alert banner with optional icon, title, and description.
+    #
+    # Uses CSS Grid with +has-[>svg]+ to auto-allocate a column for the icon
+    # when an SVG is present as a direct child.
+    #
+    # @example
+    #   Alert.render(color: :error, variant: :soft)
+    #
+    # Variants:
+    # - +color+ — :primary (default), :secondary, :success, :info, :warning, :error, :neutral
+    # - +variant+ — :solid, :outline, :soft (default), :subtle
+    #
+    # Sub-parts: {AlertTitle}, {AlertDescription}
     Alert = ClassVariants.build(
       base: "relative w-full rounded-lg px-4 py-3 text-sm " \
             "grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] " \
@@ -54,12 +67,14 @@ module Kiso
       defaults: {color: :primary, variant: :soft}
     )
 
+    # Alert title text. Rendered in the second grid column (after the icon column).
     AlertTitle = ClassVariants.build(
       base: "col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight"
     )
 
+    # Alert body text. Inherits parent text color for contrast on colored backgrounds.
     AlertDescription = ClassVariants.build(
-      base: "col-start-2 grid justify-items-start gap-1 text-sm opacity-90 [&_p]:leading-relaxed"
+      base: "col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed"
     )
   end
 end

data/lib/kiso/themes/avatar.rb

@@ -0,0 +1,53 @@
+module Kiso
+  module Themes
+    Avatar = ClassVariants.build(
+      base: "group/avatar relative flex shrink-0 rounded-full select-none items-center justify-center bg-muted",
+      variants: {
+        size: {
+          sm: "size-6",
+          md: "size-8",
+          lg: "size-10"
+        }
+      },
+      defaults: {size: :md}
+    )
+
+    AvatarImage = ClassVariants.build(
+      base: "absolute inset-0 aspect-square size-full rounded-full object-cover"
+    )
+
+    AvatarFallback = ClassVariants.build(
+      base: "flex size-full items-center justify-center rounded-full bg-muted text-muted-foreground font-medium",
+      variants: {
+        size: {
+          sm: "text-xs",
+          md: "text-sm",
+          lg: "text-base"
+        }
+      },
+      defaults: {size: :md}
+    )
+
+    AvatarBadge = ClassVariants.build(
+      base: "bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 " \
+            "inline-flex items-center justify-center rounded-full ring-2 select-none " \
+            "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden " \
+            "group-data-[size=md]/avatar:size-2.5 group-data-[size=md]/avatar:[&>svg]:size-2 " \
+            "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2"
+    )
+
+    AvatarGroup = ClassVariants.build(
+      base: "*:data-[slot=avatar]:ring-background group/avatar-group flex -space-x-2 " \
+            "*:data-[slot=avatar]:ring-2"
+    )
+
+    AvatarGroupCount = ClassVariants.build(
+      base: "bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 " \
+            "items-center justify-center rounded-full text-sm ring-2 " \
+            "group-has-data-[size=lg]/avatar-group:size-10 " \
+            "group-has-data-[size=sm]/avatar-group:size-6 " \
+            "[&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 " \
+            "group-has-data-[size=sm]/avatar-group:[&>svg]:size-3"
+    )
+  end
+end

data/lib/kiso/themes/badge.rb

@@ -1,7 +1,17 @@
 module Kiso
   module Themes
+    # @return [Array<Symbol>] the seven semantic colors available to all colored components
     COLORS = %i[primary secondary success info warning error neutral].freeze
 
+    # Inline badge for status labels, counts, and tags.
+    #
+    # @example
+    #   Badge.render(color: :success, variant: :soft, size: :md)
+    #
+    # Variants:
+    # - +color+ — :primary (default), :secondary, :success, :info, :warning, :error, :neutral
+    # - +variant+ — :solid, :outline, :soft (default), :subtle
+    # - +size+ — :xs, :sm, :md (default), :lg, :xl
     Badge = ClassVariants.build(
       base: "inline-flex items-center justify-center font-medium whitespace-nowrap shrink-0 overflow-hidden " \
             "transition-[color,box-shadow] " \
@@ -15,11 +25,11 @@ module Kiso
           subtle: "ring ring-inset"
         },
         size: {
-          xs: "px-1 py-0.5 text-[8px]/3 rounded-full gap-0.5 [&>svg]:size-2.5",
-          sm: "px-1.5 py-0.5 text-[10px]/3 rounded-full gap-0.5 [&>svg]:size-3",
-          md: "px-2 py-0.5 text-xs rounded-full gap-1 [&>svg]:size-3",
-          lg: "px-2.5 py-1 text-sm rounded-full gap-1 [&>svg]:size-3.5",
-          xl: "px-2.5 py-1 text-base rounded-full gap-1.5 [&>svg]:size-4"
+          xs: "px-2 py-0.5 text-xs rounded-full gap-1 [&>svg]:size-3",
+          sm: "px-2.5 py-0.5 text-xs rounded-full gap-1 [&>svg]:size-3",
+          md: "px-3 py-1 text-xs rounded-full gap-1.5 [&>svg]:size-3.5",
+          lg: "px-3.5 py-1 text-sm rounded-full gap-1.5 [&>svg]:size-4",
+          xl: "px-4 py-1.5 text-sm rounded-full gap-2 [&>svg]:size-4"
         },
         color: COLORS.index_with { "" }
       },