<%= kui(:badge, color: :success, variant: :soft) { "Active" } %>

<%= kui(:card) do %>
  <%= kui(:card, :header) do %>
    <%= kui(:card, :title, text: "Members") %>
  <% end %>
  <%= kui(:card, :content) do %>
    ...
  <% end %>
<% end %>

Colors

7 semantic colors configurable via theme CSS variables:

Color	Default Palette	Purpose
`primary`	blue	CTAs, brand, active states
`secondary`	teal	Secondary actions
`success`	green	Success messages
`info`	sky	Informational
`warning`	amber	Warnings
`error`	red	Errors, destructive actions
`neutral`	zinc	Text, borders, surfaces

Variants

Components that accept both color and variant use compound variants (Nuxt UI pattern):

Variant	Style
`solid`	Filled background, contrasting text
`outline`	Transparent background, colored ring
`soft`	Light tinted background, colored text
`subtle`	Light tinted background, colored text, faint ring

Theming

Components use semantic Tailwind utilities (bg-primary, text-foreground, bg-muted) that resolve to CSS variables. Dark mode flips automatically — components never use dark: prefixes.

Override brand colors in your app's CSS:

@theme inline {
  --color-primary: var(--color-orange-600);
  --color-primary-foreground: white;
}

Customizing Components

Global overrides

Override all instances of a component via Kiso.configure in an initializer:

# config/initializers/kiso.rb
Kiso.configure do |config|
  config.theme[:button] = { base: "rounded-full", defaults: { variant: :outline } }
  config.theme[:card_header] = { base: "p-8 sm:p-10" }
end

Override hashes accept base:, variants:, compound_variants:, defaults:. Applied once at boot — zero per-render cost.

Per-instance overrides

Pass css_classes: to override styles on a specific instance. Conflicting classes are resolved automatically via tailwind_merge:

<%= kui(:badge, color: :primary, css_classes: "rounded-full px-4") { "Custom" } %>

Layer order: theme default < global config < per-instance css_classes:.

Icons

Kiso uses kiso-icons for server-side inline SVG rendering. Lucide (~1500 icons) is bundled and works out of the box:

<%= kiso_icon("check") %>
<%= kiso_icon("settings", size: :md) %>
<%= kiso_icon("heroicons:check-circle") %>  <%# from a pinned set %>

Add more icon libraries:

bin/kiso-icons pin heroicons mdi tabler

Override component default icons globally:

Kiso.configure do |config|
  config.icons[:chevron_right] = "heroicons:chevron-right"
  config.icons[:menu] = "heroicons:bars-3"
end

Additional references

Load based on your task — do not load all at once:

references/components.md — all components with props and usage
references/theming.md — CSS variables, tokens, brand customization
references/icons.md — icon rendering, pinning sets, component icon overrides

kiso

Kiso

Installation

Rendering Components