diff options
Diffstat (limited to 'doc/development/fe_guide/icons.md')
| -rw-r--r-- | doc/development/fe_guide/icons.md | 114 |
1 files changed, 85 insertions, 29 deletions
diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index b469a9c6aef..3d8da6accc1 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -1,26 +1,44 @@ -# 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 |