Good to Know - Rails UI Components

Architectural Philosophy

Copy, Don't Install

This is a template library, not a gem. Copy components to your project and customize them as needed. This approach gives you full control over styling, behavior, and dependencies.

💡 Think of it as a "component starter kit" rather than a traditional library.

Component Design Patterns

1. Consistent API

All components follow similar initialization patterns:

def initialize(variant: nil, size: :md, **options)
  @variant = variant   # Visual style (primary, secondary, etc.)
  @size = size         # Size modifier (xs, sm, md, lg, xl)
  @options = options   # Additional attributes (class, data, etc.)
end

2. CSS Class Strategy

Components use a hybrid approach:

Base Classes

Core component styling using TailwindCSS utilities

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

Modifier Classes

BEM-like naming for variants and states

.btn-primary, .btn-lg, .btn-outlined

Dynamic Classes

Rails' class_names helper for conditional styling

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

3. Content Slots

Complex components use ViewComponent slots for flexibility:

# Component definition
renders_one :header, Ui::Card::Header::Component
renders_one :body
renders_one :footer, Ui::Card::Footer::Component

# Usage
<%= render Ui::Card::Component.new do |card| %>
  <% card.with_header(title: "Title") %>
  <% card.with_body { "Content" } %>
<% end %>

Styling Guidelines

TailwindCSS Best Practices

Use @apply for component base styles
Avoid long utility chains in templates
Create custom CSS for complex animations/interactions
Use CSS custom properties for themeable values

Responsive Design

Components are mobile-first and responsive by default. Use Tailwind's responsive prefixes judiciously.

@apply px-4 md:px-6 lg:px-8

💡 View Components or HTML/CSS

It's not necessary to use view components at all in the view layer. You can have standard HTML with `classes` and `data` attributes.

For example. Instead of:

<%= render Ui::Button::Component.new(variant: :primary, size: :lg).with_content "Button" %/>

You can do:

<button class="btn btn-primary btn-lg">Button</button>

Accessibility (A11y)

Built-in Features

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

Contributing & Customization

Making It Your Own

These components are meant to be a starting point. Feel free to:

Modify styling to match your brand
Add new variants and sizes
Extend functionality as needed
Remove unused components
Combine multiple components into new ones

Remember

This is your codebase once you copy the components. Make them work for your specific needs!