Design System (@n8n/design-system)
Relevant source files
The following files were used as context for generating this wiki page:
The @n8n/design-system is a centralized Vue 3 component library and design token repository used to ensure UI consistency and reusability across the n8n monorepo. It serves as the primary location for all pure Vue components, separating reusable UI logic from application-specific logic in editor-ui.
Sources: AGENTS.md:120-123, CONTRIBUTING.md:46-47
The system employs a token-based styling architecture, moving away from hardcoded values and legacy styles in favor of semantic and primitive tokens. This architecture supports high-level design consistency, easier theming, and automated enforcement of naming conventions through Stylelint.
Sources: packages/frontend/AGENTS.md:8-10, packages/@n8n/stylelint-config/README.md:5-10
Architecture and Core Principles
The design system is structured to be independent of the main application, facilitating hot reloading across the stack during development. It leverages a modern frontend stack including Vue 3, TypeScript, and Vite.
Sources: AGENTS.md:104-106, AGENTS.md:120-123
Dependency Hierarchy
The design system sits between the low-level CSS/SCSS primitives and the higher-level application modules.
The diagram shows how tokens inform the Design System, which is then consumed by frontend applications, while Stylelint enforces naming conventions across all packages.
Sources: packages/frontend/AGENTS.md:8-12, CONTRIBUTING.md:46-49, packages/@n8n/stylelint-config/README.md:12-18
Design Tokens and Styling
n8n utilizes a structured CSS variable naming convention to manage design properties. This is enforced by @n8n/stylelint-config using the @n8n/css-var-naming rule.
Sources: packages/@n8n/stylelint-config/README.md:46-48
Naming Convention Structure
Tokens must follow a canonical order with double dashes (--) between groups and single dashes (-) within groups:
--[namespace--][component[--part]--]property--value[--variant][--state][--mode][--media]
Sources: packages/@n8n/stylelint-config/README.md:52-54
Property Vocabulary
The system recognizes a specific set of properties mapped to CSS behaviors:
| Property | CSS Mapping | Description |
|---|---|---|
color | color | Text/element color |
background | background-color | Background color |
spacing | margin/padding | Spacing scale |
radius | border-radius | Border radius |
z | z-index | Z-index |
| Sources: packages/@n8n/stylelint-config/README.md:103-120 |
Token Usage Guidelines
- Prefer Semantic Tokens: Use tokens from
_tokens.scssor_primitives.scss. - Avoid Legacy: Do not use
_tokens.legacy.scss. - No Hardcoding: Never hardcode spacing as
pxvalues; use CSS variables directly.
Sources: packages/frontend/AGENTS.md:8-12, packages/frontend/AGENTS.md:20
Component Specification: N8nMarkdownEditor
A primary example of a complex component within the system is N8nMarkdownEditor, built on TipTap Vue 3. It provides block-style rich text editing with Markdown string input/output.
Sources: packages/frontend/@n8n/design-system/src/components/N8nMarkdownEditor/component-markdown-editor.md:3-8
Features and Extensions
The editor manages extensions centrally rather than requiring callsites to assemble them.
The diagram illustrates how the component centralizes extension management while providing an escape hatch for specific needs.
Sources: packages/frontend/@n8n/design-system/src/components/N8nMarkdownEditor/component-markdown-editor.md:50-65
Public API (Props)
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | string | '' | Bound Markdown value |
variant | 'ghost' | 'contained' | 'contained' | Visual style variant |
showToolbar | 'never' | 'hover' | 'always' | 'always' | Controls toolbar visibility |
| Sources: packages/frontend/@n8n/design-system/src/components/N8nMarkdownEditor/component-markdown-editor.md:23-32 |
Development and Quality Assurance
Style Enforcement
Stylelint rules are integrated into the CI/CD pipeline and pre-commit hooks (via lefthook). The cubic.yaml configuration specifically instructs AI reviewers to follow design system style rules for hardcoded visual values or legacy token usage.
Sources: cubic.yaml:31-41, packages/@n8n/stylelint-config/README.md:179-185
Development Workflow
Developers working on the design system should:
- Run
pnpm dev:fefrom the root orpnpm devwithin@n8n/design-systemto start the development server. - Follow guides in
src/styleguide/*.mdx. - Use the
n8n:design-systemskill during reviews to ensure compliance.
Sources: packages/frontend/AGENTS.md:4-7, CONTRIBUTING.md:154-156
Summary
The Design System is the cornerstone of n8n's frontend architecture, centralizing UI components and enforcing a strict, token-based styling methodology. By decoupling UI components from application logic and using automated linting for CSS variable naming, the system ensures high maintainability and visual coherence across the platform's various packages.
Sources: AGENTS.md:120-123, packages/@n8n/stylelint-config/README.md:10-18