Getting Started

The component library contains some guidance on what components are for and how to use them from both a content editor, and developer viewpoint on each individual component. There are also some more globally applicable guidelines for things like Typography, Colour, Spacing and Layout on other pages in this section.

This is mostly technical documentation intended for those using and maintaining the component library. If you don't write code, this might not be the page you're looking for, skip it :)

In this guide you will find some (hopefully) useful notes on:

• Fractal and setting it up
• Front-end architecture / file structure
• Build process / Code compilation (Gulp)
• Guide: How to add a new component

Fractal (with Gulp/NPM)

The component library is managed using Fractal, which has great documentation worth familiarising yourself with, it's already set up to run in the repo, you'll just need it installed on your system, see: Installing the Fractal CLI tool

We'll run Fractal through Gulp, more on this later, but you'll need this on your system. At time of writing, Node v20 (NPM v10) is a prequisite.

The package.json file in the root of the repository should list everything you need to run the project locally. Just run:

npm install

to grab the packages. To quickly check everything is working, you should now be able to run:

gulp

To get a viewable localhost version running on your system at this point. You can kill the process after you confirm it's working.

Some of Fractal's settings can be found in config.yml in the root and some can be found in gulpfile.babel.js, references as to how to configure Fractal can be found in the docs. Changing anything in this file will need a restart of Fractal to take effect. You likely won't need to change anything here.

File Structure

The file structure for Fractal is set in config.yml for components, assets, docs and the build folder.

The docs folder is unused, we have a folder in components (src/components/01-globals-and-docs) for these docs (yes, these ones you're reading now), as it's a bit easier to add fancier styles and examples here.

The Build Folder

The design-system folder is the build folder. This contains generated code and should not be edited. It will be overwritten when building a static version of the component library. More on this later.

The Source Folder

This contains everything you'll edit. It runs the localhost version while you're building things, and is then compiled when exporting a static HTML version.

You might see this referred to as /src/ as a placeholder later in these docs.

Templating Note

You'll notice that all the template files use Twig as a templating language. This means components can be built to be directly included in Drupal and WordPress (using Timber or likewise).

If you just want to use this as a reference library, Plain ol' HTML is valid Twig, and the compiled HTML can be viewed for all components from within Fractal in the HTML tab along the bottom of the screen.

Global Assets

Assets like fonts, images, js and styles (in Sass) are stored in assets. Edit them here, they get copied to the build folder when building a static version of the component library.

Components

Each component has a folder in components. This normally contains a .twig view template (for the HTML), some contain a config file to add context, dynamically created variants, control naming and ordering. Ideally all the styles and JS for a component will live here also. At the time of writing, all the components have their own .scss file for styles, but the JS is in one app.js file in assets.

The JavaScript could probably use breaking up and bundling better. Ideally it'd be nice to do a similar thing with JS for each component as we do for Sass styles, so:

├── components
│   └── slider
│   │   ├── slider.twig
│   │   ├── slider--variant.twig
│   │   ├── slider.config.yml
│   │   ├── _sliders.scss
│   │   └── _sliders.js

Useful: Fractal Docs on Components

Build process / Code compilation (Gulp)

The build process has been set up using Gulp for simplicity, cross-platform compatibility, and extensibility. It probably has some room for improvement, but it 'just works' for now 😬. If improved, remember to update these docs.

If you've never used Gulp on your system, install the CLI with:

npm install --global gulp-cli

Our goal for a build process, among other things is:

• Sass to CSS compilation
• Sass syntax checking
• Compact output style, works best for git diffs, but compressed (minified) is an option
• Source maps
• PostCSS/Autoprefixer
• Theme image optimisation (for SVG, JPEG, PNG, etc.)
• JavaScript transpilation (Babel)
• ESLint syntax checking
• JS minification if not taken care of by the CMS
• JS source maps

There is a gulpfile in the root where a basic command-line build process for Sass/JS has been set up.

The build process watches Sass/JS and compiles on the fly, and also runs the equivelant of fractal start to running a localhost with BrowserSync. This is the default gulp task, so you just need to run:

gulp

A gulp build task has been set up, which currently just runs fractal build, but could be extended.

There's also a gulp compile task which runs a one-time compile of styles and script without booting Fractal's webserver. This is handy for really quick edits, but ideally, check your components within Fractal!

There's also potential for a gulp deploy task, which in future could be modified to generate minified assets if needed for the target environment.

Sass (to CSS)

Global styles are located in [src]/assets/styles/.

The entry point / manifest for generation of the main CSS is in [src]/assets/styles/main.scss

• __vars is used for variables/settings, nothing in this folder outputs code, it's just variables and mixins to be called from other places. Change things here, and they'll likely cascade across the site (and any subthemes).
• _global contains global, non-componentized styles required for everything, like base typography, and some layout code.
• _grid contains the code that actually outputs the grid system, it doesn't need to be edited unless you want to for example, significantly rename classes. You can extend the grid system by editing its settings _grid.scss in __vars. (See the Docs on Grid)
• _utils contains code which outputs some useful utility classes (mostly to be used sparingly, think a slightly less horrible CSS !important but for HTML)
• _vendor is a place to add third-party styles if they can't be enqueued in another way. We mostly just use this to include Normalize.

Component styles are separated out into their component folders, and are included by main.scss. It 'reaches out' of the assets folder and into each component, for example:

@import "__vars/_all";
@import "../../components/card/cards";

NB: We do not (currently) use Sass 'globbing' to include all files (such as components) - eg. @import "../../components/*/*";. Partially as some Sass compilers don't support it for 'reasons', and partially to control the ordering of what gets imported (one of the 'reasons' some Sass compilers opt not to support globbing). Thus, with the current build process, when you add a partial, you'll need to manually (purposefully) add it to main.scss (and any other subthemes created). More on this in the guide below.

JavaScript

Our first rule is to use sparingly. If a JavaScript-free solution is available (like <details>), prefer it!

That said, it's mad to think we can eliminate JavaScript completely.

JavaScript lives in [src]/assets/js and is processed by gulp.

The entry point is app.js, which could use gulp-include syntax to bring in third-party libraries we might want to keep in [src]/assets/js/vendor/. Using "proper" best practice package management for this would be a great idea.

It ain't perfect, but it Works For Now™.

The result of gulp default is output at src/assets/dev/js, which is referenced in Fractal's localhost, and copied to the build folder when building.

There's a src/assets/dist folder which would be used by gulp deploy to create minified assets, but this is currently not in use. If the target CMS environment doesn't support concatenation and minification of CSS/JS, this is worth looking into for performance.

Guide: Adding a new component

1. From command line, run

   gulp

   from the root of the project, this should start Fractal, Sass/JS filewatching, and open your browser to the localhost.
2. Create a folder for the component in [src]/components/, eg. [src]/components/your-component/
3. Create a .twig template file (for the HTML) inside the folder, .eg [src]/components/your-component/your-component.twig - as soon as you do this, Fractal should refresh and the component should appear in the components list on the left
4. Create a .scss 'partial' file prefixed with an underscore (this lets the compiler know not to directly compile the file, because it is included by another file), eg. [src]/components/your-component/_your-component.scss
5. Reference the partial .scss in [src]/assets/styles/main.scss*, so that it's brought into the site CSS, by adding a line like so:

   @import "../../components/your-component/your-component";

   For now, this will be compiled to [src]/assets/styles/main.css, which is referenced in Fractal.
6. Write the HTML and Sass for your component
7. When you're done, run a build to a static HTML version by running

   gulp build

   from the command line. This will compile .twig to static HTML, and copy all (already compilied on-the-fly) assets (fonts/img/css/js) to the design-system folder, so the component library can be viewed without having to run a localhost version
8. Add the new/modified files to your chosen flavour of source control
9. Repeat!

^{* this will add the component to the main site styles, to include in sub-themes, add to their Sass file too, eg. main-subtheme.scss}