idsk_frontend_toolkit 7.4.2

data/app/assets/Gemfile.lock

@@ -0,0 +1,48 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.3.0)
+    ffi (1.9.18)
+    govuk-lint (3.6.0)
+      rubocop (~> 0.51.0)
+      rubocop-rspec (~> 1.19.0)
+      scss_lint
+    parallel (1.12.1)
+    parser (2.4.0.2)
+      ast (~> 2.3)
+    powerpack (0.1.1)
+    rainbow (2.2.2)
+      rake
+    rake (12.3.0)
+    rb-fsevent (0.10.2)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rubocop (0.51.0)
+      parallel (~> 1.10)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    rubocop-rspec (1.19.0)
+      rubocop (>= 0.51.0)
+    ruby-progressbar (1.9.0)
+    sass (3.5.5)
+      sass-listen (~> 4.0.0)
+    sass-listen (4.0.0)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+    scss_lint (0.56.0)
+      rake (>= 0.9, < 13)
+      sass (~> 3.5.3)
+    unicode-display_width (1.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  govuk-lint (= 3.6.0)
+  sass (= 3.5.5)
+
+BUNDLED WITH
+   1.14.6

data/app/assets/Gruntfile.js

@@ -0,0 +1,68 @@
+module.exports = function (grunt) {
+  var allSassFiles = []
+
+  grunt.file.recurse(
+    './stylesheets/',
+    function (abspath, rootdir, subdir, filename) {
+      var relpath
+      if (typeof subdir !== 'undefined') {
+        relpath = subdir + '/' + filename
+      } else {
+        relpath = filename
+      }
+      if (filename.match(/\.scss/)) {
+        allSassFiles.push("@import '" + relpath + "';")
+      }
+    }
+  )
+
+  allSassFiles.push("@import '_colour_contrast_spec.scss';")
+
+  grunt.file.write(
+    './spec/stylesheets/test.scss',
+    allSassFiles.join('\n')
+  )
+
+  grunt.initConfig({
+    clean: {
+      sass: ['spec/stylesheets/test*css']
+    },
+    jasmine: {
+      javascripts: {
+        src: [
+          'node_modules/jquery/dist/jquery.js',
+          'javascripts/govuk/analytics/google-analytics-universal-tracker.js',
+          'javascripts/govuk/analytics/govuk-tracker.js',
+          'javascripts/govuk/analytics/analytics.js',
+          'javascripts/**/*.js'
+        ],
+        options: {
+          specs: 'spec/unit/**/*.spec.js',
+          helpers: 'spec/unit/*.helper.js'
+        }
+      }
+    },
+    sass: {
+      development: {
+        files: {
+          './spec/stylesheets/test-out.css': './spec/stylesheets/test.scss'
+        },
+        options: {
+          loadPath: [
+            './node_modules',
+            './stylesheets',
+            './spec/stylesheets'
+          ],
+          style: 'nested'
+        }
+      }
+    }
+  })
+
+  grunt.loadNpmTasks('grunt-contrib-clean')
+  grunt.loadNpmTasks('grunt-contrib-jasmine')
+  grunt.loadNpmTasks('grunt-contrib-sass')
+
+  grunt.registerTask('test', ['sass', 'clean', 'jasmine'])
+  grunt.registerTask('default', ['test'])
+}

data/app/assets/LICENCE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Crown Copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/app/assets/README.md

@@ -0,0 +1,170 @@
+# GOV.UK frontend toolkit
+
+A collection of Sass and JavaScript files for using as part of your
+application's frontend.
+
+This project is not tied to a specific language and is designed to be used
+as a dependency in as many different languages as needed.
+
+There's a `Gemfile` and a `package.json` in this directory, but they are only
+for running tests and are not an indication that this project prefers
+Ruby or Node.js.
+
+## Installing
+
+### Ruby on Rails
+
+We recommend you use the [govuk_frontend_toolkit_gem][toolkit_gem_github] and
+follow the [installation instructions][toolkit_gem_github_readme].
+
+[toolkit_gem_github]: https://github.com/alphagov/govuk_frontend_toolkit_gem
+[toolkit_gem_github_readme]: https://github.com/alphagov/govuk_frontend_toolkit_gem#readme
+
+### Node.js
+
+[govuk_frontend_toolkit_npm][toolkit_npm_github] is an NPM package that can be
+[installed or included in your package.json][toolkit_npm].
+
+[toolkit_npm_github]: https://github.com/alphagov/govuk_frontend_toolkit_npm
+[toolkit_npm]: https://npmjs.org/package/govuk_frontend_toolkit
+
+If you are using a build tool that depends on Libsass then you
+may need to upgrade to a more recent version to use the grid helpers. Minimal
+compatible versions include `node-sass` 1.0.0, `grunt-sass` 0.16.0,
+`gulp-sass` 1.2.0 and `libsass` 3.0.0.
+
+### Django
+
+Requirement: [NodeJS](https://nodejs.org/en/) installed. This gives you [Node Package Manager](https://docs.npmjs.com/getting-started/installing-node)(NPM) which is required to install npm packages.
+
+The easiest way to integrate it would be to create a `package.json` file in your application with `npm init` 
+
+You then install the toolkit with `npm install --save govuk_frontend_toolkit`.
+If you need javascript files, they will live in (`node_modules/govuk_frontend_toolkit/javascripts`).
+If you need stylesheets they will live in (`node_modules/govuk_frontend_toolkit/stylesheets`).
+
+With Django you can use https://github.com/jrief/django-sass-processor to compile Sass files.
+
+Note: if you need complete styles you might want to install govuk-elements-sass package that also installs toolkit
+
+### Composer
+
+[govuk_frontend_toolkit_composer][toolkit_composer_github] is an composer package that can be
+[added to your composer.json][toolkit_composer_github_usage]
+
+[toolkit_composer_github]: https://github.com/PurpleBooth/govuk_frontend_toolkit_composer
+[toolkit_composer_github_usage]: https://github.com/PurpleBooth/govuk_frontend_toolkit_composer#installing
+
+### Other projects
+
+#### Using the tagged versions
+
+Each version of the toolkit is tagged with the version number in this format:
+
+`v*version number*`, for example `v4.1.1` for version 4.1.1.
+
+If your dependency management tool allows the use of Git repositories as dependencies, you can point to a version by using its tag.
+
+For example, if you are using [bower](http://bower.io), you can add the toolkit to your `bower.json` like so:
+
+`"govuk_frontend_toolkit": "git://github.com/alphagov/govuk_frontend_toolkit#v4.1.1"` (assuming you want version 4.1.1)
+
+#### Using git submodules
+
+You can include the toolkit as a [git submodule][git submodule].
+
+[git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+
+To add the submodule to your project run the following command substituting the path to a subdirectory in your project's assets directory:
+
+    $ git submodule add https://github.com/alphagov/govuk_frontend_toolkit.git ./path/to/assets/govuk_frontend_toolkit
+
+We recommend you use `https` rather than `ssh` for submodules as they don't require key exchanges when deploying to remote servers.
+
+If you clone a project with the toolkit submodule installed you will need to initialise the submodule with the following command:
+
+    $ git submodule init
+
+To update the toolkit to the latest version you can use:
+
+    $ git submodule update
+
+## Running tests
+
+Tests for this project use Jasmine for the JavaScript and Ruby's `scss` and `scss-lint`
+to check the stylesheets.
+
+The requirements are Node.js 0.8 or higher and PhantomJS, and Ruby:
+
+```bash
+bundle install
+npm install
+npm test
+```
+
+### Standard JavaScript
+`govuk_frontend_toolkit` uses [standardjs](http://standardjs.com/), an opinionated JavaScript linter.
+All JavaScript files follow its conventions. [Read more](https://github.com/alphagov/govuk_prototype_kit/blob/master/docs/linting.md)
+
+### Using the local test runner
+
+The test suite can be run by opening the `./spec/support/LocalTestRunner.html` file in a browser for a more detailed trace of errors.
+
+The files for unit tests and any supporting JavaScript should be added to `./spec/manifest.js` file.
+
+## Usage
+
+At the top of a Sass file in your project you should use an `@import` rule
+to include the file for the mixins you require, eg if you want the
+conditionals and typography mixins you should add:
+
+    @import '_conditionals';
+    @import '_typography';
+
+You may need to include the relative path to the toolkit if it is installed as a submodule:
+
+    @import '../toolkit/_conditionals';
+
+If you are compiling Sass from the [command-line tool](http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#using_sass), here are some options we recommend.
+
+In development:
+
+    sass --style expanded --line-numbers --load-path [path to]/govuk_frontend_toolkit/stylesheets input.scss output.css
+
+In production:
+
+    sass --style compressed --load-path [path to]/govuk_frontend_toolkit/stylesheets input.scss output.css
+
+## Documentation
+
+* [Mixin-sets](/docs/mixins.md)
+  * [Grid layout](/docs/mixins.md#grid-layout)
+  * [Conditionals](/docs/mixins.md#conditionals)
+  * [Colours](/docs/mixins.md#colours)
+  * [Typography](/docs/mixins.md#typography)
+  * [CSS3](/docs/mixins.md#css3)
+  * [Buttons](/docs/mixins.md#buttons)
+  * [Phase banner](/docs/mixins.md#-phase-banner)
+  * [Phase tags](/docs/mixins.md#-phase-tags)
+* [JavaScript](/docs/javascript.md)
+  * [Modules](/docs/javascript.md#modules)
+  * [Media player](/docs/javascript.md#media-player)
+  * [Primary links](/docs/javascript.md#primary-links)
+  * [Stick at top when scrolling](/docs/javascript.md#stick-at-top-when-scrolling)
+  * [Selection buttons](/docs/javascript.md#selection-buttons)
+  * [Shim links with button role](/docs/javascript.md#shim-links-with-button-role)
+  * [Show/Hide content](/docs/javascript.md#showhide-content)
+* [Analytics](/docs/analytics.md)
+  * [Create an analytics tracker](/docs/analytics.md#create-an-analytics-tracker)
+  * [Virtual pageviews](/docs/analytics.md#virtual-pageviews)
+  * [Custom events](/docs/analytics.md#custom-events)
+  * [Custom dimensions and custom variables](/docs/analytics.md#custom-dimensions-and-custom-variables)
+  * [Print tracking](/docs/analytics.md#print-tracking-print-intentjs)
+  * [Error tracking](/docs/analytics.md#error-tracking-error-trackingjs)
+  * [External link tracking](/docs/analytics.md#external-link-tracking-external-link-trackerjs)
+  * [Download link tracking](/docs/analytics.md#download-link-tracking-download-link-trackerjs)
+  * [Mailto link tracking](/docs/analytics.md#mailto-link-tracking-mailto-link-trackerjs)
+
+## Licence
+
+Released under the MIT Licence, a copy of which can be found in the file `LICENCE`.

data/app/assets/VERSION.txt

@@ -0,0 +1 @@
+7.4.2

data/app/assets/create-release.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+set -e
+
+REPO_PATH="alphagov/govuk_frontend_toolkit"
+
+echo "Add config for alphagov/$REPO_PATH"
+
+git config --global user.name "GOV.UK Design System CI"
+git config --global user.email "design-system-pipeline@digital.cabinet-office.gov.uk"
+git remote add origin_ssh git@github.com:$REPO_PATH.git
+
+# This openssl command was generated automatically by `travis encrypt-file`, see `.travis/README.md` for more details
+openssl aes-256-cbc -K $encrypted_53be47f46000_key -iv $encrypted_53be47f46000_iv -in .travis/govuk_frontend_toolkit_push.enc -out ~/.ssh/id_rsa -d
+chmod 600 ~/.ssh/id_rsa
+
+echo "Check to see if the version file has been updated"
+
+# get the version from the version file
+VERSION_TAG="v`cat VERSION.txt`"
+
+# Create a new tag - if the version file has been updated and a tag for that
+# version doesn't already exist
+
+# check to make sure the tag doesn't already exist
+if ! git rev-parse $VERSION_TAG >/dev/null 2>&1; then
+  echo "Creating new tag: $VERSION_TAG"
+
+  # Create a new tag and push to Github
+  git tag $VERSION_TAG
+  git push origin_ssh $VERSION_TAG
+
+  # Alias branch for the most recently released tag, for easier diffing
+  # Force push local `master` branch to the `latest-release` branch on Github
+  git push --force origin_ssh master:latest-release
+  echo "Pushed latest-release branch to GitHub"
+else
+  echo "Not creating a new tag, or updating the latest-release branch as the tag already exists..."
+fi

data/app/assets/docs/analytics.md

@@ -0,0 +1,270 @@
+# Analytics
+
+The toolkit provides an abstraction around analytics to make tracking pageviews, events and dimensions across multiple analytics providers easier. Specifically it was created to ease the migration from Google’s Classic Analytics to Universal Analytics. It includes:
+
+* a Google Analytics universal tracker wrapper
+* code to asynchronously load universal analytics
+* a generic Analytics wrapper that allows multiple trackers to be configured
+* sensible defaults such as anonymising IPs
+* data coercion into the format required by Google Analytics (eg a custom dimension’s value must be a string)
+* stripping of PII from data sent to the tracker (strips email by default, can be configured to also strip UK postcodes)
+
+## Create an analytics tracker
+
+The minimum you need to use the analytics function is:
+
+1. Include the following files from /javascripts/govuk/analytics in your project:
+  * google-analytics-universal-tracker.js
+  * analytics.js
+2. Copy the following `init` script into your own project and replace the dummy IDs with your own (they begin with `UA-`).
+  * This initialisation can occur immediately as this API has no dependencies.
+  * Load and create the analytics tracker at the earliest opportunity so that:
+    * the time until the first pageview is tracked is kept small and pageviews aren’t missed
+    * javascript that depends on `GOVUK.analytics` runs after the tracker has been created
+
+```js
+(function() {
+  "use strict";
+
+  // Load Google Analytics libraries
+  GOVUK.Analytics.load();
+
+  // Use document.domain in dev, preview and staging so that tracking works
+  // Otherwise explicitly set the domain as www.gov.uk (and not gov.uk).
+  var cookieDomain = (document.domain === 'www.gov.uk') ? '.www.gov.uk' : document.domain;
+
+  // Configure profiles and make interface public
+  // for custom dimensions, virtual pageviews and events
+  GOVUK.analytics = new GOVUK.Analytics({
+    universalId: 'UA-XXXXXXXX-X',
+    cookieDomain: cookieDomain
+  });
+
+  // Set custom dimensions before tracking pageviews
+  // GOVUK.analytics.setDimension(…)
+
+  // Activate any event plugins eg. print intent, error tracking
+  // GOVUK.analyticsPlugins.error();
+  // GOVUK.analyticsPlugins.printIntent();
+
+  // Track initial pageview
+  GOVUK.analytics.trackPageview();
+})();
+```
+
+Once instantiated, the `GOVUK.analytics` object can be used to track virtual pageviews, custom events and custom dimensions.
+
+## Virtual pageviews
+
+> Page tracking allows you to measure the number of views you had of a particular page on your web site.
+
+* [Universal Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/pages)
+
+Argument | Description
+---------|------------
+`path` (optional) | Custom path, eg `/path`
+`title` (optional) | Custom page title, Universal only
+
+
+```js
+// Track current page
+GOVUK.analytics.trackPageview();
+
+// Track a custom path
+GOVUK.analytics.trackPageview('/path');
+
+// Track a custom path and custom page title
+GOVUK.analytics.trackPageview('/path', 'Title');
+
+// As above, plus additional options passed into the `pageview` call
+GOVUK.analytics.trackPageview('/path', 'Title', {
+  sessionControl: 'start'
+});
+```
+
+## Custom events
+
+> Event tracking allows you to measure how users interact with the content of your website. For example, you might want to measure how many times a button was pressed, or how many times a particular item was used.
+
+* [Universal Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/events)
+
+Argument | Description
+---------|------------
+`category` (required) | Typically the object that was interacted with, eg "JavaScript error"
+`action` (required) | The type of interaction, eg a Javascript error message
+`options` (optional) | Optional parameters to further describe event
+
+Option | Description
+-------|------------
+`page`  | Useful for sending the URL when `window.location` has been updated using JavaScript since the Analytics tracking object was created
+`label` | Useful for categorising events, eg Javascript error source
+`value` | Values must be non-negative. Useful to pass counts, eg error happened 5 times
+`nonInteraction` | Defaults to false. When set the event will not affect bounce rate
+
+```js
+// Track a custom event with required category and action fields
+GOVUK.analytics.trackEvent('category', 'action');
+
+// Track a custom event with optional page, label, value and nonInteraction options
+GOVUK.analytics.trackEvent('category', 'action', {
+  page: '/path/to/page',
+  label: 'label',
+  value: 1,
+  nonInteraction: true // event will not affect bounce rate
+});
+```
+
+## Custom dimensions
+
+> Custom dimensions and metrics are a powerful way to send custom data to Google Analytics. Use custom dimensions and metrics to segment and measure differences between: logged in and logged out users, authors of pages, or any other business data you have on a page.
+
+* [Universal Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/custom-dims-mets)
+
+Universal custom dimensions are configured within analytics.
+
+### Set custom dimensions before tracking pageviews
+
+Many page level custom dimensions must be set before the initial pageview is tracked. Calls to `setDimension` should typically be made before the initial `trackPageview` is sent to analytics.
+
+Argument | Description
+---------|------------
+`index` (required) | The Universal dimension’s index as configured in the profile.
+`value` (required) | Value of the custom dimension
+
+```js
+// Set a custom dimension at index 1 with value and name
+GOVUK.analytics.setDimension(1, 'value');
+```
+
+### Create custom dimension helpers
+
+Because dimensions rely on the correct index and that index doesn’t indicate its purpose, it’s helpful to create methods that abstract away the details. For example:
+
+```js
+function setPixelDensityDimension(pixelDensity) {
+  GOVUK.analytics.setDimension(1, pixelDensity);
+}
+```
+
+## Tracking across domains
+
+Once an Analytics instance has been created, tracking across domains can be set up
+for pages like:
+
+```js
+GOVUK.analytics.addLinkedTrackerDomain(trackerIdHere, nameForTracker, domainToLinkTo);
+```
+
+Once this is done hits to that page will be tracked in both your local and the
+named tracker, and sessions will persist to the other domain.
+
+## Plugins
+
+Plugins are namespaced to `GOVUK.analyticsPlugins`. They should be pulled in by your project and initialised after `GOVUK.analytics` (see [Create an analytics tracker, above](#create-an-analytics-tracker)).
+
+### Print tracking (`print-intent.js`)
+
+Track when users are attempting to print content. The plugin sends a `Print intent` event and a `/print` prefixed pageview:
+
+Example event:
+
+Category | Action
+---------|-------
+Print Intent | `/current/page`
+
+Example pageview:
+
+`/print/current/page`
+
+### Error tracking (`error-tracking.js`)
+
+Track JavaScript errors, capturing the error message, file and line number. These events don’t affect bounce rate. Errors can be filtered to include only files of interest by passing in an options argument with a regexp matcher (to avoid tracking errors generated by browser plugins):
+
+```js
+GOVUK.analyticsPlugins.error({filenameMustMatch: /gov\.uk/});
+```
+
+Category | Action | Label | Value
+---------|--------|-------|-------
+JavaScript Error | The error message | file.js: line number | 1
+
+### External link tracking (`external-link-tracker.js`)
+
+The tracker will send an event for clicks on links beginning, `http` and linking outside of the current host. By default the plugin uses Google Analytics’ `transport: beacon` method so that events are tracked even if the page unloads.
+
+Category | Action | Label
+---------|--------|-------
+External Link Clicked | http://www.some-external-website.com | Link text
+
+
+### Download link tracking (`download-link-tracker.js`)
+
+The tracker will send an event for clicks on any link that matches the selector passed in. A selector must be provided. By default the plugin uses Google Analytics’ `transport: beacon` method so that events are tracked even if the page unloads.
+
+```js
+GOVUK.analyticsPlugins.downloadTracker({selector: 'a[rel="download"]'});
+```
+
+Category | Action | Label
+---------|--------|-------
+Download Link Clicked | `/some/upload/attachment/file.pdf` | Link text
+
+### Mailto link tracking (`mailto-link-tracker.js`)
+
+The tracker will send events for clicks on links beginning with `mailto`. By default the
+plugin uses Google Analytics’ `transport: beacon` method so that events are tracked even if the page unloads.
+
+Category | Action | Label
+---------|--------|-------
+Mailto Link Clicked | mailto:name@email.com | Link text
+
+### Stripping Personally Identifiable Information (PII)
+
+The tracker will strip any PII it detects from all arguments sent to the
+tracker.  If a PII is detected in the arguments it is replaced with a
+placeholder value of `[<type of PII removed>]`; for example: `[email]` if an
+email address was removed, or `[postcode]` if a postcode was removed.
+
+We have to parse all arguments which means that if you don't pass a path to
+`trackPageView` to track the current page we have to extract the current page
+and parse it, turning all `trackPageView` calls into ones with a path argument.
+We use `window.location.href.split('#')[0]` as the default path when one is
+not provided.  The original behaviour would have been to ignore the anchor
+part of the URL anyway so this doesn't change the behaviour other than to make
+the path explicit.
+
+By default we strip email addresses, but it can also be configured to strip
+postcodes too.  Postcodes are off by default because they're more likely to
+cause false positives.  If you know you are likely to include postcodes in
+the data you send to the tracker you can configure to strip postcodes at
+initialize time as follows:
+
+```js
+  GOVUK.analytics = new GOVUK.Analytics({
+    universalId: 'UA-XXXXXXXX-X',
+    cookieDomain: cookieDomain,
+    stripPostcodePII: true
+  });
+````
+
+Any value other than the JS literal `true` for `stripPostcodePII` will leave
+the analytics module configured not to strip postcodes.
+
+#### Avoding false positives
+
+Sometimes you will have data you want to send to analytics that looks like PII
+and would be stripped out.  For example on GOV.UK the content_ids that belong
+to every document can sometimes contain a string of characters that look like a
+UK postcode: in `eed5b92e-8279-4ca9-a141-5c35ed22fcf1` the substring `c35ed` in
+the final portion looks like a postcode, `C3 5ED`, and will be transformed into
+`eed5b92e-8279-4ca9-a141-5[postcode]22fcf1` which breaks the `content_id`.  To
+send data that you know is not PII, but it looks like an email address or a UK
+postcode you can provide your arguments wrapped in a `GOVUK.Analytics.PIISafe`
+object.  If any argument to an analytics function is an instance of one of these
+objects the value contained within will be extracted and sent directly to the
+analytics tracker without attempting to strip PII from it.  For example:
+
+```js
+  GOVUK.analytics.setDimension(1, new GOVUK.Analytics.PIISafe('this-is-not-an@email-address-but-it-looks-like-one'));
+  GOVUK.analytics.trackEvent('report title clicked', new GOVUK.Analytics.PIISafe('this report title looks like it contains a P0 5TC ode but it does not really'));
+````

data/app/assets/docs/functions.md

@@ -0,0 +1,62 @@
+## Functions
+
+* [`_helpers.scss`](#helpers)
+
+### <a id="helpers"></a>Helpers
+
+The pixel-to-em or `pem` function returns an em value.
+
+It sets a Sass variable, $base-font-size, to 16.
+
+A value in em is defined as em = target/context.
+
+#### Usage:
+
+Here the default context is 16 ($base-font-size),
+so there is no need to use a second argument.
+
+```
+
+.govuk-title {
+  margin-top: pem(30);
+}
+
+Compiled css:
+
+.govuk-title {
+  margin-top: 1.875em;
+}
+
+```
+
+The first argument will also accept pixel units.
+
+```
+.govuk-title {
+  margin-top: pem(19px);
+}
+
+Compiled css:
+
+.govuk-title {
+  margin-top: 1.1875em;
+}
+
+```
+
+If the context changes, use the second argument.
+
+```
+.govuk-title {
+  font-size: 48px;
+}
+
+.govuk-title-child {
+  margin-top: pem(15, 48);
+}
+
+Compiled css:
+
+.govuk-title-child {
+  margin-top: 0.3125em;
+}