Review each of the components required JavaScript, make sure they are compiled in the gulp scripts and update the documentation on how to use them.

• Use IDs instead of class names in JavaScript.
• eslint
• Fix JavaScript comment format, and comment for each component
• Compile into 1 file using Gulp and minify that file.
• Document each components JavaScript and how to include
• Write coding standards for JavaScript
• Header JavaScript: Only try to run the jQuery code if jQuery is included to stop it blocking any other scripts below.
• Test overall JavaScript

jQuery Discussion

Remove jQuery? The only component that uses jQuery is the auto complete. GDS have an accessible auto complete component (JavaScript only) that we could use.

https://githubengineering.com/removing-jquery-from-github-frontend/

• No jQuery dependency required in projects.

Use this issue to refactor the component: Pagination

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Implement ITCSS (Inverted Triangle CSS) structure to our project to help reduce specificity and increase maintainability. See the following article about ITCSS https://csswizardry.net/talks/2014/11/itcss-dafed.pdf

Have a look into Parker for plotting our specificity, so that we can track it over time. See the following articles about specificity https://csswizardry.com/2014/10/the-specificity-graph/ & https://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/ & https://cssguidelin.es/#specificity

Use this issue to refactor the component: Footer

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Details

Use this issue to discuss the Details component.

Preview the details component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

Use this issue to refactor the component: Skip to main content link

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Cookie Banner

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Do and Don't List

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the Sass for: heading captions

Use this issue to refactor the component: Panel

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Key selector

• .nhsuk-icon__chevron-down path {
• .nhsuk-icon__chevron-up path {
• .nhsuk-list--check svg,.nhsuk-list--cross svg {
• .nhsuk-c-action-link:focus span {
• .nhsuk-c-action-link:hover span {
• .nhsuk-c-care-card--black .nhsuk-c-care-card__content a {
• .nhsuk-details__text p {
• .nhsuk-c-global-alert a {
• .nhsuk-footer__logo a {
• .suggestions-item:focus div,.suggestions-item:hover div {
• .suggestions-item--selected a {
• .nhsuk-c-pagination a {
• .nhsuk-c-pagination a {

Core

• Sass comments for files that do not generate CSS
• Comment spacing - alignment
• Font face - move from settings to generic
• Variables - use of !default - base font margin 8px
• Exports - Figure out what it does - if using it then it needs adding to each components Sass file
• 'Magic numbers' - ack (need to install) - $ ack -l --sass '\dpx'
• Breakpoint name @mixin - mq - govuk
• Replace all instances of govuk-media-query with mq.
• Tools Typography - "These mixins allow us to quickly and consistently generate common text patterns such as colours..."
• Mobile first MQ's
• Minus number Sass spacing map
• Change colour to color
• Change class name .active to .is-active
• Core components and UI components
• Utilities need u- adding
• Utilities - top-and-bottom needs deleting

Components

• Care card heading margin: 0; should be margin-bottom: 0;
• Check shorthand margin/padding.background declarations - $ ack --sass '(background|margin|padding):'
• Instance of !important - look at doing it another way eg: .foo.foo ($ ack --ignore-dir=packages/core/utilities/ --sass '\!important;')
• SVG assest path variable
• -9999px replacement: http://www.zeldman.com/2012/03/01/replacing-the-9999px-hack-new-image-replacement/
• Footer list &:last-child should be > &:last-child - should be probably for all &:last-child
• Header - break into smaller files
• Header - large desktop media query - should we re-arrange it?
• Sass comments - new section with Sass file should restart comments number (1, 2, 3) - not (6, 7, 8)
• Hero - make comments on 'random numbers' eg: 240px
• Image component - 'syntax sugar' - & + &
• Back to top - make a decision on whether we keep it or not
• Pagination <a> could do with changing a class - eg: nhsuk-pagination__link
• @mixin panel could be renamed to save confusion
• Panel - need to nest .panel-group & { } - "key selector should only appear once".
• Skip link - -9999px needs replacing (see above)
• Table - nest table responsive into table.

Assets

• Icons - change logo to logo-nhs

Use this issue to refactor the component: Review Date

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Promo

Breaking changes

• The promo image is now inline. Eg: <img class="nhsuk-c-promo__img" src="..." alt="...">

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Care Card

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

We need to refactor each of the component READMEs and macros to make sure they are consistent. There is a new README template to use across all components.

• Make sure each of the component READMEs are consistent with each other.

• Each component has a GitHub issue and is linked to from the README.

• Make sure each of the parameters are consistent with each other.

• Make sure each of the macros can pass classes and attributes.

• Create a table of macro arguments for each component

• Decide on a policy on our advice to using macros due to the security risk https://mozilla.github.io/nunjucks/api.html#user-defined-templates-warning

• Action link

• Breadcrumb

• Primary Care Card

• Emergency Care Card

• Urgent Care Card

• Contents list

• Details

• Do and Don't list

• Emergency alert

• Expander

• Expander group

• Feedback banner

• Footer

• Header

• Header transactional

• Header with navigation

• Header with search

• Hero

• Hero with image

• Hero with image with content

• Images

• Inset text

• List panel

• Pagination

• Panel

• Panel with grey background

• Panel with label

• Promo

• Promo with no description

• Promo small

• Promo with image

• Review date

• Skip link

• Tables

• Warning callout

All assets referenced by the CSS are at /assets/*.
Some people might not be able to host at this location.
We should add a configuration option in sass so that the base url can be used.

What base url do other CSS frameworks use in the compiled version? Maybe a relative path would be best for the default compiled css.

Use this issue to refactor the component: Emergency Banner

Breaking changes

• Class nhsuk-c-global-alert__header is now nhsuk-c-global-alert__heading

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Contents list

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Add code comments into our scss files to explain intent and make it easier to search/grep for the components or elements we are looking for. Follow this article on writing CSS comments, including the template and titling in all of our files. https://cssguidelin.es/#commenting

Remember: Comment with our intent, not the implementation.

Use this issue to refactor the component: Table

Breaking changes

• To update

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Anywhere we use an SVG icon, the HTML validator (https://validator.w3.org) returns issues because of the IE8 fallback method we use.

<image class="nhsuk-logo nhsuk-logo__fallback" src="/assets/logos/fallback/nhs-logo.png" xlink:href=""></image>

Error: Attribute src not allowed on element image at this point.
Error: Element image is missing required attribute height.
Error: Element image is missing required attribute width.

When adding a width and a height attribute to the image, the image appearing on browsers other than IE8, which we don't want. We need to investigate the issue further and fix it on every component where an SVG icon is present.

Contents list

Use this issue to discuss the Contents list component.

Preview the contents list component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

Emergency alert

Use this issue to discuss the Emergency alert component.

Preview the emergency alert component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

Breadcrumb

Use this issue to discuss the Breadcrumb component.

Preview this component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

Github-flavour markdown can use syntax highlighting with a code after three backticks, e.g

```html
<p class="code">syntax highlighting</p>
```

resulting in:

<p class="code">syntax highlighting</p>

We should enable this syntax highlighting in our own built documentation

Final cleanup of components before releasing.

Checking / amending:

• print styling - use of @mixins
• link styling - use of @mixins
• add 12px to spacing map and update key values to be the same as px size
• alphabetise backstop.json component list
• triangle @mixin - care card and hero
• class names should use heading and not header
• check macros - each macro should use params and each component should have classes on surrounding element
• check .nhsuk-main-wrapper spacing - should be 48px on desktop and 40px on mobile
• body line-height
• promo component colour variant - grey
• center align element helper class
• update visual tests for all components
• update change log
• use the HTML syntax highlighting in READMEs

Use this issue to refactor the component: A-Z List

Breaking changes

• To update

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Feedback Banner

Breaking changes

• Class nhsuk-c-feedback-banner__header is now nhsuk-c-feedback-banner__heading

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Details

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

We need to refactor the typographic scale with Sass to make it scalable. Resulting in cleaner, more efficient code and whilst making it easier for designers and developers use typography sizing helping the design (sizes and spacing) stay consistent.

Do and don't list

Use this issue to discuss the Do and don't list component.

Preview the do and don't list component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

When we release a new version of the frontend library, we would like our compiled assets to be automatically deployed to assets.nhs.uk for people to hot link with. We can use our current Travis, Docker and Rancher implementation to do this, we need to investigate deploying to buckets.

@mikemonteith has started some proof of concept work on this in the branch ci-deployment.

Use this issue to refactor the component: Action Link

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

• docs/ should contain only human-readable markdown files.
• site/ should contain any scaffolding for building our html docs site such as layouts or .njk pages

Use this issue to refactor the component: Inset Text

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Implement PostCSS to prefix our class names with nhsuk_, add browser vendor prefixes and minify our CSS. Currently we use gulp to compile our sass to css, clean and minify it, investigate whether we need both or we can use npm scripts & PostCSS alone to reduce our dependencies. Parker will allow us to graph CSS specificity and help us with the ITCSS (Inverted Triangle CSS) structure later on.

Work has been started by @mcheung-nhs on moving our tooling over to PostCSS in the branch /feature/postcss

We could also investigate any further PostCSS plugins that would be useful, but I think we've got the important ones.

Use this issue to refactor the component: Warning Callout

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Action link

Use this issue to discuss the Action link component.

Preview the action link component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

Care card

Use this issue to discuss the Care card component.

Preview the primary care card component
Preview the emergency care card component
Preview the urgent care card component

Find out more about the action link component and when to use it in the NHS Digital service manual.

See our contributing guidelines

Update the content on the frontend GitHub pages.

Use this issue to refactor the core styles.

/settings
/tools
/elements
/objects
/utilities
/styles
/assets

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Use this issue to refactor the component: Do and Don't List

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Header

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

We need to have a look how we write out scss and prevent any bad habits, following this we also need to document a set of frontend coding styles. The following article is a good start on how we could improve our scss writing https://cssguidelin.es some key things are the way we nest our styles, magic numbers and naming spacing/conventions.

We can review our sass-lint rules to help us maintain better coding habits.

Use this issue to refactor the component: Images

Breaking changes

The img tag now uses a class named "nhsuk-c-image__img".

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Expander

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Create a testing criteria to test components and elements against. This should include; browsers, screen resolutions, assistive technologies, written tests and possibly visual regression tests in the future. These should be added to the documentation folders and to the pull request template as a checklist.

Taking inspiration from GDS and their testing policies; https://gdstechnology.blog.gov.uk/2018/06/26/changing-our-testing-requirements-for-internet-explorer-8-9-and-10/ & https://github.com/alphagov/govuk-frontend#browser-support

Use this issue to refactor the component: Breadcrumb

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG

Use this issue to refactor the component: Hero

Refactor checklist

• Sass file contains comments, using the comments template format
• Refactor code using BEM for naming
• Remove / refactor any code smells
• Remove / refactor any 'random numbers' or make comments where it is necessary to use

Component checklist

• SCSS
• SCSS lint
• HTML template
• HTML validate & lint
• Nunjucks macro
• A standalone example
• README/Documentation
• Pseudocode tests
• Visual tests
• Tested against our testing policy (Resolution, Browser & Accessibility)
• Print stylesheet considered
• CHANGELOG