rails-design-system

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

面向 Ruby on Rails 应用的全面设计系统指南，由社区维护。包含 9 个类别中的 51 条规则，并按影响程度排序，以指导自动化重构和代码生成。涵盖完整的 Rails 前端技术栈：Turbo（Drive、Frames、Streams）、Stimulus、ERB 局部模板、设计令牌、表单构建器和视图辅助方法。作为 rails-dev（控制器、模型、查询）和 tailwind（CSS 模式）的补充，覆盖系统化的 UI 组件架构层。

适用场景

在以下情形中参考这些指南：

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

按优先级划分的规则类别

优先级	类别	影响	前缀
1	设计决策	CRITICAL	decide-
2	设计令牌	CRITICAL	token-
3	Turbo 集成	HIGH	turbo-
4	局部模板模式	HIGH	partial-
5	组件架构	HIGH	comp-
6	表单系统	MEDIUM-HIGH	form-
7	辅助方法模式	MEDIUM	helper-
8	Stimulus 行为	MEDIUM	stim-
9	一致性与组织	LOW-MEDIUM	org-

快速参考

1. 设计决策（CRITICAL）

• 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. 设计令牌（CRITICAL）

• 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 集成（高优先级）

• 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 模式（高优先级）

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

5. 组件架构（高优先级）

• comp-when-to-use - 当 partial 的逻辑超出简单渲染范围时，改用组件
• comp-explicit-args - 为每个组件定义显式的类型化参数
• comp-slots-for-markup - 使用 slots 接收调用方提供的标记块
• comp-test-rendered-output - 通过断言渲染后的 HTML 来测试组件

6. 表单系统（中高优先级）

• form-custom-builder - 创建自定义 FormBuilder，以统一表单渲染
• form-set-default-builder - 将自定义 builder 设为应用的默认 builder
• form-error-display - 使用统一的标记在字段旁显示错误
• form-accessible-labels - 自动生成无障碍标签和 ARIA 属性
• form-group-wrapper - 使用统一的分组元素包裹标签、输入框和错误信息
• form-button-consistency - 通过表单 builder 统一提交按钮

7. Helper 模式（中优先级）

• helper-tag-helpers - 使用 tag helper 生成简短的 HTML 片段
• helper-conditional-classes - 使用 class_names 设置条件 CSS 类
• helper-icon-helper - 创建 icon helper，以统一图标渲染
• helper-badge-pattern - 构建 badge helper，用于显示状态指示
• helper-scope-to-domain - 将 helper 限定在特定领域，而非用作通用工具

8. Stimulus 行为（中）

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

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

• org-naming-conventions - 在 partial、组件和辅助方法中遵循一致的命名规范
• org-file-structure - 将设计系统文件组织在易于预测的位置
• org-deduplication-audit - 定期检查视图中是否存在重复模式
• org-import-maps - 使用 Import Maps 实现无需构建的 JavaScript 分发
• org-preview-with-lookbook - 在开发过程中使用 Lookbook 预览组件
• org-document-design-decisions - 在 ADR 中记录设计系统决策

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

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