kiso 0.5.2.pre → 0.6.0.pre

data/app/views/kiso/components/_textarea.html.erb

@@ -1,9 +1,12 @@
 <%# locals: (variant: :outline, size: :md, disabled: false,
              css_classes: "", **component_options) %>
+<%# Multi-line text input. Yield a block to set default content (initial value). %>
 <% component_options[:disabled] = true if disabled %>
 <%= content_tag :textarea,
     class: Kiso::Themes::Textarea.render(variant: variant, size: size, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "textarea"),
     **component_options do %>
+  <%# capture { yield }.presence renders block content as the textarea's initial value,
+      or nil if no block was provided (avoids rendering empty whitespace). %>
   <%= capture { yield }.presence %>
 <% end %>

data/app/views/kiso/components/_toggle.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (variant: :default, size: :default, pressed: false, css_classes: "", **component_options) %>
+<%# Two-state toggle button with aria-pressed. The Stimulus controller toggles
+    the data-state attribute between "on" and "off" on click. %>
 <% component_options[:type] ||= :button
    component_options[:"aria-pressed"] = pressed %>
 <%= content_tag :button,

data/app/views/kiso/components/_toggle_group.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (type: :single, variant: :default, size: :default, css_classes: "", **component_options) %>
+<%# Group of toggle buttons with single or multiple selection. The Stimulus controller
+    manages selection state and passes variant/size down to child toggle_group/items. %>
 <%= content_tag :div,
     class: Kiso::Themes::ToggleGroup.render(class: css_classes),
     role: "group",

data/app/views/kiso/components/_tooltip.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (text: nil, kbds: nil, side: :top, align: :center, delay: 0, ui: {}, css_classes: "", **component_options) %>
+<%# Tooltip positioned via Floating UI using the popover API. Pass text: for a simple
+    tooltip with optional keyboard shortcut hints (kbds:). Without text:, compose
+    manually with tooltip/trigger and tooltip/content sub-parts. %>
 <%= tag.div(
     class: css_classes.presence,
     data: kiso_prepare_options(component_options, slot: "tooltip",

data/app/views/kiso/components/alert_dialog/_action.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (color: :primary, variant: :solid, size: :md, css_classes: "", **component_options) %>
+<%# Confirm action button that closes the dialog. Uses Button theme for styling. %>
 <%= tag.button type: "button",
     class: Kiso::Themes::Button.render(color: color, variant: variant, size: size, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "alert-dialog-action",

data/app/views/kiso/components/alert_dialog/_cancel.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (color: :primary, variant: :outline, size: :md, css_classes: "", **component_options) %>
+<%# Cancel button that closes the dialog without confirming. Defaults to outline variant. %>
 <%= tag.button type: "button",
     class: Kiso::Themes::Button.render(color: color, variant: variant, size: size, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "alert-dialog-cancel",

data/app/views/kiso/components/alert_dialog/_description.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Auto-generates id from the parent dialog's @_kiso_alert_dialog_id for aria-describedby linking. %>
 <% component_options[:id] = "#{@_kiso_alert_dialog_id}-description" if @_kiso_alert_dialog_id && !component_options.key?(:id) %>
 <%= content_tag :p,
     class: Kiso::Themes::AlertDialogDescription.render(class: css_classes),

data/app/views/kiso/components/alert_dialog/_title.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Auto-generates id from the parent dialog's @_kiso_alert_dialog_id for aria-labelledby linking. %>
 <% component_options[:id] = "#{@_kiso_alert_dialog_id}-title" if @_kiso_alert_dialog_id && !component_options.key?(:id) %>
 <%= content_tag :h2,
     class: Kiso::Themes::AlertDialogTitle.render(class: css_classes),

data/app/views/kiso/components/avatar/_image.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (src:, alt: "", css_classes: "", **component_options) %>
+<%# Avatar image that hides itself on load error, revealing the fallback text beneath. %>
 <%= tag.img src: src, alt: alt,
     class: Kiso::Themes::AvatarImage.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "avatar-image"),

data/app/views/kiso/components/breadcrumb/_separator.html.erb

@@ -1,9 +1,12 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Breadcrumb separator between items. Defaults to a chevron-right icon;
+    yield a block to replace with a custom separator. %>
 <%= content_tag :li,
     class: Kiso::Themes::BreadcrumbSeparator.render(class: css_classes),
     role: "presentation",
     aria: { hidden: "true" },
     data: kiso_prepare_options(component_options, slot: "breadcrumb-separator"),
     **component_options do %>
+  <%# capture { yield }.presence returns nil when no block content, falling back to default icon. %>
   <%= capture { yield }.presence || kiso_component_icon(:chevron_right, class: "size-3.5") %>
 <% end %>

data/app/views/kiso/components/combobox/_chips.html.erb

@@ -1,10 +1,13 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Container for multi-select chips. Includes a <template> element that the
+    Stimulus controller clones to create new chips dynamically when items are selected. %>
 <%= content_tag :div,
     class: Kiso::Themes::ComboboxChips.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "combobox-chips",
       kiso__combobox_target: "chips"),
     **component_options do %>
   <%= yield %>
+  <%# Chip template cloned by Stimulus for dynamically-added selections. %>
   <%= tag.template data: { kiso__combobox_target: "chipTemplate" } do %>
     <%= tag.span class: Kiso::Themes::ComboboxChip.render,
                 data: { slot: "combobox-chip", kiso__combobox_target: "chip" } do %>

data/app/views/kiso/components/command/_dialog.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (shortcut: "k", css_classes: "", **component_options) %>
+<%# Command palette wrapped in a native <dialog>. Opens via Cmd/Ctrl+K (configurable
+    via shortcut: prop). Typically contains a command/input and command/list. %>
 <%= content_tag :dialog,
     class: Kiso::Themes::CommandDialog.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "command-dialog",

data/app/views/kiso/components/dashboard_sidebar/_collapse.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Sidebar collapse toggle for desktop. Shows open/closed panel icons that swap
+    visibility based on sidebar state via CSS. Placed inside the sidebar itself. %>
 <%= content_tag :button,
     class: Kiso::Themes::DashboardSidebarCollapse.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "dashboard-sidebar-collapse",

data/app/views/kiso/components/dialog/_close.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Dialog close button. Yields a block to override the default X icon. %>
 <% content = capture { yield }.presence %>
 <%= tag.button type: "button",
     class: Kiso::Themes::DialogClose.render(class: css_classes),

data/app/views/kiso/components/field/_error.html.erb

@@ -1,5 +1,9 @@
 <%# locals: (errors: [], css_classes: "", **component_options) %>
+<%# Form field error display. Pass errors: as an array of strings (e.g., from
+    ActiveModel) or yield a block for fully custom error markup. Renders nothing
+    when both errors and block are empty. Multiple errors render as a bulleted list. %>
 <% messages = Array(errors).compact.map(&:to_s).reject(&:blank?).uniq %>
+<%# Block override: custom error content replaces the default message rendering. %>
 <% content = capture { yield }.presence %>
 <% if content || messages.any? %>
   <%= content_tag :div,

data/app/views/kiso/components/field/_label.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Wraps the base Label component with field-specific styling and a data-slot override.
+    Manually merges the data-slot because this delegates to kui(:label) which sets its own slot. %>
 <% component_options[:data] = (component_options[:data] || {}).merge(slot: "field-label") %>
 <%= kui(:label,
     css_classes: Kiso::Themes::FieldLabel.render(class: css_classes),

data/app/views/kiso/components/field/_separator.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Horizontal divider between form fields. Optionally yield text (e.g., "or") to
+    display centered over the separator line. Sets data-content when text is present
+    so CSS can adjust spacing. %>
 <% captured = capture { yield }.presence %>
 <%= content_tag :div,
     class: Kiso::Themes::FieldSeparator.render(class: css_classes),

data/app/views/kiso/components/input_otp/_separator.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Visual separator between OTP slot groups. Defaults to a minus icon;
+    yield a block to replace with a custom separator. %>
 <%= content_tag :div,
     role: "separator",
     class: Kiso::Themes::InputOtpSeparator.render(class: css_classes),

data/app/views/kiso/components/input_otp/_slot.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (size: :md, css_classes: "", **component_options) %>
+<%# Individual character display slot for the OTP input. The Stimulus controller
+    populates the slot-char span and shows/hides the blinking caret. %>
 <%= content_tag :div,
     class: Kiso::Themes::InputOtpSlot.render(size: size, class: css_classes),
     aria: { hidden: "true" },

data/app/views/kiso/components/nav/_section.html.erb

@@ -1,4 +1,8 @@
 <%# locals: (title: nil, open: true, collapsible: true, ui: {}, css_classes: "", **component_options) %>
+<%# Navigation section with three rendering modes:
+    1. title + collapsible (default): native <details> element with toggle
+    2. title + collapsible: false: static section with non-interactive heading
+    3. No title: plain wrapper for ungrouped nav items %>
 <% if title && collapsible %>
   <%= content_tag :details,
       class: Kiso::Themes::NavSection.render(class: css_classes),

data/app/views/kiso/components/tooltip/_content.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", ui: {}, **component_options) %>
+<%# Tooltip content panel using popover="manual" for visibility control.
+    Positioned by Floating UI via the parent tooltip's Stimulus controller. %>
 <%= tag.div(
     class: Kiso::Themes::TooltipContent.render(class: css_classes),
     role: "tooltip",

data/lib/generators/kiso/install/USAGE

@@ -0,0 +1,23 @@
+Description:
+  Sets up Kiso in your application. Creates a well-commented initializer
+  with preset, theme, and icon configuration examples.
+
+  Optionally generates a DESIGN_SYSTEM.md with your app's spacing,
+  typography, color, and component conventions.
+
+Examples:
+  bin/rails generate kiso:install
+
+    Creates:
+      config/initializers/kiso.rb
+
+    Optionally creates (interactive prompt):
+      DESIGN_SYSTEM.md
+
+  bin/rails generate kiso:install --no-skip-design-system --app-name="My App"
+
+    Creates both files without interactive prompts.
+
+  bin/rails generate kiso:install --skip-design-system
+
+    Creates only the initializer, skips the design system doc.

data/lib/generators/kiso/install/install_generator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Kiso
+  module Generators
+    # Sets up Kiso in a host application.
+    #
+    # Creates a well-commented initializer and optionally generates a
+    # design system document. No required arguments — interactive prompts
+    # handle optional inputs.
+    #
+    # @example Interactive (default)
+    #   bin/rails generate kiso:install
+    #
+    # @example Non-interactive
+    #   bin/rails generate kiso:install --no-skip-design-system --app-name="Outport"
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_design_system,
+        type: :boolean,
+        default: nil,
+        desc: "Skip generating DESIGN_SYSTEM.md (default: ask interactively)"
+
+      class_option :app_name,
+        type: :string,
+        default: nil,
+        desc: "App name for the design system doc header (default: ask interactively)"
+
+      def create_initializer
+        initializer_path = "config/initializers/kiso.rb"
+        if File.exist?(File.join(destination_root, initializer_path))
+          say_status :skip, initializer_path, :yellow
+        else
+          template "initializer.rb.tt", initializer_path
+        end
+      end
+
+      def create_design_system
+        should_generate = case options[:skip_design_system]
+        when true then false
+        when false then true
+        else
+          yes?(<<~PROMPT)
+
+            Would you like to generate a Design System document?
+            This creates DESIGN_SYSTEM.md with your app's spacing, typography, color,
+            and component conventions — useful for team alignment and AI coding agents.
+
+            Generate DESIGN_SYSTEM.md? (y/n)
+          PROMPT
+        end
+
+        return unless should_generate
+
+        @app_name = resolve_app_name
+        template "design_system.md.tt", "DESIGN_SYSTEM.md"
+        @design_system_created = true
+      end
+
+      def print_next_steps
+        say ""
+        say "Kiso installed!", :green
+        say ""
+        say "  Initializer: config/initializers/kiso.rb"
+        say "  Design System: DESIGN_SYSTEM.md" if @design_system_created
+        say ""
+        say "Next steps:"
+        say "  1. Add Kiso's CSS to your Tailwind stylesheet:"
+        say '       @import "../builds/tailwind/kiso";'
+        say "  2. Add the theme script to your layout <head>:"
+        say "       <%%= kiso_theme_script %>"
+        say "  3. Customize your brand colors in your Tailwind @theme block."
+        say "     See: https://kisoui.com/guide/css-variables"
+        say ""
+      end
+
+      private
+
+      def resolve_app_name
+        return options[:app_name] if options[:app_name].present?
+        return "My App" if options[:skip_design_system] == false
+
+        response = ask(<<~PROMPT)
+          What's your app called? This is just a friendly name for the document
+          header (e.g. "Outport", "My App"). [default: My App]
+        PROMPT
+        response.presence || "My App"
+      end
+    end
+  end
+end

data/lib/generators/kiso/install/templates/design_system.md.tt

@@ -0,0 +1,190 @@
+# <%= @app_name %> Design System
+
+Built on [Kiso UI](https://kisoui.com). Reference this document before
+building any UI — it defines the visual conventions that keep
+<%= @app_name %> consistent.
+
+---
+
+## Color Palette
+
+<%= @app_name %> uses Kiso's semantic color tokens. Components reference
+tokens like `bg-primary` and `text-foreground` — never raw palette shades.
+
+| Token | Purpose |
+|-------|---------|
+| `primary` | Brand color, primary actions |
+| `secondary` | Secondary actions |
+| `success` | Positive feedback, confirmations |
+| `info` | Informational messages |
+| `warning` | Caution, non-destructive alerts |
+| `error` | Errors, destructive actions |
+| `neutral` | Default, non-colored UI |
+
+Every color has a `-foreground` companion for accessible text:
+`bg-primary text-primary-foreground`.
+
+**Customize your brand colors** in your Tailwind stylesheet:
+
+```css
+@theme {
+  --color-primary: var(--color-violet-600);
+  --color-primary-foreground: var(--color-white);
+}
+```
+
+See the full list of overridable tokens:
+[CSS Variables Reference](https://kisoui.com/guide/css-variables)
+
+---
+
+## Typography Hierarchy
+
+| Role | Classes | When to use |
+|------|---------|-------------|
+| Page title | `text-lg font-semibold` | Top-level page headings |
+| Section title | `text-base font-semibold` | Section headings within a page |
+| Card title | `text-sm font-semibold` | Card and dialog titles |
+| Body | `text-sm` | Body text, descriptions, menu items |
+| Caption | `text-xs` | Timestamps, counts, helper text, badges |
+| Label | `text-sm font-medium` | Form labels, button text |
+
+**Rules:**
+- Never go below `text-xs` (12px)
+- `font-semibold` for primary headings, `font-medium` for interactive
+  elements, default weight for body text
+- Inputs use `text-base md:text-sm` (larger on mobile for zoom prevention)
+
+---
+
+## Spacing Scale
+
+### Interactive Element Heights
+
+| Size | Class | Examples |
+|------|-------|----------|
+| xs | `h-7` | Icon buttons, compact actions |
+| sm | `h-8` | Small buttons, small inputs |
+| md (default) | `h-9` | Buttons, inputs, selects |
+| lg | `h-10` | Large buttons |
+| xl | `h-11` | Extra-large buttons |
+
+### Padding
+
+| Context | Classes | Examples |
+|---------|---------|----------|
+| Interactive (default) | `px-3 py-2` | Buttons, inputs |
+| Interactive (small) | `px-3 py-1.5` | Small buttons |
+| Interactive (compact) | `px-2 py-1` | Extra-small buttons |
+| Menu items | `px-2 py-1.5` | Dropdown, select, command items |
+| Large containers | `p-6` | Card, Dialog |
+| Medium containers | `p-4` | Popover, Sheet header |
+| Compact containers | `p-2` | Sidebar sections |
+
+### Gaps
+
+| Class | When to use |
+|-------|-------------|
+| `gap-1` | Tight lists — sidebar menus, accordion items |
+| `gap-1.5` | Between small elements — breadcrumb items |
+| `gap-2` | **Default.** Icon + text, label + control, most siblings |
+| `gap-3` | Radio/checkbox groups, form field spacing |
+| `gap-4` | Between major sections inside a container |
+| `gap-6` | Top-level container divisions (card header/content/footer) |
+
+### Border Radius
+
+Controlled by the `--kiso-radius` CSS variable. Override it to shift the
+entire scale:
+
+```css
+@theme {
+  --kiso-radius: 0.375rem; /* rounder */
+  --kiso-radius: 0;        /* sharp, no rounding */
+}
+```
+
+Or use a preset in `config/initializers/kiso.rb`:
+
+```ruby
+config.apply_preset(:rounded)  # buttons → rounded-full, cards → rounded-2xl
+config.apply_preset(:sharp)    # minimal rounding everywhere
+```
+
+---
+
+## Component Conventions
+
+Use `kui()` components instead of raw HTML. Components handle styling,
+dark mode, accessibility, and consistent structure.
+
+### Page structure
+
+```erb
+<%%= kui(:app) do %>
+  <%%= kui(:header) { "..." } %>
+  <%%= kui(:main) do %>
+    <%%= kui(:container) do %>
+      <%%= yield %>
+    <%% end %>
+  <%% end %>
+  <%%= kui(:footer) { "..." } %>
+<%% end %>
+```
+
+### Content cards
+
+```erb
+<%%= kui(:card) do %>
+  <%%= kui(:card, :header) do %>
+    <%%= kui(:card, :title) { "Title" } %>
+    <%%= kui(:card, :description) { "Description" } %>
+  <%% end %>
+  <%%= kui(:card, :content) { "..." } %>
+  <%%= kui(:card, :footer) { "..." } %>
+<%% end %>
+```
+
+### Forms
+
+```erb
+<%%= kui(:field_group) do %>
+  <%%= kui(:field) do %>
+    <%%= kui(:field, :label) { "Email" } %>
+    <%%= kui(:input, name: "email", type: "email") %>
+    <%%= kui(:field, :description) { "We'll never share your email." } %>
+  <%% end %>
+  <%%= kui(:field) do %>
+    <%%= kui(:field, :label) { "Password" } %>
+    <%%= kui(:input, name: "password", type: "password") %>
+  <%% end %>
+<%% end %>
+```
+
+### Empty states
+
+```erb
+<%%= kui(:empty, icon: "inbox", title: "No messages", description: "...") %>
+```
+
+### Feedback
+
+```erb
+<%%= kui(:alert, color: :success) do %>
+  <%%= kui(:alert, :title) { "Saved" } %>
+  <%%= kui(:alert, :description) { "Your changes have been saved." } %>
+<%% end %>
+```
+
+---
+
+## Anti-patterns
+
+| Don't | Do instead |
+|-------|------------|
+| Raw `<div>`, `<button>`, `<input>` HTML | Use `kui(:card)`, `kui(:button)`, `kui(:input)` |
+| Arbitrary spacing (`p-[13px]`, `gap-5`) | Use the documented spacing scale |
+| Raw color classes (`bg-blue-500`, `text-zinc-600`) | Use semantic tokens (`bg-primary`, `text-muted-foreground`) |
+| Tailwind `dark:` prefixes | Kiso handles dark mode via CSS variable swapping |
+| Inline styles for layout | Use Tailwind utilities from the spacing scale |
+| Custom font sizes (`text-[11px]`) | Use `text-xs`, `text-sm`, `text-base`, `text-lg` |

data/lib/generators/kiso/install/templates/initializer.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+Kiso.configure do |config|
+  # --- Style Preset ---
+  # Apply a pre-built style preset. Presets adjust border-radius, padding,
+  # and other visual properties across all components.
+  #
+  # Available presets:
+  #   :rounded — softer corners (buttons → rounded-full, cards → rounded-2xl)
+  #   :sharp   — minimal rounding (buttons → rounded-sm, cards → rounded-lg)
+  #
+  # config.apply_preset(:rounded)
+
+  # --- Global Theme Overrides ---
+  # Override component styles globally. These apply to every instance of the
+  # component — use css_classes: on individual calls for one-off overrides.
+  #
+  # Accepts: base:, variants:, compound_variants:, defaults:, ui:
+  #
+  # config.theme[:button] = { base: "rounded-full" }
+  # config.theme[:card]   = { base: "rounded-xl shadow-lg" }
+  # config.theme[:badge]  = { defaults: { variant: :outline } }
+  #
+  # Override inner sub-part elements with ui:
+  # config.theme[:card] = { ui: { header: "p-8", footer: "px-8" } }
+
+  # --- Icon Customization ---
+  # Swap default component icons. Keys are semantic names, values are icon
+  # identifiers passed to kiso_icon (e.g. "heroicons:chevron-right").
+  #
+  # config.icons[:chevron_right] = "heroicons:chevron-right"
+  # config.icons[:x] = "heroicons:x-mark"
+  # config.icons[:search] = "heroicons:magnifying-glass"
+
+  # --- App Theme ---
+  # Theme directory for appui() components. Themes live in app/themes/<name>/.
+  # Default: :default (app/themes/default/)
+  #
+  # config.app_theme = :default
+end

data/lib/kiso/cli/make.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
-# Generates scaffolding for new Kiso components.
+# Generates scaffolding for new Kiso engine components.
 #
-# Creates theme module, ERB partial, Lookbook preview, and updates
-# the require list and skill reference docs.
+# Creates theme module, ERB partial, Lookbook preview templates, and
+# updates +lib/kiso.rb+ requires and skill reference docs.
+#
+# This is the CLI equivalent of +kiso:framework_component+ Rails generator,
+# but intended for quick use without loading the Rails environment.
 #
 # @example
 #   $ bin/kiso make component alert

data/lib/kiso/cli.rb

@@ -4,6 +4,16 @@ require "thor"
 require "active_support/core_ext/string/inflections"
 
 module Kiso
+  # Command-line interface for the Kiso gem, invoked via +bin/kiso+.
+  #
+  # Routes to subcommands:
+  # - +kiso icons+ -- icon set management (delegated to kiso-icons gem)
+  # - +kiso make+  -- component scaffolding
+  # - +kiso version+ -- print gem version
+  #
+  # @see Cli::Main the top-level entry point
+  # @see Cli::Make component generator subcommand
+  # @see Cli::Icons icon management subcommand
   module Cli
   end
 end

data/lib/kiso/color_utils.rb

@@ -1,16 +1,39 @@
 # frozen_string_literal: true
 
 module Kiso
+  # Utility methods for color calculations, used by the Avatar component
+  # for automatic contrast text color on arbitrary background colors.
+  #
+  # @see Configuration#contrast_threshold
   module ColorUtils
     module_function
 
-    # Returns "white" or "black" based on WCAG relative luminance.
-    # Uses a perceptual threshold of 0.36 rather than the mathematical
-    # midpoint of 0.179, per Lea Verou's research on contrast color
-    # generation. The higher threshold produces better results on
-    # saturated chromatic colors (e.g. Tailwind 500-shade palette).
-    # Accepts 3-digit (#abc) or 6-digit (#aabbcc) hex strings.
-    def contrast_text_color(hex)
+    # Default luminance threshold for the contrast calculation.
+    # 0.42 is a perceptual midpoint per Lea Verou's research that produces
+    # better results on saturated chromatic colors than the WCAG mathematical
+    # midpoint of 0.179.
+    DEFAULT_CONTRAST_THRESHOLD = 0.42
+
+    # Returns the optimal text color ("white" or "black") for a given
+    # background color, based on WCAG relative luminance.
+    #
+    # Uses a perceptual threshold (default 0.42) rather than the
+    # mathematical midpoint of 0.179, per Lea Verou's research on
+    # contrast color generation. The higher threshold produces better
+    # results on saturated chromatic colors (e.g. Tailwind 500-shade
+    # palette).
+    #
+    # @param hex [String] a hex color string, 3-digit (#abc) or 6-digit (#aabbcc)
+    # @param threshold [Float, nil] luminance threshold override; defaults to
+    #   {Configuration#contrast_threshold}
+    # @return [String] "white" or "black"
+    #
+    # @example
+    #   ColorUtils.contrast_text_color("#3b82f6")  # => "white"
+    #   ColorUtils.contrast_text_color("#fbbf24")  # => "black"
+    def contrast_text_color(hex, threshold: nil)
+      threshold ||= Kiso.config.contrast_threshold
+
       hex = hex.delete("#")
       hex = hex.chars.map { |c| c * 2 }.join if hex.length == 3
 
@@ -19,7 +42,7 @@ module Kiso
         (c <= 0.04045) ? c / 12.92 : ((c + 0.055) / 1.055)**2.4
       }.then { |lr, lg, lb| 0.2126 * lr + 0.7152 * lg + 0.0722 * lb }
 
-      (luminance > 0.36) ? "black" : "white"
+      (luminance > threshold) ? "black" : "white"
     end
   end
 end

data/lib/kiso/configuration.rb

@@ -33,10 +33,21 @@ module Kiso
     #   end
     attr_accessor :app_theme
 
+    # @return [Float] luminance threshold for contrast text color calculation.
+    #   Colors with luminance above this value get black text, below get white.
+    #   Default is 0.42 (perceptual midpoint per Lea Verou's research).
+    #
+    # @example Tune for a darker palette
+    #   Kiso.configure do |config|
+    #     config.contrast_threshold = 0.36
+    #   end
+    attr_accessor :contrast_threshold
+
     def initialize
       @icons = default_icons
       @theme = {}
       @app_theme = :default
+      @contrast_threshold = Kiso::ColorUtils::DEFAULT_CONTRAST_THRESHOLD
     end
 
     # Resolves the active app theme directory path relative to the given root.