mirror of
https://github.com/n8n-io/n8n.git
synced 2026-09-24 23:22:38 +08:00
chore(editor): Update design-system skills and guidelines (no-changelog) (#37109)
This commit is contained in:
Rob Hough
@@ -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/<Product area>`: 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)`
|
||||
@@ -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`.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)`
|
||||
@@ -1 +0,0 @@
|
||||
../../../../.agents/skills/design-system
|
||||
+1
@@ -0,0 +1 @@
|
||||
../../../../.agents/skills/ui-design
|
||||
@@ -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/<Product area>`: 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.
|
||||
@@ -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)
|
||||
|
||||
@@ -1,17 +1,16 @@
|
||||
# Component specification
|
||||
|
||||
```
|
||||
Copy this file next to the template and call it `component-<component-name-kebap-case>.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
|
||||
<N8nCheckbox size="medium" label="Subscribe to newsletter" />
|
||||
```
|
||||
<Component size="medium" label="Subscribe to newsletter" />
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user