diff --git a/.agents/design-system-style-rules.md b/.agents/design-system-style-rules.md new file mode 100644 index 00000000000..8b14eac3e6d --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index 4b503b7d8ec..960dc25af80 100644 --- a/AGENTS.md +++ b/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. diff --git a/cubic.yaml b/cubic.yaml index 29ccbb49291..27e275cee7c 100644 --- a/cubic.yaml +++ b/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 diff --git a/packages/frontend/AGENTS.md b/packages/frontend/AGENTS.md index e347ce91779..d514a3f8678 100644 --- a/packages/frontend/AGENTS.md +++ b/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