Good to Know - Rails UI Components

Copy, Don't Install

This is a template library, not a gem. Copy components to your project and customize them freely. You own the code — no version conflicts, no breaking upgrades, full control over styling and behavior.

Component Design Patterns

Consistent API All components follow similar initialization patterns

def initialize(variant: nil, size: :md, **options)
  @variant = variant   # Visual style
  @size = size         # Size modifier
  @options = options   # HTML attributes
end

Composable Complex components use subcomponent composition

<%= ui.card do %>
  <%= ui.card_header do %>
    <%= ui.card_title "Title" %>
  <% end %>
  <%= ui.card_body do %>Content<% end %>
  <%= ui.card_footer do %>Footer<% end %>
<% end %>

CSS Strategy

Base Classes

Core component styling using TailwindCSS utilities

@apply px-4 py-2 rounded-md font-medium

Modifier Classes

BEM-like naming for variants and states

.btn-default, .btn-lg, .btn-outline

Dynamic Classes

Rails' class_names helper for conditionals

class_names("btn", "btn-#{variant}")

ViewComponent or plain HTML?

Both work — use whichever fits the context:

Via ui helper

<%= ui.btn "Save", variant: :default, size: :lg %>

Via plain HTML

<button class="btn btn-default btn-lg">Save</button>

Styling Guidelines

Use @apply for component base styles
Use semantic color tokens (bg-primary, text-foreground)
Use CSS custom properties for themeable values
Design mobile-first with responsive prefixes
Keep utility chains short in templates

Avoid

Hardcoded color values (text-blue-600)
Long utility chains in ERB templates
Inline styles for themeable properties
Overriding component internals with !important
Skipping responsive breakpoints

Accessibility

Built-in

Semantic HTML elements
ARIA attributes where needed
Keyboard navigation support
Focus management for modals/dropdowns
Screen reader friendly content

Your Responsibilities

Provide meaningful alt text for images
Ensure sufficient color contrast
Test with screen readers
Add ARIA labels for dynamic content
Follow WCAG 2.1 guidelines

Making it yours

This is your codebase once you copy the components.

Modify styling to match your brand, add new variants and sizes, extend functionality, remove unused components, or combine them into new ones.

Customize theme colors