layered-ui-rails (v0.17.0)

An open source Rails 8+ engine built on Tailwind CSS, providing customisable WCAG 2.2 AA compliant design tokens, utility classes, and Stimulus controllers for theme switching, mobile navigation, slide-out panels, modals, and tabs. Integrates with the gems you already use (Devise, Pagy, Ransack).

Features

Minimal style

Monochrome out of the box and fully extensible - override colours, typography, and components to suit your project.

Dark/light theme

System preference detection with localStorage persistence and manual toggle.

Customisable logo and icons

Override the default logos and icons to match your brand.

Responsive layout

Tested thoroughly across form factors, from mobile to ultrawide.

WCAG 2.2 AA accessible

Skip links, focus indicators, ARIA attributes, and 4.5:1 contrast ratios. Read the latest accessibility audits.

Google Lighthouse optimised

layered-ui-rails scores a perfect 100 across all four Google Lighthouse categories - performance, accessibility, best practices, and SEO.

Optional integrations

Devise authentication, Pagy pagination, and Ransack search and sort with styled controls.

Agent skill

Bundled agent skill teaches AI agents to install, configure, and build with layered-ui-rails.

Requirements

Ruby on Rails >= 8.0
Tailwind CSS Rails >= 4.0

Agent skill

An agent skill is included so AI coding agents can work with layered-ui-rails in your project. Once installed, the agent can handle the full setup - just ask it to add layered-ui-rails to your app and it will install the gem, run the generator, and configure your layout.

Project install - scoped to a single repo, available to all contributors:

bin/rails generate layered:ui:install_agent_skill

Global install - available across all your projects:

./install-skill.sh
# or install remotely without cloning the repo:
curl -fsSL https://raw.githubusercontent.com/layered-ai-public/layered-ui-rails/main/install-skill.sh | sh

Installation

Add to your Gemfile:

gem "layered-ui-rails"

Then run:

bundle install

Setup

Run the install generator to copy CSS and JS to your application:

bin/rails generate layered:ui:install

This will:

Copy layered_ui.css to app/assets/tailwind/
Add @import "./layered_ui"; to your application.css
Add import "layered_ui" to your application.js

Next, update your application.html.erb layout to render the layered-ui-rails layout and set up content blocks for navigation, panels, and page titles. See the layout guide for full details.

You can override the default logo by placing your own logo_light.svg and logo_dark.svg files in app/assets/images/layered_ui/. The asset pipeline will serve your files instead of the defaults provided by the engine. The panel button icon color can be changed by overriding the --button-primary-icon Tier 2 token, or replaced entirely by setting @l_ui_panel_icon_light_url and @l_ui_panel_icon_dark_url (rendered in light and dark mode respectively).

See the integrations page for optional Devise, Pagy, and Ransack support.

Accessibility audits

The latest accessibility audits are available at https://github.com/layered-ai-public/layered-ui-rails/blob/main/audits/accessibility.

License

Released under the Apache 2.0 License.

Trademarks

The source code is fully open, but the layered.ai name, logo, and brand assets are trademarks of LAYERED AI LIMITED. The Apache 2.0 license does not grant rights to use the layered.ai branding. Forks and redistributions must use a distinct name. See TRADEMARK.md for the full policy.

Contributing

CLA.md - contributor licence agreement