Merge branch 'docs-vue-guide-update' into 'master'

doc/development/fe_guide/icons.md

-# Icons
+# Icons and SVG Illustrations
 
-We are using SVG Icons in GitLab with a SVG Sprite, due to this the icons are only loaded once and then referenced through an ID. The sprite SVG is located under `/assets/icons.svg`. Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome usages.
+We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository.
+This repository is published on [npm][npm] and managed as a dependency via yarn.
+You can browse all available Icons and Illustrations [here][svg-preview].
+To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`.
 
-### Usage in HAML/Rails
+## Icons
 
-To use a sprite Icon in HAML or Rails we use a specific helper function :
+We are using SVG Icons in GitLab with a SVG Sprite.
+This means the icons are only loaded once, and are referenced through an ID.
+The sprite SVG is located under `/assets/icons.svg`.
+
+Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome icons.
 
-`sprite_icon(icon_name, size: nil, css_class: '')`
+### Usage in HAML/Rails
 
-**icon_name** Use the icon_name that you can find in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`).
+To use a sprite Icon in HAML or Rails we use a specific helper function :
 
-**size (optional)** Use one of the following sizes : 16,24,32,48,72 (this will be translated into a `s16` class)
+```ruby
+sprite_icon(icon_name, size: nil, css_class: '')
+```
 
-**css_class (optional)** If you want to add additional css classes
+-   **icon_name** Use the icon_name that you can find in the SVG Sprite
+    ([Overview is available here][svg-preview]).
+-   **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class)
+-   **css_class (optional)** If you want to add additional css classes
 
 **Example**
 
-`= sprite_icon('issues', size: 72, css_class: 'icon-danger')`
+```haml
+= sprite_icon('issues', size: 72, css_class: 'icon-danger')
+```
 
 **Output from example above**
 
-`<svg class="s72 icon-danger"><use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use></svg>`
+```html
+<svg class="s72 icon-danger">
+  <use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use>
+</svg>
+```
 
 ### Usage in Vue
 
@@ -28,33 +46,71 @@ We have a special Vue component for our sprite icons in `\vue_shared\components\
 
 Sample usage :
 
-`<icon
-    name="retry"
-    :size="32"
-    css-classes="top"
-  />`
-
-**name** Name of the Icon in the SVG Sprite  ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`).
-
-**size (optional)** Number value for the size which is then mapped to a specific CSS class (Available Sizes: 8,12,16,18,24,32,48,72 are mapped to `sXX` css classes)
-
-**css-classes (optional)** Additional CSS Classes to add to the svg tag.
+```javascript
+<script>
+import Icon from "~/vue_shared/components/icon.vue"
+
+export default {
+  components: {
+    Icon,
+  },
+};
+<script>
+<template>
+  <icon
+    name="issues"
+    :size="72"
+    css-classes="icon-danger"
+  />
+</template>
+```
+
+-   **name** Name of the Icon in the SVG Sprite  ([Overview is available here][svg-preview]).
+-   **size (optional)** Number value for the size which is then mapped to a specific CSS class
+    (Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes)
+-   **css-classes (optional)** Additional CSS Classes to add to the svg tag.
 
 ### Usage in HTML/JS
 
-Please use the following function inside JS to render an icon :
+Please use the following function inside JS to render an icon:
 `gl.utils.spriteIcon(iconName)`
 
-## Adding a new icon to the sprite
+## SVG Illustrations
 
-All Icons and Illustrations are managed in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository which is added as a dev-dependency.
+Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers.
+Please use the class `svg-content` around it to ensure nice rendering.
 
-To upgrade to a new SVG Sprite version run `yarn upgrade @gitlab-org/gitlab-svgs`.
+### Usage in HAML/Rails
 
-# SVG Illustrations
+**Example**
 
-Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. Please use the class `svg-content` around it to ensure nice rendering. The illustrations are also organised in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository (as they are then automatically optimised).
+```haml
+.svg-content
+  = image_tag 'illustrations/merge_requests.svg'
+```
 
-**Example**
+### Usage in Vue
 
-`= image_tag 'illustrations/merge_requests.svg'`
+To use an SVG illustrations in a template provide the path as a property and display it through a standard img tag.
+
+Component:
+
+```js
+<script>
+export default {
+  props: {
+    svgIllustrationPath: {
+      type: String,
+      required: true,
+    },
+  },
+};
+<script>
+<template>
+  <img :src="svgIllustrationPath" />
+</template>
+```
+
+[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs
+[gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs
+[svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs

doc/development/fe_guide/index.md

@@ -54,8 +54,8 @@ Vuex specific design patterns and practices.
 ## [Axios](axios.md)
 Axios specific practices and gotchas.
 
-## [Icons](icons.md)
-How we use SVG for our Icons.
+## [Icons and Illustrations](icons.md)
+How we use SVG for our Icons and Illustrations.
 
 ## [Components](components.md)