rails-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community Ruby on Rails Design System Best Practices

社区版Ruby on Rails设计系统最佳实践

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.

这是一份由社区维护的Ruby on Rails应用设计系统综合指南，包含9个类别下的51条规则，按影响程度排序，可指导自动化重构和代码生成。覆盖完整的Rails前端技术栈：Turbo（Drive、Frames、Streams）、Stimulus、ERB局部视图、设计令牌、表单构建器和视图助手。补充了

rails-dev

（控制器、模型、查询）和

tailwind

（CSS模式）的内容，聚焦系统化的UI组件架构层。

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

在以下场景中参考本指南：

决定是否提取局部视图、组件或助手
使用Tailwind CSS
```
@theme
```
定义设计令牌
创建或重构带有显式局部变量的ERB局部视图
将页面拆分为Turbo Frames以实现定向更新
使用Turbo Streams实现多元素CRUD更新
协调Turbo导航与Stimulus控制器
为复杂UI构建ViewComponent或Phlex组件
实现自定义FormBuilder以保证表单一致性
编写用于徽章、图标和条件类的视图助手
添加Stimulus控制器实现交互行为
使用Import Maps管理JavaScript依赖
审计代码库以检查UI重复和命名偏差

Rule Categories by Priority

按优先级划分的规则类别


decide-
token-
turbo-
partial-
comp-
form-
helper-
stim-
org-

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-`


decide-
token-
turbo-
partial-
comp-
form-
helper-
stim-
org-

优先级	类别	影响程度	前缀
1	设计决策	严重	`decide-`
2	设计令牌	严重	`token-`
3	Turbo集成	高	`turbo-`
4	局部视图模式	高	`partial-`
5	组件架构	高	`comp-`
6	表单系统	中高	`form-`
7	助手模式	中	`helper-`
8	Stimulus行为	中	`stim-`
9	一致性与组织	中低	`org-`

Quick Reference

快速参考

1. Design Decisions (CRITICAL)

1. 设计决策（严重）

```
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

```
decide-three-uses-rule
```
- 仅当某一模式出现3次及以上时才进行提取
```
decide-partial-vs-component
```
- 简单复用选择局部视图，复杂逻辑选择组件
```
decide-helper-vs-partial
```
- 小型HTML片段使用助手，布局块使用局部视图
```
decide-prove-then-extract
```
- 在生产环境验证模式有效性后再进行抽象
```
decide-avoid-wrapper-components
```
- 避免使用仅增加间接性而无实际价值的轻量包装组件
```
decide-design-system-scope
```
- 设计系统的范围应与应用实际需求匹配

2. Design Tokens (CRITICAL)

2. 设计令牌（严重）

```
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

```
token-tailwind-theme
```
- 使用Tailwind CSS @theme指令定义令牌
```
token-semantic-color-names
```
- 按用途而非外观为颜色命名
```
token-spacing-scale
```
- 使用受限的间距比例保证布局一致性
```
token-typography-scale
```
- 为标题、正文和UI文本定义排版比例
```
token-component-tokens
```
- 为重复模式创建组件级令牌
```
token-share-tokens-with-ruby
```
- 必要时在CSS与Ruby之间共享令牌值

3. Turbo Integration (HIGH)

3. Turbo集成（高）

```
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

```
turbo-drive-defaults
```
- 默认由Turbo Drive处理导航
```
turbo-frame-decompose
```
- 将页面拆分为Turbo Frames以实现定向更新
```
turbo-frame-naming
```
- 遵循dom_id约定为Turbo Frames命名
```
turbo-frame-vs-stream
```
- 根据变更范围选择Turbo Frames或Turbo Streams
```
turbo-stream-crud
```
- 使用Turbo Streams实现多元素页面更新
```
turbo-stimulus-coordination
```
- 协调Turbo与Stimulus避免冲突

4. Partial Patterns (HIGH)

4. 局部视图模式（高）

```
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

```
partial-explicit-locals
```
- 始终显式向局部视图传递局部变量
```
partial-presenter-objects
```
- 使用展示器对象封装视图逻辑
```
partial-naming-conventions
```
- 局部视图按渲染内容命名，前缀加下划线
```
partial-yield-blocks
```
- 使用yield块实现灵活的局部视图布局
```
partial-collection-with-spacer
```
- 使用带间隔模板的集合渲染方式
```
partial-shared-directory
```
- 将跨控制器的局部视图放在app/views/shared目录下

5. Component Architecture (HIGH)

5. 组件架构（高）

```
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

```
comp-when-to-use
```
- 当局部视图超出简单渲染需求时使用组件
```
comp-explicit-args
```
- 为每个组件定义显式的类型化参数
```
comp-slots-for-markup
```
- 使用插槽处理调用者提供的标记块
```
comp-test-rendered-output
```
- 通过断言渲染后的HTML来测试组件

6. Form System (MEDIUM-HIGH)

6. 表单系统（中高）

```
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

```
form-custom-builder
```
- 创建自定义FormBuilder保证表单渲染一致性
```
form-set-default-builder
```
- 将自定义构建器设置为应用默认值
```
form-error-display
```
- 使用一致的标记内联显示字段错误
```
form-accessible-labels
```
- 自动生成可访问标签和ARIA属性
```
form-group-wrapper
```
- 将标签+输入框+错误信息包裹在统一的组元素中
```
form-button-consistency
```
- 通过表单构建器标准化提交按钮

7. Helper Patterns (MEDIUM)

7. 助手模式（中）

```
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

```
helper-tag-helpers
```
- 使用标签助手生成小型HTML片段
```
helper-conditional-classes
```
- 使用class_names处理条件CSS类
```
helper-icon-helper
```
- 创建图标助手保证图标渲染一致性
```
helper-badge-pattern
```
- 构建徽章助手用于状态指示
```
helper-scope-to-domain
```
- 助手应限定在特定领域，而非通用工具

8. Stimulus Behaviors (MEDIUM)

8. Stimulus行为（中）

```
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

```
stim-general-purpose
```
- 编写通用控制器，而非一次性脚本
```
stim-data-attribute-config
```
- 通过数据属性而非JavaScript配置行为
```
stim-small-controllers
```
- 保持控制器小巧，遵循单一职责原则
```
stim-composable-controllers
```
- 在单个元素上组合多个控制器
```
stim-use-outlets
```
- 使用outlets实现控制器间通信
```
stim-leverage-library
```
- 优先使用stimulus-components而非编写自定义控制器

9. Consistency & Organization (LOW-MEDIUM)

9. 一致性与组织（中低）

```
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

```
org-naming-conventions
```
- 在局部视图、组件和助手间遵循一致的命名规范
```
org-file-structure
```
- 将设计系统文件组织在可预测的位置
```
org-deduplication-audit
```
- 定期审计视图以检查重复模式
```
org-import-maps
```
- 使用Import Maps实现零构建JavaScript交付
```
org-preview-with-lookbook
```
- 在开发环境中使用Lookbook预览组件
```
org-document-design-decisions
```
- 在ADR中记录设计系统决策

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

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息