[WIP] Prototyping an update to the styles guidance

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.

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 <a class="govuk-link" href="#research-on-images">we want to get feedback</a> to validate how useful it is for service teams.
 show_page_nav: true
+order: 4
 ---
 
 {% from "_example.njk" import example %}

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
 ---
 

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 `<span class="govuk-visually-hidden">(opens in new tab)</span>` 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}) }}

src/styles/links/inverse.scss

@@ -0,0 +1,5 @@
+@import "example-init";
+
+.app-example-page {
+  background-color: govuk-colour("blue");
+}

src/styles/typography/link-no-underline/index.njk → 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
 ---
 

src/styles/typography/link-no-visited-state/index.njk → 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
 ---
 

src/styles/typography/link-on-dark-background/index.njk → 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

src/styles/typography/link-opening-in-new-tab/index.njk → 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
 ---
 

src/styles/typography/link/index.njk → src/styles/links/link/index.njk

@@ -1,5 +1,5 @@
 ---
-title: Links – Typography
+title: Links – Links
 layout: layout-example.njk
 ---
 

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 %}

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

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

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.

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 `<span class="govuk-visually-hidden">(opens in new tab)</span>` 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.