Kiso

Rails component library built on ERB partials + Tailwind CSS + class_variants + tailwind_merge. Inspired by shadcn/ui and Nuxt UI, adapted for Rails + Hotwire.

Installation

# Gemfile
gem "kiso"

bundle install
bin/rails generate kiso:install

Rendering Components

Use the kui() helper to render components:

<%= 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