search

alphagov / govuk-design-system

One place for service teams to find styles, components and patterns for designing government services.
https://www.gov.uk/design-system
MIT License
488 stars 230 forks source link

Improve guidance for using Nunjucks #1281

Closed hannalaakso closed 4 years ago

hannalaakso commented 4 years ago

What

We had feedback from a user who thought that the Setup guide for production makes it sound like you'll need to use Nunjucks to use the Design System

Here are some sections of that page we could try to improve:

1. Lists under installation instructions

Both Option 1 and Option 2 include the phrase

use the component Nunjucks templates

I wonder if we could consider doing something like

use the component Nunjucks templates (optional)

to try to clarify this?

2. 'Using Nunjucks macros' section

We also have quite a lot about Nunjucks further down the same page in Using Nunjucks macros. It feels like this section could do with a bit of context to explain that Nunjucks is optional.

Why

We don't want our users to think that they will need use the Nunjucks macros to use the Design System.

Who needs to know about this

Mark

mgladdish commented 4 years ago

To clarify, I was that user.

I was fully aware that using Nunjucks in production was optional, but I was really struggling to reconcile your guidance that js should only be used for progressive enhancement whilst also suggesting that Nunjucks could/should be used in production.

There's no reference in any of the design system docs of how to reconcile those opposing suggestions, or that the Nunjucks templates are really only intended for prototypes and that production systems are expected to re-implement the html themselves.

timpaul commented 4 years ago

Hi @mgladdish - you can use Nunjucks in production whilst still following the guidance to use JavaScript as a progressive enhancement.

For example, the GOV.UK Pay team does this in their service frontend app (https://github.com/alphagov/pay-frontend), compiling Nunjucks on the server before sending the HTML to the client.

36degrees commented 4 years ago

Both Option 1 and Option 2 include the phrase

use the component Nunjucks templates

I wonder if we could consider doing something like

use the component Nunjucks templates (optional)

to try to clarify this?

All of the things in the list are optional, so I'm not sure this makes sense.

However, it's not true that if you install using npm you will be able to use the Nunjucks templates – that's only true if your environment supports it.

What if we added something like this (I've also changed 'templates' to 'macros' to be consistent):

Using this option, you will be able to:

  • selectively include the CSS or JavaScript for individual components
  • build your own styles or components based on the palette or typography and spacing mixins
  • customise the build (for example, overriding colours or enabling global styles)
  • use the component Nunjucks macros, if your environment supports it

We also have quite a lot about Nunjucks further down the same page in Using Nunjucks macros. It feels like this section could do with a bit of context to explain that Nunjucks is optional.

I think this is there to explain what the 'Nunjucks' tab in the code examples is for. Could we move (and improve!) the setup instructions to the Frontend docs, and then simplify it?

Using Nunjucks macros

Nunjucks macros generate HTML based on the options that you pass it, taking care of things like linking form labels to their controls. Using macros make it easier to keep your application up to date, as when you update GOV.UK Frontend the macros will automatically use the latest markup.

You can use Nunjucks macros as long as your application is written in JavaScript and any frameworks that you are using support it.

You can also use Nunjucks macros in the Prototype Kit.

Read more about configuring Nunjucks to work with GOV.UK Frontend macros.

If we want to keep the scope of this work a bit smaller, we could link to the Nunjucks documentation that's currently buried in the page template guidance.

hannalaakso commented 4 years ago

@36degrees Thanks for looking at this.

use the component Nunjucks macros, if your environment supports it

This sounds good to me.

Using Nunjucks macros

Nunjucks macros generate HTML based on the options that you pass it, taking care of things like linking form labels to their controls. Using macros make it easier to keep your application up to date, as when you update GOV.UK Frontend the macros will automatically use the latest markup.

You can use Nunjucks macros as long as your application is written in JavaScript and any frameworks that you are using support it.

You can also use Nunjucks macros in the Prototype Kit.

Read more about configuring Nunjucks to work with GOV.UK Frontend macros.

This sounds good as well. I think what is missing for me (and which might be beyond what we can do here) is a section for HTML:

Using HTML

You can use the HTML versions of GOV.UK Frontend styles and components in any development environment.

You need to manually update the HTML when there is a breaking release to GOV.UK Frontend - the release notes will detail any changes you will have to make to your HTML.

m-green commented 4 years ago

Guidance updates are ready for review! There are 2 PRs but I can't link one of them so here they are: