Component Library [DEPRECATED]

🚨 The Component Library has been deprecated by 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.

Running it locally

The component library is generated by running npm run comp-lib from the project root.

You can then view the Component Library by running npm server, opening a browser and going to http://localhost:9033/.

Adding/documenting a component

Each component should have one documentation block describing the component's various states.

Comment Syntax

Add a multiline comment above the component you wish to document. Each block consists of two required parts and a few optional parts:

• A heading (required)
• A description of what the style does or looks like (optional)
• An example of the markup inline (optional)
• A list of modifier classes or pseudo-classes and how they modify the style (optional)
• A reference to the style's position in the style guide (required)

The component and modifier descriptions support markdown

Example:

/*
Component Title

This is a component description. Also, *markdown* is accepted.

Markup:
<div class="button {{modifier_class}}">Button text</div>

Background: dark

Example Data:
var example = ['testData', 'testDataOther'];

:hover               - Pseudo-class example.
.component--modifier - Component modifier class.

Styleguide: Section.Seb-section
*/

.button {
  &:hover {
    ...
  }
}

.button--primary {
  ...
}

See the kss-node documentation on formatting

Custom comment tags

Experimental

Experimental means it's

• not an established component/design pattern
• It's being A/B tested so isn't being served to everyone
• It's just as likely to be removed as kept in an upcoming version.
• It depends on unnecessary helpers and is in need of a refactor.

To mark a comments as experimental place Experimental: at the start of the description.

e.g. Experimental: This is an experimental component description. Also, *markdown* is accepted.

Deprecated

Deprecated means this component/design pattern is no longer to be used and it will be removed in an upcoming version of assets frontend. To mark an example as deprecated place Deprecated: at the start of the comments description.

e.g. Deprecated: This is a deprecated component description. Also, *markdown* is accepted.

Example Data

The tag Example Data: enables JavaScript data associated with the component to be included on the components page e.g the autoComplete requires a global array of country objects on the page. Just start a paragraph in your section with Example Data: and include the JavaScript after it.

Background

The tag Background: dark enables a dark background on the component example element. This is useful if your component is white and you need to show it on a dark background. Just add Background: dark after the Markup: example.

Templates

The template that the output is generated from lives in the component-library-template repo.

Details on how to edit and contribute can be found in the project's README

That template is included in this project as a dependency in package.json

Deployment pipeline

The component library is generated and deployed to GitHub Pages as part of our internal CI job. Every commit to master results in a new deployment of the component library.

You can view the deployed component library on http://hmrc.github.io/assets-frontend

Further Details

Details on further commands for the component library can be found in the README