@not-govuk/components

NotGovUK

An implementation of the GOV.UK Design System in React that provides support for writing internal applications in addition to public ones.

The components are written in Typescript and documented in Storybook's MDX format.

Consuming these components

WRITEME!

What does "support for internal applications" mean?

The GDS styling is only suitable for public facing applications that are to be served under service.gov.uk. This is because it use the propriatary font, 'New Transport' which is only licensed to this sub-domain. In addition, GDS have requested that their crown logo also only be used in this context.

This is quite irritating for those building services within government departments as a lot of our work is on internal applications. For these applications we would like to take advantage of the good work that has been done in GDS on ensuring that applications are accessible with a good user experience. Also, as our work spans both public and internal applications we would like to be able to share components across both contexts wherever possible.

This is also quite irritating for local government, foreign governments, and indeed many other organisations who may wish to provide a good, simple, accessible user experience by building on the work done by the UK's GDS.

The GDS layout is also very narrow, probably as an optimisation geared towards simple, linear workflows such as filling out forms. This is unsuitable for less linear workflows that one might find in case-working systems or dashboards.

NotGovUK solves these problems by allowing consumers to provide an internal class on their body tag which will change the font expand the layout to use more of the screen.

Why React?

This implementation of the GOV.UK Design System uses React rather than Nunjucks as used in the original. This is because there are some considerable advantages to React over Nunjucks.

Client-side applications

React is primarily a client-side technology whereas Nunjucks is for the server-side. Rendering components on the client allows us to provide UI interactions without loading a new page from the server. This is much quicker and so have the potential to drastically improve the overall user experience.

Historically, we have shyed away from client-side applications for accessibility reasons and the difficultly of supporting older browsers. However, React allows us to create, so called, 'isomorphic' applications. That is, applications that render on both the server-side and the client-side. This allows us to do progressive enhancement and provide client-side rendering to modern clients whilst still providing server-side rendering as a fallback option.

Popularity

React is also looking to be far more popular than Nunjucks which should make it easier to resource projects in the long run.

Why Typescript?

WRITEME!

Working on this repository

Prerequisites

The following sections will assume that you are on a UNIX-derived operating system (e.g. Linux, Mac etc.) and have the following software installed on your system:

• Node.js
• (GNU?) Make
• tmux

The only hard requirement this probably Node.js. If you don't wish to install the rest or are working on a Windows system, I would suggest that you read the relevant sections of the Makefile and the .tmuxrc file.

Other dependencies

If you'd like to manually pull dependencies as a seperate step (which is unnecessary) you can run the following command:

make deps

Alternatively, if you'd like to bypass Make you can run:

npm install

Bringing up a local development environment:

This can be done by the followiung commands (assuming you are not already working inside of tmux):

tmux
make tmux

Under the hood this is doing a few things:

• pulling any missing dependencies (npm install)
• bringing up the demo app (npm start)
• bringing up development environment (npm run storybook)
• running the test suite (npm run test:watch)

All of these will react to any code changes you make, without requiring manual intervention.

The development environment is largely based on Storybook's "Design System for Developers" though I am also indebted to Michael Shilman's gist for Typescript support.

Navigating this repository

• ./src/lib/ The source code for this library as a whole.
• ./src/lib/components/ Contains directories each defining a single component. (The structure of these is explained below.)
• ./src/ The source code for the demo app. (Based on CRA.)
• ./coverage A code coverage report that can be created by running make test.
• ./storybook-static A static version of the storybook that can be created by running make docs.

Files in a typical component

1. index.ts[x] The implementation of the component. It may reference other .tsx files in order to separate business logic from presentation logic. Otherwise, it will typically be very simple and contain mostly HTML code.
2. index.scss The SCSS (CSS) code that pertains to the component.
3. index.spec.ts The tests for this component.
4. index.stories.mdx The main documentation of the component. This is what people will use to understand how to consume the component.
5. README.md Very simple documentation to aid people browsing the code via GitHub. Typically this will just link to the GOV.UK Design System and include a screenshot of the component.

Contributing

Pull requests are welcome but it is probably best to open an issue first to discuss what you think needs to change.

I would like this project to be as easy as possible to both consume and contribute to. To that end, if you think any of the documentation isn't clear please do let me know by raising an issue or a pull request.

Finally, this work is still at quite an early stage. If you run into any problems or have any questions, please do get in touch.

-- Daniel Martin, December 2019.