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