From c2f8f34e19ef7b9987538e8c2624e629b5203c17 Mon Sep 17 00:00:00 2001 From: Derick Montague Date: Wed, 12 May 2021 12:26:18 -0500 Subject: 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 Change-Id: Iad245199048f65f346e6c033a766605f303b0ade --- docs/.vuepress/config.js | 6 +- docs/customization/build.md | 162 ++++++++++++++++++ docs/customization/readme.md | 371 ++++++++++++++++++++++++++++++++++++++++ docs/customization/theme.md | 189 ++++++++++++++++++++ docs/guide/guidelines/colors.md | 2 +- docs/themes/customize.md | 187 -------------------- docs/themes/env.md | 149 ---------------- docs/themes/readme.md | 339 ------------------------------------ 8 files changed, 726 insertions(+), 679 deletions(-) create mode 100644 docs/customization/build.md create mode 100644 docs/customization/readme.md create mode 100644 docs/customization/theme.md delete mode 100644 docs/themes/customize.md delete mode 100644 docs/themes/env.md delete mode 100644 docs/themes/readme.md (limited to 'docs') diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index e48e1662..257b6fe1 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -13,8 +13,8 @@ module.exports = { link: "/guide/" }, { - text: "Themes", - link: "/themes/" + text: "Customization", + link: "/customization/" }, { text: "Github", @@ -66,7 +66,7 @@ module.exports = { ] } ], - "/themes/": ["", "customize", "env"] + "/customization/": ["", "theme", "build"] }, } }; \ No newline at end of file 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.` 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 `.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 `.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 `.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 `_.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 ` +``` + +### Scoped style block using CSS + +```html + +``` + +### Example - PageSection.vue + +```html + +``` + +:::tip +You might notice that there is an HTML element, `

`, 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(')` +- `theme-color(')` +- `gray(')` + + +#### 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. diff --git a/docs/guide/guidelines/colors.md b/docs/guide/guidelines/colors.md index d73a0373..3ba91b6a 100644 --- a/docs/guide/guidelines/colors.md +++ b/docs/guide/guidelines/colors.md @@ -5,7 +5,7 @@ values, along with additional blue, green, red, and yellow color variables used as accent colors for components. The `.scss` component files use these accent colors to override default styles set by the Bootstrap library. -- [Learn more about theme customization](/themes/) +- [Learn more about theme customization](/customization/theme/) - [Open an issue in the OpenBMC webui-vue repo](https://github.com/openbmc/webui-vue/issues/new/choose) to request a change diff --git a/docs/themes/customize.md b/docs/themes/customize.md deleted file mode 100644 index 763333d9..00000000 --- a/docs/themes/customize.md +++ /dev/null @@ -1,187 +0,0 @@ -# How to customize -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. - -### 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(')` -- `theme-color(')` -- `gray(')` - - -#### 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. diff --git a/docs/themes/env.md b/docs/themes/env.md deleted file mode 100644 index fb1a7562..00000000 --- a/docs/themes/env.md +++ /dev/null @@ -1,149 +0,0 @@ -# Configuring environment specific builds - -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.` 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 - -> [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 `.js` file in `src/env/store` - > 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 - -> [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 `.js` file in `src/env/router` - > 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). - > 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 `.js` file in `src/env/components/AppNavigation` - > 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 - ->[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 `_.scss` partial in `src/env/assets/styles` - > 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 -``` \ No newline at end of file diff --git a/docs/themes/readme.md b/docs/themes/readme.md deleted file mode 100644 index bc4d7648..00000000 --- a/docs/themes/readme.md +++ /dev/null @@ -1,339 +0,0 @@ - -# Overview - - This section discusses the structure and purpose of the theme 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 File Structure -``` -. -├─ src - ├─ assets - ├─ styles - ├─ bmc - ├─ custom - └─ helpers - ├─ bootstrap - ├─ _helpers.scss - └─ _obmc-custom.scss -``` - -## bmc -This folder contains Sass helpers and default styles for customizing the OpenBMC -Web UI. - -``` -. -├─ 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 - ├─ _colors.scss - ├─ _functions.scss - ├─ _index.scss - ├─ _motion.scss - └─ _variables.scss -``` -### custom -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. - -### helpers -The helper's folder contains a set of Sass helper files containing Sass -variables that establish the custom theme of the application. - -#### _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 [theme customization section](/themes/customize). - -### bootstrap -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. - -``` -. -├─ src - ├─ assets - ├─ styles - ├─ bootstrap - ├─ _helpers.scss - └─ _index.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. - -### _helpers.scss -``` -. -├─ src - ├─ assets - ├─ styles - ├─ _helpers.scss -``` -The `_helpers.scss` file is an import file needed when building single-file -components that require the use of BMC or Bootstrap Sass variables and -functions. This file needs to be imported as part of the ` -``` - -### Scoped style block using CSS -```html - -``` - -### Example - PageSection.vue -```html - -``` - -:::tip -You might notice that there is an HTML element, `

`, 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) -- cgit v1.2.3