summaryrefslogtreecommitdiff
path: root/docs/customization/theme.md
diff options
context:
space:
mode:
authorPatrick Williams <patrick@stwcx.xyz>2022-12-08 15:13:13 +0300
committerPatrick Williams <patrick@stwcx.xyz>2022-12-08 15:13:13 +0300
commit7385e139b0c9efca7430458cee982e63e282f4ae (patch)
tree1bbdb0164e556b76eec72cb558c66974c8f95dd8 /docs/customization/theme.md
parentb24a483eda5ca0b0ecdb4f0c61b90d76d0d8e1e0 (diff)
downloadwebui-vue-7385e139b0c9efca7430458cee982e63e282f4ae.tar.xz
prettier: re-format
Prettier is enabled in openbmc-build-scripts on Markdown, JSON, and YAML files to have consistent formatting for these file types. Re-run the formatter on the whole repository. Change-Id: I2804ee3ab5ff6bcbf986b028db2fafec8e616779 Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Diffstat (limited to 'docs/customization/theme.md')
-rw-r--r--docs/customization/theme.md63
1 files changed, 42 insertions, 21 deletions
diff --git a/docs/customization/theme.md b/docs/customization/theme.md
index 6dbce1a9..10e062d3 100644
--- a/docs/customization/theme.md
+++ b/docs/customization/theme.md
@@ -1,10 +1,12 @@
# 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.
@@ -12,59 +14,68 @@ 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)
+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)
+
+- [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/)
+
+- [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.
@@ -76,46 +87,52 @@ function that only accepts a key from the Bootstrap `$grid-breakpoints` map.
- 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)
+
+- [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
+
+- 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
+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.
@@ -123,6 +140,7 @@ 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.
@@ -137,6 +155,7 @@ 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
@@ -151,6 +170,7 @@ 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`,
@@ -160,16 +180,16 @@ 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)
+[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");
@@ -178,9 +198,10 @@ colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color)
}
```
-[Learn more about using Bootstrap
-functions](https://getbootstrap.com/docs/4.0/getting-started/theming/#functions)
+[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