@n8n/design-system 2.19.0 → 2.20.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@n8n/design-system",
-  "version": "2.19.0",
+  "version": "2.20.1",
   "main": "src/index.ts",
   "import": "src/index.ts",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/index.ts

@@ -20,7 +20,7 @@ export { default as N8nInputNumber2 } from './v2/components/InputNumber/InputNum
 export type * from './v2/components/InputNumber/InputNumber.types';
 export { default as N8nDropdownMenu } from './v2/components/DropdownMenu/DropdownMenu.vue';
 export type * from './v2/components/DropdownMenu/DropdownMenu.types';
-export { default as N8nSwitch2 } from './v2/components/Switch/Switch.vue';
-export type * from './v2/components/Switch/Switch.types';
+export { default as N8nSwitch2 } from './components/N8nSwitch/Switch.vue';
+export type * from './components/N8nSwitch/Switch.types';
 export { createPasswordRules } from './components/N8nFormInput/validators';
 export { locale };

package/src/styleguide/colour.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+import PrimitivesColorTable from './components/PrimitivesColorTable.vue';
+
+<Meta title="Styleguide/Colour" />
+
+# Colour
+
+We have a vast, beautiful color palette out of the box. Prefer using these rather than custom colours (e.g #ff0000). These are similar to Tailwind CSS.
+
+Each colour has 13 steps ranging from lightest (50) to darkest (950).
+
+<div class="sb-unstyled">
+	<PrimitivesColorTable />
+</div>
+
+## Tokens
+
+Instead of using the raw primitive colours, it's often better to use a token. These are aliases for common use cases (e.g text color) to make it easier to keep UI consistent and flexible.
+
+### Text
+
+| Token                   | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| `--text-color`          | Default body text and primary labels.           |
+| `--text-color--subtle`  | Secondary text such as helper copy or metadata. |
+| `--text-color--subtler` | Tertiary or low-emphasis text.                  |
+| `--text-color--inverse` | Text shown on dark or inverse surfaces.         |
+
+### Background
+
+| Token                   | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `--background--surface` | Base surface for cards, panels, and page sections.     |
+| `--background--hover`   | Hover state for neutral interactive surfaces.          |
+| `--background--active`  | Pressed/active state for neutral interactive surfaces. |
+| `--background--success` | Success banners, badges, or confirmation surfaces.     |
+| `--background--warning` | Warning callouts and cautionary surfaces.              |
+| `--background--danger`  | Danger/error surfaces behind destructive messaging.    |
+| `--background--info`    | Informational surfaces and neutral notices.            |
+
+### Border
+
+| Token                     | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `--border-color`          | Default border for inputs, cards, and separators. |
+| `--border-color--subtle`  | Low-contrast dividers and lightweight outlines.   |
+| `--border-color--strong`  | More prominent outlines for elevated contrast.    |
+| `--border-color--success` | Borders for success states and confirmations.     |
+| `--border-color--warning` | Borders for warning states and cautions.          |
+| `--border-color--danger`  | Borders for error states and destructive actions. |
+| `--border-color--info`    | Borders for informational states.                 |

package/src/styleguide/css-tokens.mdx

@@ -0,0 +1,97 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Styleguide/CSS Tokens" />
+
+# CSS Tokens
+
+Our CSS variables are layered so we can keep the design system consistent and themeable.
+
+## Token layers
+
+There are two main token layers
+
+1. Primitives (`@n8n/design-system/src/css/_primitives.scss`)
+2. Semantic Tokens (`@n8n/design-system/src/css/_tokens.scss`)
+
+### Primitives
+
+Raw design decisions: color scales, spacing, typography, radius, heights, durations, easing, and shadows.
+
+```scss
+--color--orange-500: oklch(...);
+--spacing--sm: 1rem;
+--font-size--md: 1rem;
+--shadow--md: 0 10px 15px -3px var(--shadow-color), 0 4px 6px -4px var(--shadow-color);
+```
+
+### Semantic theme tokens
+
+Contextual tokens used by components (`--text-color`, `--background--surface`, `--border-color--success`, etc.).
+These map to primitives (directly or through compatibility aliases), and have light/dark definitions via `@mixin theme` and `@mixin theme-dark`.
+
+## How to choose tokens
+
+- Use semantic tokens first in component styles (for example `--text-color`, `--background--surface`, `--icon-color`).
+- Use primitives when you need a low-level scale value (for example spacing, radius, or a specific color step).
+- Add new semantic tokens in `src/css/_tokens.scss` when the value is reused by multiple components or represents a shared UI meaning.
+- Add new primitive tokens in `src/css/_primitives.scss` only for new base scales.
+
+## Naming rules
+
+Naming is validated by `@n8n/css-var-naming` in `packages/@n8n/stylelint-config/src/rules/css-var-naming.ts` for files in `@n8n/design-system/src/css`.
+
+### Required format
+
+- Use groups separated by double dashes: `--group--group`.
+- Use lowercase alphanumerics; single dashes are allowed only within a group.
+- Keep values after properties (for example `--color--primary`, not `--primary--color`).
+
+```scss
+/* valid */
+--background--surface
+--button--color--background--primary--hover
+--font-weight--regular
+
+/* invalid */
+--background-surface
+--Primary--color
+--primary--color
+```
+
+### Property vocabulary
+
+Variable names must include a recognized property group such as `color`, `background`, `text-color`, `border-color`, `spacing`, `radius`, `shadow`, `font-size`, `font-weight`, `duration`, or `easing`.
+
+### Allowed exceptions
+
+- `--n8n--*` prefix bypasses validation for local/internal helper variables.
+- Namespaces `--reka--*`, `--ag--*`, and `--chat--*` are ignored for third-party interoperability.
+- Single-group variables are only allowed for specific standalone properties (for example `--border`, `--radius`, `--shadow`, `--font-family`).
+
+## Migration pattern (single-dash to double-dash)
+
+When replacing older tokens, preserve compatibility by chaining fallbacks:
+
+```scss
+--color--secondary: var(--color-secondary, var(--color--purple-600));
+```
+
+This gives us:
+
+- New naming for design system code.
+- Existing overrides for embed/custom CSS users.
+- Safe, incremental migration without breaking consumers.
+
+## Practical guidance for contributors
+
+- Prefer updating existing semantic tokens before introducing new one-off variables.
+- If you must add a temporary exception, scope it tightly with `/* stylelint-disable @n8n/css-var-naming */` and re-enable immediately.
+- Avoid hardcoded color hex values in component styles when an existing token can express the same intent.
+
+---
+
+<small>
+	Compatibility note: `src/css/_tokens.legacy.scss` contains non-semantic compatibility aliases used
+	during migration to the double-dash naming format. Keep new work on primitives + semantic tokens
+	in `src/css/_primitives.scss` and `src/css/_tokens.scss`.
+</small>

package/src/styleguide/motion.mdx

@@ -0,0 +1,104 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import MotionExamples from './components/MotionExamples.vue';
+
+<Meta title="Styleguide/Motion" />
+
+# Motion
+
+Motion should make n8n feel responsive, understandable, and calm. Use animation to explain
+state changes, guide attention, or show progress. Avoid motion that is decorative, slow,
+distracting, or repeated so often that it gets in the way.
+
+Motion utilities live in `@n8n/design-system/src/css/mixins/motion.scss`.
+
+## Principles
+
+- **Keep motion purposeful**: Use motion when it helps users understand what has changed (e.g loading states, enter/existing surfaces). Don't add motion for the sake of it.
+- **Prefer subtle movement**: Most motion should be short and low-distance. Small transitions, such as opacity and translations, are enough. Don't animate rapid frequently interactions (e.g hover states)
+- **Prefer non re-painting values**: Opacity and transform are the safest animation properties for performance. Use caution with layout and paint properties like height, width, box-shadow, background-color, and filter. When using those properties, add `will-change`.
+- **Always aim for +60fps**: Motion should feel smooth and responsive. If an animation causes jank or lag, simplify the animation or use a more performant approach.
+- **Respect reduced motion**: Always provide a non-animated fallback for users who prefer reduced motion. Motion mixins should handle `prefers-reduced-motion` internally so that consumers can use them without repeating media queries.
+- **Easing**: Use easing to make motion feel more natural. Avoid linear easing for UI interactions, as it can feel mechanical and less responsive. Instead, use `ease-out` for entrances and exits, and `ease-in-out` for movements of already visible elements. Avoid `ease-in` for most UI animations, as it can delay feedback and make the interface feel sluggish.
+
+## Available Mixins
+
+| Mixin                           | Use for                             | Notes                                                      |
+| ------------------------------- | ----------------------------------- | ---------------------------------------------------------- |
+| `motion.spin`                   | Loading indicators                  | Continuous rotation.                                       |
+| `motion.skeleton-pulse`         | Skeleton loading placeholders       | Use for placeholder surfaces, not interactive elements.    |
+| `motion.shimmer`                | Text or inline loading states       | Best for short-lived AI or thinking states.                |
+| `motion.popover-in`             | Dropdowns, menus, floating surfaces | Uses opacity, translate, and scale.                        |
+| `motion.collapsible-slide-down` | Opening collapsible content         | Animates height. Use only when height animation is needed. |
+| `motion.collapsible-slide-up`   | Closing collapsible content         | Animates height. Use only when height animation is needed. |
+| `motion.fade-in`                | Simple entrance                     | Prefer for subtle one-off reveals.                         |
+| `motion.fade-in-up`             | Entrance from below                 | Use for vertical reveal patterns.                          |
+| `motion.fade-in-down`           | Entrance from above                 | Use when the element visually comes from above.            |
+| `motion.fade-in-left`           | Entrance from left                  | Use for horizontal directional context.                    |
+| `motion.fade-in-right`          | Entrance from right                 | Use for horizontal directional context.                    |
+| `motion.fade-out`               | Simple exit                         | Use for removal without spatial movement.                  |
+| `motion.fade-out-down`          | Exit downward                       | Pair with matching entrance direction when possible.       |
+| `motion.fade-out-up`            | Exit upward                         | Pair with matching entrance direction when possible.       |
+| `motion.fade-out-left`          | Exit left                           | Pair with matching entrance direction when possible.       |
+| `motion.fade-out-right`         | Exit right                          | Pair with matching entrance direction when possible.       |
+| `motion.blink-background`       | Cursor-like attention states        | Avoid for large areas or frequent UI.                      |
+| `motion.typing-blink`           | Typing indicators                   | Use for small repeated indicators only.                    |
+| `motion.pulse-glow`             | Rare emphasis or loading pulse      | Animates `box-shadow`; use sparingly.                      |
+| `motion.pulse-glow-delayed`     | Secondary delayed pulse             | Only use with `pulse-glow`.                                |
+| `motion.width-transition`       | Width changes                       | Layout-affecting. Use cautiously.                          |
+| `motion.height-transition`      | Height changes                      | Layout-affecting. Use cautiously.                          |
+
+## Using Mixins
+
+Motion mixins expose CSS variables for local customization. Prefer local overrides over
+creating new keyframes.
+
+```scss
+.dropdown {
+	--animation--popover-in--duration: var(--duration--snappy);
+	--animation--popover-in--translate-y: var(--spacing--4xs);
+
+	@include motion.popover-in;
+}
+```
+
+## Examples
+
+<MotionExamples />
+
+## Adding New Mixins
+
+Before adding a new mixin, check whether an existing mixin can be customized with CSS
+variables.
+
+Add a new mixin only when:
+
+- The motion pattern is reused by multiple components.
+- The animation has a clear product purpose.
+- The behavior cannot be expressed cleanly with existing mixins.
+- The mixin includes reduced-motion handling.
+- The mixin uses design-system duration and easing tokens.
+
+New mixins should follow this shape:
+
+```scss
+@mixin example-motion {
+	animation: exampleMotion var(--animation--example-motion--duration, var(--duration--snappy))
+		var(--animation--example-motion--easing, var(--easing--ease-out));
+
+	@media (prefers-reduced-motion: reduce) {
+		animation: none;
+	}
+}
+
+@keyframes exampleMotion {
+	from {
+		opacity: 0;
+		transform: translateY(var(--animation--example-motion--translate, var(--spacing--4xs)));
+	}
+
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+```

package/src/styleguide/shadow.mdx

@@ -0,0 +1,96 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Styleguide/Shadow" />
+
+# Shadows
+
+Create depth and elevation for UI elements
+
+Shadows can be applied using the `shadow-*` primitive. Variants range from `xs` to `xl` and can be used to create depth and elevation for UI elements.
+
+Below is a table showcasing the different shadow variants available in the design system.
+
+| Step    | Value                    | Description                                                    |
+| ------- | ------------------------ | -------------------------------------------------------------- |
+| outline | `var(--shadow--outline)` | Used for focus outlines and similar effects.                   |
+| 2xs     | `var(--shadow--2xs)`     | Used for very subtle shadows, such as small elements.          |
+| xs      | `var(--shadow--xs)`      | Used for slightly subtle shadows, such as on buttons or cards. |
+| sm      | `var(--shadow--sm)`      | Used for standard shadows, such as on popovers or selects.     |
+| md      | `var(--shadow--md)`      | Used for more prominent shadows, such as floating elements.    |
+| lg      | `var(--shadow--lg)`      | Used for larger shadows.                                       |
+| xl      | `var(--shadow--xl)`      | Used for elevated elements, such as dialogs.                   |
+
+## Example
+
+Shadows can be applied using the `shadow-*` primitive. It's recommended to create a local variable and apply the `_primitives.scss` token for flexibility.
+
+<div class="sb-unstyled shadow-demo">
+	<div class="shadow-demo__item">
+		<div class="shadow-demo__label">.box1</div>
+		<div class="shadow-demo__card" style={{ boxShadow: 'var(--shadow--xs)' }} />
+	</div>
+	<div class="shadow-demo__item">
+		<div class="shadow-demo__label">.box2</div>
+		<div class="shadow-demo__card" style={{ boxShadow: 'var(--shadow--md)' }} />
+	</div>
+	<div class="shadow-demo__item">
+		<div class="shadow-demo__label">.box3</div>
+		<div class="shadow-demo__card" style={{ boxShadow: 'var(--shadow--xl)' }} />
+	</div>
+</div>
+
+```css
+.box {
+	width: 160px;
+	height: 160px;
+	border-radius: var(--radius--lg);
+	background: var(--background--surface);
+	box-shadow: var(--n8n--shadow--box);
+}
+
+.box1 {
+	--n8n--shadow--box: var(--shadow--xs);
+}
+
+.box2 {
+	--n8n--shadow--box: var(--shadow--md);
+}
+
+.box3 {
+	--n8n--shadow--box: var(--shadow--xl);
+}
+```
+
+<style>
+	{`
+.shadow-demo {
+	display: grid;
+	grid-template-columns: repeat(3, minmax(0, 1fr));
+	gap: var(--spacing--lg);
+	padding: var(--spacing--xl);
+	padding-bottom:calc(2rem + var(--spacing--xl));
+	border-radius:var(--radius--lg) var(--radius--lg) 0 0;
+	border: 1px solid var(--border-color);
+	border-bottom:0;
+	background: light-dark(var(--color--neutral-100), var(--color--neutral-900));
+	margin-bottom:-2rem;
+}
+.shadow-demo__item {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--spacing--md);
+}
+.shadow-demo__label {
+	color: var(--text-color);
+	font-weight: var(--font-weight--semibold);
+}
+.shadow-demo__card {
+	width: 160px;
+	height: 160px;
+	border: 1px solid var(--border-color);
+	border-radius: var(--radius--lg);
+	background: var(--background--surface);
+}
+`}
+</style>

package/src/styleguide/spacing-size.mdx

@@ -0,0 +1,78 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Styleguide/Spacing & Size" />
+
+# Spacing & Size
+
+Our spacing scale is built to keep visual rhythm consistent across components, with step names (`5xs` to `5xl`) that map to fixed pixel values.
+
+Use adjacent steps when adjusting layouts so spacing feels intentional instead of drifting into one-off values.
+The height scale complements spacing and gives controls a shared size language, so buttons, inputs, and panels align naturally.
+
+## Spacing
+
+| Name | Size (px) | Visualization                                                                  |
+| ---- | --------- | ------------------------------------------------------------------------------ |
+| 5xs  | 2px       | <span class="spacing-size spacing" style={{ width: 'var(--spacing--5xs)' }} /> |
+| 4xs  | 4px       | <span class="spacing-size spacing" style={{ width: 'var(--spacing--4xs)' }} /> |
+| 3xs  | 6px       | <span class="spacing-size spacing" style={{ width: 'var(--spacing--3xs)' }} /> |
+| 2xs  | 8px       | <span class="spacing-size spacing" style={{ width: 'var(--spacing--2xs)' }} /> |
+| xs   | 12px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--xs)' }} />  |
+| sm   | 16px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--sm)' }} />  |
+| md   | 20px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--md)' }} />  |
+| lg   | 24px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--lg)' }} />  |
+| xl   | 32px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--xl)' }} />  |
+| 2xl  | 48px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--2xl)' }} /> |
+| 3xl  | 64px      | <span class="spacing-size spacing" style={{ width: 'var(--spacing--3xl)' }} /> |
+| 4xl  | 128px     | <span class="spacing-size spacing" style={{ width: 'var(--spacing--4xl)' }} /> |
+| 5xl  | 256px     | <span class="spacing-size spacing" style={{ width: 'var(--spacing--5xl)' }} /> |
+
+## Height
+
+| Name | Size (px) | Visualization                                                                 |
+| ---- | --------- | ----------------------------------------------------------------------------- |
+| 5xs  | 8px       | <span class="spacing-size height" style={{ height: 'var(--height--5xs)' }} /> |
+| 4xs  | 12px      | <span class="spacing-size height" style={{ height: 'var(--height--4xs)' }} /> |
+| 3xs  | 16px      | <span class="spacing-size height" style={{ height: 'var(--height--3xs)' }} /> |
+| 2xs  | 20px      | <span class="spacing-size height" style={{ height: 'var(--height--2xs)' }} /> |
+| xs   | 24px      | <span class="spacing-size height" style={{ height: 'var(--height--xs)' }} />  |
+| sm   | 28px      | <span class="spacing-size height" style={{ height: 'var(--height--sm)' }} />  |
+| md   | 32px      | <span class="spacing-size height" style={{ height: 'var(--height--md)' }} />  |
+| lg   | 36px      | <span class="spacing-size height" style={{ height: 'var(--height--lg)' }} />  |
+| xl   | 40px      | <span class="spacing-size height" style={{ height: 'var(--height--xl)' }} />  |
+| 2xl  | 48px      | <span class="spacing-size height" style={{ height: 'var(--height--2xl)' }} /> |
+| 3xl  | 56px      | <span class="spacing-size height" style={{ height: 'var(--height--3xl)' }} /> |
+| 4xl  | 64px      | <span class="spacing-size height" style={{ height: 'var(--height--4xl)' }} /> |
+| 5xl  | 96px      | <span class="spacing-size height" style={{ height: 'var(--height--5xl)' }} /> |
+
+### Negative Values
+
+To get negative values, use the `calc()` function like so:
+
+```css
+.box {
+	margin-inline: calc(var(--spacing--xs) * -1); /* -12px */
+}
+```
+
+<style>
+	{`
+
+.spacing-size {
+	display: inline-block;
+	margin:var(--spacing--4xs);
+	background: var(--color--mint-500);
+	border-radius: var(--radius--4xs);
+}
+
+.spacing-size.height {
+	aspect-ratio:1/1;
+	min-width: 2px;
+}
+
+.spacing-size.spacing {
+	min-width: 2px;
+	height:var(--spacing--xs);
+}
+`}
+</style>

package/src/styleguide/type.mdx

@@ -0,0 +1,91 @@
+import { Meta, Typeset } from '@storybook/addon-docs/blocks';
+
+<Meta title="Styleguide/Type" />
+
+export const typography = {
+	type: {
+		primary: 'InterVariable, sans-serif',
+		monospace: "CommitMono, ui-monospace, Menlo, Consolas, 'DejaVu Sans Mono', monospace",
+	},
+	weight: {
+		regular: '400',
+		medium: '500',
+		bold: '600',
+	},
+	size: {
+		s1: 8,
+		s2: 10,
+		s3: 12,
+		s4: 13,
+		s5: 14,
+		m1: 16,
+		m2: 18,
+		m3: 20,
+		l1: 28,
+	},
+};
+
+export const SampleText = 'The quick brown fox jumps over the lazy dog.';
+
+# Type
+
+**Font:** InterVariable
+
+**Weights:** 400 (regular), 500 (medium), 600 (bold)
+
+<Typeset
+	fontSizes={[
+		typography.size.s1,
+		typography.size.s2,
+		typography.size.s3,
+		typography.size.s4,
+		typography.size.s5,
+		typography.size.m1,
+		typography.size.m2,
+		typography.size.m3,
+		typography.size.l1,
+	]}
+	fontWeight={typography.weight.bold}
+	sampleText={SampleText}
+	fontFamily={typography.type.primary}
+/>
+
+---
+
+**Font:** CommitMono
+
+**Weights:** 400 (regular), 600 (bold)
+
+<Typeset
+	fontSizes={[
+		typography.size.s1,
+		typography.size.s2,
+		typography.size.s3,
+		typography.size.s4,
+		typography.size.s5,
+		typography.size.m1,
+		typography.size.m2,
+		typography.size.m3,
+		typography.size.l1,
+	]}
+	fontWeight={typography.weight.bold}
+	sampleText={SampleText}
+	fontFamily={typography.type.monospace}
+/>
+
+## Usage
+
+When rendering text inside the app, use `<Heading />` or `<Text />` and stick to the style and size set.
+Both of them share the same size and weight options.
+
+| Step | Size                    | Letter spacing                    | Line height              |
+| ---- | ----------------------- | --------------------------------- | ------------------------ |
+| 4xs  | `var(--font-size--4xs)` | `var(--letter-spacing--wide)`     | `var(--line-height--xs)` |
+| 3xs  | `var(--font-size--3xs)` | `var(--letter-spacing--normal)`   | `var(--line-height--sm)` |
+| 2xs  | `var(--font-size--2xs)` | `var(--letter-spacing--normal)`   | `var(--line-height--md)` |
+| xs   | `var(--font-size--xs)`  | `var(--letter-spacing--normal)`   | `var(--line-height--md)` |
+| sm   | `var(--font-size--sm)`  | `var(--letter-spacing--normal)`   | `var(--line-height--lg)` |
+| md   | `var(--font-size--md)`  | `var(--letter-spacing--normal)`   | `var(--line-height--lg)` |
+| lg   | `var(--font-size--lg)`  | `var(--letter-spacing--tight)`    | `var(--line-height--xl)` |
+| xl   | `var(--font-size--xl)`  | `var(--letter-spacing--tighter)`  | `var(--line-height--xl)` |
+| 2xl  | `var(--font-size--2xl)` | `var(--letter-spacing--tightest)` | `var(--line-height--xl)` |