diff --git a/src/styles/colour/index.md b/src/styles/colour/index.md index f592387e4a..819be1aaad 100644 --- a/src/styles/colour/index.md +++ b/src/styles/colour/index.md @@ -2,9 +2,11 @@ title: Colour description: Always use the GOV.UK colour palette section: Styles +theme: Branding aliases: palette backlog_issue_id: 38 layout: layout-pane.njk +order: 1 --- Always use the GOV.UK colour palette. diff --git a/src/styles/images/index.md b/src/styles/images/index.md index 9b0c55a992..406a1ef5fd 100644 --- a/src/styles/images/index.md +++ b/src/styles/images/index.md @@ -2,11 +2,13 @@ title: Images description: Only use images if there’s a real user need section: Styles +theme: Design guides backlog_issue_id: 70 layout: layout-pane.njk status: Experimental statusMessage: This guidance is currently experimental because we want to get feedback to validate how useful it is for service teams. show_page_nav: true +order: 4 --- {% from "_example.njk" import example %} diff --git a/src/styles/layout/index.md b/src/styles/layout/index.md index 9f13a8fc35..1bcbc7bf0e 100644 --- a/src/styles/layout/index.md +++ b/src/styles/layout/index.md @@ -2,8 +2,9 @@ title: Layout description: Organise the layout of the page into blocks section: Styles -backlog_issue_id: +theme: Design guides layout: layout-pane.njk +order: 5 show_page_nav: true --- diff --git a/src/styles/links/index.md b/src/styles/links/index.md new file mode 100644 index 0000000000..c502025293 --- /dev/null +++ b/src/styles/links/index.md @@ -0,0 +1,60 @@ +--- +title: Links +description: Links are blue and underlined by default +section: Styles +theme: Design guides +layout: layout-pane.njk +order: 6 +show_page_nav: true +headingAliases: + Section break: horizontal rule, hr +--- + +{% from "_example.njk" import example %} + +Links are blue and underlined by default. + +If your link is at the end of a sentence or paragraph, make sure that the linked text does not include the full stop. + +{{ example({group: "styles", item: "links", example: "link", html: true, open: true}) }} + +Use the `govuk-link--no-visited-state` modifier class where it is not helpful to distinguish between visited and unvisited states, for example when linking to pages with frequently-changing content such as the dashboard for an admin interface. + +{{ example({group: "styles", item: "links", example: "link-no-visited-state", html: true, open: true}) }} + +## External links + +If it's an external link to a non-government website, make that clear in the link text. For example, 'read advice on writing link text from [name of organisation]'. There's no need to say explicitly that you're linking to an external site. [Do not use an external link icon](https://designnotes.blog.gov.uk/2016/11/28/removing-the-external-link-icon-from-gov-uk/). + +## Opening links in a new tab + +Avoid opening links in a new tab or window. It can be disorienting - and [can cause accessibility problems for people who cannot visually perceive that the new tab has opened](https://www.w3.org/TR/WCAG20-TECHS/G200.html). + +If you need a link to open in a new tab - for example, to stop the user losing information they’ve entered into a form - then include the words ‘opens in new tab’ as part of the link. There's no need to say 'tab or window', since opening in a new tab is the default behaviour for most browsers. + +Include `rel="noreferrer noopener"` along with `target="_blank"` to reduce the risk of [reverse tabnabbing](https://owasp.org/www-community/attacks/Reverse_Tabnabbing). The following example shows how to do this in HTML. + +{{ example({group: "styles", item: "links", example: "link-opening-in-new-tab", html: true, open: true}) }} + +If you're displaying lots of links together and want to save space and avoid repetition, consider doing both of the following: + +- adding a line of text before the links saying 'The following links open in a new tab' +- including `(opens in new tab)` as part of the link text, so that part of the link text is visually hidden but still accessible to screen readers + +## Links on dark backgrounds + +Use the `govuk-link--inverse` modifier class to show white links on dark backgrounds — for example, in headers, custom components, and patterns with darker backgrounds. + +Make sure all users can see the links — the white links and background colour [must have a contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). + +{{ example({group: "styles", item: "links", example: "link-on-dark-background", html: true, open: true}) }} + +## Links without underlines + +Use the `govuk-link--no-underline` modifier class to remove underlines from links. + +Only do this if the context tells the user that the text is a link, even without the underline. + +For example, links in a header or side navigation might not need underlines. Users will understand that they’re links because of where they are, at the same place, across different pages. + +{{ example({group: "styles", item: "links", example: "link-no-underline", html: true, open: true}) }} diff --git a/src/styles/links/inverse.scss b/src/styles/links/inverse.scss new file mode 100644 index 0000000000..54e44f4e09 --- /dev/null +++ b/src/styles/links/inverse.scss @@ -0,0 +1,5 @@ +@import "example-init"; + +.app-example-page { + background-color: govuk-colour("blue"); +} diff --git a/src/styles/typography/link-no-underline/index.njk b/src/styles/links/link-no-underline/index.njk similarity index 72% rename from src/styles/typography/link-no-underline/index.njk rename to src/styles/links/link-no-underline/index.njk index 2610e39f23..ce4f3b9a62 100644 --- a/src/styles/typography/link-no-underline/index.njk +++ b/src/styles/links/link-no-underline/index.njk @@ -1,5 +1,5 @@ --- -title: Links without underlines – Typography +title: Links without underlines – Links layout: layout-example.njk --- diff --git a/src/styles/typography/link-no-visited-state/index.njk b/src/styles/links/link-no-visited-state/index.njk similarity index 72% rename from src/styles/typography/link-no-visited-state/index.njk rename to src/styles/links/link-no-visited-state/index.njk index 0f445932e6..59eafae497 100644 --- a/src/styles/typography/link-no-visited-state/index.njk +++ b/src/styles/links/link-no-visited-state/index.njk @@ -1,5 +1,5 @@ --- -title: Links with no visited state – Typography +title: Links with no visited state – Links layout: layout-example.njk --- diff --git a/src/styles/typography/link-on-dark-background/index.njk b/src/styles/links/link-on-dark-background/index.njk similarity index 76% rename from src/styles/typography/link-on-dark-background/index.njk rename to src/styles/links/link-on-dark-background/index.njk index 2c1de3d8ad..d81cd2e493 100644 --- a/src/styles/typography/link-on-dark-background/index.njk +++ b/src/styles/links/link-on-dark-background/index.njk @@ -1,5 +1,5 @@ --- -title: Links on dark backgrounds – Typography +title: Links on dark backgrounds – Links layout: layout-example.njk stylesheets: - ../inverse.css diff --git a/src/styles/typography/link-opening-in-new-tab/index.njk b/src/styles/links/link-opening-in-new-tab/index.njk similarity index 73% rename from src/styles/typography/link-opening-in-new-tab/index.njk rename to src/styles/links/link-opening-in-new-tab/index.njk index 65f0109361..63cf93c435 100644 --- a/src/styles/typography/link-opening-in-new-tab/index.njk +++ b/src/styles/links/link-opening-in-new-tab/index.njk @@ -1,5 +1,5 @@ --- -title: Links that open in a new tab – Typography +title: Links that open in a new tab – Links layout: layout-example.njk --- diff --git a/src/styles/typography/link/index.njk b/src/styles/links/link/index.njk similarity index 80% rename from src/styles/typography/link/index.njk rename to src/styles/links/link/index.njk index 51b9928b6a..dc941effdf 100644 --- a/src/styles/typography/link/index.njk +++ b/src/styles/links/link/index.njk @@ -1,5 +1,5 @@ --- -title: Links – Typography +title: Links – Links layout: layout-example.njk --- diff --git a/src/styles/page-template/index.md b/src/styles/page-template/index.md index 0bac72319e..a02fc98263 100644 --- a/src/styles/page-template/index.md +++ b/src/styles/page-template/index.md @@ -2,8 +2,10 @@ title: Page template description: Template combines the boilerplate markup and components needed for a basic GOV.UK page section: Styles +theme: Design guides aliases: boilerplate layout: layout-pane.njk +order: 7 --- {% from "_example.njk" import example %} diff --git a/src/styles/spacing/index.md b/src/styles/spacing/index.md index bd5f3738e8..7b671e35c4 100644 --- a/src/styles/spacing/index.md +++ b/src/styles/spacing/index.md @@ -2,6 +2,7 @@ title: Spacing description: The Design System uses a responsive spacing scale which adapts based on screen size section: Styles +theme: Design guides aliases: margin, padding backlog_issue_id: layout: layout-pane.njk diff --git a/src/get-started/focus-states/details-focus.png b/src/styles/states/focus-states/details-focus.png similarity index 100% rename from src/get-started/focus-states/details-focus.png rename to src/styles/states/focus-states/details-focus.png diff --git a/src/get-started/focus-states/link-focus.png b/src/styles/states/focus-states/link-focus.png similarity index 100% rename from src/get-started/focus-states/link-focus.png rename to src/styles/states/focus-states/link-focus.png diff --git a/src/get-started/focus-states/radios-focus.png b/src/styles/states/focus-states/radios-focus.png similarity index 100% rename from src/get-started/focus-states/radios-focus.png rename to src/styles/states/focus-states/radios-focus.png diff --git a/src/get-started/focus-states/text-input-focus.png b/src/styles/states/focus-states/text-input-focus.png similarity index 100% rename from src/get-started/focus-states/text-input-focus.png rename to src/styles/states/focus-states/text-input-focus.png diff --git a/src/styles/states/index.md b/src/styles/states/index.md new file mode 100644 index 0000000000..5ccdc90700 --- /dev/null +++ b/src/styles/states/index.md @@ -0,0 +1,137 @@ +--- +title: States +description: Some people use keyboards or other devices to navigate through a page by jumping from one interactive element to the next. States let users know which element they’re currently on and are ready to be interacted with. +section: Styles +theme: Design guides +layout: layout-pane.njk +order: 9 +show_page_nav: true +headingAliases: + Section break: horizontal rule, hr +--- + +{% from "_example.njk" import example %} + +## Focus states + +Some people use keyboards or other devices to navigate through a page by jumping from one interactive element to the next. Focus states let users know which element they’re currently on and is ready to be interacted with. + +Focus states in the GOV.UK Design System use a combination of yellow and black to make sure they meet Web Content Accessibility Guidelines (WCAG) 2.1 level AA [non-text contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) on any background colour used on GOV.UK. + +The yellow has a high contrast with dark backgrounds and the thick black border has a high contrast against light backgrounds. + +### Principles for focus states + +A set of principles for focus states. + +### Link focus state style + +When links are focused, they have a yellow background with a black bottom border. This helps the focused link stand out from the rest of the content on the page. + +![A focused link against different GOV.UK background colours](focus-states/link-focus.png) + +Other components and elements that look like links use the link focus state style. For example, the controls on the [accordion](/components/accordion/) and [details](/components/details/) components. + +![A focused details component. In the examples, the expandable text reads "Help with nationality" and beneath is an explanation of why the user is being asked for this information.](focus-states/details-focus.png) + +### Form input focus state style + +When form inputs are focused, they have a yellow outline and a thick black border. If the element already has a border, the border gets thicker. + +![A text input labelled "What is your name?". The example shows the text input both unfocused and focused.](focus-states/text-input-focus.png) + +[Radios](/components/radios/) and [checkboxes](/components/checkboxes/) use the same style. + +![Yes and no radio options to answer the question "Have you changed your name?". In this example, the "No" option is focused.](focus-states/radios-focus.png) + +### Making focus states accessible for extended and modified components + +If you've [extended or modified components in the GOV.UK Design System](/get-started/extending-and-modifying-components/), you can use GOV.UK styles to make the focus states of these components accessible. + +How you make focus states accessible depends on if the component is: + +- focusable text without a background colour or border +- another focusable element with a background colour or border + +#### Make focusable text accessible + +If you use Sass, you should include the `govuk-focused-text` mixin in your component's `:focus` selector if that component is focusable text. For example, the component is a link in body text, or the details component: + +```scss +.app-component:focus { + @include govuk-focused-text; +} +``` + +#### Make other focusable elements accessible + +If you use Sass, you can use 3 GOV.UK Frontend variables if your component has a background colour or border. For example a text input or checkbox. + +The 3 Sass variables are: + +- `$govuk-focus-colour` - yellow background +- `$govuk-focus-text-colour` - black text +- `$govuk-focus-width` - for consistent width + +Use these variables in your components instead of numeric values for the background, text and widths. + +### If you do not use Sass + +To make a component's focus state accessible without using Sass, you can: + +- see how the `govuk-focused-text` mixin works from the [GOV.UK Frontend source code](https://github.com/alphagov/govuk-frontend/blob/25a4333b239e1c3b8a136e526981fe29172a2852/src/govuk/helpers/_focused.scss#L12-L28) +- get the values for `$govuk-focus-colour` and `$govuk-focus-text-colour` from the [colour page](/styles/colour/) + +## Hover states + +An explanation of what a hover state is, why it is important and when it is used. + +### Principles for hover states + +A set of principles for hover states. + +## Pressed states + +An explanation of what a pressed state is, why it is important and when it is used. + +### Principles for pressed states + +A set of principles for pressed states. + +## Inactive states + +An explanation of what a inactive, sometimes referred to as disabled, state is, why it is important and when it is used. + +### Principles for inactive states + +A set of principles for inactive states. + +## Error states or messages + +An explanation of what an error state is, why it is important and when it is used. + +### Principles for error states and messages + +Follow the [validation pattern](/patterns/validation/) and show an [error message](/components/error-message/) when there is a validation error. + +In the error message explain what went wrong and how to fix it. + +Use an [error summary](/components/error-summary/) at the top of a page to summarise any errors a user has made. + +When a user makes an error, you must show both an error summary and an error message next to each answer that contains an error. + +Type A - A red line to the left of the component and a error message above the component +Type B - A red line to the left of the component, an error message above the component and a red border for the input box +Type C - Thick red border around content + +Error message | Type A & B +Error summary | Type C + +Character count | Type B (with a custom red caption) +Checkboxes | Type A +Date input | Type B +File upload | Type A +Radios | Type A +Select | Type B (but no guidance about it) +Text input | Type B +Text area | Type B \ No newline at end of file diff --git a/src/styles/tone-of-voice/index.md b/src/styles/tone-of-voice/index.md new file mode 100644 index 0000000000..b934894525 --- /dev/null +++ b/src/styles/tone-of-voice/index.md @@ -0,0 +1,13 @@ +--- +title: Tone of voice +description: Principles we follow +section: Styles +theme: Content +layout: layout-pane.njk +order: 3 +show_page_nav: true +--- + +The GOV.UK Design System helps service teams follow the [Government Design Principles](https://www.gov.uk/guidance/government-design-principles) and [GOV.UK Service Manual](https://www.gov.uk/service-manual). This website also follows the [style guide](https://www.gov.uk/guidance/style-guide) and [content design](https://www.gov.uk/guidance/content-design) used by GOV.UK. + +[Our accessibility strategy](/community/accessibility-strategy/) outlines our principles and work to improve accessibility within the GOV.UK Design System. \ No newline at end of file diff --git a/src/styles/typography/index.md b/src/styles/typography/index.md index f30ce71e02..fcd16f9d90 100644 --- a/src/styles/typography/index.md +++ b/src/styles/typography/index.md @@ -2,8 +2,10 @@ title: Typography description: If your service is on the service.gov.uk subdomain you must use the GDS Transport font section: Styles +theme: Branding backlog_issue_id: 64 layout: layout-pane.njk +order: 2 show_page_nav: true headingAliases: Section break: horizontal rule, hr @@ -110,53 +112,6 @@ For example, "Your reference number is **ABC12345678**. Use this to track your a Use bold sparingly. Overuse will make it difficult for users to know which parts of your content they need to pay the most attention to. -## Links - -Links are blue and underlined by default. If your link is at the end of a sentence or paragraph, make sure that the linked text does not include the full stop. - -{{ example({group: "styles", item: "typography", example: "link", html: true, open: true}) }} - -Use the `govuk-link--no-visited-state` modifier class where it is not helpful to distinguish between visited and unvisited states, for example when linking to pages with frequently-changing content such as the dashboard for an admin interface. - -{{ example({group: "styles", item: "typography", example: "link-no-visited-state", html: true, open: true}) }} - -### External links - -If it's an external link to a non-government website, make that clear in the link text. For example, 'read advice on writing link text from [name of organisation]'. There's no need to say explicitly that you're linking to an external site. [Do not use an external link icon](https://designnotes.blog.gov.uk/2016/11/28/removing-the-external-link-icon-from-gov-uk/). - -### Opening links in a new tab - -Avoid opening links in a new tab or window. It can be disorienting - and [can cause accessibility problems for people who cannot visually perceive that the new tab has opened](https://www.w3.org/TR/WCAG20-TECHS/G200.html). - -If you need a link to open in a new tab - for example, to stop the user losing information they’ve entered into a form - then include the words ‘opens in new tab’ as part of the link. There's no need to say 'tab or window', since opening in a new tab is the default behaviour for most browsers. - -Include `rel="noreferrer noopener"` along with `target="_blank"` to reduce the risk of [reverse tabnabbing](https://owasp.org/www-community/attacks/Reverse_Tabnabbing). The following example shows how to do this in HTML. - -{{ example({group: "styles", item: "typography", example: "link-opening-in-new-tab", html: true, open: true}) }} - -If you're displaying lots of links together and want to save space and avoid repetition, consider doing both of the following: - -- adding a line of text before the links saying 'The following links open in a new tab' -- including `(opens in new tab)` as part of the link text, so that part of the link text is visually hidden but still accessible to screen readers - -### Links on dark backgrounds - -Use the `govuk-link--inverse` modifier class to show white links on dark backgrounds — for example, in headers, custom components, and patterns with darker backgrounds. - -Make sure all users can see the links — the white links and background colour [must have a contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). - -{{ example({group: "styles", item: "typography", example: "link-on-dark-background", html: true, open: true}) }} - -### Links without underlines - -Use the `govuk-link--no-underline` modifier class to remove underlines from links. - -Only do this if the context tells the user that the text is a link, even without the underline. - -For example, links in a header or side navigation might not need underlines. Users will understand that they’re links because of where they are, at the same place, across different pages. - -{{ example({group: "styles", item: "typography", example: "link-no-underline", html: true, open: true}) }} - ## Lists Use lists to make blocks of text easier to read, and to break information into manageable chunks.