rails-design-system

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