npm install the components

npm (Node.js package manager) is a package manager for Node.js based projects. npm comes pre-installed with Node.js.

The design system components require Node.js version 8 or higher. See the Node.js/npm installation guides if you require assistance installing Node.js.

Skip to step 3 if you are adding the design system to an existing npm project.

1. Set up project folder

Create a new folder for the project, in the examples below we will assume it is called design-system-starter.

2. Initialise npm

To install the components through npm, you must have a package.json file in your project folder. This file holds the project's configuration, scripts and package versions. Find out more about the package.json file on the npm documentation website.

To create a package.json file, open terminal in the project folder and run npm init -y. This will create a package.json with some default settings.

If you would like more control of the creation of the file you can run npm init and follow the prompts.

Once this is done the folder should now look like:

design-system-starter/
└─ package.json

The package.json file should look like:

{
  "name": "design-system-starter",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

3. Install the components

Individual components can be installed via the command line using npm install. When npm install is run it adds the component code to the node_modules folder.

The component name and version is also added to our list of dependencies in the package.json file. Let's start by installing the body, header and accordion components.

npm install @gold.au/body @gold.au/header @gold.au/accordion

Now that the components have been installed your folder structure should match:

design-system-starter
├─ package-lock.json
├─ package.json
└─ node_modules/@gov.au
  ├─ accordion
  ├─ animate
  ├─ body
  ├─ core
  └─ header
└─ pancake
  ├─ css
  ├─ js
  ├─ react
  └─ sass

Node modules

Each dependency in the package.json file is installed into the node_modules folder. If a component requires another component or library that dependency will also be installed.

Pancake

Pancake is a dependency of all of the components in the GOLD Design System. It will check peerDependencies for conflicts and has plugins to compile the contents of your components ( e.g. sass -> css ).

You can read more about the different settings in the Pancake GitHub repository.

You can change the location and file name of autogenerated files for example pancake/sass/auds.scss is generated from this code in the package.json file.

"pancake": {
  "sass": {
    "modules": false,
    "location": "pancake/sass/",
    "name": "auds.scss"
  },
}

If you would like more information on Pancake, Dominik Wilkowski wrote an article that explains why we use pancake and the problems it solves.

4. Create a page

Start by adding an index.html file to the project folder. Inside the file we need to add:

  • Styles for the components
  • JavaScript for any advanced components ( for example, components that open and close )
  • HTML5 and media query support for Internet Explorer 8
  • .no-js class and script that removes the class when JavaScript is enabled
  • Classes in the <html> tag for legacy browsers
  • Some HTML example components

Here is an example HTML file to get started:

<!DOCTYPE html>
<!--[if lt IE 8]>
  <html class="no-js lt-ie8 lt-ie9" lang="en">
<![endif]-->
<!--[if IE 8]>
  <html class="no-js lt-ie9 ie8" lang="en">
<![endif]-->
<!--[if IE 9 ]>
  <html class="no-js ie9" lang="en">
<![endif]-->
<!--[if !(IE)]><!-->
  <html class="no-js" lang="en">
<!--<![endif]-->
<head>
  <meta charset="utf-8">
  <title>Design system starter</title>
  
  <!-- Removes the no-js class on the <html> tag -->
  <script type="text/javascript">
    var $html = document.documentElement; if ($html.classList) $html.classList.remove("no-js"), $html.classList.add("js"); else { var className = "no-js"; $html.className = $html.className.replace(new RegExp("(^|\\b)" + className.split(" ").join("|") + "(\\b|$)", "gi"), " "), $html.className += " js" }
  </script>

  <!-- HTML5 and media query support for IE8, we recommend inserting these inline -->
  <!--[if lt IE 9]>
    <script src="https://raw.githubusercontent.com/aFarkas/html5shiv/master/dist/html5shiv.min.js"></script>
    <script src="https://raw.githubusercontent.com/scottjehl/Respond/master/dest/respond.min.js">
    </script>
  <![endif]-->

  
  <!-- Component styles -->
  <link rel="stylesheet" href="pancake/css/pancake.min.css">
</head>
<body>
 
  <!-- An example component -->
  <section class="au-accordion">
    <a href="#accordion-default" class="au-accordion__title js-au-accordion" aria-controls="accordion-default" aria-expanded="true" role="tab" onclick="return AU.accordion.Toggle( this )">Wuhuu design system</a>
    <div class="au-accordion__body" id="accordion-default">
      <div class="au-accordion__body-wrapper">
        And it looks good :)
      </div>
    </div>
  </section>
 
  <!-- Component javscript -->
  <script src="pancake/js/pancake.min.js"></script>
</body>
</html>

To start using other components you can install them and copy paste the HTML code from the documentation.