# SCSS

> This document is a work-in-progress.

This is README containing thoughts and information about organization, methodology, exceptions, etc. in regards to CSS architecture and implementation. In general, UND attempts to follow the guidelines outlined by [SASS Guidelines](https://sass-guidelin.es) when possible.

UND implements semantic CSS via BEM and also utilizes CSS utility classes when appropriate to minimize the CSS footprint.

## Table of Contents

- [Architecture](#architecture)
- [Authoring](#authoring)
- [Flags](#flags)
- [Imports](#imports)
- [Methodology](#methodology)
- [Scoping](#scoping)

## Architecture

UND follows the [7-1 Pattern](https://sass-guidelin.es/#the-7-1-pattern), but is not beholden to it. The core concepts to take away is that SCSS files should be relatively atomic and like files organized into folders.

All files in the following folders should be imported into `style.scss`.

**Current Structure**

base/
components/
helpers/
pages/
partials/
utilities/
vendor/
  <vendor name>/
    <vendor file A>
    <vendor file B>
    <vendor file C>
vendor-extensions/
  <vendor name>/
    <vendor file C>

Root folders are allowed sub folders when appropriate.

- **Base Folder:** Some of the most basic styles go here; reset CSS, fonts, typography. Basically anything with very low specificity (`0001`) like styles applied directory to an HTML elements (no classes or IDs).
- **Components Folder:** Small, modular, and re-usable features. Button styles are a good example.
- **Helpers Folder:** All utility classes should go here. Utilities classes are standalone classes that do not need any other classes to be fully implemented (though there might be an occasional modifier). If what you're working on is implementing BEM, then it's probably not a utility and is likely a component or partial.
- **Pages Folder:** Styles that are particular to certain pages, either specifically or conceptually (i.e. Universal, Landing, etc. template pages).
- **Partials Folder:** Anything that is considered page structure (i.e. header, footer, sidebar, navigation) should go in here. This includes utility classes like grid and grid-like features. Some items in this folder could be considered components, but as a whole, often represent a larger page structure, i.e. forms.
- **Utilities Folder:** Typically, files in this folder are used by the SASS preprocessor and will not output any styles on their own.
- **Vendor Folder:** Third-party libraries go here (if you're not using npm.) Files in this folder should be untouched. If modifications need to be made, create a vendor extension file in `vendor-extensions/<library name>`. All vendor files should be placed in their own folder within this folder.
- **Vendor Extensions Folder:** Modifications to any styles in the _Vendor_ folder should be made here. This could be as simple as a few CSS selectors that need different property values to a complete copy-n-paste from the source file in the _Vendor_ folder for extensive modifications. Files in this folder should mimic the structure of the vendor folder.

## Authoring

The following is a short list of practices that UND attempts to following when authoring SCSS. It is not fully exhaustive and at times, might go against what is in SASS Guidelines.

1. Always use the parent selector (`&`). While the parent selector is not always necessary, explicitly using it makes intention, and the resulting selector, more clear.

The following example (of creating a complex selector ) isn't encouraged, but it does occur from time-to-time for various reasons and when it does, should be authored like the following:

// Incorrect
.styled-list {
  li { … }
}

// Correct
.styled-list {
  & li { … }
}

2. When authoring BEM selectors, do not create element classes within the block definition.

// Incorrect
.styled-list {
  &__item { … }
  &__link { … }
}

// Correct
.styled-list { … }
.styled-list__item { … }
.styled-list__link { … }

3. **Do create** modifiers within their respective definitions, after the block/element properties.

// Incorrect
.styled-list { … }
.styled-list--sm { … }
.styled-list--lg { … }
.styled-list__item--sm { … }
.styled-list__item--lg { … }

// Correct
.styled-list {
  // Block styles

  // Modifiers
  &--sm { … }
  &--lg { … }
}

.styled-list__item {
  // Element styles

  // Modifiers
  &--sm { … }
  &--lg { … }
}

## Flags

As updates are made, any issues or areas that might need modification should be marked with a SCSS flag. A SCSS flag takes the form of a comment that contains a word or phrase that looks like a global constant in other programming languages, i.e. THIS_IS_A_FLAG.

These flags help identify like problems across all SCSS partial files with a simple find performed in the users IDE.

| Flag | Description |
|---|---|
| **ANIMATION_FILE** | Move all animations to a single location/file. |
| **COMPONENTIFY** | This feature has the potential to become a base component as it has been used more than once or many times. |
| **COMPONENT_THEME_DEPRECATED** | NEEDS TESTING. CSS selector may be a candidate to be removed or replaced by component level theming (tints). Specifically, can/will `.module--themed` be replaced by `.tint-themed`? |
| **DEPRECATED** | CSS selector, often in combination with an implementation approach, that is being phased out. |
| **DUPLICATION** | Catch all for styles that might have been unnecessarily duplicated. Investigate first before creating mixin/placeholder/function etc. |
| **EDITABLE_REGION_MARKER** | We need our editable regions to be defined in the markup to so we can get consistent spacing between templates, snippets, etc. Right now we sometimes have to write ugly selectors because wrapper DIVs do not exist for our editable regions. |
| **FONT_ISSUE** | The default font for the most comment elements (p, ul, li) are set to the least used of our three brand fonts. This requires a lot of resetting, i.e. `.content p`. We need to undo this as Sentinel leaks through too often when it shouldn't. Helvetica Neue should be the default. |
| **IE11_FLEXBOX** | As the name implies, adjustments specifically for IE11 and Flexbox. Explains why a possible atypical property and/or value of a property is being used. Informational. |
| **IE11_SVG** | As the name implies, adjustments specifically for IE11 and Flexbox. Explains why a possible atypical property and/or value of a property is being used. Informational. |
| **MANUAL_FLUID_SPACING** | Although some of these situations cannot be avoided, like targeting a specific breakpoint or two, the problem with manual fluid spacing implementations is that they are not directly tied to how fluid spacing and breakpoints are configured. If the `$spacing-fluid` variable is updated to use different values, that change will not be reflected with these elements. So we need to mark them for easy discovery if spacing configuration is changed. This closely related to, and can overlap, implementations marked `SLICE_SPCAING` or `SPLICE_SPACING`. |
| **NESTED_ACCORDION_TABS** | While accordions and tabs should not be nested within one another, in the instances they do appear, code marked with this flag is fixing with tab focus or similar. |
| **RENAME** | CSS selector needs renaming. Reasons for renaming may include: <ul><li>ambiguous name</li><li>be more expressive/accurate</li><li>not consistent with existing naming conventions</li><li>re-align to new naming conventions</li><li>synonym for existing selector</li><li>not quite BEM</li></ul> |
| **SASS_EXTEND_AVOID** | A different selector is being used than preferred because of the SASS_EXTEND_ISSUE. Once extend issues are fixed, selectors marked with this flag can be changed. |
| **SASS_EXTEND_ISSUE** | <p>Using SASS `@extend` can cause issues if used with little knowledge of what it does.</p><ol><li>It can create selectors that you were not expecting. This is mostly related to using the child combinator (`>`). These selectors can bloat your CSS and introduce unintended styles. Though gzip likely mitigates most of the bloat.</li><li>Introduce non-obvious specificity issues, specifically those related to the cascade. Extensions occur at the location of the class being extended. This can be fixed by using `!important`, though that fix sometimes causes a cascade of `!important` statements. Avoid if possible.</li><li>Selector bloat (extraneous, unintended selectors) is a real posibility when both the extending selector and the referenced selector are lienient and are complex selectors.</li><li>See [SASS Guidelines, Extend](https://sass-guidelin.es/#extend) for more details.</li></ol><p>See, https://webinista.com/updates/dont-use-extend-sass/ for examples.</p><p><strong>Example #1</strong></p><pre>.alpha {<br> border-color: blue;<br> & > .beta {<br> color: orange;<br> }<br>}<br><br>.beta {<br> color: red;<br>}<br><br>.charlie {<br> border: 1px solid black;<br> & > div {<br> @extend .alpha;<br> }<br>}</pre><p>Compiles to:</p><pre>.alpha,<br>.charlie > div {<br> border-color: blue;<br>}<br><br>.alpha > .beta,<br>.charlie > div > .beta {<br> color: orange;<br>}<br><br>.beta {<br> color: red;<br>}<br><br>.charlie {<br> border: 1px solid black;<br>}</pre><p>The intent here is for any `.beta` that is a child of `.alpha` to have orange text. But notice that any child `<div>` of `.charlie` that has a child `.beta` will also have orange text (instead of red). While these types of class nesting issues rarely appear, it is something to be aware of when using `@extend`.</p><p><strong>Example #2</strong></p><pre>.alpha {<br> @extend .charlie;<br> border-color: blue;<br>}<br><br>.beta {<br> color: red;<br>}<br><br>.charlie {<br> border: 1px solid black;<br>}</pre><p>Compiles to:</p><pre>.alpha {<br> border-color: blue;<br>}<br><br>.beta {<br> color: red;<br>}<br><br>.charlie,<br>.alpha {<br> border: 1px solid black;<br>}</pre><p>Although there was an attempt to override the border color of `.charlie` in `.alpha`, `.alpha` is extended at the location of `.charlie` which is after `.alpha`. Both selectors have the same specificity so the cascade determines which selector gets to define the border color.</p> |
| **SCSS_IMPORT_ORDER** | Properties identified by this flag are properties that are overrides and might be fixed by swapping up import order and/or not auto-loading SCSS files. |
| **SERIF_XL_ALT** | Create mixin, utility class or similar to do what `-alt` does in `.serif--xl-alt`. In this instance `-alt` is a font re-sizing feature. |
| **SLICE_SPACING** | References a method where we remove top/bottom spacing, typically for snippets, where inner elements provide their own bottom spacing and outer spacing is also defined. In these instances, the inner spacing and outer spacing combine to create more spacing than is desired; inner spacing is subtracted from the outer spacing.</p><p>This flag is applied where the `slice-fluid-spacing()` mixin cannot be used or a modification(s) is made to a breakpoint that the mixin has applied.</p><p>This flag also overlaps with `MANUAL_FLUID_SPACING` flag.</p><p>**Example:**<br>The _Stats Snippet_ has inner elements that provide `1rem` bottom margin and the snippet itself applies `3.5rem` of bottom margin. This will combine to `4.5rem` of spacing (depending on styling between the margins, they won't always collapse). To get our `3.5rem` visually spacing we subtract `1rem` from `3.5rem`. |
| **SNIPPET_HEADING_ISSUE** | <p>After launching the site, we updated the size, color, and fonts of headings.</p><p>This flag has to do with the way we attempted to maintain the styles of headings in snippets after that update. The current issue is that we cannot simply apply `.h4` to desired elements as the snippet attribute selector in `_snippets.scss` (i.e. `[class^="ous-"]`) is too specific so we have to resort to `@extend h4`. Investigate solutions.</p> |
| **SNIPPET_HEADING_SPACING** | <p>Some snippets have a top margin that, if proceeded with a heading (h2, h3, etc) will create more whitespace than we would like. This flag exists to mark places where it is currently being used and to signify that we need to review if the current implementation is adequate (i.e. add all headings vs some).</p><p>This fix is currently being applied with the placeholder `%heading_guard`.</p> |
| **SPLICE_SPACING** | See `SLICE_SPCAING`, but space is added instead of subtracted. |
| **SPACING_PLACEHOLDER** | Uses fixed and/or temporary var/mixin/placeholders until official spacing updates arrive. Placeholder versions of this could be converted to a `fluid-spacing()` mixin built on the `$spacing-fluid` variable. |
| **THEMIFY_CALIBRATE** | Designates a theme key that might need to be adjusted in the future or have a new theme key created to handle contrast issues. |
| **TINT_REQUIRED** | Check if the current property needs to be set for component theming (tints). This is most often applied to the `color` property when the value being set on the element is the same value as the tint value. New component level theming sets `color` by default for all tints. Some `color` properties may still need to be applied due to an ancestor element changing `color` within a tint element. |
| **TO_SASS_VARIABLE** | A CSS property value is boilerplate value or used in many places. Define a variable in `_vars.scss`. |
| **TO_XSL** | Helper class can be added to XSL. Possibly add modifier class to target for styling. |
| **TUITION_SIMPLIFY** | `_tuition-calc.scss` and `_tuition-table.scss` have duplicated styling. Merge duplicated styling into a single, reusable class. **VERIFY WHAT CLASSES THE JS IS USING BEFORE DOING THIS.** |
| **VIEWPORT_FULL_WIDTH** | Can be replaced by a viewport helper class/mixin. |

## Imports

When importing SCSS partial files, import them in alphabetical order. This makes an import list easier to parse (see and find what is being imported).

> **Note:** This practice can, and will be ignored, when more important concerns arise. For example, in the `/base` folder, for performance and FOUC reasons, we need to load `_fonts.scss` before anything else. Alphabetical order **should not** be ignored because one needs to fix an issue related to the cascade in CSS. If the cascade is causing an issue, fix the selector(s) in question.

Imports should also be explicit. Which means, at some point, each file should be manually imported and glob imports (`/**/*.scss`) should not be used. There are a few reasons for this practice:

- Files with a list of imports act as a table of contents. Making it easing to see what is being imported and what order.
- Simple comments can be associated with each import when needed. This is not possible when glob importing.
- While glob importing is often a short, concise one-liner, it's not obvious what is being imported and one or more folders will need to be investigated to see what is imported.
- Glob importing cannot implement potential priority ordering. **Note:** priority ordering should not be used to fix CSS cascade issue, fix the selector(s) in question when this happens.
- While this should not matter for CSS, it can be an issue with other resources; glob imports can be imported in a different order depending on the OS that is running the build script.

## Methodology

UND combines two common methodologies with its CSS; utility first CSS and semantic CSS (BEM). Currently, UND CSS contains more semantic CSS than utility CSS. While UND continues to add and implement more utility classes, it is likely that UND CSS will always have some balance of the two methodologies.

### Semantic CSS

Semantic CSS uses CSS class names to describe what is being styled, i.e. `.author-list`. This makes the CSS dependent on HTML structure, and makes HTML "lighter". Semantic CSS also makes it easier to provide hooks for JS, although, IDs and `data-` attributes should also be considered as hooks for JS.

#### When to Implement?

Almost always. Even if a particular partial or component heavily (or completely) relies on utility classes for styling, adding semantic BEM classes is almost always beneficial.

- This helps delineate where one feature/block/element begins and another ends.
- Allows us to use tools like SiteImprove to track and find instances of various features on the UND site.
- Omni CMS presents a situation where whole folders or sites may need to be re-published for a fix. Having explicit semantic classes, even with no styling attached, simplifies and make the application of a "hotfix" more direct until proper implementation can be conducted.
- Non-styled BEM selectors should be added to both the HTML and SCSS. This is a form of documenting that reduces the need for investigation, i.e. one does not have to search through XSL to see if the original author added a BEM element selector that the current author can use or needs to create. It can also help prevent the creation of selectors that are meant to target the same element but have the same name.

##### Example

The "styled" list below might only change the default margin and padding to the `<ul>` along with a top border flourish. Everything else is default styling for the `<li>` and optional `<a>`. Following the guidelines above would result in the following HTML and SCSS.

###### HTML

<ul class="styled-list">
  <li class="styled-list__item">
    Lorem ipsum dolor.
  </li>
  <li class="styled-list__item">
    <a href="#" class="styled-list__link">
      Lorem ipsum dolor
    </a>
  </li>
</ul>

###### SCSS

.styled-list {
  margin: 2rem 0 3rem;
  padding: 0 0 0 3rem;
  border-top: 4px solid #009a44;
}

.styled-list__item {}

.styled-list__link {}

### Utility-First CSS

> Utility classes in the UND CSS are a work in progress. Many areas need to be expanded upon or even started. UND also needs to consider if utility placeholders should be created that all utility classes are derived from.

Utility-first CSS uses CSS class names that have a single responsibility (defines a single CSS property). This makes our CSS agnostic of our HTML structure, but makes our HTML dependent on the CSS. HTML weight is also increased with this approach as multiple classes must be applied to get a desired result, but is great for prototyping as all styles already exist.

Do we want to implement the following pattern?

#### Example

// in /utilities/_placeholders.scss
%text-bold {
  font-weight: bold !important;
}

%text-serif {
  font-family: 'Sentinel SSm A', 'Sentinel SSm B', 'Trocchi', 'Georgia', serif !important;
}

// in /helpers/_text.scss
.text-bold {
  @extend %text-bold;
}

.text-serif {
  @extend %text-serif;
}

Then you could compose semantic BEM with utilities internally.

.styled-list {
  @extend %text-bold, %text-serif;
}

### Specificity

In short, ID and element selectors should be avoided and class selectors favored in almost all instances.

- CSS selectors should avoid being complex selectors (having multiple classes, IDs, elements referenced in the selector).
- Specificity should be kept at a minimum at all times.
- Inline CSS should only be applied when there is a specific, well reasoned (and documented) reason to do so.
- Implementing BEM resolves most specificity issues and eliminates high specificity ("ugly") selectors, i.e. `.some-selector > div > span .grand-child > div`.

## Scoping

While BEM is at the core of our semantic CSS app
// The following may or may not be used but
// are listed here to show the options test

// Scopes: specific themes, style
// College | Internal | Programs | Action
[class^="s-"],
[class*=" s-"] {}
.s-college,
.s-center,
.s-internal,
.s-program {}

// Templates: essentially page layouts/shells
// Universal | Home | Landing | College Home
// Program Finder | Program Page
[class^="t-"],
[class*=" t-"] {}
.t-home,
.t-landing,
.t-college-home,
.t-program-finder,
.t-program-page,
.t-universal {}

// OU Actions [oua]
// Preview = prv, Publish = pub, Edit = edt
// These match the variables in the xsl
[class^="oua-"],
[class*=" oua-"] {}
.oua-prv,
.oua-pub,
.oua-edt{}