theme.md (c2f8f34e19ef7b9987538e8c2624e629b5203c17) theme.md (7385e139b0c9efca7430458cee982e63e282f4ae)
1# Theme customization
1# Theme customization
2
2Customization of the application requires knowledge of Sass and CSS. It also
3will require becoming familiar with the Bootstrap and Bootstrap-Vue component
4libraries. This section outlines the global options and variables that can be
5removed or updated to meet organizational brand guidelines.
6
7## Environment specific builds
3Customization of the application requires knowledge of Sass and CSS. It also
4will require becoming familiar with the Bootstrap and Bootstrap-Vue component
5libraries. This section outlines the global options and variables that can be
6removed or updated to meet organizational brand guidelines.
7
8## Environment specific builds
9
8Any organization can create a build that meets their branding and other
9customization needs. This includes customization of the state store, routing,
10application navigation, and theming.
11
12[Read more in the Build Customization section](/customization/build)
13
14### Configuring environment specific builds
10Any organization can create a build that meets their branding and other
11customization needs. This includes customization of the state store, routing,
12application navigation, and theming.
13
14[Read more in the Build Customization section](/customization/build)
15
16### Configuring environment specific builds
17
15The complete instructions can be found in the `env` directory in a file called
18The complete instructions can be found in the `env` directory in a file called
16env.md or by viewing the [Configuring environment specific builds
17page](./env.md)
19env.md or by viewing the
20[Configuring environment specific builds page](./env.md)
18
19## Bootstrap Sass Options
21
22## Bootstrap Sass Options
23
20The Bootstrap Sass options are global styling toggles. The naming convention for
21these built-in variables is `enabled-*`.
22
23### $enable-rounded
24The Bootstrap Sass options are global styling toggles. The naming convention for
25these built-in variables is `enabled-*`.
26
27### $enable-rounded
28
24This option enables or disables the border-radius styles on various components.
25
26- Set to `false` to remove rounded corners on all container elements and buttons
27
28### $enable-validation-icons
29This option enables or disables the border-radius styles on various components.
30
31- Set to `false` to remove rounded corners on all container elements and buttons
32
33### $enable-validation-icons
34
29This option enables or disables background-image icons within textual inputs and
30some custom forms for validation states.
31
32- Set to `false` due to inability to style icons using CSS
33
34### More information
35This option enables or disables background-image icons within textual inputs and
36some custom forms for validation states.
37
38- Set to `false` due to inability to style icons using CSS
39
40### More information
35- [View all the Bootstrap Sass
36 Options](https://getbootstrap.com/docs/4.2/getting-started/theming/#sass-options)
37
41
42- [View all the Bootstrap Sass Options](https://getbootstrap.com/docs/4.2/getting-started/theming/#sass-options)
43
38## Bootstrap Sass Variables
44## Bootstrap Sass Variables
45
39These are global variables that Bootstrap defines in the
40`/node_modules/bootstrap/scss/variables.scss` helper file. Adding a variable
41listed in this file to the `/src/assets/styles/bmc/helpers/_variables.scss` file
42will override the Bootstrap defined value.
43
44### $transition-base
46These are global variables that Bootstrap defines in the
47`/node_modules/bootstrap/scss/variables.scss` helper file. Adding a variable
48listed in this file to the `/src/assets/styles/bmc/helpers/_variables.scss` file
49will override the Bootstrap defined value.
50
51### $transition-base
52
45This variable sets the base CSS transition style throughout the application.
53This variable sets the base CSS transition style throughout the application.
54
46- Set to `all $duration--moderate-02 $standard-easing--productive`
47
48### $transition-fade
55- Set to `all $duration--moderate-02 $standard-easing--productive`
56
57### $transition-fade
58
49This variable sets the transition when showing and hiding elements.
50
51- Set to `opacity $duration--moderate-01 $standard-easing--productive`
52
53### $transition-collapse
59This variable sets the transition when showing and hiding elements.
60
61- Set to `opacity $duration--moderate-01 $standard-easing--productive`
62
63### $transition-collapse
64
54This variable sets the CSS transitions throughout the application when expanding
55and collapsing elements.
56
57- Set to `height $duration--slow-01 $standard-easing--expressive`
58
59### More Information
65This variable sets the CSS transitions throughout the application when expanding
66and collapsing elements.
67
68- Set to `height $duration--slow-01 $standard-easing--expressive`
69
70### More Information
60- [Carbon Design System Motion
61 Guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/)
62- [Including Animation In Your Design
63 System](https://www.smashingmagazine.com/2019/02/animation-design-system/)
64
71
72- [Carbon Design System Motion Guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/)
73- [Including Animation In Your Design System](https://www.smashingmagazine.com/2019/02/animation-design-system/)
74
65## OpenBMC Custom Sass Options
66
67### $responsive-layout-bp
75## OpenBMC Custom Sass Options
76
77### $responsive-layout-bp
78
68This variable determines when the primary navigation is hidden and when the
69hamburger menu is displayed. The breakpoint is defined using a Bootstrap
70function that only accepts a key from the Bootstrap `$grid-breakpoints` map.
71
72- xs - Navigation is always displayed
73- sm - Navigation displayed when the viewport is greater than 576px
74- md - Navigation displayed when the viewport is greater than 768px
75- lg - Navigation displayed when the viewport is greater than 992px
76- xl - Navigation displayed when the viewport is less than 1200px
77
78#### Responsive Resources
79This variable determines when the primary navigation is hidden and when the
80hamburger menu is displayed. The breakpoint is defined using a Bootstrap
81function that only accepts a key from the Bootstrap `$grid-breakpoints` map.
82
83- xs - Navigation is always displayed
84- sm - Navigation displayed when the viewport is greater than 576px
85- md - Navigation displayed when the viewport is greater than 768px
86- lg - Navigation displayed when the viewport is greater than 992px
87- xl - Navigation displayed when the viewport is less than 1200px
88
89#### Responsive Resources
79- [Bootstrap responsive
80 breakpoints](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
81- [Bootstrap Sass
82 Mixins](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
83- [Customizing the Bootstrap
84 Grid](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
85
90
91- [Bootstrap responsive breakpoints](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
92- [Bootstrap Sass Mixins](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
93- [Customizing the Bootstrap Grid](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints)
94
86### $header-height
95### $header-height
96
87This variable determines the height of the OpenBMC Web UI header element.
88
89- Default value: 56px
90
91### $navigation-width
97This variable determines the height of the OpenBMC Web UI header element.
98
99- Default value: 56px
100
101### $navigation-width
102
92This variable determines the width of the primary navigation menu when expanded.
93
94- Default value: 300px
95
96### $container-bgd
103This variable determines the width of the primary navigation menu when expanded.
104
105- Default value: 300px
106
107### $container-bgd
108
97This option sets the background of page containers. Changing the value of this
98variable will change the background color for the following elements:
109This option sets the background of page containers. Changing the value of this
110variable will change the background color for the following elements:
99- Login page
111
112- Login page
100- Primary navigation section
101- Quick links section on the overview page
102
103#### Value
113- Primary navigation section
114- Quick links section on the overview page
115
116#### Value
117
104- Default value: $gray-200
105
106### $primary-nav-hover
118- Default value: $gray-200
119
120### $primary-nav-hover
121
107The semantic naming of this variable identifies its purpose. This color should
108always be slightly darker than the `$container-bgd` value.
109
110- Default value: $gray-300
111
112## Updating Colors
122The semantic naming of this variable identifies its purpose. This color should
123always be slightly darker than the `$container-bgd` value.
124
125- Default value: $gray-300
126
127## Updating Colors
128
113Supporting a different color palette is a simple process. The default color
114palette is supported using the Sass variables outlined in the color guidelines
129Supporting a different color palette is a simple process. The default color
130palette is supported using the Sass variables outlined in the color guidelines
115and color maps outlined in the theme's overview. The following sections provide
131and color maps outlined in the theme's overview. The following sections provide
116directions to update the settings to meet your organization's needs.
117
118### Color
132directions to update the settings to meet your organization's needs.
133
134### Color
135
119The OpenBMC Web UI uses Sass variables and maps to build its layout and
120components. Bootstrap variables and maps use the `!default` flag to allow for
121overrides. There are three Sass maps created to establish the color palette.
122These include the `color` map, `theme-color` map, and `gray` map. These maps are
123used by Bootstrap to build the application's CSS stylesheets.
124
125#### All Colors
136The OpenBMC Web UI uses Sass variables and maps to build its layout and
137components. Bootstrap variables and maps use the `!default` flag to allow for
138overrides. There are three Sass maps created to establish the color palette.
139These include the `color` map, `theme-color` map, and `gray` map. These maps are
140used by Bootstrap to build the application's CSS stylesheets.
141
142#### All Colors
143
126The OpenBMC Web UI custom colors are available as Sass variables and a Sass map
127in `/src/assets/styles/bmc/helpers/_variables.scss`. The OpenBMC theme only
128requires a subset of the colors to create the look and feel of the application.
129Adding, removing, or updating the color variables and map is how the application
130color palette can be customized. Using these variables outside of the helper
131files is discouraged to avoid tightly coupling the OpenBMC Web UI theme to
132specific colors.
133
134The `color` map is not as important as the `theme-color` map. A tight-coupling
135of the Sass variable name to the color name makes it hard to use the `color` map
136keys for customization. Using these keys in Sass stylesheets or single-file
137components is discouraged.
138
139#### Theme Colors
144The OpenBMC Web UI custom colors are available as Sass variables and a Sass map
145in `/src/assets/styles/bmc/helpers/_variables.scss`. The OpenBMC theme only
146requires a subset of the colors to create the look and feel of the application.
147Adding, removing, or updating the color variables and map is how the application
148color palette can be customized. Using these variables outside of the helper
149files is discouraged to avoid tightly coupling the OpenBMC Web UI theme to
150specific colors.
151
152The `color` map is not as important as the `theme-color` map. A tight-coupling
153of the Sass variable name to the color name makes it hard to use the `color` map
154keys for customization. Using these keys in Sass stylesheets or single-file
155components is discouraged.
156
157#### Theme Colors
158
140The theme color variables and the `theme-color` map consist of a subset of the
141color variables. This smaller color palette creates a scheme that is not
142dependent on specific colors like blue or green. Several of the Bootstrap
143`theme-color` map keys are required to generate the CSS styles. The OpenBMC Web
144UI `theme-color` map has the same keys as the Bootstrap `theme-color` map with
145custom values.
146
147The `theme-color` map is used heavily throughout the application. The
148Bootstrap-Vue components `variant` prop also utilizes the `theme-color` map.
149This map is the key to customizing the application's color palette. Take a look
150at the [color guidelines](/guide/guidelines/colors) to better understand default
151theme-colors map.
152
153#### Gray Colors
159The theme color variables and the `theme-color` map consist of a subset of the
160color variables. This smaller color palette creates a scheme that is not
161dependent on specific colors like blue or green. Several of the Bootstrap
162`theme-color` map keys are required to generate the CSS styles. The OpenBMC Web
163UI `theme-color` map has the same keys as the Bootstrap `theme-color` map with
164custom values.
165
166The `theme-color` map is used heavily throughout the application. The
167Bootstrap-Vue components `variant` prop also utilizes the `theme-color` map.
168This map is the key to customizing the application's color palette. Take a look
169at the [color guidelines](/guide/guidelines/colors) to better understand default
170theme-colors map.
171
172#### Gray Colors
173
154The gray color palette contains nine shades of gray that range from light to
155dark. Bootstrap sets a default gray color value for each color variable from
156100-900 in increments of one hundred, for example, `$gray-100`, `$gray-200`,
157`$gray-300` through `gray-900`. Bootstrap does not create a color map for any of
158the colors except gray. The Bootstrap documentation indicates that adding color
159maps for all the default colors is scheduled to be delivered in a future patch.
160The OpenBMC Web UI color theme overrides all shades of the Bootstrap default
161gray variable values.
162
174The gray color palette contains nine shades of gray that range from light to
175dark. Bootstrap sets a default gray color value for each color variable from
176100-900 in increments of one hundred, for example, `$gray-100`, `$gray-200`,
177`$gray-300` through `gray-900`. Bootstrap does not create a color map for any of
178the colors except gray. The Bootstrap documentation indicates that adding color
179maps for all the default colors is scheduled to be delivered in a future patch.
180The OpenBMC Web UI color theme overrides all shades of the Bootstrap default
181gray variable values.
182
163[Learn more about Bootstrap
164colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color)
183[Learn more about Bootstrap colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color)
165
166### Bootstrap Color Functions
184
185### Bootstrap Color Functions
186
167- `color('<color map key>)`
168- `theme-color('<theme color map key>)`
169- `gray('<gray color palette key'>)`
170
187- `color('<color map key>)`
188- `theme-color('<theme color map key>)`
189- `gray('<gray color palette key'>)`
190
171
172#### Example
191#### Example
192
173```SCSS
174.some-selector {
175 color: color("blue");
176 background: theme-color("light");
177 border: 1px solid gray("900")
178}
179```
180
193```SCSS
194.some-selector {
195 color: color("blue");
196 background: theme-color("light");
197 border: 1px solid gray("900")
198}
199```
200
181[Learn more about using Bootstrap
182functions](https://getbootstrap.com/docs/4.0/getting-started/theming/#functions)
201[Learn more about using Bootstrap functions](https://getbootstrap.com/docs/4.0/getting-started/theming/#functions)
202
183## Adding a logo
203## Adding a logo
204
184The updated page header can include a small logo. The guidelines for adding a
185logo and the suggested logo dimensions are currently in progress. It may be
186challenging to meet all organization brand guidelines due to the minimal height
187of the page header. The company logo might be able to be set in the primary
188navigation, but a design supporting that option will be the focus of future
189design work.
205The updated page header can include a small logo. The guidelines for adding a
206logo and the suggested logo dimensions are currently in progress. It may be
207challenging to meet all organization brand guidelines due to the minimal height
208of the page header. The company logo might be able to be set in the primary
209navigation, but a design supporting that option will be the focus of future
210design work.