CSS

1. Approach
   1. CSS MUST be treated as a progressive enhancement
   2. CSS MUST be served as a static file and MUST NOT be compiled at runtime
   3. Compiled CSS MUST NOT contain a source file map in the .css file itself
   4. Compiled CSS SHOULD contain a link to a separate source file (.map.css)
   5. Compiled CSS SHOULD be compressed (e.g. sass --style=compressed [src] [dest])
2. Style/linting
   1. CSS SHOULD adhere to the BEM methodology
   2. CSS MUST be styled with Prettier
      1. Styling CSS with Prettier SHOULD NOT use any custom options (Prettier's philosophy on options)
   3. CSS MUST be linted with Stylelint
      1. Stylelint MUST use the stylelint-selector-bem-pattern plugin
      2. Stylelint COULD use the stylelint-order plugin
      3. Stylelint COULD extend the TNA Frontend stylelint configuration
      4. Stylelint COULD be configured to ignore some rules
3. Style content
   1. CSS colours MUST be defined as either hex values or rgb
   2. CSS colours defined using rgb SHOULD use the newer syntax (rgb(255 128 0) rather than rgb(255, 128, 0))
   3. CSS colours with alpha SHOULD use the newer rgb syntax (e.g. rgb(255 128 0/0.5))
   4. CSS SHOULD work without support for CSS variables
   5. CSS variables COULD be used to enhance customisability
4. Media
   1. If we expect the web content to be printed or saved to a PDF, CSS print styles SHOULD be considered
   2. A <link> element that imports CSS SHOULD have a media attribute defined

SASS/SCSS

SASS is a preprocessor that compiles SASS syntax to CSS. It comes with a loose, indentation-based syntax.

SCSS is a newer SASS syntax and is more aligned to CSS, requiring braces and semicolons and allowing comments.

1. Approach
   1. SCSS COULD be used as an enhancement to CSS
   2. As SCSS is a superset of CSS, the same CSS standards above MUST also apply to SCSS
2. Style/linting
   1. The SCSS syntax MUST be used over the SASS syntax
   2. Stylelint MUST extend stylelint-config-standard-scss
3. Frameworks, tools and libraries
   1. The Dart Sass library MUST be used instead of Node Sass or LibSass to compile SCSS into CSS

BEM

The CSS methodology we use is BEM.

On 4th February 2021, frontend developers met to agree a CSS methodology. Having considered a recommendation for utility CSS (as represented in tailwindcss) and results of the most recent state of CSS survey, the team agreed that the BEM methodology would best reflect the needs of the team at this time.

TNA Frontend uses a mix of BEM and classless strategies. Simple "top-level" elements such as <ul> have a class (tna-ul) while the <li> elements within it do not, as the <ul> element should only contain <li>. For more information, see details of the structure of TNA Frontend.

Stylelint

Stylelint is "a mighty CSS linter that helps you avoid errors and enforce conventions".

npm install stylelint stylelint-config-standard-scss stylelint-selector-bem-pattern stylelint-order

An example .stylelintrc file that addresses all the standards above:

{
  "extends": [
    "stylelint-config-standard-scss"
  ],
  "plugins": [
    "stylelint-selector-bem-pattern"
  ],
  "rules": {
    "at-rule-empty-line-before": null,
    "block-no-empty": null,
    "declaration-empty-line-before": null,
    "property-no-vendor-prefix": null,
    "value-keyword-case": null,
    "scss/dollar-variable-empty-line-before": null,
    "scss/double-slash-comment-empty-line-before": null,
    "selector-class-pattern": null,
    "plugin/selector-bem-pattern": {
      "preset": "bem"
    }
  }
}

# Run stylelint against all CSS files in the src directory...
stylelint 'src/**/*.css'

# ...or all SCSS files
stylelint 'src/**/*.scss'

TNA Frontend Stylelint config

TNA Frontend comes with a Stylelint config which you can use in your project.

It includes property ordering for which you will need to install the stylelint-order module:

npm install stylelint-order

You can then change your stylelint.config.mjs to extend the TNA Frontend config:

import data from "./node_modules/@nationalarchives/frontend/config/stylelint.config.js";

// Add your own rules
data.ignoreFiles = ["app/**/*.css", "tmp/**/*"];

export default data;

Working with high contrast environments

There are two ways of requesting and setting high contrast views in a web application. They use the CSS media features of:

• prefers-contrast
• forced-colors

prefers-contrast

The TNA Frontend's "system" theme follows the preference for prefers-contrast which can be no-preference, more, less or custom. See MDN Web Docs - prefers-contrast.

TNA Frontend currently only supports the prefers-contrast values of no-preference and more.

You can use this media feature to make designs with increased contrast.

forced-colors

Windows offers a "High Contrast Mode" which allows a user to choose their own colour palette. This can be queried using the forced-colors CSS media feature.

Using forced-colors has some accessibility concerns because the browser has no visibility of the colour palette.

Read the article The difference between Increased Contrast Mode and Windows High Contrast Mode (Forced Colours Mode) for more information.

Use this media feature only to make small changes such as adding extra borders. Do not set colours using forced-colors.