V&A Visual Style Guide

View online at vam-fractal-main.surge.sh.

Requirements

This visual style guide is built on top of Fractal, a project by Clearleft. Active development requires the latest LTS version (18.x) of Node.js to be installed.

The documentation for Fractal is super useful. Have a read through the Core Concept documentation before modifying.

Including in other projects

Add the following to your project package.json file, replacing the branch name (i.e., #main) if required, with any feature branch name or commit ID in the vam-fractal project that you want to use:

"vam-fractal": "vanda/vam-fractal#main"

Component modules have their own SASS and can also contain Javascript files which are imported directly from the vam-fractal node-module directory installed as a dependency in your project package.json file. These assets should be compiled as required within the project itself.

Font and SVG (as an icon sprite) assets can be accessed by creation of symlinks. For example,

SVGs:

ln -s node_modules/vam-fractal/build/svg/vam-sprite.svg assets/svg

Fonts:

ln -s node_modules/vam-fractal/build/fonts assets/

Installation

After cloning this repository, in a terminal enter:

$ npm install

Development

If you haven't read the documentation for Fractal yet, get over there now.

In a terminal enter:

$ npm run dev

1. Compiled assets and other assets for distribution are linted and processed into a new root directory, /build
2. The Node.js environment variable is set to: NODE_ENV=development by prepending to the application initialisation command in package.json. Compiled assets are generated with code sourcemaps but are not minified for ease of investigation in development mode.
3. The Fractal server is started and a local build is rendered at localhost:8000 - change the port number in the root fractal.config.js if required
4. The local build runs Webpack in watch mode, meaning that any changes to the component module SASS or Javascript files will result in the compilation to /build being updated
5. The Fractal server is started with the server.sync property set to true so changes to component module files will also cause a page refresh in the browser using Fractal's BrowserSync integration

Creating a Fractal 'static build'

It is possible to create a static build like that hosted at vam-fractal-main.surge.sh

In a terminal enter:

$ npm run build

1. Compiled assets and other assets for distribution are linted and processed into a new or existing root directory, /build
2. Node.js environment variable is set to: NODE_ENV=production and compiled assets are minified. No code sourcemaps are produced. Filenames are appended with a 'cache busting' hash number
3. A Fractal 'static build' is generated using the component modules and the generated assets in the /build directory. This is processed into a new root directoy, /www

Adding a new Fractal component

New Fractal modular components are added in src/components

1. Where the component contains a _[name].scss file, a reference to this stylesheet should be set in src/assets/styles/vam-style.scss.

   The Dart SASS compiler supports the SASS-preferred use of @use and @forward directives in place of the imminently deprecated @import statement. There should be no @import statements used in the project. Note that commonly used SASS stylesheets for base rules, mixins, etc. are organised in their own directories and loaded using a single entry-point file _index.scss within that directory. This allows these stylesheets to be namespaced and immediately identifiable in the component _[name].scss file.

   For example, in _[name].scss

   @use "[path]/base";
   
   .exmple-selector {
      @include base.typography-typeSetting(4, "regular");
   }
   

   Here we state that we want _[name].scss to be exposed to the base namespace. However, this namespace contains several stylesheets which themselves often contain groupings of variables, maps, functions and mixins, etc.

   So to further define within _[name].scss the source of our required object, in this case the mixin typeSetting(), a single entry-point file at src/components/base/_index.scss uses the @forward directive to expose the SASS file at src/components/base/typography_typography.scss with an alias: typography-

   Use of an alias provides an immediate indication of the typeSetting() object location as being in the typography component stylesheet within the base namespace.

2. If the new component contains its own Javascript file in the form of _[name].js then this should be registered in src/assets/scripts/vam-scripts.js

3. The [name].html document should use the Nunjucks Javascript templating language

4. Set variants of the component in the [name].config.js Fractal configuration file

Linting

The SASS is linted via stylelint. The configuration and custom rule set is found in /.stylelint.json. When modifying or adding to the SASS please read through the documentation around the rules.

The standard shareable SASS configuration for styleint, stylelint-config-standard-scss is used. In an effort to adhere to this standard please only add to the /.stylelint.json configuration if agreed and absolutely necessary.

The deployment and distribution will fail if the SASS linting fails.

Adding a new SVG icon asset

To add a new SVG icon and add it to the SVG sprite:

1. Save the SVG file into the src/assets/svg directory
2. Edit src/components/base/icons/icons.config.js, adding the name of the icon taken from the filename to the array

If a development build has been run and Webpack is watching files in src/assets then the new SVG icon will be bundled immediately into the SVG sprite at build/svg/vam-sprite.svg

Running either the development build or creating a Fractal 'static build' will incorporate the new SVG icon into the SVG sprite. The SVG icon is optimised before addition into the sprite and the sprite itself is then minified for distribution.

Acknowledgements

• Clearleft
• This set up has been heavily inspired by Bits of 24 ways by Paul Robert Lloyd. Thank you.