Welcome to the W3C design system
This design system documents the styles, components and templates available to use on your website.
Find out how to get started.
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.
All CSS is found within
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:
global Sass variables for your project - more about settings
global Sass functions e.g. em/rem calculation, unit stripping
global Sass mixins for font size/line-height combinations, media queries and vertical spacing
essential styles forming the base of your project, like typography, reset and global elements like links and lists. Print styles also reside here - more about styles
heavily influenced by Every Layout, these are the styles for the basic layout types, which can be combined and customised to make a variety of components and templates - more about layouts
any functionality that comes from external sources - more about third-party plugins
styles required for specific page templates and/or content types - more about templates
overrides or helper classes - more about utilities
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
- Core component styles
- Template-specific styles
- Utility styles
advanced.css, which contains
advanced.scss determine which Sass files will be compiled into the relevant stylesheet. CSS is organised 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 - as noted previously, they reside in 30-base but are included in
print.css are served to all browsers.
advanced.css, is only served to browsers that meet the following CSS media query that sits within
<!-- 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) ">
There are two general rules for JS:
data-attributesare 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
- If a class is added to the HTML by JS, prefix it with
.js-slider. This helps provide context within the stylesheets.
The architecture takes inspiration from Chris Ferdinandi's How I structure my vanilla JS projects.
All JS is found 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.
/main are concatenated together into
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:
A number of filters exist to help format data in Twig templates. They are documented in their dedicated page.