6 files changed, 107 insertions, 41 deletions
diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md
new file mode 100644
index 00000000000..66a8abe42f7
--- /dev/null
+++ b/doc/development/fe_guide/components.md
@@ -0,0 +1,61 @@
+# Components
+
+## Contents
+* [Dropdowns](#dropdowns)
+* [Modals](#modals)
+
+## Dropdowns
+
+See also the [corresponding UX guide](../ux_guide/components.md#dropdowns).
+
+### How to style a bootstrap dropdown
+1. Use the HTML structure provided by the [docs][bootstrap-dropdowns]
+1. Add a specific class to the top level `.dropdown` element
+
+
+    ```Haml
+    .dropdown.my-dropdown
+      %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false }
+        %span.dropdown-toggle-text
+          Toggle Dropdown
+        = icon('chevron-down')
+
+      %ul.dropdown-menu
+        %li
+          %a
+            item!
+    ```
+
+    Or use the helpers
+    ```Haml
+    .dropdown.my-dropdown
+      = dropdown_toggle('Toogle!', { toggle: 'dropdown' })
+      = dropdown_content
+        %li
+          %a
+            item!
+    ```
+
+[bootstrap-dropdowns]: https://getbootstrap.com/docs/3.3/javascript/#dropdowns
+
+## Modals
+
+See also the [corresponding UX guide](../ux_guide/components.md#modals).
+
+We have a reusable Vue component for modals: [vue_shared/components/gl-modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl-modal.vue)
+
+Here is an example of how to use it:
+
+```html
+  <gl-modal
+    id="dogs-out-modal"
+    :header-title-text="s__('ModalExample|Let the dogs out?')"
+    footer-primary-button-variant="danger"
+    :footer-primary-button-text="s__('ModalExample|Let them out')"
+    @submit="letOut(theDogs)"
+  >
+    {{ s__('ModalExample|You’re about to let the dogs out.') }}
+  </gl-modal>
+```
+
+![example modal](img/gl-modal.png)
diff --git a/doc/development/fe_guide/dropdowns.md b/doc/development/fe_guide/dropdowns.md
index 6314f8f38d2..e9d6244355c 100644
--- a/doc/development/fe_guide/dropdowns.md
+++ b/doc/development/fe_guide/dropdowns.md
@@ -1,32 +1 @@
-# Dropdowns
-
-
-## How to style a bootstrap dropdown
-1. Use the HTML structure provided by the [docs][bootstrap-dropdowns]
-1. Add a specific class to the top level `.dropdown` element
-
-
-    ```Haml
-    .dropdown.my-dropdown
-      %button{ type: 'button', data: { toggle: 'dropdown' }, 'aria-haspopup': true, 'aria-expanded': false }
-        %span.dropdown-toggle-text
-          Toggle Dropdown
-        = icon('chevron-down')
-
-      %ul.dropdown-menu
-        %li
-          %a
-            item!
-    ```
-
-    Or use the helpers
-    ```Haml
-    .dropdown.my-dropdown
-      = dropdown_toggle('Toogle!', { toggle: 'dropdown' })
-      = dropdown_content
-        %li
-          %a
-            item!
-    ```
-
-[bootstrap-dropdowns]: https://getbootstrap.com/docs/3.3/javascript/#dropdowns
+This page has moved [here](components.md#dropdowns).
diff --git a/doc/development/fe_guide/img/gl-modal.png b/doc/development/fe_guide/img/gl-modal.png
new file mode 100644
index 00000000000..47302e857bc
--- /dev/null
+++ b/doc/development/fe_guide/img/gl-modal.png
diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md
index 72cb557d054..12dfc10812b 100644
--- a/doc/development/fe_guide/index.md
+++ b/doc/development/fe_guide/index.md
@@ -21,6 +21,8 @@ Working with our frontend assets requires Node (v4.3 or greater) and Yarn
 [jQuery][jquery] is used throughout the application's JavaScript, with
 [Vue.js][vue] for particularly advanced, dynamic elements.
 
+We also use [Axios][axios] to handle all of our network requests.
+
 ### Browser Support
 
 For our currently-supported browsers, see our [requirements][requirements].
@@ -77,8 +79,10 @@ Axios specific practices and gotchas.
 ## [Icons](icons.md)
 How we use SVG for our Icons.
 
-## [Dropdowns](dropdowns.md)
-How we use dropdowns.
+## [Components](components.md)
+
+How we use UI components.
+
 ---
 
 ## Style Guides
@@ -122,6 +126,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the
 [webpack]: https://webpack.js.org/
 [jquery]: https://jquery.com/
 [vue]: http://vuejs.org/
+[axios]: https://github.com/axios/axios
 [airbnb-js-style-guide]: https://github.com/airbnb/javascript
 [scss-lint]: https://github.com/brigade/scss-lint
 [install]: ../../install/installation.md#4-node
diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md
index 02773162801..917d28b48ee 100644
--- a/doc/development/fe_guide/style_guide_js.md
+++ b/doc/development/fe_guide/style_guide_js.md
@@ -207,10 +207,39 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod
     var c = pureFunction(values.foo);
   ```
 
-1. Avoid constructors with side-effects
+1. Avoid constructors with side-effects.
+Although we aim for code without side-effects we need some side-effects for our code to run.
+
+If the class won't do anything if we only instantiate it, it's ok to add side effects into the constructor (_Note:_ The following is just an example. If the only purpose of the class is to add an event listener and handle the callback a function will be more suitable.)
+
+```javascript
+// Bad
+export class Foo {
+  constructor() {
+    this.init();
+  }
+  init() {
+    document.addEventListener('click', this.handleCallback)
+  },
+  handleCallback() {
+
+  }
+}
+
+// Good
+export class Foo {
+  constructor() {
+    document.addEventListener()
+  }
+  handleCallback() {
+  }
+}
+```
+
+On the other hand, if a class only needs to extend a third party/add event listeners in some specific cases, they should be initialized oustside of the constructor.
 
 1. Prefer `.map`, `.reduce` or `.filter` over `.forEach`
-A forEach will cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
+A forEach will most likely cause side effects, it will be mutating the array being iterated. Prefer using `.map`,
 `.reduce` or `.filter`
   ```javascript
     const users = [ { name: 'Foo' }, { name: 'Bar' } ];
@@ -302,20 +331,20 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation.
 
 #### Naming
 1. **Extensions**: Use `.vue` extension for Vue components.
-1. **Reference Naming**: Use camelCase for their instances:
+1. **Reference Naming**: Use PascalCase for their instances:
   ```javascript
     // bad
-    import CardBoard from 'cardBoard'
+    import cardBoard from 'cardBoard.vue'
 
     components: {
-      CardBoard:
+      cardBoard,
     };
 
     // good
-    import cardBoard from 'cardBoard'
+    import CardBoard from 'cardBoard.vue'
 
     components: {
-      cardBoard:
+      CardBoard,
     };
   ```
 
diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md
index 86a8b4135af..655d94793dd 100644
--- a/doc/development/fe_guide/style_guide_scss.md
+++ b/doc/development/fe_guide/style_guide_scss.md
@@ -7,6 +7,8 @@ easy to maintain, and performant for the end-user.
 
 ### Naming
 
+Filenames should use `snake_case`.
+
 CSS classes should use the `lowercase-hyphenated` format rather than
 `snake_case` or `camelCase`.