Maquina UI Standards — Maquina
Claude Code plugin for building consistent, accessible UIs in Rails using maquina_components. ERB partials, Tailwind CSS 4, and Stimulus with AI-assisted generation.
A Claude Code plugin that teaches Claude how to build UIs with maquina_components — ERB partials styled with Tailwind CSS 4 and data attributes, inspired by shadcn/ui.
What Is This?
A Claude Code skill that provides:
- Component catalog — All 15+ components with ERB examples
- Form patterns — Validation, error handling, inline layouts
- Layout patterns — Sidebar navigation, page structure
- Turbo integration — Frames, Streams, component updates
- Spec checklist — Review criteria for UI quality
When installed, Claude generates code that matches your component conventions without back-and-forth corrections.
The Problem It Solves
Without the skill, asking Claude to build a view results in generic Rails patterns:
<div class="card">
<h2><%= @user.name %></h2>
</div>
With the skill, Claude uses your actual components:
<%= render "components/card" do %>
<%= render "components/card/header" do %>
<%= render "components/card/title", text: @user.name %>
<% end %>
<% end %>
The skill eliminates the “use the card partial, not a div” corrections that slow down AI-assisted development.
Quick Start
1. Add the Marketplace
/plugin marketplace add maquina-app/rails-claude-code
2. Install the Plugin
/plugin install maquina-ui-standards@rails
3. Start Building
> Create the users index view with a table showing name, email, and status
Requirements
The maquina_components gem must be installed in your Rails application:
bundle add maquina_components
rails generate maquina_components:install
What It Provides
| Reference | Purpose |
|---|---|
| Component catalog | All available components with ERB examples |
| Form patterns | Validation states, error handling, inline layouts |
| Layout patterns | Sidebar navigation, page headers, content areas |
| Turbo integration | Frames, Streams, and component updates |
| Spec checklist | Accessibility and consistency review criteria |
Usage Examples
Create a View
> Create the users index view with a table showing name, email, and status
Claude generates:
<%= render "components/page_header", title: "Users", description: "Manage team members" %>
<%= render "components/card" do %>
<%= render "components/card/content" do %>
<table data-component="table">
<thead>
<tr>
<th>Name</th>
<th>Email</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<% @users.each do |user| %>
<tr>
<td><%= user.name %></td>
<td><%= user.email %></td>
<td>
<%= render "components/badge",
variant: user.active? ? :success : :secondary do %>
<%= user.active? ? "Active" : "Inactive" %>
<% end %>
</td>
</tr>
<% end %>
</tbody>
</table>
<% end %>
<% end %>
Implement a Form
> Implement the project form with name, description, and a framework combobox
Claude generates:
<%= form_with model: @project do |form| %>
<div class="space-y-4">
<div>
<%= form.label :name %>
<%= form.text_field :name, data: { field: true } %>
</div>
<div>
<%= form.label :description %>
<%= form.text_area :description, data: { field: true }, rows: 4 %>
</div>
<div>
<%= form.label :framework_id %>
<%= render "components/combobox",
name: "project[framework_id]",
selected_value: @project.framework_id,
options: @frameworks.map { |f| { value: f.id, label: f.name } },
placeholder: "Select a framework" %>
</div>
<div class="flex justify-end gap-2">
<%= link_to "Cancel", projects_path,
data: { component: "button", variant: "outline" } %>
<%= form.submit "Save",
data: { component: "button", variant: "primary" } %>
</div>
</div>
<% end %>
Review Existing Code
> Review this view against the maquina UI standards and suggest improvements
Claude checks for:
- Proper component usage instead of raw HTML
- Correct data attributes on form fields
- Accessibility attributes
- Consistent spacing and layout patterns
- Turbo Frame and Stream integration
Component Patterns
Partial Components
Components rendered as partials with strict locals:
<%# Card with header and content %>
<%= render "components/card" do %>
<%= render "components/card/header" do %>
<%= render "components/card/title", text: "Appointments" %>
<%= render "components/card/description", text: "Manage your schedule" %>
<% end %>
<%= render "components/card/content" do %>
<!-- Content here -->
<% end %>
<% end %>
Data Attribute Components
Form elements and buttons use data attributes for styling:
<%# Text input %>
<%= form.text_field :name, data: { field: true } %>
<%# Button %>
<%= link_to "Edit", edit_path,
data: { component: "button", variant: "outline", size: "sm" } %>
<%# Badge %>
<%= render "components/badge", variant: :success do %>
Active
<% end %>
Layout Patterns
<%# Sidebar layout %>
<%= render "components/sidebar/provider", state: sidebar_state do %>
<%= render "components/sidebar" do %>
<%= render "components/sidebar/header" do %>
<!-- Logo -->
<% end %>
<%= render "components/sidebar/content" do %>
<%= render "components/sidebar/group", title: "Navigation" do %>
<%= render "components/sidebar/menu" do %>
<%= render "components/sidebar/menu_item" do %>
<%= render "components/sidebar/menu_link",
href: dashboard_path,
icon: :home,
label: "Dashboard",
active: current_page?(dashboard_path) %>
<% end %>
<% end %>
<% end %>
<% end %>
<% end %>
<%= render "components/sidebar/inset" do %>
<%= yield %>
<% end %>
<% end %>
Package Contents
maquina-ui-standards/
├── agents/maquina-ui-standards.md # Main skill
├── QUICKSTART.md # Quick reference
└── references/
├── component-catalog.md # All available components
├── form-patterns.md # Validation, error handling
├── layout-patterns.md # Pages, dashboards
├── turbo-integration.md # Frames, streams
└── spec-checklist.md # Accessibility, consistency
Team Installation
Add to your project’s .claude/settings.json:
{
"extraKnownMarketplaces": {
"rails": {
"source": {
"source": "github",
"repo": "maquina-app/rails-claude-code"
}
}
},
"enabledPlugins": [
"maquina-ui-standards@rails"
]
}
Alternative: Claude Skill Installation
If you prefer using Claude Skills instead of the plugin system, copy the skill to your project:
mkdir -p .claude/skills
# Copy from maquina_components repository
cp -r skill .claude/skills/maquina-ui-standards
Then reference it in your CLAUDE.md:
## UI Components
This project uses maquina_components for UI. Before implementing views,
forms, or interactive components, read the UI standards skill:
.claude/skills/maquina-ui-standards/SKILL.md
Always consult the skill when:
- Creating or modifying views
- Implementing forms
- Adding interactive components
- Building layouts with sidebar/header patterns
- Working with Turbo Streams that update UI