n8n:ui-design

UI 设计

关于在前端构建、设置样式和使用组件的全面指南。

参考资料

• 为组件设置样式时，请使用 packages/frontend/@n8n/design-system/src/styleguide/*.mdx
• 对于动画，请使用 rules/web-animation-guidelines.md
• 审查 UI 更改时，请使用 rules/web-interface-guidelines.md

最佳实践

• 始终使用 packages/frontend/@n8n/design-system/src/css/ 中 _tokens.scss 或 _primitives.scss 定义的 CSS 变量。在将长度、颜色、字体大小和时长写为字面值之前，先查找对应值。每个间距 token 都会在注释中标明对应的 px 值：--spacing--5xs: 0.125rem; /** 2px **/。使用 grep 搜索该注释，以查找对应 px 值的 token。每个 token 系列都会匹配一项，因此请根据属性选择对应系列：margin 和 padding 使用 --spacing--*，border-radius 使用 --radius--*，height 使用 --height--*。样式指南 packages/frontend/@n8n/design-system/src/styleguide/spacing-size.mdx 以表格形式列出了相同的比例。间距比例从 2px 起，因此数值较小并不是硬编码的理由。只有在查找不到对应 token 时才硬编码，并在注释中说明原因。
• 始终优先使用 packages/frontend/@n8n/design-system/src/components 中已有的组件。优先选择未标记为 @deprecated 的组件。
• 如果需要为纯色组件添加 hover/active 透明度行为，优先使用带明确百分比的 color-mix()。
• 使用动画或过渡效果时，始终优先使用 packages/frontend/@n8n/design-system/src/css/mixins/motion.scss 中的 mixin。

组件

优先使用现有的 design-system 组件，而不是自行实现：

• “添加一个用于确认删除工作流的模态对话框” → 使用 N8nDialog
• “添加一个下拉菜单以选择工作流状态” → 使用 N8nDropdown 或 N8nSelect
• “添加一个带 + 图标、用于添加新项的按钮” → 使用带 iconOnly prop 的 N8nButton，并用 N8nTooltip 包装。使用 N8nIcon 和恰当的 aria-label。
• “添加一个破坏性操作按钮” → 使用 variant="destructive" 的 N8nButton
• “将背景颜色设为白色/黑色” → 浅色模式下使用 var(--background--surface) 表示白色，深色模式下使用 "black"
• “优雅地淡入标题” → 使用 motion.scss 中的 fade-in-up mixin，并设置 var(--duration--base)