Design System
Relevant source files
The following files were used as context for generating this wiki page:
The @n8n/design-system package provides a reusable library of Vue 3 components, design tokens, icons, and directives for n8n. It centralizes UI logic to ensure consistency across different areas of the application, such as the workflow editor and settings.
Sources: packages/frontend/@n8n/design-system/README.md:5-7, AGENTS.md:154-156
Core Architecture
The design system operates as a workspace package within a monorepo. It exports compiled CSS, design tokens, and Vue components. The library relies on vue and vue-router as peer dependencies.
Integration Flow
The following diagram illustrates how an application consumes the design system.
To initialize the system, an application must import style.css and theme.css and register the N8nPlugin. This plugin enables critical directives like v-n8n-html, which multiple components use to render text.
Sources: packages/frontend/@n8n/design-system/README.md:15-18, packages/frontend/@n8n/design-system/README.md:55-68
Design Tokens and CSS Variables
The system enforces a strict CSS variable naming convention through @n8n/stylelint-config. This ensures that tokens follow a predictable hierarchy.
Naming Convention Pattern
--[namespace--][component[--part]--]property--value[--variant][--state][--mode][--media]
Token Vocabulary
| Property | CSS Mapping | Description |
|---|---|---|
color | color | Standard text or element color |
background | background-color | Background colors |
spacing | margin/padding | Spacing scale (sm, md, lg, etc.) |
radius | border-radius | Border radius values |
z | z-index | Layering depth |
Sources: packages/@n8n/stylelint-config/README.md:38-42, packages/@n8n/stylelint-config/README.md:89-105
Component Development
All components in the design system are generic and reusable. Developers must follow specific rules when building or refactoring components.
Development Requirements
- Stories: Every new component must have a Storybook story in
packages/frontend/@n8n/design-system. - Testing: Each component must include a
.test.tsfile. - Documentation: Public interfaces must contain comments explaining the purpose of each prop or method.
- I18n: Components must use internationalization for user-facing strings and accessible labels.
Sources: packages/frontend/@n8n/design-system/AGENTS.md:5-13, packages/frontend/@n8n/design-system/README.md:104-106
Storybook Organization
Stories are categorized into four main areas:
- Style Guide: Styles, tokens, and utilities.
- Core: Components used globally.
- Areas/: Patterns for specific features (e.g.,
Areas/Settings). - Experimental: Beta components.
Sources: packages/frontend/@n8n/design-system/AGENTS.md:17-23
Export Structure
The package provides several subpaths for consuming specific assets.
| Subpath | Contents |
|---|---|
@n8n/design-system | The main barrel containing components and exported types. |
@n8n/design-system/plugin | The N8nPlugin for directive registration. |
@n8n/design-system/icons/lucide | Icon body loaders for Lucide icons. |
@n8n/design-system/style.css | Compiled component-specific styles. |
@n8n/design-system/theme.css | Design tokens, CSS reset, and font-face rules. |
Sources: packages/frontend/@n8n/design-system/README.md:86-94
Contribution Guidelines
The Design System is maintained by the @n8n/design team. When contributing:
- Use the
n8n:ui-designskill for building or refactoring. - Use
n8n:content-designfor copy and wording. - Ensure components are generic and do not contain business logic specific to one product area.
- Provide a component specification using the
COMPONENT_API_SPEC_TEMPLATE.mdfor review before implementation.
Sources: packages/frontend/@n8n/design-system/AGENTS.md:5-11, packages/frontend/@n8n/design-system/README.md:104-109, AGENTS.md:139-141