fordie / assets-frontend

Shared static assets for frontends on the Multichannel Digital Tax Platform - http://hmrc.github.io/assets-frontend

assets-frontend

This repository contains the source files and documentation for the Components & Design Patterns used to design and build digital services for the HMRC Tax Platform.

It provides additional styles on top of the GOV.UK styles.

Quick Start

Requirements

• Node.js == 4.8.4
• npm >= 2.11.3

To install multiple versions of Node.js, you may find it easier to use a node version manager:

• nvm
• n

Installation

Clone this repository and run install:

$ git clone https://github.com/hmrc/assets-frontend.git
$ cd assets-frontend
$ npm install

Running

1. Run npm start
2. Assets are then available at http://localhost:9032/assets/999-SNAPSHOT/
3. The Design System is available at http://localhost:9034/
4. The Component Library [DEPRECATED] is available at http://localhost:9033/

Usage

Using assets locally

Prototypes

For now, the quickest and simplest way to add assets-frontend to your prototype is to grab the built CSS and JS from production.

Just replace VERSION in the links below with the released version you want to use (we recommend using the latest).

If your prototype is based on the GOV.UK prototype kit then do the following:

CSS

Save the file found at https://www.tax.service.gov.uk/assets/VERSION/stylesheets/application.min.css to /app/assets/sass/assets-frontend.scss.

And add the following to app/views/includes/head.html:

<link href="/public/stylesheets/assets-frontend.scss" rel="stylesheet" type="text/css" />

JavaScript

Save the file found at https://www.tax.service.gov.uk/assets/VERSION/javascripts/application.min.js to /app/assets/javascripts/assets-frontend.js

And add the following to app/views/includes/head.html

<script src="/public/javascripts/assets-frontend.js"></script>

Frontends

If your frontend is based on init-service, then you just need to make sure the configuration for assets in the application.conf file has the line version = ${?ASSETS_FRONTEND_VERSION} after declaring the actual version.

Once it has, you just need to set an environment variable before running your frontend:

$ ASSETS_FRONTEND_VERSION=999-SNAPSHOT sbt run

If you’re using service-manager, please read the service manager guidance in the Wiki.

Using assets in production

Running npm run build calls the build gulp task and this happens on our internal Jenkins instances.

The final step of our internal release pipeline is to version and deploy the compiled assets to https://www.tax.service.gov.uk/assets/VERSION/.

Releasing assets for use in production is currently a manual process which is owned by the Service Design Tools team.

If you’d like a new version of assets-frontend released, please get in touch with us in the #team-sdt Slack channel.

HMRC Design System

The HMRC Design System can be viewed here.

For detailed information on how the HMRC Design System works, please read the Design System page in the Wiki.

Component Library - [DEPRECATED]

🚨 The Component Library has been deprecated in favour of the HMRC Design System.🚨

If your service relies on a component or pattern that doesn’t appear in the HMRC Design System then please follow the Design System contribution guidelines.

For detailed information on how the Component Library works, please read the Component Library guidance in the Wiki.

Contributing

Design Patterns

For details on how to contribute Design Patterns, please take a few minutes to review our Design Pattern standards and contribution process before you submit your request, otherwise it may be rejected.

Features and issues

If you’ve spotted an issue or thought of a feature that you’d like to contribute to assets-frontend, please take a few minutes to review our contribution process and guidelines for Assets Frontend before you submit your request, otherwise it may be rejected.

License

This code is open source software licensed under the Apache 2.0 License.