steveclarke 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