LBCamden Frontend

LBCamden Frontend contains the code you need to start building a user interface for Camden platforms and services.

It uses components from the GOV.UK Frontend, and extends these with components via customisations developed for Camden specific implementations.

Tip

LBCamden Frontend is best used in conjunction with the guidance included in the LBCamden Design System documentation.

LBCamden Frontend is currently in beta while the governance processes for contribution and usage are defined. More information is available on the Before you start design system page.

Developing applications with LBCamden Frontend

To start implementing LBCamden Frontend into a project, read Get started for developers within the Design System documentation. This includes instructions about how to install the LBCamden Frontend package and the suggested routes for integration.

Extending or customising LBCamden Frontend

To extend or customise LBCamden Frontend, start by cloning this repository, and then use npm i to install all dependencies.

Important

While LBCamden Frontend is publicly available, the contribution process for external changes is still being established. See the contributing section for more information.

Reviewing the Frontend Library

From version 1.0.0, LBCamden Frontend is entirely Storybook based, allowing components to be viewed and configured via the browser based UI.

Warning

Previous versions that implemented the GOV.UK Frontend Review app are no longer supported.

To start Storybook, use the following command and follow the instructions in the terminal

npm run start

Storybook displays both the GOV.UK Frontend components (previously called "Base" components) and LBCamden Frontend components (previously called "Bespoke" components). It also displays examples of common patterns and full page designs.

Each component within Storybook includes instances of that component configured with parameters that are contained within the component's fixtures file. For information about expanding the example instances, see the Adding new examples section.

Component structure

Each component within LBCamden Frontend follows the GOV.UK Frontend component structure.

A valid component has:

• a directory within the src/lbcamden/components directory with a kebab case name
• a macro.njk file which serves as an entry point for the component
• a template.njk file containing the component's mark up and dynamic functionality via Nunjucks code
• a .scss file named the same as the component's directory
• a .yaml file named the same as the component's directory, which contains information about the component's parameters and example configurations rendered in Storybook
• a template.test.js file containing the standard component accessibility test and any further functional tests required

Additionally, components may also have:

• a .js file named the same as the component's directory, which contains additional dynamic functionality relating to the component
• a .test.js file named the same as the component's directory, which contains additional tests that relate to dynamic functionality defined in the file above
• Additional .scss or .njk files to allow for more modular component structure
• a README.md file with additional information about the component and its usage

For a component's CSS to be bundled as part of the main LBCamden Frontend stylesheet, you must import it in the _all.scss file within the src/lbcamden/components directory.

Important

Placing additional files inside a component's directory may cause the build and test processes to fail. More information can be found in tests/after-build-package.test.js.

GOV.UK styles and LBCamden styles

LBCamden Frontend components uses a mix of upstream GOV.UK and bespoke LBCamden styles and variables.

All GOV.UK styles are prefixed with govuk-.

All LBCamden styles must be prefixed with lbcamden-.

Overriding GOV.UK Frontend component styles

It is strongly encouraged that the functionality or mark up of upstream GOV.UK components is not modified. However, to override the look and feel of a GOV.UK component, it is possible to override the default styles via .scss files.

To override the styles of a specific GOV.UK component, add or amend a file matching that components name in the src/lbcamden/elements directory.

To override GOV.UK SASS variables, add or amend a file in the src/lbcamden/settings directory.

To override a specific GOV.UK styles, add or amend a file in the src/lbcamden/overrides directory.

Adding new examples #

Each component in LBCamden Frontend implements example configurations that are displayed in Storybook.

You can add or amend examples within the examples section of the yaml file within the component directory. This file is parsed into the fixtures.json file contained within the LBCamden Frontend package at build time.

Testing LBCamden Frontend

While developing new components or amending aspects of LBCamden Frontend, we recommend you regularly lint and test code using the tools provided.

How to run linting

LBCamden Frontend includes linting for both scss files (using Stylelint) and JavaScript (using Standard)

To run all linting tools sequentially, use the following command or see the 'scripts' section of package.json for the commands to run individual linters.

npm run lint

How to run the test suite

LBCamden Frontend includes a suite of tests for all components (using Vitest). As part of extending or customising LBCamden Frontend it is required that additional tests are included where appropriate.

As well as component specific tests, each component is tested for WCAG 2.2 AA compliance using a Vitest implementation of Axe.

To run all tests, use the following command and monitor the output.

npm run test

By default, Vitest will run in watch mode. See the 'scripts' section of package.json for the commands to run individual tests or single run test suites.

Tip

VS Code users may find the Vitest extension useful while developing changes.

How to run visual regression tests

LBCamden Frontend implements visual regression tests for each component, pattern and full page example using Chromatic. Visual regression testing is only available to internal Camden users, or via personal Chromatic accounts. It is necessary to create a Chromatic project and retrieve the project token to be able to run the tests.

To set the Chromatic project token, use

export CHROMATIC_PROJECT_TOKEN=YOUR_CHROMATIC_PROJECT_TOKEN

and then

npm run chromatic

to run build and upload all components to Chromatic for testing. Follow the instruction outputted to review changes and re-baseline the project if necessary.

Releasing LBCamden Frontend

LBCamden Frontend is published as a package via npm. This repository contains scripts to build and release updates. Only authorised internal users can release a new version of the package.

Setting up a new release

1. Ensure you are checked into main and have pulled the latest version
2. Create a new release branch, using the following command, where X.Y.Z is your next release following semver versioning

git checkout -b release-X.Y.Z

3. Update both package.json and src/lbcamden/package.json to ensure version matches X.Y.Z
4. Build the latest package and dist directories for this release, using the command

npm run build

5. Once built, use the following command to verify the output matches the required format.

npm run test:build

6. Add the newly created files and commit the changes. Push the new release branch back to Github using the command

git push origin release-X.Y.Z

and create a new PR for this release branch. Update all existing PRs to use this branch as their new target.

How to package up ahead of release

To build the package ahead of release, with the release branch checked out, use the following command.

npm run build

This script collects and parses the files required for each component, and bundles the supporting CSS and JS files. The output of this process is placed in the /package directory which is included in the repository source control.

Once built, use the following command to verify the output matches the required format.

npm run test:build

If any changes were created by the npm run build command, commit these after testing the build.

Visual regression tests should also be run against changes prior to releasing an update.

Once all tests have completed, merge the release-x.y.z branch into the main branch.

How to release

To publish an updated LBCamden package, use the following command when checked into the main branch.

npm run release
npm run release:publish

The process will require authentication into the LBCamden npm organisation.

Once released, you must update the Releases section of the LBCamden Frontend repository and set the current release to "Latest".

Example pages and patterns

In addition to individual components, it is possible to create and amend full page and pattern examples that are displayed within Storybook. Full page and pattern examples are stored within the examples directory.

Important

The full page and pattern examples contained within LBCamden Frontend may contradict guidance in the Design System documentation. The Design System should be considered the source of truth for all patterns and guidance.

Getting updates

Breaking changes are published as part of the release notes for each release.

LBCamden Frontend aims to follow semantic versioning, and implements MAJOR, MINOR and PATCH releases.

When implementing LBCamden Frontend into a project, we recommend you have functional (for example Cypress) and visual regression (for example Chromatic) tests in place to make sure upstream changes do not impact downsteam implementations.

Browser support

LBCamden Frontend aims to follow the GOV.UK Frontend standards for browser support.

Accessibility and assistive technology

LBCamden Frontend aims to meet WCAG 2.2 AA for all components. This does not mean that any project implementing LBCamden Frontend is automatically compliant, and all projects will require further automated and manual testing to ensure compliance. The LBCamden Design System documentation contains more information in the Accessibility section.

Security

We are an advocate of responsible vulnerability disclosure. If you’ve found a vulnerability, we would like to know so we can fix it.

While we are working on our security policy, please contact the Design System team if you have any questions. Further information and guidance about disclosing security issues can also be found via the GOV.UK Frontend Security policy.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

Contributing #

We are working on our contribution process. If you are interested in implementing or extending LBCamden Frontend while we establish our formal processes, please contact the Design System team.

Contact the team #

To ask questions, inform us about any security issues, or discuss how to implement or extend LBCamden Frontend, please contact the Design System team via design-system@camden.gov.uk.