1# Presentation Layer Architecture
2
3This section discusses the structure and purpose of the SCSS files and how to
4customize the application using Bootstrap theming.
5
6[Read more about Bootstrap
7Theming](https://getbootstrap.com/docs/4.0/getting-started/theming)
8
9## SCSS Directory Structure
10
11### `bmc` Directory
12
13The `bmc` directory contains Sass helpers and default styles for customizing the OpenBMC
14Web UI.
15
16```{5}
17.
18├─ src
19   ├─ assets
20      ├─ styles
21         ├─ bmc
22            ├─ custom
23            └─ helpers
24         ├─ bootstrap
25         └─ _obmc-custom.scss
26```
27
28### `custom` Directory
29
30The `custom` Directory imports all the styles needed to customize the UI. These
31are small changes used to reach parity with the OpenBMC Design Workgroup's
32agreed-upon design. The file naming convention closely follows the Bootstrap or
33Boostrap-vue library file naming since most of the ruleset selectors in these
34files are based on these two libraries.
35
36```{6}
37.
38├─ src
39   ├─ assets
40      ├─ styles
41         ├─ bmc
42            ├─ custom
43               ├─ alert.scss
44               ├─ _badge.scss
45               ├─ _base.scss
46               ├─ _bootstrap-grid.scss
47               ├─ _buttons.scss
48               ├─ _calendar.scss
49               ├─ _card.scss
50               ├─ _dropdown.scss
51               ├─ _forms.scss
52               ├─ _index.scss
53               ├─ _kvm.scss
54               ├─ _modal.scss
55               ├─ _pagination.scss
56               ├─ _sol.scss
57               ├─ _tables.scss
58               └─ _toasts.scss
59         ├─ helpers
60         ├─ bootstrap
61         └─ _obmc-custom.scss
62```
63
64### `helpers` Directory
65
66The `helpers` directory contains a set of Sass helper files containing Sass
67variables that establish the custom theme of the application.
68
69```{6}
70.
71├─ src
72   ├─ assets
73      ├─ styles
74         ├─ bmc
75         ├─ helpers
76                ├─ _colors.scss
77                ├─ _functions.scss
78                ├─ _index.scss
79                ├─ _motion.scss
80                └─ _variables.scss
81         ├─ bootstrap
82         └─ _obmc-custom.scss
83```
84
85#### `_colors.scss`
86
87The `_colors.scss` file sets all the SASS variables and color maps for the OpenBMC
88Web UI. Any color settings needed to meet company brand guidelines will happen
89in this file.
90
91##### Sass Color Variables
92
93```scss
94$black: #000;
95$white: #fff;
96
97$blue-500: #2d60e5;
98$green-500: #0a7d06;
99$red-500: #da1416;
100$yellow-500: #efc100;
101
102$gray-100: #f4f4f4;
103$gray-200: #e6e6e6;
104$gray-300: #d8d8d8;
105$gray-400: #cccccc;
106$gray-500: #b3b3b3;
107$gray-600: #999999;
108$gray-700: #666666;
109$gray-800: #3f3f3f;
110$gray-900: #161616;
111```
112
113##### Custom Color Variables
114
115```scss
116// Sass Base Color Variables
117$blue: $blue-500;
118$green: $green-500;
119$red: $red-500;
120$yellow: $yellow-500;
121```
122
123##### Custom Colors Map
124
125```scss
126$colors: (
127  "blue": $blue,
128  "green": $green,
129  "red": $red,
130  "yellow": $yellow,
131);
132```
133
134##### Custom Theme Color Variables
135
136```scss
137// Sass Theme Color Variables
138// Can be used as variants
139$danger: $red;
140$dark: $gray-900;
141$info: $blue;
142$light: $gray-100;
143$primary: $blue;
144$secondary: $gray-800;
145$success: $green;
146$warning: $yellow;
147```
148
149##### Custom Theme Colors Map
150
151```scss
152$theme-colors: (
153  "primary": $primary,
154  "secondary": $secondary,
155  "dark": $dark,
156  "light": $light,
157  "danger": $danger,
158  "info": $info "success": $success "warning": $warning,
159);
160```
161
162##### Color Resources
163
164- [Learn more about Bootstrap
165  colors](https://getbootstrap.com/docs/4.0/getting-started/theming/#color)
166- [Learn more about Bootstrap
167  variables](https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables)
168- [View the color palette and hex values in the color
169  guidelines](/guide/guidelines/colors)
170
171#### `_functions.scss`
172
173Two functions provide a customized way to set color highlights. The
174`theme-color-light` and `theme-color-dark` are custom functions used to create
175colors for the `alert`, `badge`, `card`, and `toast` components. They have also
176set color highlights for some pseudo-elements like `: hover`.
177
178##### Functions
179
180```scss
181// This function is usually used to get a lighter
182// theme variant color to use as a background color
183@function theme-color-light($variant) {
184  @return theme-color-level($variant, -11.3);
185}
186
187@function theme-color-dark($variant) {
188  @return theme-color-level($variant, 2);
189}
190```
191
192##### Examples
193
194```scss{8-10,16}
195.b-table-sort-icon-left {
196    background-position: left calc(1.5rem / 2) center !important;
197    padding-left: calc(1.2rem + 0.65em) !important;
198    &:focus {
199      outline: none;
200      box-shadow: inset 0 0 0 2px theme-color('primary') !important;
201    }
202    &:hover {
203      background-color: theme-color-dark('light');
204    }
205  }
206}
207
208&.alert-info {
209border-left-color: theme-color("info");
210background-color: theme-color-light("info");
211fill: theme-color("info");
212}
213```
214
215#### `_motion.scss`
216
217This bezier curves and durations in this file determine the motion styles
218throughout the application. These guidelines from the Cabon Design System avoid
219easing curves that are unnatural, distracting, or purely decorative.
220
221##### Motion Styles
222
223```scss
224$duration--fast-01: 70ms; //Micro-interactions such as button and toggle
225$duration--fast-02: 110ms; //Micro-interactions such as fade
226$duration--moderate-01: 150ms; //Micro-interactions, small expansion, short distance movements
227$duration--moderate-02: 240ms; //Expansion, system communication, toast
228$duration--slow-01: 400ms; //Large expansion, important system notifications
229$duration--slow-02: 700ms; //Background dimming
230
231$standard-easing--productive: cubic-bezier(0.2, 0, 0.38, 0.9);
232$standard-easing--expressive: cubic-bezier(0.4, 0.14, 0.3, 1);
233$entrance-easing--productive: cubic-bezier(0, 0, 0.38, 0.9);
234$entrance-easing--expressive: cubic-bezier(0, 0, 0.3, 1);
235$exit-easing--productive: cubic-bezier(0.2, 0, 1, 0.9);
236$exit-easing--expressive: cubic-bezier(0.4, 0.14, 1, 1);
237```
238
239##### Example
240
241```scss{6,9}
242.link-skip-nav {
243  position: absolute;
244  top: -60px;
245  left: 0.5rem;
246  z-index: $zindex-popover;
247  transition: $duration--moderate-01 $exit-easing--expressive;
248  &:focus {
249    top: 0.5rem;
250    transition-timing-function: $entrance-easing--expressive;
251  }
252}
253```
254
255##### Motion Resources
256
257- [Including Animation In Your Design
258  System](https://www.smashingmagazine.com/2019/02/animation-design-system/)
259- [Carbon Design System motion
260  guidelines](https://www.carbondesignsystem.com/guidelines/motion/basics/)
261
262#### `_variables.scss`
263
264This file contains all the global Sass options. There are Bootstrap option
265overrides, Bootstrap global variable overrides, and custom BMC global variables.
266Read more about these in the [Customization section](/customize/theme).
267
268### `bootstrap` Directory
269
270The `bootstrap` directory contains all the import references. The references are
271split into multiple files to support import order based on dependency. Helper
272styles need to be imported before all other styles.
273
274```{6}
275.
276├─ src
277   ├─ assets
278      ├─ styles
279         ├─ bmc
280         ├─ bootstrap
281            ├─ _helpers.scss
282            └─ _index.scss
283         └─ _obmc-custom.scss
284```
285
286#### `_helpers.scss`
287
288This file contains all the helper import references for Bootstrap.
289
290#### `_index.scss`
291
292This file contains all the import references needed to support the base,
293components, and utility styles.
294
295### `_obmc-custom.scss`
296
297```{9}
298.
299├─ src
300   ├─ assets
301      ├─ styles
302         ├─ bmc
303         ├─ bootstrap
304         └─ _obmc-custom.scss
305```
306
307The `obmc-custom.scss` file defines all of the presentational layer
308dependencies.
309
310- [Read more about Bootstrap
311  options](https://getbootstrap.com/docs/4.0/getting-started/theming/#sass-options)
312- [Read more about
313  Importing](https://getbootstrap.com/docs/4.0/getting-started/theming/#importing)
314
315## Component / View Styles
316
317Some stylistic changes only apply to a single-file component or view instance.
318In this case, rather than adding a Sass file, the scoped styles include the
319styles in the component's `<style>` block. It is required to import the
320`_helpers` Sass file when using a BMC or Bootstrap variable in the component's
321`<style>` block. Without this import, webpack cannot compile the OpenBMC Web UI
322CSS styles correctly.
323
324### Scoped style block using SASS
325
326```html
327<style scoped lang="scss">
328  ...
329</style>
330```
331
332### Scoped style block using CSS
333
334```html
335<style scoped>
336  ...;
337</style>
338```
339
340### Example - PageSection.vue
341
342```html
343<style lang="scss" scoped>
344  .page-section {
345    margin-bottom: $spacer * 2;
346  }
347
348  h2 {
349    @include font-size($h3-font-size);
350    margin-bottom: $spacer;
351    &::after {
352      content: "";
353      display: block;
354      width: 100px;
355      border: 1px solid $gray-300;
356      margin-top: 10px;
357    }
358  }
359</style>
360```
361
362:::tip
363You 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.
364:::
365
366[Learn more about single file components](https://vuejs.org/v2/guide/single-file-components.html)
367
368Customization of the application requires knowledge of Sass and CSS. It also
369will require becoming familiar with the Bootstrap and Bootstrap-Vue component
370libraries. This section outlines the global options and variables that can be
371removed or updated to meet organizational brand guidelines.
372