diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17a53f3e8d..baf4837f8e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Removed the `requires` attribute on the `@Extension` annotation and instead create a new `@Requires` annotation ([#1097](https://github.com/scm-manager/scm-manager/pull/1097))
+- Update guide to prevent common pitfalls in ui development ([#1107](https://github.com/scm-manager/scm-manager/pull/1107))
 - Use os specific locations for scm home directory ([#1109](https://github.com/scm-manager/scm-manager/pull/1109))
 - Use Library/Logs/SCM-Manager on OSX for logging ([#1109](https://github.com/scm-manager/scm-manager/pull/1109))
 - Cleanup outdated jaxb annotation in scm-core ([#1136](https://github.com/scm-manager/scm-manager/pull/1136))
diff --git a/docs/en/development/common-pitfall.md b/docs/en/development/ui-common-pitfall.md
similarity index 50%
rename from docs/en/development/common-pitfall.md
rename to docs/en/development/ui-common-pitfall.md
index a226bdd4ed..f9b74cfc41 100644
--- a/docs/en/development/common-pitfall.md
+++ b/docs/en/development/ui-common-pitfall.md
@@ -2,19 +2,51 @@
 title: Common pitfall occurred while developing the SCM V2 
 ---
 
-## React Component is loaded unexpectedly
+## Introduction
+There are quite some common pitfalls which can cause an inconsistent or broken ui. 
+You can avoid most ugly ui glitches and broken surfaces or just improve your frontend code 
+by asking yourself some questions while building the components.
 
-### Bug
+## Design
+There exists a scm styleguide which can support you build fitting and beautiful ui components.
+Find the styleguide in "scm-ui/ui-styles".
+
+- Have I used the colors from the scm styleguide? 
+- Have I used familiar fonts which are already in use on this surface?
+- Is my component scalable / resizeable?
+- What happens if I insert very long / short content?
+- Is my component mobile friendly (tablet / smartphone)?
+- Does my component fit into the existing surface?
+- Does the ui become confusing / overcrowded / ugly because of my component?
+- Can I reduce the shown texts and use icons (tooltips) instead?
+- Are there enough whitespaces in my component / around my component?
+- Have I used translation keys and translated my content at least in german and english?
+
+## Small, reuseable components
+The SCM-Manager provides a storybook which tests many reuseable components with usage examples. 
+You can also find some more ui components which doesn't have stories yet in "scm-ui/ui-components".
+If a component which can be reused is missing, feel free to add it to ui-components.
+
+- Have I checked ui-components before creating an entirely new component?
+- If creating a new component should it be added to ui-components?
+- Have I written one or more stories which tests my new component in the storybook?
+- Does my component have too much code / logic? Can it be cut down in some smaller components?
+- Have I created the new component as a react functional component?
+
+## Other common errors
+### React Component is loaded unexpectedly
+
+#### Bug
 
 A react component is updated without any changes in the props or states.
 
-### Fix
+#### Fix
 
 Use the [why-did-you-update](https://github.com/maicki/why-did-you-update) library to analyze the causes of the updates.
 
 A common cause is the definition of [new functions in render()](https://github.com/maicki/why-did-you-update#changes-are-in-functions-only).
 
-### Example
+#### Example
 
 ```javascript
 class Main extends React.Component<Props> {
diff --git a/docs/en/navigation.yml b/docs/en/navigation.yml
index a406038586..045f97f29e 100644
--- a/docs/en/navigation.yml
+++ b/docs/en/navigation.yml
@@ -16,7 +16,7 @@
   entries:
   - /development/intellij-idea-configuration/
   - /development/build-from-source/
-  - /development/common-pitfall/
+  - /development/ui-common-pitfall/
   - /administration/permission-concept/
   - /development/error-handling/
   - /development/i18n/