name: rails-design-system description: Ruby on Rails 设计系统指南，用于以最小抽象构建一致、可维护的UI。此技能应在创建或重构Rails视图、部分、组件、表单构建器、辅助器、Stimulus控制器、Turbo帧、Turbo流或设计令牌时使用。触发任务包括ERB部分、Turbo导航、Turbo流、ViewComponent、Phlex、Tailwind设计令牌、自定义表单构建器、视图辅助器、Stimulus行为、Import Maps、Lookbook预览或设计系统一致性审计。

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

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

何时应用

参考这些指南当：

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

规则类别按优先级

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

快速参考

1. 设计决策（关键）

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. 设计令牌（关键）

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帧以进行目标更新
turbo-frame-naming - 使用dom_id约定命名Turbo帧
turbo-frame-vs-stream - 根据更改范围选择Turbo帧 vs Turbo流
turbo-stream-crud - 使用Turbo流进行多元素页面更新
turbo-stimulus-coordination - 协调Turbo和Stimulus而不冲突

4. 部分模式（高）

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

5. 组件架构（高）

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

6. 表单系统（中高）

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

7. 辅助器模式（中）

helper-tag-helpers - 使用标签辅助器用于小生成HTML片段
helper-conditional-classes - 使用class_names用于条件CSS类
helper-icon-helper - 创建图标辅助器用于一致图标渲染
helper-badge-pattern - 构建徽章辅助器用于状态指示器
helper-scope-to-domain - 将辅助器范围限定到特定域，而非通用实用程序

8. Stimulus行为（中）

stim-general-purpose - 编写通用控制器，而非一次性脚本
stim-data-attribute-config - 通过数据属性配置行为，而非JavaScript
stim-small-controllers - 保持控制器小且单一职责
stim-composable-controllers - 在一个元素上组合多个控制器
stim-use-outlets - 使用出口用于跨控制器通信
stim-leverage-library - 在编写自定义控制器前使用stimulus-components

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

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

如何使用

阅读单个参考文件以获取详细解释和代码示例：

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

参考文件

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