Getting Started

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

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, then to check everything is working, you should be able to run:

fractal start

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

Fractal's settings can be found in fractal.config.js in the root, as per the docs. Changing anything in this file will need a restart of Fractal to take effect.

In the long term, we'll run Fractal through Gulp, more on this later.

The file structure for Fractal is set in fractal.js 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

src 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.

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). While that might not be directly appropriate for your project's integration, it sped up the development of components at the time 😇.

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 src/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 src/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

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.

We used to use a 'designer-friendly' GUI app for code compilation, set up for use with CodeKit which sadly is a Mac only app. A suitable cross-platform GUI alternative might be PrePros.

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 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 subthemes).
• _global contains global, non-componentized styles required for everything, like base typography, layout wrappers
• _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 or upgrade it to use flexbox rather than floats. You can extend the grid system by editing its settings _grid.scss in __vars.
• _utils contains code which outputs utility classes
• _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 '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 currently uses gulp-include syntax to bring in third-party libraries we keep in src/assets/js/vendor/. Using "proper" package management for this would be a great idea.

As mentioned above, it'd also be really nice to separate out what are currently three functions for the megaNav, tabs and slider into separate files in their component folders, and bundle them 'properly' using modern JavaScript methods.

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.

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

   (or fractal 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-ldn.scss}