diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md
index 62ac56a6bce..a29cfa096b2 100644
--- a/doc/development/ux_guide/basics.md
+++ b/doc/development/ux_guide/basics.md
@@ -35,26 +35,15 @@ This is the typeface used for code blocks. GitLab uses the OS default font.
## Icons
GitLab uses Font Awesome icons throughout our interface.
-
-The trash icon is used for destructive actions that deletes information.
-
-
-The pencil icon is used for editing content such as comments.
-
-
-The bell icon is for notifications, such as Todos.
-
-
-The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label.
-
-
-The standard RSS icon is used for linking to RSS/atom feeds.
-
-
-An 'x' is used for closing UI elements such as dropdowns.
-
-
-A plus is used when creating new objects, such as issues, projects, etc.
+| | |
+| :-----------: | :---- |
+|  | The trash icon is used for destructive actions that deletes information. |
+|  | The pencil icon is used for editing content such as comments.|
+|  | The bell icon is for notifications, such as Todos. |
+|  | The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. |
+|  | The standard RSS icon is used for linking to RSS/atom feeds. |
+|  | An 'x' is used for closing UI elements such as dropdowns. |
+|  | A plus is used when creating new objects, such as issues, projects, etc. |
> TODO: update this section, add more general guidance to icon usage and personality, etc.
@@ -62,20 +51,13 @@ A plus is used when creating new objects, such as issues, projects, etc.
## Color
-
-Blue is used to highlight primary active elements (such as current tab), as well as other organization and managing commands.
-
-
-Green is for actions that create new objects.
-
-
-Orange is used for warnings
-
-
-Red is reserved for delete and other destructive commands
-
-
-Grey, and white (depending on context) is used for netral, secondary elements
+| | |
+| :------: | :------- |
+|  | Blue is used to highlight primary active elements (such as the current tab), as well as other organizational and managing commands.|
+|  | Green is for actions that create new objects. |
+|  | Orange is used for warnings |
+|  | Red is reserved for delete and other destructive commands |
+|  | Grey is used for neutral secondary elements. Depending on context, white is sometimes used instead. |
> TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage.
diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md
index 8e51edd23ef..28383ad7dfc 100644
--- a/doc/development/ux_guide/components.md
+++ b/doc/development/ux_guide/components.md
@@ -75,10 +75,29 @@ Text should be in sentence case, where only the first word is capitalized. "Crea
> TODO: Rationalize this. Ensure that we still believe this.
### Colors
-Follow the color guidance on the [basics](basics.md#color) page. The default color treatment is the white/grey button.
+The default color treatment is the white/grey button. Follow the guidance on the [basics](basics.md#color) page to add meaningful color to a button.
+
+### Secondary states
+
+Primary buttons darken the color of their background and border for hover, focus and active states. An inner shadow is added to the active state to denote the button being pressed.
+
+| Values | Info | Success | Warning | Danger |
+| :------ | :------: | :------: | :------: | :------: |
+| Background: `$color-light`
Border: `$border-color-light` |  |  |  |  |
+| Background: `$color-normal`
Border: `$border-color-normal` |  |  |  |  |
+| Background: `$color-dark`
Border: `$border-color-dark` |  |  |  |  |
+
+Since secondary buttons only have a border on their resting state, their hover and focus states add a background color, which gets darkened on active.
+
+| Values | Success Secondary | Close | Spam |
+| :------ | :------: | :------: | :------: |
+| Font: `$border-color-light`
Border: `$border-color-light` |  |  |  |
+| Background: `$color-light`
Border: `$border-color-light` |  |  |  |
+| Background: `$color-normal`
Border: `$border-color-normal` |  |  |  |
---
+
## Dropdowns
Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.)
diff --git a/doc/development/ux_guide/img/button-close--active.png b/doc/development/ux_guide/img/button-close--active.png
new file mode 100644
index 00000000000..824bfc8f31b
Binary files /dev/null and b/doc/development/ux_guide/img/button-close--active.png differ
diff --git a/doc/development/ux_guide/img/button-close--hover.png b/doc/development/ux_guide/img/button-close--hover.png
new file mode 100644
index 00000000000..0291e121894
Binary files /dev/null and b/doc/development/ux_guide/img/button-close--hover.png differ
diff --git a/doc/development/ux_guide/img/button-close--resting.png b/doc/development/ux_guide/img/button-close--resting.png
new file mode 100644
index 00000000000..986d7174ce7
Binary files /dev/null and b/doc/development/ux_guide/img/button-close--resting.png differ
diff --git a/doc/development/ux_guide/img/button-danger--active.png b/doc/development/ux_guide/img/button-danger--active.png
new file mode 100644
index 00000000000..d3c64424b26
Binary files /dev/null and b/doc/development/ux_guide/img/button-danger--active.png differ
diff --git a/doc/development/ux_guide/img/button-danger--hover.png b/doc/development/ux_guide/img/button-danger--hover.png
new file mode 100644
index 00000000000..8506e093306
Binary files /dev/null and b/doc/development/ux_guide/img/button-danger--hover.png differ
diff --git a/doc/development/ux_guide/img/button-danger--resting.png b/doc/development/ux_guide/img/button-danger--resting.png
new file mode 100644
index 00000000000..69ad6bb796b
Binary files /dev/null and b/doc/development/ux_guide/img/button-danger--resting.png differ
diff --git a/doc/development/ux_guide/img/button-info--active.png b/doc/development/ux_guide/img/button-info--active.png
new file mode 100644
index 00000000000..23be20b225c
Binary files /dev/null and b/doc/development/ux_guide/img/button-info--active.png differ
diff --git a/doc/development/ux_guide/img/button-info--hover.png b/doc/development/ux_guide/img/button-info--hover.png
new file mode 100644
index 00000000000..4cb4e38558c
Binary files /dev/null and b/doc/development/ux_guide/img/button-info--hover.png differ
diff --git a/doc/development/ux_guide/img/button-info--resting.png b/doc/development/ux_guide/img/button-info--resting.png
new file mode 100644
index 00000000000..5883340aa83
Binary files /dev/null and b/doc/development/ux_guide/img/button-info--resting.png differ
diff --git a/doc/development/ux_guide/img/button-spam--active.png b/doc/development/ux_guide/img/button-spam--active.png
new file mode 100644
index 00000000000..55b44898684
Binary files /dev/null and b/doc/development/ux_guide/img/button-spam--active.png differ
diff --git a/doc/development/ux_guide/img/button-spam--hover.png b/doc/development/ux_guide/img/button-spam--hover.png
new file mode 100644
index 00000000000..3dc8ed34c54
Binary files /dev/null and b/doc/development/ux_guide/img/button-spam--hover.png differ
diff --git a/doc/development/ux_guide/img/button-spam--resting.png b/doc/development/ux_guide/img/button-spam--resting.png
new file mode 100644
index 00000000000..b6bf10a5b64
Binary files /dev/null and b/doc/development/ux_guide/img/button-spam--resting.png differ
diff --git a/doc/development/ux_guide/img/button-success--active.png b/doc/development/ux_guide/img/button-success--active.png
new file mode 100644
index 00000000000..895a52831cb
Binary files /dev/null and b/doc/development/ux_guide/img/button-success--active.png differ
diff --git a/doc/development/ux_guide/img/button-success--hover.png b/doc/development/ux_guide/img/button-success--hover.png
new file mode 100644
index 00000000000..e4c74bd9778
Binary files /dev/null and b/doc/development/ux_guide/img/button-success--hover.png differ
diff --git a/doc/development/ux_guide/img/button-success--resting.png b/doc/development/ux_guide/img/button-success--resting.png
new file mode 100644
index 00000000000..2fa971b5347
Binary files /dev/null and b/doc/development/ux_guide/img/button-success--resting.png differ
diff --git a/doc/development/ux_guide/img/button-success-secondary--active.png b/doc/development/ux_guide/img/button-success-secondary--active.png
new file mode 100644
index 00000000000..e7383b36946
Binary files /dev/null and b/doc/development/ux_guide/img/button-success-secondary--active.png differ
diff --git a/doc/development/ux_guide/img/button-success-secondary--hover.png b/doc/development/ux_guide/img/button-success-secondary--hover.png
new file mode 100644
index 00000000000..4af2a68cf1b
Binary files /dev/null and b/doc/development/ux_guide/img/button-success-secondary--hover.png differ
diff --git a/doc/development/ux_guide/img/button-success-secondary--resting.png b/doc/development/ux_guide/img/button-success-secondary--resting.png
new file mode 100644
index 00000000000..a5a4ec512c8
Binary files /dev/null and b/doc/development/ux_guide/img/button-success-secondary--resting.png differ
diff --git a/doc/development/ux_guide/img/button-warning--active.png b/doc/development/ux_guide/img/button-warning--active.png
new file mode 100644
index 00000000000..5877d46c94d
Binary files /dev/null and b/doc/development/ux_guide/img/button-warning--active.png differ
diff --git a/doc/development/ux_guide/img/button-warning--hover.png b/doc/development/ux_guide/img/button-warning--hover.png
new file mode 100644
index 00000000000..308e1adc8a3
Binary files /dev/null and b/doc/development/ux_guide/img/button-warning--hover.png differ
diff --git a/doc/development/ux_guide/img/button-warning--resting.png b/doc/development/ux_guide/img/button-warning--resting.png
new file mode 100644
index 00000000000..28e5e601520
Binary files /dev/null and b/doc/development/ux_guide/img/button-warning--resting.png differ
diff --git a/doc/development/ux_guide/img/color-blue.png b/doc/development/ux_guide/img/color-blue.png
index 2ca360173eb..844e926f1f5 100644
Binary files a/doc/development/ux_guide/img/color-blue.png and b/doc/development/ux_guide/img/color-blue.png differ
diff --git a/doc/development/ux_guide/img/color-green.png b/doc/development/ux_guide/img/color-green.png
index 489db8f4343..5c4c23c7067 100644
Binary files a/doc/development/ux_guide/img/color-green.png and b/doc/development/ux_guide/img/color-green.png differ
diff --git a/doc/development/ux_guide/img/color-grey.png b/doc/development/ux_guide/img/color-grey.png
index 58c474d5ce9..5247649a0ce 100644
Binary files a/doc/development/ux_guide/img/color-grey.png and b/doc/development/ux_guide/img/color-grey.png differ
diff --git a/doc/development/ux_guide/img/color-orange.png b/doc/development/ux_guide/img/color-orange.png
index 4c4b772d438..1103c715225 100644
Binary files a/doc/development/ux_guide/img/color-orange.png and b/doc/development/ux_guide/img/color-orange.png differ
diff --git a/doc/development/ux_guide/img/color-red.png b/doc/development/ux_guide/img/color-red.png
index 3440ad48f05..77ecbbc0a20 100644
Binary files a/doc/development/ux_guide/img/color-red.png and b/doc/development/ux_guide/img/color-red.png differ
diff --git a/doc/development/ux_guide/img/icon-add.png b/doc/development/ux_guide/img/icon-add.png
index 0d4c1a7692a..bcad5e84591 100644
Binary files a/doc/development/ux_guide/img/icon-add.png and b/doc/development/ux_guide/img/icon-add.png differ
diff --git a/doc/development/ux_guide/img/icon-close.png b/doc/development/ux_guide/img/icon-close.png
index 88d2b3b0c6d..dfe1495f5fa 100644
Binary files a/doc/development/ux_guide/img/icon-close.png and b/doc/development/ux_guide/img/icon-close.png differ
diff --git a/doc/development/ux_guide/img/icon-edit.png b/doc/development/ux_guide/img/icon-edit.png
index f73be7a10fb..50f6f841868 100644
Binary files a/doc/development/ux_guide/img/icon-edit.png and b/doc/development/ux_guide/img/icon-edit.png differ
diff --git a/doc/development/ux_guide/img/icon-notification.png b/doc/development/ux_guide/img/icon-notification.png
index 4758632edd7..6ddfaa44f66 100644
Binary files a/doc/development/ux_guide/img/icon-notification.png and b/doc/development/ux_guide/img/icon-notification.png differ
diff --git a/doc/development/ux_guide/img/icon-rss.png b/doc/development/ux_guide/img/icon-rss.png
index c7ac9fb1349..b766488b32d 100644
Binary files a/doc/development/ux_guide/img/icon-rss.png and b/doc/development/ux_guide/img/icon-rss.png differ
diff --git a/doc/development/ux_guide/img/icon-subscribe.png b/doc/development/ux_guide/img/icon-subscribe.png
index 5cb277bfd5d..650168296c6 100644
Binary files a/doc/development/ux_guide/img/icon-subscribe.png and b/doc/development/ux_guide/img/icon-subscribe.png differ
diff --git a/doc/development/ux_guide/img/icon-trash.png b/doc/development/ux_guide/img/icon-trash.png
index 357289a6fff..b02178ca992 100644
Binary files a/doc/development/ux_guide/img/icon-trash.png and b/doc/development/ux_guide/img/icon-trash.png differ