Overview

Reusable front-end components and styles used to build digital policing products and services.

It provides a shared visual language (layout, brand, responsive behaviour, dark mode) and a multi-runtime component API (aspComponent) for Nunjucks, Twig, and Razor.

See live examples and guidance on when to use components in the ASP Digital Design System.

Features

Shared CSS styles, layouts, and brand assets
Component library with Nunjucks, Twig, and Razor outputs
Unified aspComponent contract via src/component-manifest.json
Responsive design and dark mode support
Accessibility testing with axe (see Definition of done / Design System guidance)
Automated releases via semantic-release (Conventional Commits)
Published as npm (@policedigitalservices/asp-frontend), NuGet (AspFrontend), and CDN assets

Requirements

Node.js (see .nvmrc in the repository for the CI version)
.NET 8 SDK (for src/dotnet/ development and tests)

Installation

Clone and install:

git clone https://github.com/policedigitalservices/asp-frontend.git
cd asp-frontend
npm install
npm run start

Consuming apps typically depend on the published packages or CDN build rather than cloning for production use.

Node / Formation-style apps:

const { registerAspComponentNunjucks } = require('@policedigitalservices/asp-frontend');
registerAspComponentNunjucks(nunjucksEnv);

PHP / Timber: enable src/php/timber-twig-asp-component.php via Composer, then use aspComponent in Twig.

Razor / .NET: install the AspFrontend NuGet package from GitHub Packages, call .AddAspFrontend() in Program.cs, then @await Html.AspComponentAsync(...).

Macro imports via the components/*/macro.njk pattern remain supported.

Configuration

Commit messages must follow Conventional Commits (enforced by Husky / commitlint)
Releases on master are automated by semantic-release — do not bump versions or npm publish locally for normal releases
CDN URL/version for consuming WordPress sites is typically set via ASP_CDN_URL and ASP_CDN_VERSION (see WP Blocks)

Hosting

CDN assets — built and deployed via Azure Pipelines
Packages — published to GitHub Packages (npm + NuGet)

Tech stack

Node.js / npm
Nunjucks, Twig, Razor (.NET 8)
ESLint, Stylelint, Mocha, Jest, axe
GitHub Actions + Azure Pipelines
semantic-release

Current package version: 2.19.1 (see changelog).

Used by

In-house applications and microsites that share the design system look and feel, including (non-exhaustive):

Formation
Custodian
Subscriber
Windsor
Velocity
VIM
Staff Welfare Fund
Circulation
WP Blocks (renders Frontend macros in WordPress)
Design System

Integrations

In house applications

Force IT

> TODO: Add content.

Third party