pproenca/dot-skills/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

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