{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"paragraph","content":[{"text":"With the styling power that CSS provides as a base technology, it is very easy and tempting to write styles that apply in one situation that should not in another. In line with our architectural goal of composition, we now target component styles using the ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]},{"text":"Block Element Modifier (BEM)","type":"text"},{"text":" naming convention. While this is not foolproof because all styles still reside within the global namespace within a web browser, the BEM convention drastically reduces the likelihood of a style regression caused by naming clashes, specificity battles and the Cascade. We manipulate basic CSS by using SCSS, a superset of CSS that offers features that allow succinct authoring techniques while outputting selectors that appropriately target markup while also allowing extensibility by other developers.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#172b4d"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Implementation","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SCSS usage","type":"text"}]},{"type":"paragraph","content":[{"text":"As part of the Tui framework we made the decision to switch our CSS preprocessor over to SCSS. SCSS has become the leading CSS preprocessor and provides us with better build performance.","type":"text"}]},{"type":"paragraph","content":[{"text":"The existing CSS from the Basis theme has already been converted over to SCSS in the ","type":"text"},{"text":"Legacy theme","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff0000"}},{"type":"link","attrs":{"href":"https://totara.atlassian.net/wiki/spaces/DEV/pages/121185020"}}]},{"text":". The Ventura CSS sits on top of the existing legacy styles, but is predominantly CSS variable overrides from core Tui component style definitions.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Key differences between SCSS and LESS","type":"text"}]},{"type":"paragraph","content":[{"text":"SCSS is an imperative language while LESS is a declarative language - this impacts where and how variables should be defined. Previously with LESS, variables could be used before their declaration and if defined multiple times the last definition was used throughout, while with SCSS the variables must be defined before use.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Global variable","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"sass"},"content":[{"text":"$red: #ff0000;","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Chaining/static variables","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"sass"},"content":[{"text":"$red: #ff0000 !default;","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Creating a mixin","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"sass"},"content":[{"text":"@mixin box-shadow($shadow) {\n\tbox-shadow: $shadow;\n}","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Calling a mixin","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"@include box-shadow($shadow);","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Block Element Modifier (BEM) methodology","type":"text"}]},{"type":"paragraph","content":[{"text":"We have introduced the BEM methodology as part of the Tui framework.","type":"text"}]},{"type":"paragraph","content":[{"text":"BEM is a popular CSS naming methodology. The key benefits of using this methodology are that it provides a consistent approach throughout the code base and helps you to manage both inheritance and specificity.","type":"text"}]},{"type":"paragraph","content":[{"text":"BEM provides elements with unique classes allowing CSS to be targeted at particular use cases. This essentially creates a limited scope where styles are applied, reducing the amount of styles inherited through the cascade. Elements having unique classes also reduces the need to have nested CSS selectors when targeting a particular element, which often leads to issues with specificity.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following example shows how the BEM class structure has been applied to the checkbox component:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"

\n\t\n\tOK\n

","type":"text"}]},{"type":"paragraph","content":[{"text":"For classes with multiple words we use the camelCase naming convention:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"

\n\t\n\tOK\n

","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Blocks","type":"text"}]},{"type":"paragraph","content":[{"text":"A BEM block is a standalone entity that is meaningful on its own. They can be nested but semantically they remain equal. Within Tui we treat each of our Vue components as a block entity.","type":"text"}]},{"type":"paragraph","content":[{"text":"The block sets the class namespace for all of its inner elements which semantically ties them together. The block name should be descriptive enough to express what it is and unique enough to avoid name conflicts with other blocks. For multi-word block names we use camel case.","type":"text"},{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Checkbox block entity","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"

...

","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The Tui framework has a convention of prefixing each block with ","type":"text"},{"text":"tui-","type":"text","marks":[{"type":"code"}]},{"text":", this should not be used by non-totara components or plug-ins. ","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Elements","type":"text"}]},{"type":"paragraph","content":[{"text":"Each block has its own set of unique elements which cannot be used or styled by other blocks and have no stand-alone meaning. Their classes are prefixed with the block class followed by a double underscore.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"

\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Sub-elements further extend their parent element class with a dash prefix. ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"

\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Blocks with several layers of elements usually suggests that a subcomponent is more appropriate.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Modifiers","type":"text"}]},{"type":"paragraph","content":[{"text":"The modifier is a flag used to modify the appearance, state or behaviour of a block or element. Examples of modifiers include ","type":"text"},{"text":"disabled","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"active","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"large","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"small","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"hasButton","type":"text","marks":[{"type":"code"}]},{"text":". The modifiers allow blocks to be customised while keeping the styles self-contained. Modifiers should be used instead of overwriting the styles from outside of the block with specificity.","type":"text"}]},{"type":"paragraph","content":[{"text":"Modifiers are prefixed with the block class followed by a double dash.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"

","type":"text"}]},{"type":"paragraph","content":[{"text":"Block modifiers will usually be enabled or disabled by their parent components, within Vue we use standalone boolean props to manage this.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Block","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Parent block","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Variables","type":"text"}]},{"type":"paragraph","content":[{"text":"Within the Tui framework we have two types of style variables, SCSS variables and CSS variables.","type":"text"}]},{"type":"paragraph","content":[{"text":"CSS variables are the preferred approach going forward but there are a number of places where we are required to have static variables such as in CSS media queries.","type":"text"}]},{"type":"paragraph","content":[{"text":"In Totara 16 and earlier we only support root-level CSS variables to allow for full compatibility with IE11.","type":"text"}]},{"type":"paragraph","content":[{"text":"Global variables are fetched before the static and component CSS and are included from the following file:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"client/component/tui/src/global_styles/_variables.scss","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Static CSS","type":"text"}]},{"type":"paragraph","content":[{"text":"For any styles that can't be generated at a component level or for elements that aren't generated by components we have a static SCSS file. The styles in this file are included before any of the component styles.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"html"},"content":[{"text":"client/component/tui/src/global_styles/static.scss","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Importing SCSS","type":"text"}]},{"type":"paragraph","content":[{"text":"To import more ","type":"text"},{"text":".scss","type":"text","marks":[{"type":"strong"}]},{"text":" files into ","type":"text"},{"text":"static.scss","type":"text","marks":[{"type":"strong"}]},{"text":", use the system component-based frankenstyle import paths (for example ","type":"text"},{"text":"@import 'theme_customtheme/oldstyles/totara/nav';","type":"text","marks":[{"type":"strong"}]},{"text":"), rather than relative importing, which is not supported at this time.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Code style","type":"text"}]},{"type":"paragraph","content":[{"text":"A number of minor coding style changes were introduced as part of the Tui frameworks.","type":"text"}]},{"type":"paragraph","content":[{"text":"SCSS uses 2 space indentation instead of 4 space and rule ordering was introduced for the CSS to keep the code more consistent. We enforce this with Prettier during the development and integration process.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Sizing and helpers","type":"text"}]},{"type":"paragraph","content":[{"text":"Generally, all sizing is derived from the root font size. In Totara 19 and later, this is the browser default, equivalent to ","type":"text"},{"text":"16px","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Most other sizes in Totara are derived from the root font size, via the ","type":"text"},{"text":"rem","type":"text","marks":[{"type":"code"}]},{"text":" unit.","type":"text"}]},{"type":"paragraph","content":[{"text":"You can convert a pixel value to the equivalent ","type":"text"},{"text":"rem","type":"text","marks":[{"type":"code"}]},{"text":" value using the ","type":"text"},{"text":"rem-px","type":"text","marks":[{"type":"code"}]},{"text":" helper. For example, ","type":"text"},{"text":"rem-px(32)","type":"text","marks":[{"type":"code"}]},{"text":" evaluates to ","type":"text"},{"text":"2rem","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"expand","attrs":{"title":"Totara 18 and earlier"},"content":[{"type":"paragraph","content":[{"text":"In Totara 18 and earlier, the root font size is ","type":"text"},{"text":"10px","type":"text","marks":[{"type":"code"}]},{"text":" and these helpers are not available, as the math to convert to ","type":"text"},{"text":"rem","type":"text","marks":[{"type":"code"}]},{"text":" is very simple.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tips and known limitations","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Style isolation","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"paragraph","content":[{"text":"The Tui framework does aim at style isolation, however it does not make use of real isolation via the Shadow DOM. This particular feature was not initially used because we required support for IE11, which does not support the Shadow DOM. There is an alternative available within Vue SFCs, 'scoped styles', however we also have not adopted this approach which generates a unique identifier and applies that to selectors. The reason we have not adopted this approach is because of style inheritance across themes - if there is a unique identifier on a given selector then a child theme wanting to override that selector would need to also somehow know about the unique identifier.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"paragraph","content":[{"text":"Because we have not adopted Shadow DOM style encapsulation or scoped styles, all styles are still in the global scope. We rely on the BEM naming convention to greatly decrease the likelihood of selector clashes.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"paragraph","content":[{"text":"Because of our ongoing dependency on the Legacy theme, which styles parts of the UI such as the primary navigation and footer, we still have globally scoped Bootstrap and Legacy-based far-reaching styles battling for dominance with Tui framework specifics. We could not rely on the CSS value ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"unset","type":"text","marks":[{"type":"code"}]},{"text":" because that too is not supported in IE11, therefore, Tui components provide the overrides they need to operate in isolation.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SCSS functions and CSS Variables","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"paragraph","content":[{"text":"As part of the switch to SCSS several of the existing methods are no longer supported. Any methods that manipulate a passed non-predefined value such as a CSS variable will no longer work, this includes the following: ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"Darken()","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"Lighten()","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"mix()","type":"text","marks":[{"type":"code"}]},{"text":" & ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"button-variant()","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Recommended reading","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"getbem","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}},{"type":"link","attrs":{"href":"http://getbem.com/"}}]},{"text":" provides a great overview of the BEM methodology","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"https://caniuse.com/","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}},{"type":"link","attrs":{"href":"https://caniuse.com/"}}]},{"text":" For checking compatibility with your supported browsers","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SCSS ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"official documentation","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}},{"type":"link","attrs":{"href":"https://sass-lang.com/documentation"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Guidance","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}},{"type":"link","attrs":{"href":"http://8gramgorilla.com/mastering-sass-extends-and-placeholders/"}}]},{"text":" on using SCSS ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"@extends","type":"text","marks":[{"type":"code"}]},{"text":" and %","type":"text","marks":[{"type":"textColor","attrs":{"color":"#003366"}}]},{"text":"placeholders","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Mozilla overview of ","type":"text"},{"text":"CSS variables","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties"}}]}]}]}]}],"version":1}