alphagov / govuk_elements

❗️GOV.UK Elements is deprecated, and will only receive major bug fixes and security patches.

The GOV.UK Design System launched on 22 June 2018

GOV.UK Elements:

• is no longer maintained
• will only be updated for major bug fixes and security patches
• does not meet the Web Content Accessibility Guidelines (WCAG 2.1 level AA) accessibility standard

This framework will remain available in case you’re currently using it. To help your service meet accessibility requirements, you should use the GOV.UK Design System. You can migrate to the Design System from GOV.UK Elements.

GOV.UK elements ·

GOV.UK elements is three things:

1. An online design guide, explaining how to make your service look consistent with the rest of GOV.UK.
2. An example of how to use the code in the GOV.UK template and the GOV.UK frontend toolkit.
3. An npm package of the Sass files.

GOV.UK elements guide

https://govuk-elements.herokuapp.com/.

Using govuk-elements-sass

Installation and usage instructions can be found in the govuk-elements-sass README.

Running this site locally

If you would like to clone the repository and run it locally, you will need Node.js (at least version v0.10.0).

Clone this repository

git clone [email protected]:alphagov/govuk_elements.git

Install all dependencies

npm install

Run the app

npm start

Go to localhost:3000 in your browser.

Running tests

To check the whole codebase, run:

npm test

Linting

GOV.UK lint

GOV.UK elements uses govuk-lint, which uses scss-lint as its scss linter.

Standard JavaScript

GOV.UK elements uses standardjs, an opinionated JavaScript linter. All JavaScript files follow its conventions.

Both linters run on CI to ensure that new pull requests are in line with them.

Running Wraith to compare changes

GOV.UK elements uses Wraith so that regressions can be easily spotted.

This needs to be run from the Wraith directory /tests/wraith and some dependencies need to be installed on the local machine first.

1. Install Wraith and its dependencies.

    gem install wraith
    
    brew install phantomjs
    
    brew install imagemagick
   

2. Take a baseline of the current version.

On master run:

    wraith history config.yaml

3. Switch to your feature branch and make changes.

On your feature branch run:

    wraith latest config.yaml

Releasing a new version

Follow the instructions in CONTRIBUTING.md.

Pattern libraries using GOV.UK elements

Here are examples of service-specific pattern libraries using GOV.UK elements.

• Rural Payments style guide | Source Code
• Land Registry pattern library | Source Code
• Digital Marketplace frontend toolkit | Source Code

Contributing

You can find contribution guidelines in CONTRIBUTING.md

govuk_elements's Issues

Radio button background not grey on de-select

Radio button backgrounds are no longer being re-greyed on de-select in the radio button section of the GOV.UK elements guide:

Checkboxes are not effected by this issue. They are still being re-greyed on de-select.

The changes to selection-buttons.js in this commit may have introduced the radio button issue.

Some colours aren't shown

Some colours from the palette aren't shown on the Colour page - eg. light-blue-25. Is this intentional?

https://github.com/alphagov/govuk_frontend_toolkit/blob/master/stylesheets/colours/_palette.scss

Make default table text size the same as body copy

We should assume that table text is the same 19px size as standard body copy, unless specified otherwise. Would be nice if the .font-xsmall class could be applied to an entire table though.

Release notes

Is there any chance of including release notes (e.g. whats changed and any bug fixes) when a new version is released(https://github.com/alphagov/govuk_elements/releases/tag/v1.1.4)?

This should be fairly easy to do inside github (https://github.com/alphagov/govuk_elements/releases) where it allows you to create draft release and for you to add to it as PR are merged.

Here is an example of release notes https://github.com/firebug/websocket-monitor/releases/tag/websocketmonitor-0.5.3

This would help when it comes to updating other projects that rely on govuk_elements and things to look out for that could potentially break like additional files added/removed or even restructured to govuk_elements

Highlight box colour contrast too low for WCAG AA

Highlight boxes (as visible at the bottom of https://govuk-elements.herokuapp.com/colour/ ) have a too low colour contrast (3.17) to comply with WCAG2 level AA.
Offending line is:
https://github.com/alphagov/govuk_elements/blob/master/public/sass/elements/_components.scss#L7
Suggest: #0c857b as the nearest colour that satisfies the requirement

Hide code snippets when JavaScript is disabled.

Prism.js is used to format and style the code snippets.

When JavaScript is disabled, hide the code snippets.

Radio buttons jump up and down on Safari when activated

Radio buttons, when activated drop down by about 10 pixels in Safari 8 and 9 on OS X. They jump back up to their original positions when the animation ends.

(filed the original issue in the wrong place)

Inline radio improvements (spacing)

Inline radio buttons have a margin bottom of 15px. This margin is for spacing, if conditionally revealing content exists. Very nice.

The problem is when conditionally revealing content does not exist. Where we simply want a Yes/No answer. In this case it makes no sense to have a margin bottom value. And as a result, this puts the space consistency out of rhythm.

My suggestion would be to apply the margin top on the panel if it sits within an inline field set.

This would then fix the spacing issue for inline radio when no conditional content is required

Beta phase tag colours don't meet WCAG 2.0 AA

The white text on orange (#f47738) background used in the beta phase tag doesn't meet the contrast criteria for WCAG AA.

It give us a contrast ratio of 2.8:1

WCAG AA requires a ratio of 4.5:1
WCAG AAA requires a ratio of 7:1

NPM install causes warning error with Node other than 4.0

The package.json in this repo specifies Node 4.0 specifically - if users have a newer version they'll get a warning when installing this with npm install.

Can the specificity be reduce to accept any 4.x.x version?

Add example of meta-data

Most gov.uk pages have meta-data items like

Last updated: 15 October 2015

on them but I cannot see this in the typography elements.

Central Style guide

Hi.

I've been working on the Department for Education School Perf. Tables (Alpha now moving to Beta) and wanted to ask if there is a central style guide for all the gov uk components etc.

So far I've found style guides like this http://rural-payments-styleguide.herokuapp.com/elements/snippets/#layout which gives us a lot structure but no skin separation and no javascript examples plus its navigation is a bit painful for the less front end savy dev's.

I come from an OOCSS background where structure and skin is separated. We have three projects here that we want to skin but maintain a gov uk structure plus we have extra feature rich components like maps, mobile swipe interactions etc etc.

I'm now looking to build a style guide during our beta journey that gives the less front end savy developers a easy way to just grab html, js etc.. and get on. So what I'm trying to find is a one stop shop that gives us the following ability:

• a style guide build tool process (like hologram) lets us integrate our skins with the gov uk sass components and generate a style guide which we host on each published DFE website
• The style guide should contain overview\description of each (most) components, html and js examples etc..
• simple navigation for less front end savy dev's to find what they need

Is there any such place the fulfils this?

Disabled button styles do not have sufficient contrast

The style for disabled buttons does not have sufficient contrast - it's 2.48:1.

IMHO in most cases we should avoid using disabled styles, but where they are needed, we should come up with a style that can be seen easily.

Duplication of content on the README.md

The bit of stuff starting...

Take a look at /public/sass/_govuk-elements.scss to see

... is in there twice.

Details polyfill doesn't open/close with spacebar/enter key when JAWS is running

In user testing we've seen a partially sighted user unable to open the details element when using JAWS screen reader. The summary is described as a button, when pressing the spacebar/enter key, the key name is read out but the element never opens.

JAWS seems to prevent the spacebar/enter key from being captured, unless another key is pressed before. So, if you press the Windows key and then spacebar the details element does open.

I've been able to replicate this problem using Vista/IE9/JAWS 13. I've tried adding aria-pressed attributes to the summary element and have tried replacing role="group" with role="application" but neither of these have worked.

select.form-control element arrows are hidden in webkit

When using select.form-control the drop down arrows are hidden in webkit caused by this line.

Before I override this in our project I just wanted to find out the reasoning just in case there is something i have misunderstood, or maybe this is a bug here? :)

thanks.

Clarify specific markup requirements for details tag

The progressive disclosure example shows how to polyfill a <details> tag in browsers that do not provide support for it. However, the polyfill only works for markup in exactly the form given in the example; it does not work generally for all <details> tags.

Could this be made clearer?

TypeError: 'undefined' is not a function (evaluating 'this.markSelected.bind(this)')

When trying to reuse selection-buttons.js in a Rails app (https://github.com/ministryofjustice/accelerated_claims) - I get the following error when running integration tests in Phantomjs:

TypeError: 'undefined' is not a function (evaluating 'this.markSelected.bind(this)')

How do you run integration tests?

It appears that phantomjs does not support bind(). Is the solution to add my own bind function when testing, as described here:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind#Polyfill

Enhancement to radio, checkboxes and conditionally revealing content

I have noticed that for all radios, checkboxes and conditionally revealing content they all assume no value has been chosen. In most cases this is good as it forces the user to make a choice.

What about the following scenario:

A user returns to a page with the ability to update an already populated form, which may or may not include radios, checkboxes and conditionally revealing content based on form selection.

I would have expected that if the input has "checked" or checked="checked" then all required styling would be applied, but this does not look to be the case.

Is this something to be added in future releases?

Make govuk_elements SASS it's own module

It'd be really neat to be able to install just the SASS from govuk elements much in the same way as the govuk_frontend_toolkit

So probably using npm we could have something like:

npm install --save govuk_elements_sass

We are currently copying it and other people are installing all of elements just to get at the SASS so making this into it's own module would solve lots of problems.

Add example of search box with inline search button

We use these everywhere – e.g. www.gov.uk homepage, all other pages in the header

Can we add one to this repo?

we should probably change the content of the grid example

https://github.com/alphagov/govuk_elements/blob/master/views/examples/grid_layout.html

Consider removing type attributes and removing self-closing tags

It would be good to remove type attributes as they are not required in a HTML5 document.

It would also be good having consistency. In some cases we have self closing tags and in other cases not. They are not required in a HTML5 document.

For example:
rel="stylesheet" />
rel="stylesheet">

Would it be possible to publish this as an npm module?

We're using a lot of the components for this down at the passports exemplar, but keeping up to date with changes is tricky as it's a manual process.

Just being able to update the version in our package.json would make life a lot easier - as we do with the mustache tempaltes and forntent toolkit.

Thanks.

File upload pattern

It would be good to have a pattern for this, I see Digital Marketplace has this

http://alphagov.github.io/digitalmarketplace-frontend-toolkit/forms/upload.html

Sass placeholders are not supported

This was resolved in #40, however, has been reverted as node-sass 1.0.1 fails to build on Heroku

Once the issue with node-sass has been resolved, #40 can be re-merged and GOV.UK elements can use the same grid examples as the GOV.UK front end toolkit.

The 'code' class can overlap when on adjacent lines

Example:

A gem wrapper around govuk_elements

For ease of using govuk_elements in Ruby on Rails apps, could you create a govuk_elements_gem?

This approach would be consistent with the gem wrapper around the govuk_frontend_toolkit: https://github.com/alphagov/govuk_frontend_toolkit_gem

Discussion: Background colour for radio buttons and checkboxes

Does the current background colour make radio buttons and checkboxes hard to see?

Should radio buttons and checkboxes also use a 2px dark grey border?

Is the 'selected' style for radio buttons and checkboxes too similar to the styles for form controls (white background, black border).

Could you add a section on 'panels'?

I was expecting a small bit of guidance around panels in the form elements section of the guide.

They get used inside the Errors and validation section (see screenshot), and there are examples of using panel panel-border-narrow in the 'Conditionally revealing content' section of the form elements. This is cool, but it's a bit hidden away.

Could you add a section on how to and where to use panels?

Could we add a 'binary' class for yes no buttons?

Proposal:

Add a binary class so that yes/no buttons sit next to each other even on small screens.

Currently:

Proposed:

The <abbr> tag and style

What is the desired style of this tag?

In Chrome we have no underline and in Firefox we have a dotted border bottom. Because no styling has been applied other than cursor: help; I am under the impression this is how GDS want it.

Has this been missed? Should I set text-decoration: none on this element?

Any steer would be good.

Thanks

Example of 'Conditionally revealing content'

The provided example on this page is :
'

Do you know their National Insurance number?

  <legend class="visuallyhidden">Do you know their National Insurance number?</legend>

  <div class="form-group">

    <label class="block-label" data-target="example-ni-no" for="radio-indent-1">
      <input id="radio-indent-1" type="radio" name="radio-indent-group" value="Yes">
      Yes
    </label>

    <label class="block-label" for="radio-indent-2">
      <input id="radio-indent-2" type="radio" name="radio-indent-group" value="No">
      No
    </label>

    <div class="panel panel-border-narrow js-hidden" id="example-ni-no">
      <label class="form-label" for="national-insurance">National Insurance number</label>
      <input class="form-control" name="national-insurance" type="text" id="national-insurance">
    </div>

  </div>

</fieldset>

'

The 'No' label is missing the data-target="example-ni-no" attribute

Different sized buttons

Hi, is there any particular reason why the govuk element button class (https://github.com/alphagov/govuk_elements/blob/master/public/sass/elements/_buttons.scss#L7)
uses different padding to the govuk frontend toolkits button mixin (https://github.com/alphagov/govuk_frontend_toolkit/blob/master/stylesheets/design-patterns/_buttons.scss#L30)

GOVUK Elements Button class:

padding: em(10) em(15) em(5);

GOVUK Frontend Toolkit Button mixin:

padding: 0.3em 0.6em 0.2em;

GOVUK Elements button class calls GOVUK Frontend Toolkits button mixin and then overwrites the padding as above.

I’m happy to remove it from govuk elements, update govuk frontend so GOVUK Elements button class still has the same amount of padding and to pr it. Its just a pain to line up buttons when you use .button and then button mixin to create secondary buttons.

Any thoughts about it?

Proposal: Add elements for Printing / Downloadable documents

There's some patterns here for downloadable documents. Would probably make sense if they were in this repo?

I mainly think so because I've just added the download link into a prototype I'm working on by copying over the SCSS and the icon, so it seems like it would save time.

Error validation summary guidance leads to repetition

If you follow both our validation guidance, and our guidance to have 'one thing per page', I'm concerned that you'll end up with redundant repetition on the page.

For example, if there's one thing on the page: "What is your national insurance number?", then the summary error and the field error will be the same.

Is there a way to make this situation accessible (eg using a visually hidden element, or focusing the field error) without adding redundant elements to the page?

An example:

Colour contrast for borders on form elements

We currently recommend using $grey-2 (1.81:1 contrast) for borders on form elements. It has been suggested that the contrast is not sufficient and that the 1px border width is too thin.

Propose increasing the border width to 2px.

If this not sufficient, it may well be necessary to also darken the border colour to $grey-1 (4.56:1 contrast).

A pull request for this change can be found in #104.

Awaiting feedback from Edward Horsford @edwardhorsford at passports (in user research 12/10/15) and Simon Wilson from Inheritance Tax.

Example of errors for date fields

Currently there are no examples of where errors should be presented or how they should be presented.

My initial thought were that it would be between the day/month/year labels and the fields but what if the validations only relate to one part of the date like an invalid month.

Any other suggests?

This is taken from Register to Vote

Fieldset does not require both width and float

https://github.com/alphagov/govuk_elements/blob/master/public/sass/elements/_forms.scss#L31

The above rule contains conflicting rules of width: 100% and float: left with clear: both.
This triggers a rendering bug in IOS Webkit experienced in portrait mode on an iPad.

Proposed solution is to remove the float and clear rules.

Inline class on the fieldset causing issues with the requirement for stacked items inside

I have found in our service we have a requirement to have stacked radio options within an inline group of options of Guilty / Not guilty

Essentially placing a fieldset inside a fieldset which is totally fine. The problem is that the second fieldset block labels pick up the inline styling regardless of having no inline class associated with the second fieldset.

Do you have something in place to cater for this that I am not aware of?

I think this is a little too generic

.inline .block-label

I have worked around the problem by adding a new class with attributes to override the inherited attributes.

.stacked .block-label

Toggled content not displaying

When toggling content on the Elements app, the toggled content doesn't display:

Observed on mac on Chrome 49

Document grunt scss lint

Update the config file .scss-lint.yml to document where this file differs from the default config: https://github.com/brigade/scss-lint/blob/master/config/default.yml and why.

Form label and hint inside a fieldset

I think some improvements need to be made for form labels and hints within a fieldset for example a YES/NO question.

In the examples presented. All checkboxes, radio buttons have effectively a medium title which is all very nice for questions that follow the radio or checkbox structure. (Single page questions)

The problem I have found is when you work with standard form inputs and introduce radios etc... you need consistency with the form patterns for everything as an example:

http://onlineplea.herokuapp.com/#/your-details

This page demonstrates consistency, however I have had to add a hack which I am not proud of. Perhaps time can be spent looking into this issue:

CSS

.form-hint {
  margin-bottom: 0;
  padding-bottom: em(7);  
}

legend span ~ span {
  margin-top: em(-7);
} 

HTML

<legend>
   <span class="form-label-bold">Label</span>
   <span class="form-hint">Help</span>
</legend>

This fixes spacing issues. But I don't like it.

Perhaps I have missed something, or approached this the wrong way. Any advice and or direction would be good.

Hidden text (progressive disclosure) improvements

Something that has been bugging me about this control is the fact that if you double click on the link you get a selection highlight. Might I suggest we add the following attributes for the summary element.

.summary {
    -webkit-user-select: none;
       -moz-user-select: none;
        -ms-user-select: none;
            user-select: none;
  }

This prevents the highlight on clicking the link.

Perhaps there is good reason why this has not been done, and if so I would love to know why. I understand that you can no longer make a selection of the link, but why would you need to. This is not content copy.

Thanks

using cursor keys, you can't get 2015 or 2016 in the year input

http://govuk-elements.herokuapp.com/form-elements/example-date/

Missing the latest frontend toolkit sass

It seems to me that the package is still missing the latest frontend toolkit sass from here https://github.com/alphagov/govuk_frontend_toolkit/tree/master/stylesheets

I can’t work out from the docs if the user is supposed to manually copy the files over.

Use JavaScript modules

Update JavaScript to use the the module pattern, as set out in the govuk frontend toolkit.

Hidden text (progressive disclosure) example no longer has blue triangle in Firefox Nightly / Developer Edition

Hi,

If you use Firefox Developer Edition or Firefox Nightly the blue triangle no longer renders for progressive disclosure exampes using the <summary> and <details> tags:

I imagine this is due to native support for <summary> and <details> recently landing in Firefox dev builds. I believe it'll arrive in release Firefox in version 49 (mid September).

I don't know if this is a CSS, JS polyfil or Firefox issue, but there is a ticket on bugzilla tracking <summary> and <details> support if more info is required.

Thanks!

Please publish the latest version to NPM

Please publish the latest version to NPM

reference to non-existent class in _buttons.scss

This is currently failing compilation on our application because .button-link does not exist.

details summary {
      @extend .button-link;
}