diff options
Diffstat (limited to 'docs/themes')
| -rw-r--r-- | docs/themes/customize.md | 187 | ||||
| -rw-r--r-- | docs/themes/env.md | 149 | ||||
| -rw-r--r-- | docs/themes/readme.md | 339 |
3 files changed, 0 insertions, 675 deletions
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('<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. 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.<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 - -> [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` - > 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 `<ENV_NAME>.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 `<ENV_NAME>.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 `_<ENV_NAME>.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 `<style>` block to -support Sass compilation. Although it is possible to prepend these helpers in -webpack, it will break any use of imported single-file components used in the -Vuepress documentation. - -### _obmc-custom.scss``` -``` -. -├─ src - ├─ assets - ├─ styles - └─ _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) |