Vue 3 Frontend & Design System
Relevant source files
The following files were used as context for generating this wiki page:
- packages/frontend/@n8n/design-system/README.md
- packages/frontend/@n8n/design-system/AGENTS.md
- packages/frontend/@n8n/design-system/package.json
- packages/frontend/@n8n/design-system/src/components/N8nMarkdownEditor/component-markdown-editor.md
- packages/frontend/@n8n/design-system/src/components/N8nSettingsPageHeader/SettingsPageHeader.vue
- packages/@n8n/stylelint-config/README.md
- AGENTS.md
- CONTRIBUTING.md
The n8n frontend architecture utilizes Vue 3, Vite, and Pinia within a monorepo structure. The core of the user interface resides in @n8n/design-system, a centralized component library that ensures visual consistency across the application. This system provides reusable components, design tokens, icons, and specialized directives.
Sources: packages/frontend/@n8n/design-system/README.md, AGENTS.md:144-150
Architecture Overview
The frontend is split into two primary modules:
packages/frontend/editor-ui: The main Vue application for the workflow editor.packages/frontend/@n8n/design-system: The reusable component library.
The application uses Vite for building and Pinia for state management. Storybook serves as the development environment for components, while Vitest and Playwright handle unit and E2E testing respectively.
Sources: AGENTS.md:144-150, CONTRIBUTING.md:23-28
Dependency and Integration Flow
The following diagram illustrates how a consumer application integrates the design system:
The N8nPlugin is mandatory for components like N8nNotice and N8nTooltip as they render text via the v-n8n-html directive.
Sources: packages/frontend/@n8n/design-system/README.md:50-85
Design System Tokens and Styling
n8n enforces a strict CSS variable naming convention to maintain a structured design vocabulary. Styles are authored in SCSS and compiled into tokens.
CSS Variable Naming Convention
Variables follow a specific hierarchical pattern:
--[namespace--][component[--part]--]property--value[--variant][--state][--mode][--media]
Sources: packages/@n8n/stylelint-config/README.md:31-45
| Required Group | Description | Examples |
|---|---|---|
property | The CSS property mapping | color, spacing, radius, shadow |
value | Semantic name or scale value | primary, md, neutral-850, pill |
Sources: packages/@n8n/stylelint-config/README.md:95-125
Style Exports
The package exports multiple entry points for styles:
style.css: Contains compiled component styles.theme.css: Contains design tokens, CSS reset, and element-plus overrides.css/*: SCSS sources including mixins (e.g., breakpoints) and token maps for custom toolchains.
Sources: packages/frontend/@n8n/design-system/README.md:120-130
Component Development Standards
Developers must follow specific rules when contributing to @n8n/design-system:
- Generic Components: Components must be reusable across multiple product areas.
- Mandatory Assets: Every new component requires a
.test.tsfile and a Storybook story. - Documentation: All public interfaces must include JSDoc comments.
- Internationalization: All user-facing strings must use i18n translations via the
@n8n/i18npackage.
Sources: packages/frontend/@n8n/design-system/AGENTS.md:3-12, packages/frontend/@n8n/design-system/README.md:175-180
Storybook Organization
Stories are categorized to maintain a clear hierarchy:
Style Guide: Tokens and utilities.Core: Universal components.Areas/<Product area>: Context-specific patterns (e.g.,Areas/Settings).Experimental: Beta features.
Sources: packages/frontend/@n8n/design-system/AGENTS.md:14-22
Rich Text and Markdown Editing
The system includes advanced components for Markdown handling, specifically N8nMarkdownEditor, built on TipTap Vue 3.
N8nMarkdownEditor Configuration
The editor supports GitHub-Flavored Markdown (GFM) and manages extensions internally to ensure consistency.
Feature Support
- Variants:
ghost(minimal affordance) andcontained(input-like styling). - Toolbar: Design-system owned controls for bold, italic, links, lists, and code blocks.
- Sanitization: All Markdown output is sanitized to prevent XSS, especially when using
v-n8n-html.
Sources: packages/frontend/@n8n/design-system/src/components/N8nMarkdownEditor/component-markdown-editor.md:25-35, packages/frontend/@n8n/design-system/README.md:65-75
Development and Build Scripts
The design system uses vite for building and pnpm for workspace management.
| Task | Command | Description |
|---|---|---|
| Development | pnpm dev | Starts Storybook on port 6006 |
| Build | pnpm build | Builds the dist folder via Vite |
| Typecheck | pnpm typecheck | Runs vue-tsc on the source code |
| Test | pnpm test | Executes unit tests via Vitest |
| Lint | pnpm lint | Lints TS and Vue files; lint:styles lints SCSS |
Sources: packages/frontend/@n8n/design-system/README.md:135-150, packages/frontend/@n8n/design-system/package.json:30-45
Summary
The Vue 3 Frontend & Design System provides a robust, token-driven architecture for the n8n interface. By centralizing UI logic in @n8n/design-system and enforcing strict naming conventions and development guidelines, the project ensures high code quality, accessibility through i18n, and visual consistency across all workflow editing and settings modules.
Sources: packages/frontend/@n8n/design-system/README.md, AGENTS.md:144-150