README
ONS Design System
Installing as a dependency
Nunjucks macros for components and templates are available from npm. Built CSS and JS is also available if you need access to pre-release CSS/JS, otherwise CSS and JS should be loaded from the CDN.
yarn add @ons/design-system
Run Locally
You'll need Git, Node.js, and Yarn to run this project locally.
The version of node required is outlined in .nvmrc.
Using nvm (optional)
If you work across multiple Node.js projects there's a good chance they require different Node.js and npm versions.
To enable this we use nvm (Node Version Manager) to switch between versions easily.
- install nvm
- Run nvm install in the project directory (this will use .nvmrc)
Install dependencies
yarn install
Start a local server
yarn start
Once the server has started, navigate to http://localhost:3030
Mixed Markdown/Nunjucks syntax in .njk pages
The design system documentation is authored with files that contain a mix of Markdown and Nunjucks syntax. These files begin with frontmatter and then contain Markdown syntax; for example:
---
title: Foo
---
## Some section
A simple paragraph of _markdown_.
Simple Nunjucks placeholders/variables can be added into these files without any special syntax; for example:
A paragraph of _markdown_ with some template value {{ foo.bar }}.
{{
patternlibExample({"path": "components/foo/examples/foo/index.njk"})
}}
For the most part no special syntax is needed when mixing Nunjucks templating into the markdown syntax. If syntax contains nested character sequence }} then it must be wrapped within +++ fences. The {% ... %} syntax must also be wrapped within +++ fences. This applies for things like imports, calling macros, defining blocks, etc:
+++
{% from "views/partials/example/_macro.njk" import patternlibExample %}
{% from "components/external-link/_macro.njk" import onsExternalLink %}
+++
As a rule of thumb; code highlight blocks should always be wrapped with +++ fences:
+++
{% from "components/code-highlight/_macro.njk" import onsCodeHighlight %}
{{ onsCodeHighlight({
"code": '[
{
"en": "England"
},
{
"en": "Wales"
},
{
"en": "Scotland"
},
{
"en": "Northern Ireland"
},
]'
}) }}
+++
Mixed markdown files are easier to maintain when each section that is fenced with +++ is a standalone unit. For example, each code example should have it's own +++ fence even if they immediately follow one another. This is because content can be edited around these fenced units.
Testing
To test locally ensure you've followed all the steps above to install dependencies. You can have three options:
Run tests locally in watch mode
This will watch your test files and JavaScript for changes and rerun the test suite each time a change is detected.
Note: This will only run tests on the ES6 bundle.
yarn test:local
Run ES6 and ES5 bundle tests
Running this will run the test suite twice, once against the ES6 bundle and again against the ES5 bundle. However, as local tests only run on evergreen browsers it will be unlikely that you see the ES5 testing fail if the ES6 testing passes.
yarn test
Run tests in BrowserStack
All unit tests are automatically cross browser tested in BrowserStack by TravisCI when a pull request is created or if a change is pushed to an existing pull request.
You can also run cross browser testing in BrowserStack manually against your local branch by running this command:
Note: You will need to set your BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY environment variables to allow authentication with BrowserStack. Username and access keys can be found under Automate on the BrowserStack settings page.
yarn test:browserstack
Run visual regression tests
To run visual regression (VR) tests on pull requests using our VR testing tool percy.io you must include [test-visual] in your commit message e.g. git commit -m "Update button border width [test-visual]". This prevents unnecessary builds and saves the limited quota we have available.
Build
Generate a build into ./build.
yarn build