Customising your design system

The major projects in use

To make full use of this boilerplate, you'll need to be familiar with these projects:

• Visual Framework for life science websites: designed for use when you don't want your other CSS and JS to break
• Gulp: a task runner to get Fractal and Eleventy to "talk to each other" and other niceties around file optimisation and Sass
• Fractal component library: modular and nested components
• Eleventy static site generator: fast and flexible templating, and adapted to use of Fractal components
• Nunjucks: "A rich and powerful templating language for JavaScript", it's common to Fractal, Eleventy and also used by the Visual Framework

How things work

1. Visual Framework

• The Visual Framework is a methedology around components and how they're made; and
• This boilerplate uses the vf-core to assemble Sass and component structure

2. Gulp

• Gulp will initiate all the tasks and for local development gulp dev is your go-to command
• Review ./gulpfile.js for insight into the specific tasks

3. Fractal

• Fractal is responsible for assembling the Visual Framework-compatible components and their templates
• Local components live in .src/components
• Visual Framework core components are installed by yarn to node_modules and symlinked from .src/components/vf-core-components

4. Eleventy

• Eleventy is responsible for page building and high level templates
• Eleventy is also passed the Visual Framework components via Fractal so you have full use of a component's assets and Nunjuck templates
• Review ./eleventy.js for insight into the configuration

5. Nunjucks

This templating language is used throughout so you can not only use a nice templatin language but also have direct access to component templates:

Code: {% render "@vf-sample", {text: "with some text"} %}

Returns: <p>I'm a sample with some text</p>

Want Markdown? You can use it for entire files or by with Nunjuck blocks and tags.

Markdown file support

Name your file with the Markdown suffix (index.md) or a page's front matter:

templateEngineOverride: njk, md

Markdown filter

Nunjcuks:{{ "I'm some `markdown`" | markdown | safe }}

Returns: <p>I'm some <code>markdown</code></p>

Markdown tag

Nunjcuks:
{% markdown %}
[A link](#)
{% endmarkdown %}

Returns: 
A link

Actions to do, files to edit

Now that you know a bit about the configuration, here's how to start customising.

Browse, add, make components

• See what components are already installed: /components
• Browse all vf-core components
• Directions to add pre-made components
• Then reference the new component in ./src/components/vf-componenet-rollup/index.scss

Configuration options

• In ./package.json update the vfConfig property
• In .src/site/_data/siteConfig.js add site name and e-mail options
• In ./eleventy.js update pathPrefix, or comment it out if you don't deploy to a subdirectory

Customise page templates

Page templates are located at .src/site/_data/site/_includes/layouts, you can learn more about layout's in Eleventy's docs.

Add pages

Pages are located at .src/site/_data/site/. Have a look at some of the existing pages and copy them to make new pages.

Local CSS, JS, images

There's usually a need for "edge cases":

• CSS/Sass: ./src/scss/app.scss, and reference like /vf-demo-design-system/css/app.css
• JS: ./src/js/your-js-file.scss, and reference like /vf-demo-design-system/js/scripts.js
• Images: ./src/site/images, and reference like /vf-demo-design-system/images/myimage.png

Outputs: what is made

When you run gulp dev or gulp build, Eleventy will build your static pages and trigger the Visual Framework.

• Generated site is output to ./build
• <link rel="stylesheet" media="all" href="/vf-demo-design-system/css/styles.css" />
• <script src="/vf-demo-design-system/scripts/scripts.js"></script>

Deploying your design system

• Manually: run gulp build and copy ./build to your server
• CI: See ./travis.yml file for ideas

Common issue: Not deploying to the right subdirectory? Make sure in ./eleventy.js you've updated pathPrefix.

The component library

A full component library is available at /components

The component library is generated by tapping into an export Fractal's component index:

1. the component list is updated whenever a component is edited or added
2. the data is eposed to Eleventy at ./src/site/_data/fractalEnvironment.js
3. individual component pages are created using Eleventy's pagination feature
   • ./src/site/components/component-view.njk
   • ./src/site/components/vf-core-components.njk
4. a page template drives the layout of the components ./src/site/_includes/layouts/components.njk