+
+## 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. |
diff --git a/packages/frontend/@n8n/design-system/src/styleguide/components/PrimitivesColorTable.vue b/packages/frontend/@n8n/design-system/src/styleguide/components/PrimitivesColorTable.vue
new file mode 100644
index 00000000000..ba0e2c4d9c7
--- /dev/null
+++ b/packages/frontend/@n8n/design-system/src/styleguide/components/PrimitivesColorTable.vue
@@ -0,0 +1,239 @@
+
+
+
+
-
-
-
diff --git a/packages/frontend/@n8n/design-system/src/styleguide/css-tokens.mdx b/packages/frontend/@n8n/design-system/src/styleguide/css-tokens.mdx
new file mode 100644
index 00000000000..3215f6c3beb
--- /dev/null
+++ b/packages/frontend/@n8n/design-system/src/styleguide/css-tokens.mdx
@@ -0,0 +1,97 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+
+
+# 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.
+
+---
+
+
+ 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`.
+
diff --git a/packages/frontend/@n8n/design-system/src/styleguide/fonts.stories.ts b/packages/frontend/@n8n/design-system/src/styleguide/fonts.stories.ts
deleted file mode 100644
index c051ed5f3e2..00000000000
--- a/packages/frontend/@n8n/design-system/src/styleguide/fonts.stories.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { type StoryFn } from '@storybook/vue3-vite';
-
-import Sizes from './Sizes.vue';
-import VariableTable from './VariableTable.vue';
-
-export default {
- title: 'Styleguide/Font',
-};
-
-export const FontSize: StoryFn = () => ({
- components: {
- Sizes,
- },
- template:
- "",
-});
-
-const Template =
- (template: string): StoryFn =>
- () => ({
- components: {
- VariableTable,
- },
- template,
- });
-
-export const LineHeight = Template(
- "",
-);
-
-export const FontWeight = Template(
- '',
-);
-
-export const FontFamily = Template(
- '',
-);
diff --git a/packages/frontend/@n8n/design-system/src/styleguide/shadow.mdx b/packages/frontend/@n8n/design-system/src/styleguide/shadow.mdx
new file mode 100644
index 00000000000..61ac04f0787
--- /dev/null
+++ b/packages/frontend/@n8n/design-system/src/styleguide/shadow.mdx
@@ -0,0 +1,96 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+
+
+# 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.
+
+