> **n8n:ui-design** — skill 43 of 43 in [n8n-io/n8n](https://skillsdocs.com/n8n-io/n8n).
>
> Book (all skills, one file): https://skillsdocs.com/n8n-io/n8n.md
> Machine manifest: https://skillsdocs.com/n8n-io/n8n/.well-known/agent-skills/index.json
> Origin: credited — this skill is installed into this repository and in use here, not published from it, so there is no install command.
> Upstream: https://github.com/n8n-io/n8n/blob/master/.agents/skills/ui-design/SKILL.md @ `master`
> Raw bytes, no header: https://raw.githubusercontent.com/n8n-io/n8n/master/.agents/skills/ui-design/SKILL.md
> Base for relative paths: https://raw.githubusercontent.com/n8n-io/n8n/master/.agents/skills/ui-design/
> Licence: Other — https://github.com/n8n-io/n8n
>
> Bundled files (2), referenced from this skill's directory:
>   - `rules/web-animation-guidelines.md` — https://raw.githubusercontent.com/n8n-io/n8n/master/.agents/skills/ui-design/rules/web-animation-guidelines.md
>   - `rules/web-interface-guidelines.md` — https://raw.githubusercontent.com/n8n-io/n8n/master/.agents/skills/ui-design/rules/web-interface-guidelines.md
>
> Content © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request

<!-- Verbatim upstream SKILL.md follows, YAML frontmatter included. -->

---
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 from `_tokens.scss` or `_primitives.scss` in
  `packages/frontend/@n8n/design-system/src/css/`. Look up every length, color,
  font-size and duration before you write it as a literal. Each spacing token
  carries its px value in a comment: `--spacing--5xs: 0.125rem; /** 2px **/`.
  Grep that comment to find the token for a px value. The grep gives one hit for
  each token family, so pick the family that matches the property: `--spacing--*`
  for margin and padding, `--radius--*` for border-radius, `--height--*` for
  height. The styleguide
  `packages/frontend/@n8n/design-system/src/styleguide/spacing-size.mdx` lists the
  same scale as a table. The spacing scale starts at 2px, so a small value is not
  a reason to hardcode. Hardcode only if the lookup finds no token. Give the
  reason in a comment.
- 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)`