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

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