Design System

Relevant source files

The following files were used as context for generating this wiki page:

• packages/frontend/@n8n/design-system/package.json
• packages/frontend/@n8n/design-system/README.md
• packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/components/SimplifiedEmptyLayout.vue
• packages/frontend/editor-ui/src/constants.ts
• packages/frontend/@n8n/chat/src/css/markdown.scss
• CLAUDE.md
• CONTRIBUTING.md

The @n8n/design-system is a dedicated Vue 3 component library within the n8n monorepo. Its primary purpose is to centralize reusable UI components and design tokens, ensuring a consistent and coherent user experience across the entire n8n platform. This package is a key part of the frontend architecture, providing the building blocks for the main editor-ui application and other frontend packages.

The system is developed and visualized using Storybook, allowing for isolated component development and testing. It leverages technologies like Vite for building, Tailwind CSS for styling, and Vitest for unit testing. By encapsulating UI logic and styling, the design system promotes code reusability, accelerates development, and maintains visual consistency.

Sources: CLAUDE.md:65-67, packages/frontend/@n8n/design-system/README.md:3-5, packages/frontend/@n8n/design-system/package.json

Architecture and Tooling

The @n8n/design-system package is an integral part of the n8n monorepo, which is managed by pnpm workspaces. This setup allows it to be a dependency for other frontend packages like editor-ui.

Sources: CLAUDE.md:12-14, CONTRIBUTING.md:23-24

Build and Development Workflow

The development and build process for the design system is managed through a series of pnpm scripts defined in its package.json.

This diagram shows the main development and build commands for the design system package.

Key scripts include:

Script	Description
dev	Alias for storybook. Starts the Storybook development server.
build	Compiles the components using Vite for production use.
storybook	Runs Storybook in development mode on port 6006 for component preview.
build:storybook	Creates a static build of the Storybook site.
test	Executes unit tests with Vitest.
lint	Lints the source code using ESLint.
lint:styles	Lints CSS/SCSS files using Stylelint.
typecheck	Runs TypeScript type checking using vue-tsc.

Sources: packages/frontend/@n8n/design-system/package.json:6-18, packages/frontend/@n8n/design-system/README.md:9-31

Core Dependencies

The design system is built upon a modern frontend stack:

• Vue 3: The core JavaScript framework for building components.
• Vite: The build tool used for development and production builds.
• TypeScript: For static typing and improved code quality.
• Tailwind CSS: A utility-first CSS framework for styling.
• Storybook: For developing and documenting components in isolation.
• Vitest: The testing framework for unit tests.
• Sass: For advanced CSS capabilities.

Sources: packages/frontend/@n8n/design-system/package.json:20-59, CLAUDE.md:58

Component Usage

The design system exports a suite of Vue components that are consumed by other applications within the n8n ecosystem, most notably editor-ui.

Example: Component Import and Usage

The following example from SimplifiedEmptyLayout.vue demonstrates how components from the design system are imported and used to build a UI view.

// packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/components/SimplifiedEmptyLayout.vue
<script setup lang="ts">
import { N8nCard, N8nHeading, N8nText, N8nIcon } from '@n8n/design-system';
// ...
</script>

<template>
	<div :class="$style.simplifiedLayout">
		<div :class="$style.content">
			<div :class="$style.welcome">
				<N8nHeading tag="h1" size="2xlarge" :class="$style.welcomeTitle">
					<!-- ... -->
				</N8nHeading>
				<N8nText size="large" color="text-base" :class="$style.welcomeDescription">
					<!-- ... -->
				</N8nText>
			</div>

			<div :class="$style.actionsContainer">
				<N8nCard
					v-if="showReadyToRunV2Card"
					:class="$style.actionCard"
					hoverable
					@click="handleReadyToRunV2Click"
				>
					<div :class="$style.cardContent">
						<N8nIcon
							:class="$style.cardIcon"
							icon="sparkles"
							color="foreground-dark"
							:stroke-width="1.5"
						/>
						<N8nText size="large" class="mt-xs">
							{{ i18n.baseText('workflows.empty.readyToRunV2') }}
						</N8nText>
					</div>
				</N8nCard>
            </div>
        </div>
    </div>
</template>

This demonstrates the modularity of the design system, where atomic components like N8nHeading, N8nText, N8nIcon, and N8nCard are composed to create more complex layouts.

Sources: packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/components/SimplifiedEmptyLayout.vue:3,19-54

Styling and Theming

Styling is a core responsibility of the design system, managed primarily through SCSS and Tailwind CSS.

Markdown Styling

The design system provides a comprehensive set of styles for rendering Markdown content, ensuring it appears consistently throughout the application (e.g., in chat messages or sticky notes). These styles are defined in markdown.scss and cover everything from headers and lists to code blocks and blockquotes.

The styles are applied via the .chat-message-markdown class.

This diagram shows how different HTML elements are styled within the markdown context.

Key styling rules include:

• Headings (h1-h6): Defined with a modular scale for font sizes.
• Blockquotes: Styled with a left border using the --theme CSS variable.
• Code (code, pre): Uses a monospace font family and has specific styles for inline and block-level code. It also loads themes for highlight.js for syntax highlighting, including a dark theme variant.
• Lists (ul, ol): Standardized padding and margins.

Sources: packages/frontend/@n8n/chat/src/css/markdown.scss:5-316

Tailwind CSS Configuration

While the tailwind.config.js file is not directly provided in the context, its presence is indicated by the tailwindcss dependency in package.json. A standard Tailwind configuration file defines the project's design tokens, such as color palettes, font families, spacing units, and breakpoints. This allows developers to use utility classes (e.g., mt-xs, text-large) that map to predefined design values, ensuring consistency.

Sources: packages/frontend/@n8n/design-system/package.json:30

Iconography

The design system includes an N8nIcon component, which is used to render SVG icons consistently. The available icons are defined as a set of IconName types. Other parts of the application, like editor-ui, consume these icons by referencing their names.

A mapping in constants.ts shows how specific data types are associated with icons from the design system.

Data Type	Icon Name
string	type
number	hash
boolean	square-check
date	calendar
array	list
object	box
file	file

This demonstrates a clear link between application logic (data types) and the visual representation provided by the design system.

Sources: packages/frontend/editor-ui/src/constants.ts:404-413, packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/components/SimplifiedEmptyLayout.vue:42-47

Summary

The @n8n/design-system package is a critical piece of the n8n frontend infrastructure. It provides a centralized, version-controlled library of reusable Vue components, styling rules, and design tokens. By leveraging tools like Storybook and Tailwind CSS, it enables efficient development and ensures a consistent, high-quality user interface across the n8n platform. Its modular nature allows it to be easily consumed by other packages, promoting a clean separation of concerns between UI presentation and application logic.

Sources: CLAUDE.md:65-67, packages/frontend/@n8n/design-system/README.md