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

tailwind

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

decide-

token-

turbo-

partial-

comp-

form-

helper-

stim-

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