Add FE selectors docsadd-fe-selector-docs

Rename Design Patterns docs
to Best Practices.
Add FE docs for best practises
when creating/using selectors.

2 files changed, 31 insertions, 3 deletions

diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/best_practices.md
index 0342d16a87c..75864050e28 100644
--- a/doc/development/fe_guide/design_patterns.md
+++ b/doc/development/fe_guide/best_practices.md
@@ -1,4 +1,29 @@
-# Design Patterns
+# Best Practices
+
+Frontend design patterns and best practices.
+
+
+## Selectors
+
+When deciding on the selectors to apply or query on an element, you should consider the 3 main use cases of selectors; style, behaviour and testing.
+
+In order to decouple these 3 concerns, you should use different selectors.
+
+1. Style: Any `class` value that does not match an existing prefix.
+
+    Examples: `.general-settings`, `.alert-wrapper`
+
+1. Behaviour: Any `data-` or `class` value prefixed with `js-`. We prefer new changes to use data attributes.
+
+    Examples: `data-js-tooltip`, `.js-navbar`
+
+1. Testing/QA: Any `data-` or `class` value prefixed with `qa-`. We prefer new changes to use data attributes.
+
+    Examples: `data-qa-projects-dropdown`, `.qa-your-projects-link`
+
+> The mark of maintainable HTML, CSS, and JavaScript is when individual developers can easily and confidently edit parts of the code base without those changes inadvertently affecting other, unrelated parts.
+>
+> From [Decoupling Your HTML, CSS, and JavaScript](https://philipwalton.com/articles/decoupling-html-css-and-javascript/).
 
 ## Singletons
 
@@ -53,6 +78,7 @@ When writing a class that needs to manipulate the DOM guarantee a container opti
 This is useful when we need that class to be instantiated more than once in the same page.
 
 Bad:
+
 ```javascript
 class Foo {
   constructor() {
@@ -63,6 +89,7 @@ new Foo();
 ```
 
 Good:
+
 ```javascript
 class Foo {
   constructor(opts) {
@@ -72,6 +99,7 @@ class Foo {
 
 new Foo({ container: '.my-element' });
 ```
+
 You can find an example of the above in this [class][container-class-example];
 
 [container-class-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index 86b8972a69e..17516bfa29f 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -45,9 +45,9 @@ or make changes to our frontend development guidelines.
 How we write frontend tests, run the GitLab test suite, and debug test related
 issues.
 
-## [Design Patterns](design_patterns.md)
+## [Best Practices](best_practices.md)
 
-Common JavaScript design patterns in GitLab's codebase.
+Frontend design patterns and practices.
 
 ## [Vue.js Best Practices](vue.md)