Keystone UI

Keystone UI is a reusable UI component system for Rails applications built on the view_component gem. It provides stable, authoritative UI primitives that avoid ERB noise, prevent UI drift, and enable safe mass updates.

Principles

All UI lives in ViewComponents (no partials).
Components are Ruby objects with explicit keyword arguments.
Helpers are thin render wrappers with no logic or conditionals.
Styling uses Tailwind CSS utility classes applied directly in components.

Installation

Prerequisites

Rails 7+
tailwindcss-rails v4+

Steps

Add the gem to your Gemfile:

gem "keystone_ui"

Run bundle install.
Run the install generator:

rails generate keystone:install

The generator handles setup automatically:

If app/assets/tailwind/application.css does not exist, the generator creates it with the Tailwind import and Keystone source import. No need to run tailwindcss:install first.
If it already exists, the generator injects the Keystone source import after the existing Tailwind import line.
It wires the Stimulus controllers by appending registerControllers(application) to app/javascript/controllers/index.js, so interactive components (accordion, modal, stat card info, …) work out of the box. If that file isn't present, the generator prints the one line to add manually.

At boot time, the engine initializer writes keystone_source.css with @source directives pointing to the gem's component files so Tailwind scans them automatically. The engine also adds the gem's controllers to your importmap automatically.

How Tailwind integration works

The generator commits only an @import "./keystone_source.css" line — no machine-specific paths in git.
On every app boot (dev server, assets:precompile, CI), the engine writes keystone_source.css with @source and @import directives, including the stylesheet of keystone_ui-styles, which keystone_ui depends on.
Tailwind's JIT scanner finds all component classes automatically.
When keystone updates with new components, they're picked up on the next build with no action required.
keystone_source.css is the only stylesheet a host imports for keystone_ui and the gems built on it. No keystone gem ships a Tailwind file that tailwindcss-rails turns into a generated stylesheet in app/assets/builds/tailwind.

Registering a gem's Tailwind files

A gem built on keystone_ui adds its own CSS and the files Tailwind should scan in an initializer, and keystone_source.css includes them:

initializer "my_gem.tailwind" do
  KeystoneUi.configuration.tailwind_imports << root.join("app/assets/tailwind/my_gem.css").to_s
  KeystoneUi.configuration.tailwind_sources << root.join("app/views/**/*.erb").to_s
end

Upgrading from older versions

Re-run the generator. It removes legacy @import and @source inline(...) lines automatically:

rails generate keystone:install

Light and dark mode

keystone_ui decides light and dark mode for the whole app, including the dark: classes in your own views. The html element's data-theme attribute decides it:

<html data-theme="dark">   <!-- always dark -->
<html data-theme="light">  <!-- always light -->
<html>                     <!-- follows the operating system -->

Do not declare your own @custom-variant dark in application.css. keystone_ui's rule applies to your classes as well as keystone_ui's components.

Letting users choose

Place the toggle anywhere in a view:

<%= ui_theme_toggle %>

It offers Light, Dark and System. The choice applies at once and is kept in a keystone_theme cookie until the user picks another option, and the server marks the html tag from that cookie so later pages open in the chosen mode. The install generator adds the helper that does this to app/views/layouts/application.html.erb:

<html <%= keystone_theme_attributes %> lang="en">

Add it by hand if your layout lives elsewhere.

Which mode a page gets

Strongest first:

The toggle's choice in this browser.
A mode supplied by another gem, such as a signed-in user's saved mode.
Light.

A gem supplies a mode by registering a callable that receives the view and returns "light", "dark", "system", "custom" or nil. A custom mode marks the page data-theme="custom":

KeystoneUi.configure do |config|
  config.theme_mode_supplier = ->(view) { view.current_user&.theme_mode }
end

Color System

Keystone UI components use two semantic color scales — accent and surface — defined as CSS custom properties. Components reference these via Tailwind classes like bg-accent-500, text-accent-600, bg-surface-100, etc. This means your entire UI updates when you change the color values — no need to touch component code.

Defaults

keystone_ui-styles, which keystone_ui installs and imports for you, sets the default values:

Scale	Default palette	Used for
`accent`	Blue (`#3b82f6` at 500)	Buttons, links, focus rings, active states, badges
`surface`	Zinc (`#71717a` at 500)	Backgrounds, borders, text on dark mode surfaces

Each scale provides shades 50-950, matching Tailwind's standard shade range.

Customizing colors

Override the CSS custom properties in your app's application.css (after the Tailwind import):

@import "tailwindcss";
@import "./keystone_source.css";

@theme {
  /* Override accent to indigo */
  --color-accent-50: #eef2ff;
  --color-accent-100: #e0e7ff;
  --color-accent-200: #c7d2fe;
  --color-accent-300: #a5b4fc;
  --color-accent-400: #818cf8;
  --color-accent-500: #6366f1;
  --color-accent-600: #4f46e5;
  --color-accent-700: #4338ca;
  --color-accent-800: #3730a3;
  --color-accent-900: #312e81;
  --color-accent-950: #1e1b4e;
}

You only need to override the shades you use. All Keystone components will pick up the new colors automatically.

Usage in gems and engines

If you're building a gem or engine that uses keystone_ui, do not set theme colors in your gem. The host app owns the theme. Your gem just uses the accent/surface Tailwind classes and they'll inherit whatever the host app has configured.

In your gem's test/dummy app, set up colors the same way a host app would:

Add keystone_ui to your gemspec as a dependency
Run rails generate keystone:install in test/dummy
The default blue/zinc theme applies automatically — no extra config needed
To test with a custom theme, override the variables in test/dummy/app/assets/tailwind/application.css:

@import "tailwindcss";
@import "./keystone_source.css";

@theme {
  --color-accent-500: #6366f1;
  /* ... */
}

Key principle: gems use bg-accent-500, text-surface-700, etc. in their views. The host app decides what those colors actually are — either statically in CSS, or dynamically with keystone_colors for per-user theming.

Per-user theming

For dynamic, per-user color customization (e.g. letting users pick their own accent color), see the keystone_colors gem, which generates the CSS custom properties from user preferences at runtime.

Looks

A look is one CSS file that changes how components look without editing the gem. It sets the --ks- variables that keystone_ui-styles defines, and a component reads them through the ks- classes it renders. Buttons, panels, cards, alerts, badges, form fields, the modal, the mobile action menu, the column picker, multi select, copy button, theme toggle, checkbox row, radio card, option card, file upload and colour picker read them today. So do the stat card, chart card, card link, call to action banner, feature grid, hero, data table, code, accordion, disclosure, tab switcher, progress, funnel, bucket, pipeline and swipe deck, and the navbar title, nav items, nav dropdown, bottom nav, mobile header and settings link.

Writing a look file

This look changes the corner radius, font, label weight, border, padding and colours of every button:

/* app/assets/tailwind/look.css */
:root {
  --ks-radius-control: 9999px;
  --ks-font-body: "Roboto", sans-serif;
  --ks-font-weight-strong: 500;
  --ks-border-width-control: 1px;
  --ks-spacing: 0.3rem;

  --ks-color-accent: #6200ee;
  --ks-color-accent-hover: #7c4dff;
  --ks-color-neutral: #616161;
  --ks-color-neutral-hover: #757575;
  --ks-color-danger: #b00020;
  --ks-color-danger-hover: #c51162;
  --ks-color-on-fill: #ffffff;

  --ks-color-accent-dark: #bb86fc;
  --ks-color-accent-hover-dark: #d1b3ff;
  --ks-color-neutral-dark: #9e9e9e;
  --ks-color-neutral-hover-dark: #bdbdbd;
  --ks-color-danger-dark: #cf6679;
  --ks-color-danger-hover-dark: #e0879a;
  --ks-color-on-fill-dark: #000000;
}

Each colour variable has a -dark partner that a button reads on a dark page. A look that sets only the light variable leaves dark pages with the default colour. The keystone_ui-styles README lists every variable and its default.

Where a look file goes

A host imports its look file after keystone_source.css:

@import "tailwindcss";
@import "./keystone_source.css";
@import "./look.css";

keystone_ui-styles puts its defaults in Tailwind's base layer, and a :root rule outside any layer overrides them. The look's :root rule must not sit inside an @layer block.

Shipping a look in a gem

A gem that ships a look registers its file in an initializer, and keystone_source.css imports it after keystone_ui-styles:

initializer "my_look.tailwind" do
  KeystoneUi.configuration.tailwind_imports << root.join("app/assets/tailwind/my_look.css").to_s
end

Offering several looks

A host can offer several looks and let the page pick one. Each look file scopes its variables to the look's name:

/* app/assets/tailwind/looks/material.css */
:root[data-look="material"] {
  --ks-radius-control: 9999px;
  --ks-color-accent: #6200ee;
  --ks-color-accent-dark: #bb86fc;
}

Register each look by name with its file, and name the default:

# config/initializers/keystone_ui.rb
KeystoneUi.configure do |config|
  config.register_look :plain, Rails.root.join("app/assets/tailwind/looks/plain.css")
  config.register_look :material, Rails.root.join("app/assets/tailwind/looks/material.css")
  config.default_look = :plain
end

keystone_source.css imports every registered look, and keystone_theme_attributes marks the html tag with data-look="plain". A gem can choose the look per request by setting config.look_supplier to a lambda that receives the view and returns a look's name. A name that is not registered leaves the page on the default. A host that registers no looks gets no data-look attribute. A Turbo visit carries the next page's look onto the page, as it does the theme.

Boot stops with KeystoneUi::LookCheck::Error when a registered look's file does not exist, when the file sets no --ks- variables under :root[data-look="<name>"], or when default_look names a look that is not registered, so a mistake shows up the moment the app starts.

Helper API (primary surface)

Use the helpers in ERB. Consuming apps should not instantiate components directly.

<%= ui_card(
  title: "Revenue",
  summary: "$42,300 this month",
  link: reports_path
) %>

<%= ui_button(
  label: "Create invoice",
  href: new_invoice_path,
  variant: :primary
) %>

<%= ui_data_table(
  items: @products,
  columns: [
    { name: "Name" },
    { quantity: "Quantity" },
    { price: "Price" }
  ],
  empty_message: "No products found."
) do |table| %>
  <% table.link(:name) { |item| product_path(item) } %>
<% end %>

Available Components

`ui_card`

Renders a card layout with a title, summary, and a single call-to-action link.

Required props

title: (String)
summary: (String)
link: (String or URL)

Optional props

cta: (String, default "Read more")
edge_to_edge: (Boolean, default false) — when true, removes horizontal border-radius and side borders on mobile, restoring them at the sm breakpoint. Useful for cards that span the full viewport width on small screens.
class: (String) — extra classes added to the component's outer element for this one use

`ui_button`

Renders a deterministic button or link. If href is present, an <a> tag is rendered. Otherwise, a <button> tag is rendered with type="button".

Required props

label: (String)

Optional props

href: (String or URL)
variant: (:primary | :secondary | :danger, default :primary)
size: (:sm | :md | :lg, default :md)

`ui_data_table`

Renders a responsive data table. Accepts a collection of items (ActiveRecord objects, Structs, or hashes) and column definitions that map lookup keys to header labels.

Required props

items: (Array) — collection of AR objects, Structs, or hashes
columns: (Array of Hashes or Column objects) — each hash maps a lookup key to a header label, e.g. { name: "Name" }. Use Keystone::Ui::Column for per-column options.

Optional props

empty_message: (String) — message displayed when items is empty
sort: (Symbol/String) — current sort column key
sort_direction: (Symbol) — :asc or :desc
sort_url: (Lambda) — (col, dir) → url for generating sort links
hidden_columns: (Array) — column keys to hide (only affects hideable columns)

Column options

Keystone::Ui::Column.new(key, header_text, mobile_hidden: false, sortable: false, hideable: false)

Option	Default	Description
`mobile_hidden:`	`false`	hide on small screens (`hidden sm:table-cell`)
`sortable:`	`false`	render header as clickable sort link
`hideable:`	`false`	allow hiding via `hidden_columns:` / column picker

Mobile-hidden columns

Use Keystone::Ui::Column objects to hide columns on mobile. Columns with mobile_hidden: true receive hidden sm:table-cell classes, hiding them on small screens and showing them from the sm breakpoint up. Columns are visible on mobile by default.

<%= ui_data_table(
  items: @products,
  columns: [
    Keystone::Ui::Column.new(:name, "Name"),
    Keystone::Ui::Column.new(:quantity, "Quantity", mobile_hidden: true),
    Keystone::Ui::Column.new(:price, "Price")
  ]
) %>

Sortable columns

Mark columns as sortable: true and pass sort:, sort_direction:, and sort_url: to render clickable header links with sort arrows. Sort links use data-turbo-action="replace" for clean Turbo navigation. Toggle logic: active asc → desc, active desc → asc, inactive → asc.

<%
  columns = [
    Keystone::Ui::Column.new(:name, "Name", sortable: true),
    Keystone::Ui::Column.new(:quantity, "Quantity", mobile_hidden: true),
    Keystone::Ui::Column.new(:price, "Price", sortable: true)
  ]
%>
<%= ui_data_table(
  items: @products,
  columns: columns,
  sort: params[:sort],
  sort_direction: params[:direction],
  sort_url: ->(col, dir) { products_path(sort: col, direction: dir) }
) %>

Hidden columns

Mark columns as hideable: true and pass hidden_columns: to filter them out server-side. Non-hideable columns are always shown even if listed in hidden_columns:.

<%= ui_data_table(
  items: @products,
  columns: columns,
  hidden_columns: current_user.hidden_columns_for(:products)
) %>

Linkable cells

Register links via table.link(:column_key) in the block. The block receives the current item and must return a URL string. The cell's value is wrapped in an <a> tag.

<%= ui_data_table(
  items: @products,
  columns: [
    { name: "Name" },
    { quantity: "Quantity" },
    { price: "Price" }
  ]
) do |table| %>
  <% table.link(:name) { |item| product_path(item) } %>
<% end %>

Actions column

Pass a block to add a trailing "Actions" column. The block receives the component instance; call actions on it with a sub-block that receives each item.

<%= ui_data_table(
  items: @products,
  columns: [
    { name: "Name" },
    { status: "Status" }
  ]
) do |table| %>
  <% table.link(:name) { |item| product_path(item) } %>
  <% table.actions do |item| %>
    <%= ui_action_menu_item(label: "Edit", href: edit_product_path(item)) %>
    <%= ui_action_menu_item(label: "Delete", href: product_path(item), method: :delete) %>
  <% end %>
<% end %>

Each row's actions show in an action menu, opened by an ellipsis button, so a table never shows buttons. When an actions column is present, position-based styling classes shift automatically — the last data column receives middle styling and the actions column receives last styling.

`ui_column_picker`

Renders a "Columns" dropdown button with checkboxes for showing/hiding hideable columns. Pair with ui_data_table's hidden_columns: param.

Required props

columns: (Array of Column objects) — same array passed to ui_data_table

Optional props

hidden_columns: (Array) — currently hidden column keys
save_url: (String) — PATCH endpoint to persist preferences; omit for no persistence

On checkbox change, the Stimulus column-picker controller PATCHes { hidden_columns: [...] } as JSON to save_url, then reloads via Turbo.visit.

<%= ui_column_picker(
  columns: columns,
  hidden_columns: @hidden_columns,
  save_url: table_preferences_path("products")
) %>

`ui_page`

Wraps page content with consistent max-width and horizontal padding. When the page also uses ui_form_page or ui_show_page, it shows their desktop back link or breadcrumbs, and the form page title, at its top.

Optional props

max_width: (:sm | :md | :lg | :xl | :full, default :full) — constrains content width. Values map to max-w-2xl, max-w-4xl, max-w-6xl, max-w-7xl, or no constraint.
padding: (:standard | :none, default :standard) — adds responsive horizontal padding (px-4 sm:px-6 lg:px-8).
class: (String) — extra classes added to the component's outer element for this one use

<%= ui_page(max_width: :lg) do %>
  <!-- page content -->
<% end %>

`ui_section`

Groups related content with an optional header (title, subtitle, action) and vertical spacing.

Optional props

title: (String) — section heading
subtitle: (String) — secondary text below the title
action: — slot for a trailing action (e.g. a button)
menu: — a list of { label:, href:, method: } items shown in an action menu in the header, such as Edit and Delete
spacing: (:sm | :md | :lg, default :md) — top margin between sections
class: (String) — extra classes added to the component's outer element for this one use

<%= ui_section(title: "Products", subtitle: "All active items", spacing: :lg) do %>
  <!-- section content -->
<% end %>

`ui_grid`

Renders a CSS grid with responsive column counts and configurable gap sizes.

Optional props

cols: (Hash, default { default: 1 }) — maps breakpoints to column counts (1-12). Keys: :default, :sm, :md, :lg.
gap: (:sm | :md | :lg | :xl, default :md) — uniform gap size
gap_x: (Symbol) — horizontal gap (overrides gap:)
gap_y: (Symbol) — vertical gap (overrides gap:)

<%= ui_grid(cols: { default: 1, sm: 2, lg: 4 }, gap: :lg) do %>
  <!-- grid items -->
<% end %>

`ui_panel`

Renders a bordered, rounded container with padding and optional shadow.

Optional props

padding: (:sm | :md | :lg, default :md)
radius: (:md | :lg | :xl, default :lg)
shadow: (Boolean, default true)

<%= ui_panel(padding: :lg) do %>
  <!-- panel content -->
<% end %>

`ui_card_link`

Renders a clickable card that wraps its content in an <a> tag with hover styling.

Required props

href: (String or URL)

Optional props

padding: (:sm | :md | :lg, default :md)
shadow: (Boolean, default true)

<%= ui_card_link(href: product_path(@product)) do %>
  <h3>Product name</h3>
  <p>Product description</p>
<% end %>

`ui_form`

Wraps content in a <form> tag with proper method handling. For non-GET/POST methods (patch, put, delete), it renders a hidden _method input following Rails conventions. Supports multipart for file uploads.

Required props

action: (String) — form action URL

Optional props

method: (:get | :post | :patch | :put | :delete, default :post) — HTTP method. Non-native methods use a hidden _method field.
multipart: (Boolean, default false) — sets enctype="multipart/form-data" for file uploads
data: (Hash) — data attributes for the form element

<%= ui_form(action: items_path, method: :post) do %>
  <%= ui_form_field(attribute: :name, required: true) %>
  <%= ui_button(label: "Save", type: :submit) %>
<% end %>

<%= ui_form(action: item_path(@item), method: :patch, multipart: true) do %>
  <%= ui_form_field(attribute: :name) %>
  <%= ui_file_upload(name: "item[photo]", accept: "image/*", hint: "Max 5MB") %>
  <%= ui_button(label: "Save", type: :submit) %>
<% end %>

`ui_file_upload`

Renders a styled file upload with a clickable drop zone. Clicking anywhere on the zone opens the native file picker. Supports drag-and-drop — the zone highlights with accent colors on drag-over. Displays the selected file name(s) after pick or drop. Uses the file-upload Stimulus controller.

Required props

name: (String) — input name attribute

Optional props

label: (String, default "Choose file") — label text above the drop zone
accept: (String) — accepted file types (e.g. "image/*", ".pdf,.doc")
multiple: (Boolean, default false) — allow multiple file selection
hint: (String) — help text below the drop zone (e.g. file size limits)

<%= ui_file_upload(name: "avatar", accept: "image/*", hint: "PNG or JPG, max 5MB") %>
<%= ui_file_upload(name: "documents[]", multiple: true, label: "Upload documents", hint: "PDF, DOC up to 10MB each") %>

`ui_form_field`

Wraps a label, input, hint, and error message in a consistent layout. Infers label text from the attribute name when not explicitly provided.

Required props

attribute: (Symbol) — the form attribute name

Optional props

label: (String) — explicit label text (inferred from attribute: if omitted)
type: (:text | :number | :email | :password | :textarea, default :text)
required: (Boolean, default false) — shows a red asterisk after the label
hint: (String) — help text below the input
placeholder: (String)
min: / max: (for number inputs)
disabled: (Boolean, default false) — shows the value in an input that cannot be typed into and is not submitted

<%= ui_form_field(
  attribute: :name,
  label: "List Name",
  required: true,
  hint: "Enter a descriptive name"
) %>

`ui_input`

Renders a standalone <input> element with consistent styling.

Required props

name: (String)

Optional props

type: (:text | :number | :email | :password, default :text)
value: (String/Number)
placeholder: (String)
disabled: (Boolean, default false)
min: / max: / step: (for number type)

<%= ui_input(name: "search", placeholder: "Search...") %>
<%= ui_input(name: "quantity", type: :number, value: 1, min: 1) %>

`ui_textarea`

Renders a multi-line <textarea> element with consistent styling.

Required props

name: (String)

Optional props

value: (String)
rows: (Integer, default 3)
placeholder: (String)
disabled: (Boolean, default false)

<%= ui_textarea(name: "notes", rows: 5, placeholder: "Add notes...") %>

`ui_page_header`

Renders a page title area with an optional subtitle and action slot. On small screens the title stacks above actions; on wider screens they sit side-by-side.

Required props

title: (String) — the page heading

Optional props

subtitle: (String) — secondary text below the title
class: (String) — extra classes added to the component's outer element for this one use

Block API — register an action slot via header.action:

<%= ui_page_header(title: "Products", subtitle: "Manage your catalog") do |header| %>
  <% header.action do %>
    <%= ui_button(label: "New Product", href: new_product_path) %>
  <% end %>
<% end %>

`ui_alert`

Renders a styled alert/flash message with type variants, optional title, and dismissible button.

Required props

message: (String) — the alert message

Optional props

type: (:info | :success | :warning | :error, default :info) — determines background/text color
title: (String) — bold title above the message
dismissible: (Boolean, default false) — shows a dismiss button when true
class: (String) — extra classes added to the component's outer element for this one use

<%= ui_alert(message: "Changes saved successfully.", type: :success) %>
<%= ui_alert(message: "Could not save record.", type: :error, title: "Error", dismissible: true) %>

`ui_select`

Renders a styled <select> dropdown.

Required props

name: (String)

Optional props

options: (Array of [label, value] pairs, default [])
selected: (String) — pre-selected value
include_blank: (String) — blank option label
disabled: (Boolean, default false)

<%= ui_select(
  name: "status",
  options: [["Active", "active"], ["Inactive", "inactive"]],
  selected: "active",
  include_blank: "Select status..."
) %>

`ui_badge`

Renders an inline status badge.

Required props

label: (String)

Optional props

variant: (:neutral | :success | :danger | :warning | :info, default :neutral)
class: (String) — extra classes added to the component's outer element for this one use

<%= ui_badge(label: "Active", variant: :success) %>
<%= ui_badge(label: "Expired", variant: :danger) %>

`ui_stat_card`

Renders a metric card for dashboards.

Required props

label: (String)
value: (String/Number)

Optional props

variant: (:neutral | :success | :danger | :warning | :info, default :neutral)
suffix: (String) — unit label after the value
definition: (String) — what the metric captures
calculation: (String) — how the metric is computed
change: (Number) — percent change against the previous period, shown as ▲/▼
href: (String) — turns the value into a link to that URL; the card itself stays unlinked

When definition: or calculation: is given, an info button appears. Hovering or focusing it shows the details in a panel floating below the card, and tapping it toggles the panel on touch screens. The card never changes size.

<%= ui_stat_card(label: "Revenue", value: "$42,300", variant: :success, suffix: "/mo") %>
<%= ui_stat_card(label: "Merged", value: 12, href: "/pull_requests?state=merged", definition: "Pull requests merged in the range.") %>

`ui_calculation`

Shows the working behind a figure, closed by default under a quiet "How this is worked out" row, so a reader can check how a number was reached without it taking over the page. Put it under the figure it explains, such as a ui_stat_card.

Required props

groups: (Array of Hashes) — each with lines: and an optional title:. Each line is a Hash with label:, working: and result:.

Optional props

summary: (String, default "How this is worked out") — the text on the row that opens it

Each line is laid out as its label, its working and its result in three columns, in the same quiet text as a form hint.

<%= ui_stat_card(label: "Perfect value", value: "$107,695.00") %>
<%= ui_calculation(groups: [
  { title: "Store runs", lines: [
    { label: "Money a year", working: "$34.00 × 1,825", result: "$62,050.00" },
    { label: "Time a year", working: "1 hour × 1,825 × $25.00 an hour", result: "$45,625.00" }
  ] },
  { title: "How it adds up", lines: [
    { label: "Perfect value", working: "$107,675.00 in costs + $20.00 missed out", result: "$107,695.00" }
  ] }
]) %>

`ui_chart_card`

Renders a card wrapper for chart content with a title and configurable height.

Required props

title: (String)

Optional props

height: (:sm | :md | :lg, default :md) — maps to h-48, h-64, h-96

<%= ui_chart_card(title: "Monthly Revenue", height: :lg) do %>
  <!-- chart content -->
<% end %>

`ui_copy_button`

Renders a button that copies text to the clipboard.

Required props

text: (String) — the text to copy

Optional props

label: (String, default "Copy")
success_message: (String, default "Copied!")
error_message: (String, default "Failed!")

<%= ui_copy_button(text: "https://example.com/invite/abc123") %>

`ui_modal`

Renders a modal dialog with title, close button, and backdrop.

Required props

title: (String)

Optional props

size: (:sm | :md | :lg | :xl, default :md)

<%= ui_modal(title: "Confirm Delete", size: :sm) do %>
  <p>This action cannot be undone.</p>
<% end %>

`ui_accordion`

Renders collapsible question/answer items.

Optional props

items: (Array of Hashes) — each with :question and :answer keys

<%= ui_accordion(items: [
  { question: "What is Keystone?", answer: "A UI component library for Rails." },
  { question: "How do I install it?", answer: "Add the gem and run the generator." }
]) %>

`ui_tab_switcher`

Renders a tab bar with active state indicator. Uses Stimulus tab-switcher controller.

Required props

tabs: (Array of Strings) — tab labels

<%= ui_tab_switcher(tabs: ["Overview", "Details", "History"]) do %>
  <!-- tab panel content -->
<% end %>

`ui_option_card`

Renders a toggleable card option (radio-like selection).

Required props

name: (String) — input name
value: (String) — input value

Optional props

selected: (Boolean, default false)
input_data: (Hash) — data attributes for the hidden input
label_data: (Hash) — data attributes for the label

<%= ui_option_card(name: "theme", value: "dark", selected: true) do %>
  Dark Mode
<% end %>

`ui_hero`

Renders a large hero section for landing pages.

Required props

title: (String)

Optional props

subtitle: (String)
badge: (String) — small badge text above the title
layout: (:split | :centered, default :split)

<%= ui_hero(title: "Build faster with Keystone", subtitle: "UI components for Rails", badge: "New") do |hero| %>
  <% hero.with_aside do %>
    <!-- image or illustration -->
  <% end %>
<% end %>

`ui_feature_grid`

Renders a grid of feature cards with icons.

Required props

title: (String)
features: (Array of Hashes) — each with :icon, :title, :description

Optional props

subtitle: (String)

<%= ui_feature_grid(
  title: "Why Keystone?",
  subtitle: "Built for Rails developers",
  features: [
    { icon: "🚀", title: "Fast", description: "No build step required." },
    { icon: "🎨", title: "Themeable", description: "CSS custom properties." }
  ]
) %>

`ui_cta_banner`

Renders a call-to-action banner with title, subtitle, and action buttons.

Required props

title: (String)

Optional props

subtitle: (String)

<%= ui_cta_banner(title: "Ready to get started?", subtitle: "Try Keystone today.") do %>
  <%= ui_button(label: "Get Started", href: signup_path) %>
<% end %>

`ui_color_picker`

Renders an HSV color picker with swatch preview. Uses Stimulus color-picker controller.

Required props

name: (String) — form input name

Optional props

value: (String, default "#000000") — initial hex color
label: (String)

<%= ui_color_picker(name: "accent_color", value: "#3b82f6", label: "Accent") %>

`ui_navbar`

Renders the top-level navigation bar with slots for desktop and mobile sections. Sticky by default.

Optional props

sticky: (Boolean, default true)

Slots: logo, desktop_links, desktop_right, mobile_left, mobile_center, mobile_right

<%= ui_navbar do |nav| %>
  <% nav.with_logo do %>
    <%= link_to "MyApp", root_path %>
  <% end %>
  <% nav.with_desktop_links do %>
    <%= ui_nav_item(label: "Dashboard", href: root_path, active: true) %>
  <% end %>
<% end %>

`ui_nav_item`

Renders a single nav link within the navbar.

Required props

label: (String)
href: (String)

Optional props

active: (Boolean, default false)

<%= ui_nav_item(label: "Dashboard", href: "/", active: current_page?(root_path)) %>

`ui_nav_dropdown`

Renders a dropdown menu within the navbar. Uses Stimulus dropdown controller.

Required props

title: (String)
area: (Symbol/String)

Optional props

active: (Boolean, default false)

<%= ui_nav_dropdown(title: "Settings", area: :settings, active: false) do %>
  <%= link_to "Profile", profile_path %>
  <%= link_to "Billing", billing_path %>
<% end %>

`ui_bottom_nav`

Renders a mobile bottom tab bar. Hidden on desktop (lg:hidden).

No props. Wrap ui_bottom_nav_item calls inside.

<%= ui_bottom_nav do %>
  <%= ui_bottom_nav_item(label: "Home", href: "/", icon: "<svg>…</svg>", active: true) %>
  <%= ui_bottom_nav_item(label: "Search", href: "/search", icon: "<svg>…</svg>") %>
<% end %>

`ui_bottom_nav_item`

Renders a single bottom nav tab.

Required props

label: (String)
href: (String)
icon: (String) — raw SVG string

Optional props

active: (Boolean, default false)

<%= ui_bottom_nav_item(label: "Home", href: "/", icon: "<svg>…</svg>", active: true) %>

`ui_mobile_header`

Renders a mobile header with back link, centered title, and optional subtitle. Hidden on lg: screens.

Required props

title: (String)
back_url: (String)

Optional props

subtitle: (String)

<%= ui_mobile_header(title: "Edit Product", back_url: products_path) %>

`ui_action_menu`

Renders an ellipsis (⋯) button that opens a dropdown of actions, at every screen size. Uses Stimulus dropdown controller. Fill it with ui_action_menu_item.

<%= ui_action_menu do %>
  <%= ui_action_menu_item(label: "Edit", href: edit_product_path(@product)) %>
  <%= ui_action_menu_item(label: "Delete", href: product_path(@product), method: :delete) %>
<% end %>

`ui_action_menu_item`

One entry in an action menu. A link when method: is :get, and a form button that sends the method otherwise. An item that deletes asks for confirmation first.

Param	Required	Default
`label:`	yes	—
`href:`	yes	—
`method:`	no	`:get`
`confirm:`	no	`nil`

`ui_mobile_actions`

Renders an ellipsis dropdown for mobile action menus. Hidden on lg: screens. Uses Stimulus dropdown controller.

No props. Pass action links as block content.

<%= ui_mobile_actions do %>
  <%= link_to "Edit", edit_product_path(@product) %>
  <%= link_to "Delete", product_path(@product), data: { turbo_method: :delete } %>
<% end %>

`ui_form_page`

Wraps a form page with title and back navigation. Sets content_for signals so the navbar can render mobile header context. On lg screens and wider, where the mobile header is hidden, it shows a link back to back_url at the top of the page's ui_page, so call ui_page on the same page.

Required props

title: (String)

Optional props

back_url: (String) — defaults to the last link of the trail; with no back_url: and no trail, rendering raises KeystoneUi::MissingBackLink naming the page
subtitle: (String)
trail: (Array of [label, href] pairs) — the pages above this one; on lg screens and wider, breadcrumbs ending with title take the place of the back link. When the page passes none, it uses the trail the app supplies through config.trail_supplier

<%= ui_form_page(title: "New Product", back_url: products_path) %>
<%= ui_form_page(title: "New Product", back_url: products_path, trail: [["Catalog", catalog_path], ["Products", products_path]]) %>

`ui_show_page`

Wraps a show/detail page with title and back navigation. Sets content_for signals so the navbar can render mobile header context. On lg screens and wider, where the mobile header is hidden, it shows a link back to back_url at the top of the page's ui_page, so call ui_page on the same page.

Required props

title: (String)

Optional props

back_url: (String) — defaults to the last link of the trail; with no back_url: and no trail, rendering raises KeystoneUi::MissingBackLink naming the page
subtitle: (String)
trail: (Array of [label, href] pairs) — the pages above this one; on lg screens and wider, breadcrumbs ending with title take the place of the back link. When the page passes none, it uses the trail the app supplies through config.trail_supplier

<%= ui_show_page(title: @product.name, back_url: products_path, subtitle: "Details") %>
<%= ui_show_page(title: @product.name, back_url: products_path, trail: [["Catalog", catalog_path], ["Products", products_path]]) %>

Supplying every page's trail from the app

Set config.trail_supplier to a lambda that receives the view and returns that page's trail. ui_form_page and ui_show_page call it when the page passes no trail:, and a page that passes no back_url: goes back to the trail's last link. Returning nil leaves the page with its own back_url and no breadcrumbs.

KeystoneUi.configure do |config|
  config.trail_supplier = ->(view) { Breadcrumbs.trail_for(view) }
end

`ui_breadcrumbs`

Shows the pages above the current one as links separated by ›, ending with the current page, which is not linked. Shown on lg screens and wider only, where the mobile header is hidden. Use it on a page that uses neither ui_form_page nor ui_show_page; those two take the same trail through trail:.

Required props

trail: (Array of [label, href] pairs)

Optional props

current: (String) — the current page, shown last

<%= ui_breadcrumbs(trail: [["Catalog", catalog_path]], current: "Products") %>

`ui_settings_link`

Renders a settings row link with label and chevron icon.

Required props

label: (String)
href: (String)

<%= ui_settings_link(label: "Account", href: account_settings_path) %>

Releasing

Cutting a new version to RubyGems.org is documented in RELEASING.md.

Name		Name	Last commit message	Last commit date
.github		.github
app		app
bin		bin
config		config
docs		docs
lib		lib
roadmaps		roadmaps
test		test
the_local		the_local
.gitignore		.gitignore
.gitkeep		.gitkeep
.rubocop.yml		.rubocop.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Gemfile		Gemfile
MIT-LICENSE		MIT-LICENSE
PLAN.md		PLAN.md
README.md		README.md
RELEASING.md		RELEASING.md
Rakefile		Rakefile
keystone_ui.gemspec		keystone_ui.gemspec
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Keystone UI

Principles

Installation

Prerequisites

Steps

How Tailwind integration works

Registering a gem's Tailwind files

Upgrading from older versions

Light and dark mode

Letting users choose

Which mode a page gets

Color System

Defaults

Customizing colors

Usage in gems and engines

Per-user theming

Looks

Writing a look file

Where a look file goes

Shipping a look in a gem

Offering several looks

Helper API (primary surface)

Available Components

ui_card

ui_button

ui_data_table

ui_column_picker

ui_page

ui_section

ui_grid

ui_panel

ui_card_link

ui_form

ui_file_upload

ui_form_field

ui_input

ui_textarea

ui_page_header

ui_alert

ui_select

ui_badge

ui_stat_card

ui_calculation

ui_chart_card

ui_copy_button

ui_modal

ui_accordion

ui_tab_switcher

ui_option_card

ui_hero

ui_feature_grid

ui_cta_banner

ui_color_picker

ui_navbar

ui_nav_item

ui_nav_dropdown

ui_bottom_nav

ui_bottom_nav_item

ui_mobile_header

ui_action_menu

ui_action_menu_item

ui_mobile_actions

ui_form_page

ui_show_page

Supplying every page's trail from the app

ui_breadcrumbs

ui_settings_link

Releasing

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

`ui_card`

`ui_button`

`ui_data_table`

`ui_column_picker`

`ui_page`

`ui_section`

`ui_grid`

`ui_panel`

`ui_card_link`

`ui_form`

`ui_file_upload`

`ui_form_field`

`ui_input`

`ui_textarea`

`ui_page_header`

`ui_alert`

`ui_select`

`ui_badge`

`ui_stat_card`

`ui_calculation`

`ui_chart_card`

`ui_copy_button`

`ui_modal`

`ui_accordion`

`ui_tab_switcher`

`ui_option_card`

`ui_hero`

`ui_feature_grid`

`ui_cta_banner`

`ui_color_picker`

`ui_navbar`

`ui_nav_item`

`ui_nav_dropdown`

`ui_bottom_nav`

`ui_bottom_nav_item`

`ui_mobile_header`

`ui_action_menu`

`ui_action_menu_item`

`ui_mobile_actions`

`ui_form_page`

`ui_show_page`

`ui_breadcrumbs`

`ui_settings_link`