kiso

Kiso 是一个面向 Rails 的组件库，使用 ERB partials + Tailwind CSS + class_variants + tailwind_merge 构建，灵感来自 shadcn/ui 和 Nuxt UI，并针对 Rails + Hotwire 做了适配。它适用于创建界面、定制主题、构建表单或组合组件的场景。

安装

在 Gemfile 中加入：

gem "kiso"

然后执行：

bundle install bin/rails generate kiso:install

渲染组件

使用 kui() 辅助方法渲染组件，例如徽章与卡片：

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

颜色

提供 7 种语义颜色，均可通过主题 CSS 变量配置：

• primary：默认蓝色，用于 CTA、品牌、激活状态
• secondary：默认 teal，用于次级操作
• success：默认绿色，用于成功消息
• info：默认 sky，用于信息提示
• warning：默认 amber，用于警告
• error：默认红色，用于错误与破坏性操作
• neutral：默认 zinc，用于文本、边框、表面

变体

同时接受 color 与 variant 的组件使用复合变体（Nuxt UI 模式）：

• solid：填充背景，对比色文本
• outline：透明背景，彩色 ring
• soft：浅色背景，彩色文本
• subtle：浅色背景，彩色文本，微弱的 ring

主题

组件使用语义化 Tailwind 工具类（bg-primary、text-foreground、bg-muted），解析为 CSS 变量。深色模式自动翻转——组件从不使用 dark: 前缀。

可在应用 CSS 中覆盖品牌色：

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

定制组件

全局覆盖：在初始化器中通过 Kiso.configure 覆盖某组件的所有实例：

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

覆盖哈希接受 base:、variants:、compound_variants:、defaults:。在启动时应用一次——零渲染开销。

单实例覆盖：传入 css_classes: 覆盖特定实例的样式，冲突类名由 tailwind_merge 自动解决：

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

层叠顺序：主题默认 < 全局配置 < 单实例 css_classes:。

图标

Kiso 使用 kiso-icons 进行服务端内联 SVG 渲染。内置 Lucide（约 1500 个图标），开箱即用：

<%= kiso_icon("check") %> <%= kiso_icon("settings", size: :md) %> <%= kiso_icon("heroicons:check-circle") %> <%# 来自已固定的图标集 %>

添加更多图标库：

bin/kiso-icons pin heroicons mdi tabler

全局覆盖组件默认图标：

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

附加参考

按任务加载，不要一次性全部加载：

• references/components.md —— 所有组件及其 props 与用法
• references/theming.md —— CSS 变量、tokens、品牌定制
• references/icons.md —— 图标渲染、固定图标集、组件图标覆盖

限制

官方资料未提供关于收费、价格、性能指标或具体平台兼容范围的更多信息，暂未提供。