Add more styles information

nationalarchives · Nov 13, 2023 · e07383e · e07383e
1 parent 76c8f2e
commit e07383e
Show file tree

Hide file tree

Showing 7 changed files with 125 additions and 19 deletions.
diff --git a/lib/index.scss b/lib/index.scss
@@ -295,6 +295,14 @@ table {
       background-color: #111;
     }
   }
+
+  .fa-check {
+    color: colour.brand-colour("green");
+  }
+
+  .fa-xmark {
+    color: colour.brand-colour("pink");
+  }
 }
 
 .tna-template__body {

diff --git a/src/styles/colours/index.md b/src/styles/colours/index.md
@@ -5,6 +5,7 @@ group: styles
 ---
 
 {% from "_example.njk" import example %}
+{% from "nationalarchives/components/message/macro.njk" import tnaMessage %}
 
 ## Brand colours
 
@@ -53,14 +54,7 @@ Always use the provided TNA colour palette.
 
 ### System theme
 
-The system theme follows the operating system preference for `prefers-color-scheme` which can either be `light` or `dark`.
-
-The system theme also follows the preference for `prefers-contrast` which can be `no-preference`, `more`, `less` or `custom`.
-
-At this time, only `prefers-contrast: no-preference` and `prefers-contrast: more` are supported.
-
-- [MDN Web Docs - prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)
-- [MDN Web Docs - prefers-contrast](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast)
+The system theme follows the operating system preference for `prefers-color-scheme` ([MDN Web Docs - prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)) which can either be `light` or `dark`.
 
 ```html
 <html class="tna-template tna-template--system-theme">
@@ -75,24 +69,56 @@ At this time, only `prefers-contrast: no-preference` and `prefers-contrast: more
 
 ### Light theme
 
+A light theme can be used with `tna-template--light-theme`.
+
 {{ example({ group: "styles", item: "colours", example: "theme-light", html: false, nunjucks: false, open: false, size: "xl", noPadding: true }) }}
 
 ### Dark theme
 
+A dark theme can be used with `tna-template--dark-theme`.
+
 {{ example({ group: "styles", item: "colours", example: "theme-dark", html: false, nunjucks: false, open: false, size: "xl", noPadding: true }) }}
 
-### High contrast themes
+## High contrast themes
 
 The high contrast themes are applied on top of the existing light and dark themes with an extra `tna-template--high-contrast-theme` class on the `tna-template` element.
 
-#### Light high contrast theme
+The [system theme](#system-theme) follows the preference for `prefers-contrast` which can be `no-preference`, `more`, `less` or `custom`. See [MDN Web Docs - prefers-contrast](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast).
+
+TNA Frontend currently only supports the `prefers-contrast` values of `no-preference` and `more`.
+
+The colour tools from TNA Frontend come with a mixin for high-contrast which enables you to add styles when high contrast mode is enabled:
+
+```scss
+@use "@nationalarchives/frontend/nationalarchives/tools/colour";
+
+.my-component {
+  @include colour.on-high-contrast {
+    @include colour.colour-border("keyline-dark", 1px);
+  }
+}
+```
+
+### Light high contrast theme
 
 {{ example({ group: "styles", item: "colours", example: "theme-light-high-contrast", html: false, nunjucks: false, open: false, size: "xl", noPadding: true }) }}
 
-#### Dark high contrast theme
+### Dark high contrast theme
 
 {{ example({ group: "styles", item: "colours", example: "theme-dark-high-contrast", html: false, nunjucks: false, open: false, size: "xl", noPadding: true }) }}
 
+### Windows High Contrast Mode (Forced Colours Mode)
+
+Windows offers a "High Contrast Mode" which allows a user to choose their own colour palette. This can be queried using the `forced-colors` CSS media feature.
+
+Using `forced-colors` has some [accessibility concerns](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors#accessibility_concerns) because the browser has no visibility of the colour palette.
+
+{{ tnaMessage({
+  message: "National Archives services must not use the <code>forced-colors</code> CSS media query."
+}) }}
+
+Read the article [The difference between Increased Contrast Mode and Windows High Contrast Mode (Forced Colours Mode)](https://www.tempertemper.net/blog/the-difference-between-increased-contrast-mode-and-windows-high-contrast-mode) for more information.
+
 ## Accent colours
 
 Accent colours can be added on a per-template basis. Add one of the following classes to the `.tna-template` element:

diff --git a/src/styles/index.md b/src/styles/index.md
@@ -8,6 +8,6 @@ order: 2
 
 Make services look and feel like The National Archives.
 
-If you are using the GOV.UK Prototype Kit with TNA Frontend or have TNA Frontend included in your build, the coded examples in the Design System will not need any additional styling.
+If you are using the GOV.UK Prototype Kit with [TNA Frontend](https://github.com/nationalarchives/tna-frontend) or have TNA Frontend included in your build, the coded examples in the Design System will not need any additional styling.
 
 If you need to apply styles manually, you should still follow existing National Archives conventions. For example, do not assign new meanings to colours, do not change the style of buttons or adjust the thickness of borders on form inputs.
diff --git a/src/styles/layout/index.md b/src/styles/layout/index.md
@@ -8,11 +8,11 @@ group: styles
 
 ## Base template
 
-A template is included in `tna-frontend` that has support for the blocks specified below.
+A template is included in [TNA Frontend](https://github.com/nationalarchives/tna-frontend) that has support for the blocks specified below.
 
 You can use this template in your prototypes or copy the structure into your production application.
 
-See the [generic page template](https://github.com/nationalarchives/tna-frontend/blob/main/src/nationalarchives/templates/layouts/_generic.njk) in `tna-frontend`.
+See the [generic page template](https://github.com/nationalarchives/tna-frontend/blob/main/src/nationalarchives/templates/layouts/_generic.njk) in TNA Frontend.
 
 <!-- {{ example({ group: "styles", item: "layout", example: "template", html: false, nunjucks: false, open: false, size: "xxl", noPadding: true }) }} -->
 
@@ -65,9 +65,9 @@ The blocks are nested in the following way:
 | `theme`              | Sets the [theme colour](/design-system/styles/colours/#theme-colours) of the site                  | `system`               |
 | `themeAccent`        | Sets the [accent colour](/design-system/styles/colours/#accent-colours) of the site                | `black`                |
 | `themeColor`         | The [theme-color](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color) | `#000000`              |
-| `assetPath`          | The path for the icons and images included from `tna-frontend`                                     | `/assets`              |
-| `tnaFrontendJsPath`  | The path to prefix the `all.js` from `tna-frontend` (if used within the `bodyEnd` block)           | `/static/tna-frontend` |
-| `tnaFrontendCssPath` | The path to prefix the `all.css` from `tna-frontend` (if used within the `stylesheets` block)      | `/static/tna-frontend` |
+| `assetPath`          | The path for the icons and images included from TNA Frontend                                       | `/assets`              |
+| `tnaFrontendJsPath`  | The path to prefix the `all.js` from TNA Frontend (if used within the `bodyEnd` block)             | `/static/tna-frontend` |
+| `tnaFrontendCssPath` | The path to prefix the `all.css` from TNA Frontend (if used within the `stylesheets` block)        | `/static/tna-frontend` |
 | `bodyClasses`        | Classes to add to the `<body>` element                                                             | [none]                 |
 | `mainClasses`        | Classes to add to the `<main>` element                                                             | [none]                 |
 

diff --git a/src/styles/links/index.md b/src/styles/links/index.md
@@ -14,7 +14,7 @@ If your link is at the end of a sentence or paragraph, make sure that the linked
 
 ## Colours
 
-Link colours on different background types and in different themes have been included in `tna-frontend`. Sometimes black or white links are used. See some examples of how [colours](/design-system/styles/colours/) should be used in National Archive services.
+Link colours on different background types and in different themes have been included in [TNA Frontend](https://github.com/nationalarchives/tna-frontend). Sometimes black or white links are used. See some examples of how [colours](/design-system/styles/colours/) should be used in National Archive services.
 
 Visited links should be purple. This helps users understand what content they have already viewed.
 

diff --git a/src/styles/media/index.md b/src/styles/media/index.md
@@ -0,0 +1,72 @@
+---
+layout: collection-page.njk
+title: Media
+group: styles
+---
+
+Responsive breakpoints are referred to in relative size terms rather than specific devices such as "desktop", "tablet" and "mobile".
+
+[TNA Frontend](https://github.com/nationalarchives/tna-frontend) has definitions for four different device sizes:
+
+- large
+- medium
+- small
+- tiny
+
+Device sizes can vary but the [default breakpoints](https://github.com/nationalarchives/tna-frontend/blob/main/src/nationalarchives/variables/_media.scss) are:
+
+- 1025px and above for large devices
+- 769px&ndash;1024px for medium devices
+- 481px&ndash;768px for small devices
+- 480px and below for tiny devices
+
+## Media queries
+
+Use the provided media tools from TNA Frontend to help you with media queries.
+
+```scss
+@use "@nationalarchives/frontend/nationalarchives/tools/media";
+
+.my-div {
+  display: flex;
+
+  @include media.on-mobile {
+    flex-direction: column;
+  }
+}
+```
+
+The available mixins are:
+
+| Query                   | Tiny                                        | Small                                       | Medium                                      | Large                                       |
+| ----------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------- |
+| `on-tiny`               | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  |
+| `on-mobile`             | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  |
+| `on-small`              | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  |
+| `on-smaller-than-large` | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-xmark"></i> No |
+| `on-larger-than-tiny`   | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-check"></i> Yes |
+| `on-medium`             | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-xmark"></i> No  |
+| `on-larger-than-mobile` | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-check"></i> Yes | <i class="fa-solid fa-fw fa-check"></i> Yes |
+| `on-large`              | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-xmark"></i> No  | <i class="fa-solid fa-fw fa-check"></i> Yes |
+
+## Print
+
+The media tools from TNA Frontend also come with a print styles mixin.
+
+Use the mixin to change the layout of the page or remove unnecessary elements when printing.
+
+```scss
+@use "@nationalarchives/frontend/nationalarchives/tools/media";
+
+.my-breadcrumbs {
+  @include media.on-print {
+    display: none;
+  }
+}
+```
+
+## High contrast
+
+TNA Frontend has support for additional styles in high contrast mode.
+
+See [colours - high contrast themes](/design-system/styles/colours/#high-contrast-themes) on how to impliment these.
diff --git a/src/styles/spacing/index.md b/src/styles/spacing/index.md
@@ -8,7 +8,7 @@ group: styles
 
 ## Global spacing
 
-A top margin has been applied to some elements within `tna-frontend` in order to space them evenly on a page.
+A top margin has been applied to some elements within [TNA Frontend](https://github.com/nationalarchives/tna-frontend) in order to space them evenly on a page.
 
 The common mixin `space-above` is used to apply a consistent `2rem` margin to the top of elements such as: