Community Ruby on Rails Design System Best Practices

Comprehensive design system guide for Ruby on Rails applications, maintained by Community. Contains 51 rules across 9 categories, prioritized by impact to guide automated refactoring and code generation. Covers the full Rails frontend stack: Turbo (Drive, Frames, Streams), Stimulus, ERB partials, design tokens, form builders, and view helpers. Complements rails-dev (controllers, models, queries) and tailwind (CSS patterns) by covering the systematic UI component architecture layer.

When to Apply

Reference these guidelines when:

• Deciding whether to extract a partial, component, or helper

• Defining design tokens with Tailwind CSS @theme

• Creating or refactoring ERB partials with explicit locals

• Decomposing pages into Turbo Frames for targeted updates

• Using Turbo Streams for multi-element CRUD updates

• Coordinating Turbo navigation with Stimulus controllers

• Building ViewComponent or Phlex components for complex UI

• Implementing a custom FormBuilder for consistent forms

• Writing view helpers for badges, icons, and conditional classes

• Adding Stimulus controllers for interactive behaviors

• Managing JavaScript dependencies with Import Maps

• Auditing the codebase for UI duplication and naming drift

Rule Categories by Priority

Priority Category Impact Prefix

1 Design Decisions CRITICAL decide-

2 Design Tokens CRITICAL token-

3 Turbo Integration HIGH turbo-

4 Partial Patterns HIGH partial-

5 Component Architecture HIGH comp-

6 Form System MEDIUM-HIGH form-

7 Helper Patterns MEDIUM helper-

8 Stimulus Behaviors MEDIUM stim-

9 Consistency & Organization LOW-MEDIUM org-

Quick Reference

1. Design Decisions (CRITICAL)

• decide-three-uses-rule

• Extract only after a pattern appears in 3+ places

• decide-partial-vs-component

• Choose partials for simple reuse, components for complex logic

• decide-helper-vs-partial

• Use helpers for tiny HTML fragments, partials for layout blocks

• decide-prove-then-extract

• Prove patterns in production before abstracting

• decide-avoid-wrapper-components

• Avoid thin wrappers that add indirection without value

• decide-design-system-scope

• Scope the design system to what the app actually needs

2. Design Tokens (CRITICAL)

• token-tailwind-theme

• Define tokens with Tailwind CSS @theme directive

• token-semantic-color-names

• Name colors by purpose, not appearance

• token-spacing-scale

• Use a constrained spacing scale for consistent layout

• token-typography-scale

• Define a typography scale for headings, body, and UI text

• token-component-tokens

• Create component-level tokens for repeated patterns

• token-share-tokens-with-ruby

• Share token values between CSS and Ruby when needed

3. Turbo Integration (HIGH)

• turbo-drive-defaults

• Let Turbo Drive handle navigation by default

• turbo-frame-decompose

• Decompose pages into Turbo Frames for targeted updates

• turbo-frame-naming

• Name Turbo Frames with dom_id conventions

• turbo-frame-vs-stream

• Choose Turbo Frames vs Turbo Streams by scope of change

• turbo-stream-crud

• Use Turbo Streams for multi-element page updates

• turbo-stimulus-coordination

• Coordinate Turbo and Stimulus without conflicts

4. Partial Patterns (HIGH)

• partial-explicit-locals

• Always pass locals explicitly to partials

• partial-presenter-objects

• Use presenter objects to encapsulate view logic

• partial-naming-conventions

• Name partials by what they render, prefixed with underscore

• partial-yield-blocks

• Use yield blocks for flexible partial layouts

• partial-collection-with-spacer

• Use collection rendering with spacer templates

• partial-shared-directory

• Place cross-controller partials in app/views/shared

5. Component Architecture (HIGH)

• comp-when-to-use

• Use components when partials outgrow simple rendering

• comp-explicit-args

• Define explicit typed arguments for every component

• comp-slots-for-markup

• Use slots for caller-provided markup blocks

• comp-test-rendered-output

• Test components by asserting on rendered HTML

6. Form System (MEDIUM-HIGH)

• form-custom-builder

• Create a custom FormBuilder for consistent form rendering

• form-set-default-builder

• Set the custom builder as the application default

• form-error-display

• Display field errors inline with consistent markup

• form-accessible-labels

• Generate accessible labels and ARIA attributes automatically

• form-group-wrapper

• Wrap label + input + error in a consistent group element

• form-button-consistency

• Standardize submit buttons through the form builder

7. Helper Patterns (MEDIUM)

• helper-tag-helpers

• Use tag helpers for small generated HTML fragments

• helper-conditional-classes

• Use class_names for conditional CSS classes

• helper-icon-helper

• Create an icon helper for consistent icon rendering

• helper-badge-pattern

• Build a badge helper for status indicators

• helper-scope-to-domain

• Scope helpers to specific domains, not generic utilities

8. Stimulus Behaviors (MEDIUM)

• stim-general-purpose

• Write general-purpose controllers, not one-off scripts

• stim-data-attribute-config

• Configure behavior through data attributes, not JavaScript

• stim-small-controllers

• Keep controllers small and single-responsibility

• stim-composable-controllers

• Compose multiple controllers on one element

• stim-use-outlets

• Use outlets for cross-controller communication

• stim-leverage-library

• Use stimulus-components before writing custom controllers

9. Consistency & Organization (LOW-MEDIUM)

• org-naming-conventions

• Follow consistent naming across partials, components, and helpers

• org-file-structure

• Organize design system files in predictable locations

• org-deduplication-audit

• Periodically audit views for duplicated patterns

• org-import-maps

• Use Import Maps for zero-build JavaScript delivery

• org-preview-with-lookbook

• Preview components with Lookbook in development

• org-document-design-decisions

• Document design system decisions in ADRs

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information