1 files changed, 189 insertions, 0 deletions
diff --git a/docs/customization/theme.md b/docs/customization/theme.md
new file mode 100644
index 00000000..6dbce1a9
--- /dev/null
+++ b/docs/customization/theme.md
@@ -0,0 +1,189 @@
+# Theme customization
+Customization of the application requires knowledge of Sass and CSS. It also
+will require becoming familiar with the Bootstrap and Bootstrap-Vue component
+libraries. This section outlines the global options and variables that can be
+removed or updated to meet organizational brand guidelines.
+
+## Environment specific builds
+Any organization can create a build that meets their branding and other
+customization needs. This includes customization of the state store, routing,
+application navigation, and theming.
+
+[Read more in the Build Customization section](/customization/build)
+
+### Configuring environment specific builds
+The complete instructions can be found in the `env` directory in a file called
+env.md or by viewing the [Configuring environment specific builds
+page](./env.md)
+
+## Bootstrap Sass Options
+The Bootstrap Sass options are global styling toggles. The naming convention for
+these built-in variables is `enabled-*`.
+
+### $enable-rounded
+This option enables or disables the border-radius styles on various components.
+
+- Set to `false` to remove rounded corners on all container elements and buttons
+
+### $enable-validation-icons
+This option enables or disables background-image icons within textual inputs and
+some custom forms for validation states.
+
+- Set to `false` due to inability to style icons using CSS
+
+### More information
+- [View all the Bootstrap Sass
+  Options](https://getbootstrap.com/docs/4.2/getting-started/theming/#sass-options)
+
+## Bootstrap Sass Variables
+These are global variables that Bootstrap defines in the
+`/node_modules/bootstrap/scss/variables.scss` helper file. Adding a variable
+listed in this file to the `/src/assets/styles/bmc/helpers/_variables.scss` file
+will override the Bootstrap defined value.
+
+### $transition-base
+This variable sets the base CSS transition style throughout the application.
+- Set to `all $duration--moderate-02 $standard-easing--productive`
+
+### $transition-fade
+This variable sets the transition when showing and hiding elements.
+
+- Set to `opacity $duration--moderate-01 $standard-easing--productive`
+
+### $transition-collapse
+This variable sets the CSS transitions throughout the application when expanding
+and collapsing elements.
+
+- Set to `height $duration--slow-01 $standard-easing--expressive`
+
+### More Information
+- [Carbon Design System Motion
+  Guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/)
+- [Including Animation In Your Design
+  System](https://www.smashingmagazine.com/2019/02/animation-design-system/)
+
+## OpenBMC Custom Sass Options
+
+### $responsive-layout-bp
+This variable determines when the primary navigation is hidden and when the
+hamburger menu is displayed. The breakpoint is defined using a Bootstrap
+function that only accepts a key from the Bootstrap `$grid-breakpoints` map.
+
+- xs - Navigation is always displayed
+- sm - Navigation displayed when the viewport is greater than 576px
+- md - Navigation displayed when the viewport is greater than 768px
+- lg - Navigation displayed when the viewport is greater than 992px
+- xl - Navigation displayed when the viewport is less than 1200px
+
+#### Responsive Resources
+- [Bootstrap responsive
+  breakpoints](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
+- [Bootstrap Sass
+  Mixins](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
+- [Customizing the Bootstrap
+  Grid](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
+
+### $header-height
+This variable determines the height of the OpenBMC Web UI header element.
+
+- Default value: 56px
+
+### $navigation-width
+This variable determines the width of the primary navigation menu when expanded.
+
+- Default value: 300px
+
+### $container-bgd
+This option sets the background of page containers. Changing the value of this
+variable will change the background color for the following elements:
+-  Login page
+- Primary navigation section
+- Quick links section on the overview page
+
+#### Value
+- Default value: $gray-200
+
+### $primary-nav-hover
+The semantic naming of this variable identifies its purpose. This color should
+always be slightly darker than the `$container-bgd` value.
+
+- Default value: $gray-300
+
+## Updating Colors
+Supporting a different color palette is a simple process. The default color
+palette is supported using the Sass variables outlined in the color guidelines
+and color maps outlined in the theme's overview.  The following sections provide
+directions to update the settings to meet your organization's needs.
+
+### Color
+The OpenBMC Web UI uses Sass variables and maps to build its layout and
+components. Bootstrap variables and maps use the `!default` flag to allow for
+overrides. There are three Sass maps created to establish the color palette.
+These include the `color` map, `theme-color` map, and `gray` map. These maps are
+used by Bootstrap to build the application's CSS stylesheets.
+
+#### All Colors
+The OpenBMC Web UI custom colors are available as Sass variables and a Sass map
+in `/src/assets/styles/bmc/helpers/_variables.scss`. The OpenBMC theme only
+requires a subset of the colors to create the look and feel of the application.
+Adding, removing, or updating the color variables and map is how the application
+color palette can be customized. Using these variables outside of the helper
+files is discouraged to avoid tightly coupling the OpenBMC Web UI theme to
+specific colors.
+
+The `color` map is not as important as the `theme-color` map. A tight-coupling
+of the Sass variable name to the color name makes it hard to use the `color` map
+keys for customization. Using these keys in Sass stylesheets or single-file
+components is discouraged.
+
+#### Theme Colors
+The theme color variables and the `theme-color` map consist of a subset of the
+color variables. This smaller color palette creates a scheme that is not
+dependent on specific colors like blue or green. Several of the Bootstrap
+`theme-color` map keys are required to generate the CSS styles. The OpenBMC Web
+UI `theme-color` map has the same keys as the Bootstrap `theme-color` map with
+custom values.
+
+The `theme-color` map is used heavily throughout the application. The
+Bootstrap-Vue components `variant` prop also utilizes the `theme-color` map.
+This map is the key to customizing the application's color palette. Take a look
+at the [color guidelines](/guide/guidelines/colors) to better understand default
+theme-colors map.
+
+#### Gray Colors
+The gray color palette contains nine shades of gray that range from light to
+dark. Bootstrap sets a default gray color value for each color variable from
+100-900 in increments of one hundred, for example, `$gray-100`, `$gray-200`,
+`$gray-300` through `gray-900`. Bootstrap does not create a color map for any of
+the colors except gray. The Bootstrap documentation indicates that adding color
+maps for all the default colors is scheduled to be delivered in a future patch.
+The OpenBMC Web UI color theme overrides all shades of the Bootstrap default
+gray variable values.
+
+[Learn more about Bootstrap
+colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color)
+
+### Bootstrap Color Functions
+- `color('<color map key>)`
+- `theme-color('<theme color map key>)`
+- `gray('<gray color palette key'>)`
+
+
+#### Example
+```SCSS
+.some-selector {
+  color: color("blue");
+  background: theme-color("light");
+  border: 1px solid gray("900")
+}
+```
+
+[Learn more about using Bootstrap
+functions](https://getbootstrap.com/docs/4.0/getting-started/theming/#functions)
+## Adding a logo
+The updated page header can include a small logo. The guidelines for adding a
+logo and the suggested logo dimensions are currently in progress. It may be
+challenging to meet all organization brand guidelines due to the minimal height
+of the page header. The company logo might be able to be set in the primary
+navigation, but a design supporting that option will be the focus of future
+design work.