diff options
Diffstat (limited to 'docs/customization')
| -rw-r--r-- | docs/customization/build.md | 162 | ||||
| -rw-r--r-- | docs/customization/readme.md | 371 | ||||
| -rw-r--r-- | docs/customization/theme.md | 189 |
3 files changed, 722 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 +``` diff --git a/docs/customization/readme.md b/docs/customization/readme.md new file mode 100644 index 00000000..64118060 --- /dev/null +++ b/docs/customization/readme.md @@ -0,0 +1,371 @@ +# Presentation Layer Architecture + +This section discusses the structure and purpose of the SCSS files and how to +customize the application using Bootstrap theming. + +[Read more about Bootstrap +Theming](https://getbootstrap.com/docs/4.0/getting-started/theming) + +## SCSS Directory Structure + +### `bmc` Directory + +The `bmc` directory contains Sass helpers and default styles for customizing the OpenBMC +Web UI. + +```{5} +. +├─ src + ├─ assets + ├─ styles + ├─ bmc + ├─ custom + └─ helpers + ├─ bootstrap + └─ _obmc-custom.scss +``` + +### `custom` Directory + +The `custom` Directory imports all the styles needed to customize the UI. These +are small changes used to reach parity with the OpenBMC Design Workgroup's +agreed-upon design. The file naming convention closely follows the Bootstrap or +Boostrap-vue library file naming since most of the ruleset selectors in these +files are based on these two libraries. + +```{6} +. +├─ src + ├─ assets + ├─ styles + ├─ bmc + ├─ custom + ├─ alert.scss + ├─ _badge.scss + ├─ _base.scss + ├─ _bootstrap-grid.scss + ├─ _buttons.scss + ├─ _calendar.scss + ├─ _card.scss + ├─ _dropdown.scss + ├─ _forms.scss + ├─ _index.scss + ├─ _kvm.scss + ├─ _modal.scss + ├─ _pagination.scss + ├─ _sol.scss + ├─ _tables.scss + └─ _toasts.scss + ├─ helpers + ├─ bootstrap + └─ _obmc-custom.scss +``` + +### `helpers` Directory + +The `helpers` directory contains a set of Sass helper files containing Sass +variables that establish the custom theme of the application. + +```{6} +. +├─ src + ├─ assets + ├─ styles + ├─ bmc + ├─ helpers + ├─ _colors.scss + ├─ _functions.scss + ├─ _index.scss + ├─ _motion.scss + └─ _variables.scss + ├─ bootstrap + └─ _obmc-custom.scss +``` + +#### `_colors.scss` + +The `_colors.scss` file sets all the SASS variables and color maps for the OpenBMC +Web UI. Any color settings needed to meet company brand guidelines will happen +in this file. + +##### Sass Color Variables + +```scss +$black: #000; +$white: #fff; + +$blue-500: #2d60e5; +$green-500: #0a7d06; +$red-500: #da1416; +$yellow-500: #efc100; + +$gray-100: #f4f4f4; +$gray-200: #e6e6e6; +$gray-300: #d8d8d8; +$gray-400: #cccccc; +$gray-500: #b3b3b3; +$gray-600: #999999; +$gray-700: #666666; +$gray-800: #3f3f3f; +$gray-900: #161616; +``` + +##### Custom Color Variables + +```scss +// Sass Base Color Variables +$blue: $blue-500; +$green: $green-500; +$red: $red-500; +$yellow: $yellow-500; +``` + +##### Custom Colors Map + +```scss +$colors: ( + "blue": $blue, + "green": $green, + "red": $red, + "yellow": $yellow, +); +``` + +##### Custom Theme Color Variables + +```scss +// Sass Theme Color Variables +// Can be used as variants +$danger: $red; +$dark: $gray-900; +$info: $blue; +$light: $gray-100; +$primary: $blue; +$secondary: $gray-800; +$success: $green; +$warning: $yellow; +``` + +##### Custom Theme Colors Map + +```scss +$theme-colors: ( + "primary": $primary, + "secondary": $secondary, + "dark": $dark, + "light": $light, + "danger": $danger, + "info": $info "success": $success "warning": $warning, +); +``` + +##### Color Resources + +- [Learn more about Bootstrap + colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color) +- [Learn more about Bootstrap + variables](https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables) +- [View the color palette and hex values in the color + guidelines](/guide/guidelines/colors) + +#### `_functions.scss` + +Two functions provide a customized way to set color highlights. The +`theme-color-light` and `theme-color-dark` are custom functions used to create +colors for the `alert`, `badge`, `card`, and `toast` components. They have also +set color highlights for some pseudo-elements like `: hover`. + +##### Functions + +```scss +// This function is usually used to get a lighter +// theme variant color to use as a background color +@function theme-color-light($variant) { + @return theme-color-level($variant, -11.3); +} + +@function theme-color-dark($variant) { + @return theme-color-level($variant, 2); +} +``` + +##### Examples + +```scss{8-10,16} +.b-table-sort-icon-left { + background-position: left calc(1.5rem / 2) center !important; + padding-left: calc(1.2rem + 0.65em) !important; + &:focus { + outline: none; + box-shadow: inset 0 0 0 2px theme-color('primary') !important; + } + &:hover { + background-color: theme-color-dark('light'); + } + } +} + +&.alert-info { +border-left-color: theme-color("info"); +background-color: theme-color-light("info"); +fill: theme-color("info"); +} +``` + +#### `_motion.scss` + +This bezier curves and durations in this file determine the motion styles +throughout the application. These guidelines from the Cabon Design System avoid +easing curves that are unnatural, distracting, or purely decorative. + +##### Motion Styles + +```scss +$duration--fast-01: 70ms; //Micro-interactions such as button and toggle +$duration--fast-02: 110ms; //Micro-interactions such as fade +$duration--moderate-01: 150ms; //Micro-interactions, small expansion, short distance movements +$duration--moderate-02: 240ms; //Expansion, system communication, toast +$duration--slow-01: 400ms; //Large expansion, important system notifications +$duration--slow-02: 700ms; //Background dimming + +$standard-easing--productive: cubic-bezier(0.2, 0, 0.38, 0.9); +$standard-easing--expressive: cubic-bezier(0.4, 0.14, 0.3, 1); +$entrance-easing--productive: cubic-bezier(0, 0, 0.38, 0.9); +$entrance-easing--expressive: cubic-bezier(0, 0, 0.3, 1); +$exit-easing--productive: cubic-bezier(0.2, 0, 1, 0.9); +$exit-easing--expressive: cubic-bezier(0.4, 0.14, 1, 1); +``` + +##### Example + +```scss{6,9} +.link-skip-nav { + position: absolute; + top: -60px; + left: 0.5rem; + z-index: $zindex-popover; + transition: $duration--moderate-01 $exit-easing--expressive; + &:focus { + top: 0.5rem; + transition-timing-function: $entrance-easing--expressive; + } +} +``` + +##### Motion Resources + +- [Including Animation In Your Design + System](https://www.smashingmagazine.com/2019/02/animation-design-system/) +- [Carbon Design System motion + guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/) + +#### `_variables.scss` + +This file contains all the global Sass options. There are Bootstrap option +overrides, Bootstrap global variable overrides, and custom BMC global variables. +Read more about these in the [Customization section](/customize/theme). + +### `bootstrap` Directory + +The `bootstrap` directory contains all the import references. The references are +split into multiple files to support import order based on dependency. Helper +styles need to be imported before all other styles. + +```{6} +. +├─ src + ├─ assets + ├─ styles + ├─ bmc + ├─ bootstrap + ├─ _helpers.scss + └─ _index.scss + └─ _obmc-custom.scss +``` + +#### `_helpers.scss` + +This file contains all the helper import references for Bootstrap. + +#### `_index.scss` + +This file contains all the import references needed to support the base, +components, and utility styles. + +### `_obmc-custom.scss` + +```{9} +. +├─ src + ├─ assets + ├─ styles + ├─ bmc + ├─ bootstrap + └─ _obmc-custom.scss +``` + +The `obmc-custom.scss` file defines all of the presentational layer +dependencies. + +- [Read more about Bootstrap + options](https://getbootstrap.com/docs/4.0/getting-started/theming/#sass-options) +- [Read more about + Importing](https://getbootstrap.com/docs/4.0/getting-started/theming/#importing) + +## Component / View Styles + +Some stylistic changes only apply to a single-file component or view instance. +In this case, rather than adding a Sass file, the scoped styles include the +styles in the component's `<style>` block. It is required to import the +`_helpers` Sass file when using a BMC or Bootstrap variable in the component's +`<style>` block. Without this import, webpack cannot compile the OpenBMC Web UI +CSS styles correctly. + +### Scoped style block using SASS + +```html +<style scoped lang="scss"> + ... +</style> +``` + +### Scoped style block using CSS + +```html +<style scoped> + ...; +</style> +``` + +### Example - PageSection.vue + +```html +<style lang="scss" scoped> + .page-section { + margin-bottom: $spacer * 2; + } + + h2 { + @include font-size($h3-font-size); + margin-bottom: $spacer; + &::after { + content: ""; + display: block; + width: 100px; + border: 1px solid $gray-300; + margin-top: 10px; + } + } +</style> +``` + +:::tip +You might notice that there is an HTML element, `<h2>`, used in the example. This is an anti-pattern in global `.scss` files. However, in a single file component that generates the markup it is acceptable. +::: + +[Learn more about single file components](https://vuejs.org/v2/guide/single-file-components.html) + +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. 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. |