diff --git a/.agents/skills/design-system/SKILL.md b/.agents/skills/design-system/SKILL.md deleted file mode 100644 index 415d055a1be..00000000000 --- a/.agents/skills/design-system/SKILL.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: n8n:design-system -description: Guidelines on using Design System styles and components. Use when working on .vue files in packages/frontend. Triggers for tasks that include component architecture, styling, UI changes, or feature work. ---- - -# Design System - -Comprehensive guide for building, styling, and using components in the frontend. - -## When to Apply -Reference these guidelines when: -- Working on `.{vue|css|scss}` files in `packages/frontend` -- Adding new components to `packages/frontend/@n8n/design-system` -- Refactoring styles for Vue components -- Implementing new UI components or features -- Reviewing changes to UI - -## Rules -- Follow guidelines in `packages/frontend/@n8n/design-system/src/styleguide/*.mdx` -- ALWAYS use CSS variables for styles from `packages/frontend/@n8n/design-system/src/css/_tokens.scss` or `packages/frontend/@n8n/design-system/src/css/_primitives.scss`. Use hard-coded values only when no suitable tokens. -- ALWAYS prefer using existing components from `packages/frontend/@n8n/design-system/src/components`. Prefer components that aren't marked `@deprecated`. -- Use `light-dark()` when alternating colors for ligh/dark mode -- If you need to add hover/active alpha behavior to solid components, prefer `color-mix()` with explicit percentages. -- When working with animations or transitions, ALWAYS prefer using mixins from `packages/frontend/@n8n/design-system/src/css/mixins/motion.scss` -- When reviewing animations, follow the guides in `rules/web-animation-guidelines.md` -- When reviewing UI changes or adding new components, follow `rules/web-interface-guidelines.md` - -## Storybook Stories - -- ALWAYS add new stories to `packages/frontend/@n8n/design-system`. -- Every story must use one of these title categories: - - `Style Guide`: styles, tokens, and utilities - - `Core`: components used across the app - - `Areas/`: patterns and components for a specific product area, for example `Areas/Settings` or `Areas/Assistant` - - `Experimental`: beta components that require caution -- The last `title` segment is the component name and MUST be PascalCase (`Core/EmptyState`, not `Core/empty-state`). Category prefixes are unrestricted. - -## Examples -- "Add a modal dialog for confirming workflow deletion" → Use `N8nDialog` -- "Add a dropdown to select workflow status" → Use `N8nDropdown` or `N8nSelect` -- "Add button with + icon to add new tiem" → Wrap `N8nButton` with `iconOnly` prop with `N8nTooltip` and wrap in `N8nTooltip`. Use `N8nIcon` and proper aria-label. -- "Add a destructive action button" → use `N8nButton` with `variant="destructive"` -- "Make background color white/black" → Use `var(--background--surface)` for white on light mode and "black" on dark mode -- "Animate the title in gracefully" -> Use `fade-in-up` mixin from `motion.scss` with `var(--duration--base)` diff --git a/.agents/skills/experiments/SKILL.md b/.agents/skills/experiments/SKILL.md index 0a51017536c..0c50b93917e 100644 --- a/.agents/skills/experiments/SKILL.md +++ b/.agents/skills/experiments/SKILL.md @@ -20,4 +20,4 @@ Start with the relevant mode in [reference.md](reference.md): - `Review` for auditing experiment changes. - `Retire` for cleaning up completed or abandoned experiments. -When experiment work touches Vue components or user-facing copy, also follow `n8n:design-system` and `n8n:content-design`. +When experiment work touches Vue components or user-facing copy, also follow `n8n:ui-design` and `n8n:content-design`. diff --git a/.agents/skills/experiments/reference.md b/.agents/skills/experiments/reference.md index 3c0af89d4c2..2f8d42be38f 100644 --- a/.agents/skills/experiments/reference.md +++ b/.agents/skills/experiments/reference.md @@ -66,7 +66,7 @@ Use this guide for code under `packages/frontend/editor-ui/src/experiments/` and - Wire experiments at the narrowest host surface that owns the decision. - Keep experiment components inside the experiment folder unless they become generally reusable. - All user-facing text in Vue code must use i18n. Follow `n8n:content-design` when writing or revising copy. -- Follow `n8n:design-system` for Vue component structure, n8n design-system components, and CSS variables. +- Follow `n8n:ui-design` for Vue component structure, n8n design-system components, and CSS variables. - At the end of scaffold or wiring work, tell the user what remains manual, such as PostHog configuration, route guards, modal registration, or extra workflow payload files. ## Test diff --git a/.agents/skills/ui-design/SKILL.md b/.agents/skills/ui-design/SKILL.md new file mode 100644 index 00000000000..ea2d602bc2b --- /dev/null +++ b/.agents/skills/ui-design/SKILL.md @@ -0,0 +1,28 @@ +--- +name: n8n:ui-design +description: Guidelines on designing and building UI. Use when working in editor-ui or design-system packages. Triggers for tasks that include refactoring components, styling changes, or feature work. +--- + +# UI Design + +Comprehensive guide for building, styling, and using components in the frontend. + +## References +- When styling components, use `packages/frontend/@n8n/design-system/src/styleguide/*.mdx` +- For animations, use `rules/web-animation-guidelines.md` +- When reviewing UI changes, use `rules/web-interface-guidelines.md` + +## Best practices +- ALWAYS use CSS variables for styles from `packages/frontend/@n8n/design-system/src/css/_tokens.scss` or `packages/frontend/@n8n/design-system/src/css/_primitives.scss`. Use hard-coded values only when no suitable tokens. +- ALWAYS prefer using existing components from `packages/frontend/@n8n/design-system/src/components`. Prefer components that aren't marked `@deprecated`. +- If you need to add hover/active alpha behavior to solid components, prefer `color-mix()` with explicit percentages. +- When working with animations or transitions, ALWAYS prefer using mixins from `packages/frontend/@n8n/design-system/src/css/mixins/motion.scss` + +## Components +Use existing `design-system` components over creating custom implementations: +- "Add a modal dialog for confirming workflow deletion" → Use `N8nDialog` +- "Add a dropdown to select workflow status" → Use `N8nDropdown` or `N8nSelect` +- "Add button with + icon to add new tiem" → Wrap `N8nButton` with `iconOnly` prop with `N8nTooltip` and wrap in `N8nTooltip`. Use `N8nIcon` and proper aria-label. +- "Add a destructive action button" → use `N8nButton` with `variant="destructive"` +- "Make background color white/black" → Use `var(--background--surface)` for white on light mode and "black" on dark mode +- "Animate the title in gracefully" -> Use `fade-in-up` mixin from `motion.scss` with `var(--duration--base)` diff --git a/.agents/skills/design-system/rules/web-animation-guidelines.md b/.agents/skills/ui-design/rules/web-animation-guidelines.md similarity index 100% rename from .agents/skills/design-system/rules/web-animation-guidelines.md rename to .agents/skills/ui-design/rules/web-animation-guidelines.md diff --git a/.agents/skills/design-system/rules/web-interface-guidelines.md b/.agents/skills/ui-design/rules/web-interface-guidelines.md similarity index 100% rename from .agents/skills/design-system/rules/web-interface-guidelines.md rename to .agents/skills/ui-design/rules/web-interface-guidelines.md diff --git a/.claude/plugins/n8n/skills/design-system b/.claude/plugins/n8n/skills/design-system deleted file mode 120000 index 930eaae214e..00000000000 --- a/.claude/plugins/n8n/skills/design-system +++ /dev/null @@ -1 +0,0 @@ -../../../../.agents/skills/design-system \ No newline at end of file diff --git a/.claude/plugins/n8n/skills/ui-design b/.claude/plugins/n8n/skills/ui-design new file mode 120000 index 00000000000..4176305551d --- /dev/null +++ b/.claude/plugins/n8n/skills/ui-design @@ -0,0 +1 @@ +../../../../.agents/skills/ui-design \ No newline at end of file diff --git a/packages/frontend/@n8n/design-system/AGENTS.md b/packages/frontend/@n8n/design-system/AGENTS.md new file mode 100644 index 00000000000..2ad4a8bffd3 --- /dev/null +++ b/packages/frontend/@n8n/design-system/AGENTS.md @@ -0,0 +1,20 @@ +# @n8n/design-system + +## References +- @README.md +- When working on components, use `n8n:ui-design` skill +- Follow guidelines from [W3C-APG](https://www.w3.org/WAI/ARIA/apg/patterns/) where applicable + +## Rules +- Every public interface for component props must have comments explaining what each prop is for +- Every component must include a `.test.ts` file with relevant tests +- Every user-facing string, including accessible labels, must have i18n translation +- For copy wording, use `n8n:content-design` skill +- Every component should have a related `*.stories.ts` file +- ALWAYS add new stories to `packages/frontend/@n8n/design-system`. +- Every story must use one of these title categories: + - `Style Guide`: styles, tokens, and utilities + - `Core`: components used across the app + - `Areas/`: patterns and components for a specific product area, for example `Areas/Settings` or `Areas/Assistant` + - `Experimental`: beta components that require caution +- The last `title` segment is the component name and MUST be PascalCase (`Core/EmptyState`, not `Core/empty-state`). Category prefixes are unrestricted. diff --git a/packages/frontend/@n8n/design-system/README.md b/packages/frontend/@n8n/design-system/README.md index bd1620bb831..4e12aa03bbe 100644 --- a/packages/frontend/@n8n/design-system/README.md +++ b/packages/frontend/@n8n/design-system/README.md @@ -11,6 +11,8 @@ the directives plugin. Run `pnpm dev` to see the components in Storybook. - [Exports](#exports) - [Develop the package](#develop-the-package) - [Pack and publish](#pack-and-publish) +- [Contributing](#contributing) +- [Owners](#owners) - [License](#license) ## Consume the package @@ -184,6 +186,15 @@ pnpm turbo run build --filter=@n8n/design-system pnpm pack --pack-destination /tmp/ds-pack ``` -## License +## Contributing +- Always follow the core `CONTRIBUTING.md` guidelines in the root repo. +- Design System components should be generic, reusable across multiple areas of the product. +- Each component must have tests and stories attached +- If replacing an existing component, make sure a migration path is considered +- For brand new components, provide `component-*.md` spec using `specification/COMPONENT_API_SPEC_TEMPLATE.md` for review first +## Owners +@n8n/design + +## License You can find the license information [here](https://github.com/n8n-io/n8n/blob/master/README.md#license) diff --git a/packages/frontend/@n8n/design-system/specification/COMPONENT_API_SPEC_TEMPLATE.md b/packages/frontend/@n8n/design-system/specification/COMPONENT_API_SPEC_TEMPLATE.md index 1922760caa2..85dd39129b3 100644 --- a/packages/frontend/@n8n/design-system/specification/COMPONENT_API_SPEC_TEMPLATE.md +++ b/packages/frontend/@n8n/design-system/specification/COMPONENT_API_SPEC_TEMPLATE.md @@ -1,17 +1,16 @@ -# Component specification - +``` Copy this file next to the template and call it `component-.md`. -This component specification describes the public API of a component intended to be added to the component library of our design system. -To be made available for review in a GitHub pull request before implementation. -With two approvals, you can be quite sure that the API won't be challenged anymore on the implementation PR. +This component specification describes the public API of a component intended to be added to the component library of our design system. To be made available for review in a GitHub pull request before implementation. +``` -- **Component Name:** N8nCheckbox -- **Element+ Component:** [ElCheckbox](https://element-plus.org/en-US/component/checkbox) -- **Reka UI Component:** [Checkbox](https://reka-ui.com/docs/components/checkbox) -- **Nuxt UI Component:** [Checkbox](https://ui.nuxt.com/docs/components/checkbox) +# Component name +_Short description of the component goes here_ -^ Only list what exists in the external component libraries. Nuxt uses Reka under the hood. We use it as guideline on for the public API of our reka-ui-based components +- **Reference:** [Some Base UI Component](https://element-plus.org/en-US/component/checkbox) + +## Why? +_Explain what this component does and why we need it_ ## Public API Definition @@ -32,13 +31,9 @@ With two approvals, you can be quite sure that the API won't be challenged anymo - `label`: `{ label?: string | undefined; }` -**CSS Variables** -- `--checkbox--border-color` -- `--checkbox--border-color--checked` - -### Template usage example +### Examples ```vue - -``` \ No newline at end of file + +``` diff --git a/packages/frontend/AGENTS.md b/packages/frontend/AGENTS.md index cb8dcb5e5f2..f8386155a93 100644 --- a/packages/frontend/AGENTS.md +++ b/packages/frontend/AGENTS.md @@ -6,11 +6,6 @@ Extra information, specific to the frontend codebase. Use this when doing any fr Scaffold one with `pnpm n8n-module-sdk create`. Then obey `packages/@n8n/module-cli/frontend-module-guide.md`. A module owns its tsconfig, its lint config and its vitest config. A module must never import `@/…` or another `@n8n/frontend-module-*`. -- When reviewing CSS/SCSS/Vue changes in `@n8n/design-system` or `editor-ui`, always use `n8n:design-system` skill. -- ALWAYS follow the guides in `@n8n/design-system/src/styleguide/*.mdx` -- PREFER using **semantic tokens** for styling from `@n8n/design-system/src/css/_tokens.scss` or `@n8n/design-system/src/css/_primitives.scss`. -- AVOID using legacy tokens from `@n8n/design-system/src/css/_tokens.legacy.scss` -- PREFER using existing components from `@n8n/design-system` over creating new ones - When rendering `el-plus` popovers/dropdowns/selects inside `N8nDialog`, prefer to keep them in the dialog stacking context with `:teleported="false"` unless they intentionally need to escape. - Available icon names are in `packages/frontend/@n8n/design-system/src/components/N8nIcon/icons.ts`. Use keys from `updatedIconSet` only — `deprecatedIconSet` entries must not be used in new code.