version: "1.0.1" name: rails-design-system description: Ruby on Rails design system guidelines for building consistent, maintainable UI with minimal abstraction. This skill should be used when creating or refactoring Rails views, partials, components, form builders, helpers, Stimulus controllers, Turbo Frames, Turbo Streams, or design tokens. Triggers on tasks involving ERB partials, Turbo navigation, Turbo Streams, ViewComponent, Phlex, Tailwind design tokens, custom form builders, view helpers, Stimulus behaviors, Import Maps, Lookbook previews, or design system consistency audits.

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