Welcome to the W3C design system

This design system documents the styles, components and templates available to use.

The organization and compilation of front end assets (CSS and JavaScript) is discussed below.

CSS

The design system uses Sass - specifically the SCSS syntax - which is compiled into CSS files. The CSS approach is heavily influenced by Andy Bell's CUBE CSS. This has some similarities with the BEM Methodology but with a more judicious use of class names.

CSS architecture

CSS is managed within /assets-src/styles/sass.

The architecture is split into a series of levels, each level representing a directory containing Sass, split out into multiple partial files.

More generic and wide-reaching styles sit within the lower numbered levels, with specificity increasing with each level:

  • 00-settings:
    global Sass variables for your project - more about settings
  • 10-functions:
    global Sass functions e.g. em/rem calculation, unit stripping
  • 20-mixins:
    global Sass mixins for viewport media queries and vertical spacing
  • 30-base:
    essential styles forming a solid base for building upon. Includes a global reset, typography, plus starter styles for HTML elements like links and lists. Print styles also reside here - more about base styles
  • 40-layouts:
    drawing on the techniques of Every Layout, these are styles for the basic layout types, which can be combined and customized to make a variety of content components and page templates - more about layouts
  • 50-core-components:
    styles for the basic page components available in the design system, un-enhanced by JavaScript - more about components
  • 60-advanced-components:
    styles for components that are enhanced in some way with JavaScript - more about components
  • 70-third-party-plugins:
    styles for components/functionality from sources external to the design system, typically via scripts. They may include some customizations specifically required to work with the design system.
  • 80-templates:
    styles for specific page templates - more about templates
  • 90-utilities:
    specific overrides and helper classes - more about utilities

CSS compilation

The Sass files are compiled into three separate CSS stylesheets:

  • core.css, which contains:
    • Settings, Functions and Mixins (referenced elsewhere within the stylesheet)
    • Base styles
    • Layouts
    • Core component styles
    • Template-specific styles
    • Utility styles
  • advanced.css, which contains
    • Settings, Functions and Mixins (referenced elsewhere within the stylesheet)
    • Styles from Base for hiding and showing items (to allow for extending SASS placeholders)
    • Advanced component styles
    • Third party plugins involving JavaScript
  • print.css (print stylesheet)

The files core.scss and advanced.scss determine which Sass files will be compiled into the relevant stylesheet. CSS is organized in specificity order, from low to high. The individual Sass partials are included using the @import directive in the order denoted by the level in which they reside, remembering the impact of the CSS cascade.

Print styles are a slight exception; they reside in 30-base but are included in print.scss.

Both core.css and print.css are served to all browsers. advanced.css, is only served to browsers that support the following CSS media query that sits within <head>:

<!--
CSS Mustard Cut
Print (Edge doesn't apply to print otherwise)
Edge, Chrome 39+, Opera 26+, Safari 9+, iOS 9+, Android ~5+, Android UCBrowser ~11.8+
FF 47+
-->
<link rel="stylesheet" id="advanced-stylesheet" href="../dist/assets/styles/advanced.css" media="
    only print,
    only all and (pointer: fine), only all and (pointer: coarse), only all and (pointer: none),
    only all and (min--moz-device-pixel-ratio:0) and (display-mode:browser), (min--moz-device-pixel-ratio:0) and (display-mode:fullscreen)
">

This technique is known as ‘cutting the mustard’. While this can be done via a JavaScript query, the design system, inspired by the Springer Nature Frontend Playbook, uses the CSS Only Mustard Cut.

JavaScript (JS)

There are two general rules for JS:

  • data-attributes are preferred as hooks within the HTML for applying JS functionality. They are less likely to be accidentally over-written than classes. In the case of some third-party scripts, it may be necessary to use an id instead.
  • If a class is added to the HTML by JS, prefix it with .js-, e.g. .js-slider. This helps provide context within the stylesheets.

JS architecture

The architecture takes inspiration from Chris Ferdinandi's How I structure my vanilla JS projects.

JS is managed within /assets-src/js. This directory contains a mixture of individual files, and the following subdirectories:

  • /libraries: contains third party scripts, e.g. Font Face Observer and Accessible autocomplete.
  • /libraries-extensions: contains any custom implementations for the third party scripts that may be required to work with the design system.
  • /main: contains code used on most/all pages.

JS compilation

Scripts within /main are concatenated together into main.js and main.min.js, which is loaded everywhere.

Individual files are minified into files of the same name, but are kept separate. They are typically used on only one or two templates.

Webpack is used to concatenate and minify JS. The configuration files sit within the project root: webpack.config.js and webpack.config.min.js

Twig filters

A number of filters exist to help format data in Twig templates. They are documented in their dedicated page.