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