Update docs theme section to customization

The themes section of the webui style guide contained a section named
theme. This section also included information about the environmental
builds. The name was misleading and confusing, so we determined in the
GUI Design Work Group to update the section name.

Signed-off-by: Derick Montague <derick.montague@ibm.com>
Change-Id: Iad245199048f65f346e6c033a766605f303b0ade

1 files changed, 162 insertions, 0 deletions

diff --git a/docs/customization/build.md b/docs/customization/build.md
new file mode 100644
index 00000000..b10fd9db
--- /dev/null
+++ b/docs/customization/build.md
@@ -0,0 +1,162 @@
+# Build Customization
+
+This document provides instructions for how to add environment specific
+modifications to the Web UI.
+
+- [Setup](#setup)
+- [Store](#store)
+- [Router](#router)
+- [App Navigation](#app-navigation)
+- [Theming](#theming)
+- [Local development](#local-development)
+- [Production build](#production-build)
+
+## Setup
+
+1. Create a `.env.<ENV_NAME>` file in the project root
+2. Add `NODE_ENV=production` key value pair in the file
+3. Add `VUE_APP_ENV_NAME` key with the value set to the new environment name
+
+Example `.env.ibm`:
+
+```
+NODE_ENV=production
+VUE_APP_ENV_NAME=ibm
+```
+
+## Store
+
+:::tip
+[Vuex store modules](https://vuex.vuejs.org/guide/modules.html) contain the
+application's API calls.
+:::
+
+1. If making customizations to the default store, add `CUSTOM_STORE=true` key
+   value pair to the new .env file.
+2. Create a `<ENV_NAME>.js` file in `src/env/store`
+   :::danger
+   The filename needs to match the `VUE_APP_ENV_NAME` value defined in the
+   .env file. The store import in `src/main.js` will resolve to this new
+   file.
+   :::
+3. Import the base store
+4. Import environment specific store modules
+5. Use the [Vuex](https://vuex.vuejs.org/api/#registermodule) `registerModule`
+   and `unregisterModule` instance methods to add/remove store modules
+6. Add default export
+
+Example `src/env/store/ibm.js`:
+
+```
+import store from '@/store; //@ aliases to src directory
+import HmcStore from './Hmc/HmcStore';
+
+store.registerModule('hmc', HmcStore);
+
+export default store;
+```
+
+## Router
+
+:::tip
+[Vue Router](https://router.vuejs.org/guide/) determines which pages are
+accessible in the UI.
+:::
+
+1. If making customizations to the default router, add `CUSTOM_ROUTER=true` key
+   value pair to the new .env file.
+2. Create a `<ENV_NAME>.js` file in `src/env/router`
+   :::danger
+   The filename needs to match the `VUE_APP_ENV_NAME` value defined in the
+   .env file. The routes import in `src/router/index.js` will resolve to this
+   new file.
+   :::
+3. Define new [routes](https://router.vuejs.org/api/#routes).
+   :::tip
+   Use static imports (over lazy-loading routes) to avoid creating separate
+   JS chunks. Static imports also helps to keep the total build size down.
+   :::
+4. Add default export
+
+## App navigation
+
+The Vue Router definition is closely tied to the app navigation but should be
+configured separately. The Vue Router is responsible for defining the
+application routes which is not always the same as what is visible in the app
+navigation. This configuration will make customizations to the rendered markup
+in src/components/AppNavigation/AppNavigation.vue.
+
+1. If making customizations to the app navigation, add `CUSTOM_APP_NAV=true` key
+   value pair to the new .env file.
+2. Create a `<ENV_NAME>.js` file in `src/env/components/AppNavigation`
+   :::danger
+   The filename needs to match the `VUE_APP_ENV_NAME` value defined in the
+   .env file. The AppNavigationMixin import in
+   `src/components/AppNavigation/AppNavigation.vue` will resolve to this new
+   file.
+   :::
+3. Your custom mixin should follow a very similar structure to the default
+   AppNavigationMixin.js file. It should include a data property named
+   `navigationItems` that should be an array of of navigation objects. Each
+   navigation object should have an `id` and `label` property defined.
+   Optionally it can include `icon`, `route`, or `children` properties.
+4. Add default export
+
+## Theming
+
+:::tip
+[Bootstrap theming](https://getbootstrap.com/docs/4.5/getting-started/theming/)
+allows for easy visual customizations.
+:::
+
+1. If making customizations to the default styles, add `CUSTOM_STYLES=true` key
+   value pair to the new .env file.
+2. Create a `_<ENV_NAME>.scss` partial in `src/env/assets/styles`
+   :::danger
+   The filename needs to match the `VUE_APP_ENV_NAME` value defined in the
+   .env file. The webpack sass loader will attempt to import a file with this
+   name.
+   :::
+3. Add style customizations. Refer to [bootstrap documentation](https://getbootstrap.com/docs/4.5/getting-started/theming/)
+   for details about [color
+   overrides](https://getbootstrap.com/docs/4.5/getting-started/theming/#variable-defaults)
+   and [other customizable
+   options](https://getbootstrap.com/docs/4.5/getting-started/theming/#sass-options).
+
+Example for adding custom colors
+
+`src/env/assets/styles/_ibm.scss`
+
+```
+// Custom theme colors
+
+$primary: rebeccapurple;
+$success: lime;
+```
+
+## Local development
+
+1. Add the same `VUE_APP_ENV_NAME` key value pair to your
+   `env.development.local` file.
+2. Use serve script
+   ```
+   npm run serve
+   ```
+
+## Production build
+
+Run npm build script with vue-cli `--mode` [option
+flag](https://cli.vuejs.org/guide/mode-and-env.html#modes). This requires
+[corresponding .env file to exist](#setup).
+
+```
+npm run build -- --mode ibm
+```
+
+**OR**
+
+pass env variable directly to script
+
+```
+VUE_APP_ENV_NAME=ibm npm run build
+```