Senren UI (senren-ui)

洗練 — refined, polished, sophisticated.

Live Docs & Component Reference → senren-ui.dev

A Rails-native UI component library built on ViewComponent, Hotwire (Turbo + Stimulus), and TailwindCSS, with a centralized AI-agent skill system and a source-copy install model inspired by shadcn/ui.

• A Rails engine + generators that ship UI components into your host app.
• A registry of well-tested ViewComponents and Stimulus controllers.
• A centralized .senren/skill.md file so AI coding agents understand every installed component, its dependencies, and its anti-patterns.
• A multi-agent instruction sync for Codex, Claude, Copilot, and Cursor.

• Not React, Vue, Alpine, or any external state framework.
• Not a CSS-only kit — components ship Ruby + ERB + (optional) Stimulus.
• Not an opaque dependency — installed components live in your app under app/components/senren/ and you own them.

Add to your Rails app's Gemfile:

gem "senren-ui", path: "../../senren-rails", require: "senren/rails"   # local path during dev
# or once published:
# gem "senren-ui", require: "senren/rails"

Then:

bundle install
bin/rails generate senren:install
bin/rails senren:add button card badge alert form input \
  textarea native_select table dropdown_menu dialog alert_dialog

bin/rails generate senren:install           # one-time setup
bin/rails generate senren:component picker --client  # custom component with Stimulus
bin/rails generate senren:component picker --no-client  # without Stimulus
bin/rails senren:add dialog --client        # install interactive official component
bin/rails senren:add button                 # install static official component
bin/rails senren:skill:sync                 # rebuild .senren/skill.md
bin/rails senren:agents:sync                # rebuild .senren/agent-rules + adapters
bin/rails senren:doctor                     # check installation health

<%= render Senren::ButtonComponent.new(variant: :primary) do %>
  Save changes
<% end %>

<%= render Senren::CardComponent.new do |card| %>
  <% card.with_header { "Account settings" } %>
  <% card.with_body   { "Manage your account details." } %>
  <% card.with_footer do %>
    <%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
  <% end %>
<% end %>

This repository ships as a workspace with a real Rails dogfooding app:

senren-workspace/
  senren-rails/        # the local gem source directory
  apps/
    todolist/          # real Rails app that uses senren-ui via local path

apps/todolist is the production-like acceptance test for Senren — a small SaaS-style Todo manager built entirely from Senren components.

After install, your app contains:

• .senren/skill.md — centralized component guide for AI agents, grouped by Actions / Forms / Overlays / Navigation / Layout / Data Display / SaaS Blocks / Rich Content.
• .senren/registry.yml — mirror of the gem-side registry.
• .senren/installed_components.yml — ledger of installed components.
• .senren/conventions.md — Senren conventions for humans and agents.
• .senren/agent-rules.md — source of truth for generated agent rules.
• AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/senren.mdc — marker-managed adapter files for each agent.

The skill file uses <!-- senren:skill:start --> / :end markers; only the region between them is rewritten by the generator, so any notes you add outside the markers are preserved.

Agent adapter files are also marker-managed, so Senren updates only its own generated block and preserves your existing instructions outside that block.

See registry/components.yml for the canonical list. v0.1 ships:

• Phase 1 — Foundation (full): Button, Link, Badge, Typography, Separator, Skeleton, Avatar, Alert, Card, AspectRatio.
• Phase 2 — Forms (full): Form, Input, Textarea, Checkbox, CheckboxGroup, RadioButton, NativeSelect, Select, Switch, MaskedInput.
• Phase 3 — Overlays (full): Dialog, AlertDialog, DropdownMenu, Popover, Tooltip, HoverCard, Sheet, ContextMenu.
• Phases 4–6 (scaffolded stubs): Navigation/Layout, Data/Advanced, SaaS Blocks. Each is registered, has a class, and renders a clearly marked placeholder until promoted to full implementation.

bundle install
bun install
bundle exec rake test            # gem tests
bun run controllers:check        # lint + syntax check for templates/controllers/*.js
bun run controllers:lint:fix     # auto-fix lint issues for controllers
bundle exec rake test:system     # Stimulus/system tests

See CONTRIBUTING.md. Two rules to know up front:

1. Every meaningful change creates or updates a file in history/.
2. Architectural decisions are captured in plans/ before code is written.

MIT — see LICENSE.