docs(editor): Add shared design-system AI style review rules (no-changelog) (#27008)

.agents/design-system-style-rules.md

@@ -0,0 +1,62 @@
+# Design System Style Review Rules
+
+Use these rules when reviewing CSS/SCSS/Vue style changes, especially in
+`packages/frontend/` and `packages/frontend/@n8n/design-system/`.
+
+## 1) Token source priority
+
+Prefer this order when choosing visual values:
+
+1. Semantic tokens from
+   `packages/frontend/@n8n/design-system/src/css/_tokens.scss`
+2. Primitives from
+   `packages/frontend/@n8n/design-system/src/css/_primitives.scss`
+3. Hard-coded values only when no suitable token exists
+
+If no token exists, request a short rationale in the PR.
+
+## 2) Hard-coded visual values
+
+Flag hard-coded visual values and suggest token alternatives. This includes:
+
+- Colors (`#fff`, `rgb()`, `hsl()`, `oklch()`)
+- Spacing and sizing (`px`, `rem`, numeric layout constants in styles)
+- Radius, border widths/styles, and shadows
+- Typography values (font size, weight, line-height)
+- Motion values (durations and easing like `cubic-bezier(...)`)
+
+Severity: strong warning (expected migration to tokens/primitives when possible).
+
+## 3) Legacy token usage
+
+In `_tokens.scss`, the compatibility section labeled
+"Legacy tokens (kept for compatibility)" is considered legacy usage.
+
+When new or modified code uses these legacy token families, flag it as a
+migration opportunity and recommend semantic token usage where available.
+
+Severity: strong warning (discourage new usage, allow compatibility paths).
+
+## 4) Deprecated style and component surfaces
+
+Flag new usage of deprecated/legacy style surfaces in design-system components,
+for example:
+
+- `Button.legacy.scss` and legacy button override classes
+- Legacy button variants/types (for example `highlight`, `highlight-fill`)
+- Legacy component variants that exist for compatibility (for example legacy
+  tabs variant)
+
+Severity: strong warning (prefer modern semantic variants/components).
+
+## 5) Token substitution changes
+
+If a PR changes one token reference to another (for example
+`--text-color` -> `--text-color--subtle`), flag it as a soft warning.
+
+Ask for intent in the PR description/comment:
+
+- Intentional design adjustment, or
+- Potential accidental visual regression
+
+Do not treat token substitution as a hard failure by default.

AGENTS.md

@@ -140,6 +140,8 @@ const children = getChildNodes(workflow.connections, 'NodeName', 'main', 1);
 - **All UI text must use i18n** - add translations to `@n8n/i18n` package
 - **Use CSS variables directly** - never hardcode spacing as px values
 - **data-testid must be a single value** (no spaces or multiple values)
+- For style changes and design-system updates, follow
+  `.agents/design-system-style-rules.md`
 
 When implementing CSS, refer to @packages/frontend/CLAUDE.md for guidelines on
 CSS variables and styling conventions.

cubic.yaml

@@ -41,13 +41,16 @@ reviews:
 
     Approve if reasonably tested. Let humans handle edge cases.
 
-    ## Step 4: Design System Tokens
+    ## Step 4: Design System Style Rules
 
-    For any hard-coded visual values in CSS (colors, shadows, spacing), check
-    `@n8n/design-system/src/css/_primitives.scss` and
-    `@n8n/design-system/src/css/_tokens.scss` for an appropriate alternative.
-    If one exists, suggest using it. If none exist, ask why the hard-coded
-    value is required.
+    Follow `.agents/design-system-style-rules.md` for all CSS/SCSS/Vue style
+    review guidance.
+
+    Enforcement level:
+    - Strong warning: hard-coded visual values, legacy token usage, deprecated
+      style/component surfaces
+    - Soft warning: token-to-token substitutions (ask for intent to avoid
+      accidental regressions)
   custom_rules:
     - name: Security Review
       description: |-
@@ -210,11 +213,12 @@ reviews:
         humans handle edge cases.
     - name: Design System Tokens
       description: |-
-        For any hard-coded visual values in CSS (colors, shadows, spacing),
-        check `@n8n/design-system/src/css/_primitives.scss` and
-        `@n8n/design-system/src/css/_tokens.scss` for an appropriate alternative.
-        If one exists, suggest using it. If none exist, ask why the hard-coded
-        value is required.
+        Follow `.agents/design-system-style-rules.md`.
+
+        Apply balanced enforcement:
+        - Strong warning: hard-coded visual values, legacy token usage, and
+          deprecated style/component surfaces.
+        - Soft warning: token-to-token substitutions (request intent/rationale).
     - name: Use workflowDocumentStore for Migrated Workflow Fields
       description: |-
         We are actively migrating workflow state from `workflowsStore` (Pinia store defined in

packages/frontend/AGENTS.md

@@ -2,6 +2,11 @@
 
 Extra information, specific to the frontend codebase.
 
+### Style Review Rules
+
+For CSS/SCSS/Vue style changes and updates touching `@n8n/design-system`,
+follow `.agents/design-system-style-rules.md`.
+
 ### CSS Variables Reference
 
 Use the following CSS variables to maintain consistency across the