Design System

Comprehensive guide for building, styling, and using components in the frontend.

When to Apply

Reference these guidelines when:

• Working on .{vue|css|scss} files in packages/frontend
• Adding new components to packages/frontend/@n8n/design-system
• Refactoring styles for Vue components
• Implementing new UI components or features
• Reviewing changes to UI

Rules

• Follow guidelines in packages/frontend/@n8n/design-system/src/styleguide/*.mdx
• ALWAYS use CSS variables for styles from packages/frontend/@n8n/design-system/src/css/_tokens.scss or packages/frontend/@n8n/design-system/src/css/_primitives.scss. Use hard-coded values only when no suitable tokens.
• ALWAYS prefer using existing components from packages/frontend/@n8n/design-system/src/components. Prefer components that aren't marked @deprecated.
• Use light-dark() when alternating colors for ligh/dark mode
• If you need to add hover/active alpha behavior to solid components, prefer color-mix() with explicit percentages.
• When working with animations or transitions, ALWAYS prefer using mixins from packages/frontend/@n8n/design-system/src/css/mixins/motion.scss
• When reviewing animations, follow the guides in rules/web-animation-guidelines.md
• When reviewing UI changes or adding new components, follow rules/web-interface-guidelines.md

Storybook Stories

• ALWAYS add new stories to packages/frontend/@n8n/design-system.
• Every story must use one of these title categories:
  • Style Guide: styles, tokens, and utilities
  • Core: components used across the app
  • Areas/<Product area>: patterns and components for a specific product area, for example Areas/Settings or Areas/Assistant
  • Experimental: beta components that require caution
• The last title segment is the component name and MUST be PascalCase (Core/EmptyState, not Core/empty-state). Category prefixes are unrestricted.

Examples

• "Add a modal dialog for confirming workflow deletion" → Use N8nDialog
• "Add a dropdown to select workflow status" → Use N8nDropdown or N8nSelect
• "Add button with + icon to add new tiem" → Wrap N8nButton with iconOnly prop with N8nTooltip and wrap in N8nTooltip. Use N8nIcon and proper aria-label.
• "Add a destructive action button" → use N8nButton with variant="destructive"
• "Make background color white/black" → Use var(--background--surface) for white on light mode and "black" on dark mode
• "Animate the title in gracefully" -> Use fade-in-up mixin from motion.scss with var(--duration--base)