diff --git a/tests/linters/.eslintrc.js b/.eslintrc.js
similarity index 100%
rename from tests/linters/.eslintrc.js
rename to .eslintrc.js
diff --git a/tests/linters/.htmlhintrc b/.htmlhintrc
similarity index 100%
rename from tests/linters/.htmlhintrc
rename to .htmlhintrc
diff --git a/.prettierrc.js b/.prettierrc.js
index 20a955687..2bc62970f 100644
--- a/.prettierrc.js
+++ b/.prettierrc.js
@@ -13,6 +13,7 @@ module.exports = {
{
files: '*.scss',
options: {
+ printWidth: 120,
singleQuote: false
}
}
diff --git a/tests/linters/.stylelintignore b/.stylelintignore
similarity index 100%
rename from tests/linters/.stylelintignore
rename to .stylelintignore
diff --git a/.stylelintrc.js b/.stylelintrc.js
new file mode 100644
index 000000000..d5629a62d
--- /dev/null
+++ b/.stylelintrc.js
@@ -0,0 +1,87 @@
+module.exports = {
+ extends: 'stylelint-config-gds/scss',
+ ignoreFiles: [
+ '**/dist/**',
+ '**/vendor/**',
+
+ // Ignore CSS-in-JS (including dotfiles)
+ '**/?(.)*.{cjs,js,mjs}'
+ ],
+ overrides: [
+ {
+ customSyntax: 'postcss-markdown',
+ files: ['**/*.md']
+ },
+ {
+ customSyntax: 'postcss-markdown',
+ files: ['**/coding-standards.md', '**/README.md'],
+ rules: {
+ // Allow markdown `*.md` CSS bad examples
+ 'block-no-empty': null,
+ 'color-no-hex': null,
+ 'selector-max-id': null,
+ 'selector-no-qualifying-type': null,
+
+ // Allow markdown `*.md` Sass bad examples
+ 'scss/dollar-variable-pattern': null
+ }
+ },
+ {
+ customSyntax: 'postcss-scss',
+ files: ['**/*.scss'],
+ rules: {
+ // Disallow hex colours
+ // https://stylelint.io/user-guide/rules/color-no-hex/
+ 'color-no-hex': true,
+
+ // Properties and values that are disallowed
+ // https://stylelint.io/user-guide/rules/declaration-property-value-disallowed-list/
+ 'declaration-property-value-disallowed-list': {
+ transition: ['all'],
+ '/^border/': ['none']
+ },
+
+ // Disallow @mixin before @extends
+ // /~https://github.com/hudochenkov/stylelint-order/blob/master/rules/order/README.md#extended-at-rule-objects
+ 'order/order': [
+ {
+ type: 'at-rule',
+ name: 'extend'
+ },
+ {
+ type: 'at-rule',
+ name: 'mixin'
+ }
+ ],
+
+ // Allow underscores (but not numbers) in mixin naming pattern
+ // /~https://github.com/stylelint-scss/stylelint-scss/tree/master/src/rules/at-mixin-pattern
+ 'scss/at-mixin-pattern': [
+ /^([a-z-_])*$/,
+ {
+ message: 'Mixin names may only contain [a-z-_] characters'
+ }
+ ],
+
+ // Allow underscores in $variable naming pattern
+ // /~https://github.com/stylelint-scss/stylelint-scss/tree/master/src/rules/dollar-variable-pattern
+ 'scss/dollar-variable-pattern': [
+ /^([a-z0-9-_])*$/,
+ {
+ message: 'Variable names may only contain [a-z0-9-_] characters'
+ }
+ ],
+
+ // Allow underscores (but not numbers) in %placeholder naming pattern
+ // /~https://github.com/stylelint-scss/stylelint-scss/tree/master/src/rules/percent-placeholder-pattern
+ 'scss/percent-placeholder-pattern': [
+ /^([a-z-_])*$/,
+ {
+ message: 'Placeholders may only contain [a-z-_] characters'
+ }
+ ]
+ }
+ }
+ ],
+ plugins: ['stylelint-order']
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc246d2f4..5aedcf18d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,9 @@
:new: **New features**
- Adds `text` param for Inset text ([PR 1113](/~https://github.com/nhsuk/nhsuk-frontend/pull/1113))
+- Make it easier to set checkbox and radio checked items ([PR 1105](/~https://github.com/nhsuk/nhsuk-frontend/pull/1105))
+
+## 9.2.0 - 12 February 2025
:wrench: **Fixes**
@@ -12,6 +15,7 @@
- Fix appearance of disabled warning buttons ([Issue 1034]([/~https://github.com/nhsuk/nhsuk-service-manual-community-backlog/issues/1034]))
- Fix reverse button text colour ([PR 1080]([/~https://github.com/nhsuk/nhsuk-frontend/pull/1080]))
- Fix details component requiring html param in uppercase ([PR 1090](/~https://github.com/nhsuk/nhsuk-frontend/pull/1090), [Issue 1089](/~https://github.com/nhsuk/nhsuk-frontend/issues/1089))
+- Replace image component example images to match assets used on service manual ([Issue 1091](/~https://github.com/nhsuk/nhsuk-frontend/issues/1091))
## 9.1.0 - 4 November 2024
diff --git a/app/components/checkboxes/index.njk b/app/components/checkboxes/index.njk
index 28149af8d..7f27eacac 100644
--- a/app/components/checkboxes/index.njk
+++ b/app/components/checkboxes/index.njk
@@ -20,6 +20,7 @@
"classes": "nhsuk-fieldset__legend--m"
}
},
+ "values": ["british"],
"hint": {
"text": "If you have more than 1 nationality, select all options that are relevant to you."
},
diff --git a/app/components/images/index.njk b/app/components/images/index.njk
index 5527ebb14..912b552b7 100644
--- a/app/components/images/index.njk
+++ b/app/components/images/index.njk
@@ -11,16 +11,16 @@
{{ image({
- "src": "https://assets.nhs.uk/prod/images/S_1017_allergic-conjunctivitis_M15.2e16d0ba.fill-320x213.jpg",
- "sizes": "(min-width: 1020px) 320px, (min-width: 768px) 50vw, 100vw",
- "srcset": "https://assets.nhs.uk/prod/images/S_1017_allergic-conjunctivitis_M15.2e16d0ba.fill-640x427.jpg 640w, https://assets.nhs.uk/prod/images/S_1017_allergic-conjunctivitis_M15.2e16d0ba.fill-767x511.jpg 767w",
- "alt": "Picture of allergic conjunctivitis",
- "caption": "Itchy, red, watering eyes"
+ src: "https://service-manual.nhs.uk/assets/image-example-stretch-marks-600w.jpg",
+ sizes: "(max-width: 768px) 100vw, 66vw",
+ srcset: "https://service-manual.nhs.uk/assets/image-example-stretch-marks-600w.jpg 600w, https://service-manual.nhs.uk/assets/image-example-stretch-marks-1000w.jpg 1000w",
+ alt: "Close-up of a person’s tummy showing a number of creases in the skin under their belly button. Shown on light brown skin.",
+ caption: "Stretch marks can be pink, red, brown, black, silver or purple. They usually start off darker and fade over time."
}) }}
{{ image({
- "src": "https://assets.nhs.uk/prod/images/S_1017_allergic-conjunctivitis_M15.2e16d0ba.fill-320x213.jpg",
- "alt": "Picture of allergic conjunctivitis"
+ "src": "https://service-manual.nhs.uk/assets/image-example-stretch-marks-600w.jpg",
+ "alt": "Close-up of a person’s tummy showing a number of creases in the skin under their belly button. Shown on light brown skin."
}) }}
`s to be full-width by default.
- */
+////
+/// Tables
+///
+/// 1. Force `
`s to be full-width by default.
+///
+/// @group elements
+////
table {
@include nhsuk-responsive-margin(7, "bottom");
border-spacing: 0;
vertical-align: top;
- width: 100%; /* [1] */
+ width: 100%; // [1]
@include mq($media-type: print) {
page-break-inside: avoid;
diff --git a/packages/core/generic/_box-sizing.scss b/packages/core/generic/_box-sizing.scss
index 8bcbb64e3..b254df322 100644
--- a/packages/core/generic/_box-sizing.scss
+++ b/packages/core/generic/_box-sizing.scss
@@ -1,13 +1,13 @@
-/* ==========================================================================
- GENERIC / #BOX-SIZING
- ========================================================================== */
-
-/**
- * Set the global `box-sizing` state to `border-box`.
- *
- * https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice
- * http://paulirish.com/2012/box-sizing-border-box-ftw
- */
+////
+/// Box sizing
+///
+/// Set the global `box-sizing` state to `border-box`.
+///
+/// @link https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice
+/// @link http://paulirish.com/2012/box-sizing-border-box-ftw
+///
+/// @group generic
+////
html {
-moz-box-sizing: border-box;
@@ -17,8 +17,8 @@ html {
* {
&,
- &:before,
- &:after {
+ &::before,
+ &::after {
-moz-box-sizing: inherit;
-webkit-box-sizing: inherit;
box-sizing: inherit;
diff --git a/packages/core/generic/_font-face.scss b/packages/core/generic/_font-face.scss
index 0d79cf0e5..e1f044e4c 100644
--- a/packages/core/generic/_font-face.scss
+++ b/packages/core/generic/_font-face.scss
@@ -1,13 +1,13 @@
-// ==========================================================================
-// SETTINGS / #FONT-FACE
-// ==========================================================================
-
-// NHS uses the Frutiger font, it was originally made
-// for print, but we've had to adapt for web.
-// NHS England has a licence for the Frutiger webfont that the NHS website team can use.
-// All other NHS England teams and other NHS organisations must have their own licence with Monotype.
-
-/* stylelint-disable indentation */
+////
+/// Font face
+///
+/// NHS uses the Frutiger font, it was originally made
+/// for print, but we've had to adapt for web.
+/// NHS England has a licence for the Frutiger webfont that the NHS website team can use.
+/// All other NHS England teams and other NHS organisations must have their own licence with Monotype.
+///
+/// @group settings
+////
@function nhsuk-font-url($filename) {
@return url($nhsuk-fonts-path + $filename);
diff --git a/packages/core/objects/_grid.scss b/packages/core/objects/_grid.scss
index f61ebd534..72b518b95 100644
--- a/packages/core/objects/_grid.scss
+++ b/packages/core/objects/_grid.scss
@@ -1,6 +1,8 @@
-/* ==========================================================================
- OBJECTS / #GRID
- ========================================================================== */
+////
+/// Grid
+///
+/// @group objects
+////
@include govuk-exports("govuk/objects/grid") {
@include govuk-grid-row;
diff --git a/packages/core/objects/_main-wrapper.scss b/packages/core/objects/_main-wrapper.scss
index 003ce08d0..9ee0d10d7 100644
--- a/packages/core/objects/_main-wrapper.scss
+++ b/packages/core/objects/_main-wrapper.scss
@@ -1,29 +1,25 @@
-/* ==========================================================================
- OBJECTS / #MAIN-WRAPPER
- ========================================================================== */
-
-/**
- * Page wrapper for the grid system
- *
- * Usage:
- *
- *
- *
- *
- *
- *
- * Original code taken from GDS (Government Digital Service)
- * /~https://github.com/alphagov/govuk-frontend
- *
- * 1. In IE11 the `main` element can be used, but is not recognized –
- * meaning it's not defined in IE's default style sheet,
- * so it uses CSS initial value, which is inline.
- */
+////
+/// Page wrapper for the grid system
+///
+/// 1. In IE11 the `main` element can be used, but is not recognized –
+/// meaning it's not defined in IE's default style sheet,
+/// so it uses CSS initial value, which is inline
+///
+/// @group objects
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
+/// @example html
+///
+///
+///
+///
+///
+////
@mixin govuk-main-wrapper {
- @include top-and-bottom();
- display: block; /* [1] */
+ @include top-and-bottom;
+ display: block; // [1]
padding-top: nhsuk-spacing(4);
padding-bottom: nhsuk-spacing(4);
diff --git a/packages/core/objects/_width-container.scss b/packages/core/objects/_width-container.scss
index b9b7bb4f1..4d409ea2a 100644
--- a/packages/core/objects/_width-container.scss
+++ b/packages/core/objects/_width-container.scss
@@ -1,31 +1,27 @@
-/* ==========================================================================
- OBJECTS / #WIDTH-CONTAINER
- ========================================================================== */
-
-/**
- * Page width for the grid system
- *
- * Original code taken from GDS (Government Digital Service)
- * /~https://github.com/alphagov/govuk-frontend
- *
- * 1. On mobile, add half width gutters
- * 2. Limit the width of the container to the page width
- * 3. From desktop, add full width gutters
- * 4. As soon as the viewport is greater than the width of the page plus the
- * gutters, just centre the content instead of adding gutters.
- * 5. Full width container, spanning the entire width of the viewport
- */
+////
+/// Page width for the grid system
+///
+/// 1. On mobile, add half width gutters
+/// 2. Limit the width of the container to the page width
+/// 3. From desktop, add full width gutters
+/// 4. As soon as the viewport is greater than the width of the page plus the
+/// gutters, just centre the content instead of adding gutters.
+/// 5. Full width container, spanning the entire width of the viewport
+///
+/// @group objects
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+////
@mixin govuk-width-container {
- margin: 0 $nhsuk-gutter-half; /* [1] */
+ margin: 0 $nhsuk-gutter-half; // [1]
- max-width: $nhsuk-page-width; /* [2] */
+ max-width: $nhsuk-page-width; // [2]
@include govuk-media-query($from: desktop) {
- margin: 0 $nhsuk-gutter; /* [3] */
+ margin: 0 $nhsuk-gutter; // [3]
}
- /* [4] */
+ // [4]
@include govuk-media-query($and: "(min-width: #{($nhsuk-page-width + $nhsuk-gutter * 2)})") {
margin: 0 auto;
}
@@ -33,10 +29,10 @@
@mixin nhsuk-width-container-fluid {
margin: 0 $nhsuk-gutter-half;
- max-width: 100%; /* [5] */
+ max-width: 100%; // [5]
@include govuk-media-query($from: desktop) {
- margin: 0 $nhsuk-gutter; /* [3] */
+ margin: 0 $nhsuk-gutter; // [3]
}
}
@@ -44,6 +40,7 @@
.nhsuk-width-container {
@include govuk-width-container;
}
+
.nhsuk-width-container-fluid {
@include nhsuk-width-container-fluid;
}
diff --git a/packages/core/settings/_all.scss b/packages/core/settings/_all.scss
index 9ecdf14b1..f7119574d 100644
--- a/packages/core/settings/_all.scss
+++ b/packages/core/settings/_all.scss
@@ -1,6 +1,6 @@
-// ==========================================================================
-// #SETTINGS
-// ==========================================================================
+////
+/// Settings
+////
@import "breakpoints";
@import "colours";
diff --git a/packages/core/settings/_breakpoints.scss b/packages/core/settings/_breakpoints.scss
index ef95d668f..46c6ef86a 100644
--- a/packages/core/settings/_breakpoints.scss
+++ b/packages/core/settings/_breakpoints.scss
@@ -1,26 +1,26 @@
-// ==========================================================================
-// SETTINGS / #BREAKPOINTS
-// ==========================================================================
-
-//
-// sass-mq config - /~https://github.com/sass-mq/sass-mq
-//
-// mq() takes up to three optional parameters:
-// $from: inclusive min-width boundary
-// $until: exclusive max-width boundary
-// $and: additional custom directives
-// $media-type: $mq-media-type // defaults to 'all'
-//
-// 1. To enable support for browsers that do not support @media queries,
-// (IE <= 8, Firefox <= 3, Opera <= 9) set $mq-responsive to false
-// Create a separate stylesheet served exclusively to these browsers,
-// meaning @media queries will be rasterized, relying on the cascade itself
-// 2. Define the breakpoint from the $mq-breakpoints list that should
-// be used as the target width when outputting a static stylesheet
-// (i.e. when $mq-responsive is set to 'false').
+////
+/// Breakpoints
+///
+/// @link /~https://github.com/sass-mq/sass-mq sass-mq config
+///
+/// mq() takes up to three optional parameters:
+/// $from: inclusive min-width boundary
+/// $until: exclusive max-width boundary
+/// $and: additional custom directives
+/// $media-type: $mq-media-type // defaults to 'all'
+///
+/// 1. To enable support for browsers that do not support @media queries,
+/// (IE <= 8, Firefox <= 3, Opera <= 9) set $mq-responsive to false
+/// Create a separate stylesheet served exclusively to these browsers,
+/// meaning @media queries will be rasterized, relying on the cascade itself
+/// 2. Define the breakpoint from the $mq-breakpoints list that should
+/// be used as the target width when outputting a static stylesheet
+/// (i.e. when $mq-responsive is set to 'false').
///
+/// @group settings
+////
-$mq-responsive: true; // [1] //
+$mq-responsive: true; // [1]
$mq-breakpoints: (
mobile: 320px,
@@ -29,4 +29,4 @@ $mq-breakpoints: (
large-desktop: 990px
);
-$mq-static-breakpoint: desktop; // [2] //
+$mq-static-breakpoint: desktop; // [2]
diff --git a/packages/core/settings/_colours.scss b/packages/core/settings/_colours.scss
index b5b4ed63b..0b8def3f0 100644
--- a/packages/core/settings/_colours.scss
+++ b/packages/core/settings/_colours.scss
@@ -1,20 +1,18 @@
-// ==========================================================================
-// SETTINGS / #COLOURS
-// ==========================================================================
-
-//
-// NHS colour palette
-//
-// Colours are prefixed with color_ to make them easier to
-// search for within the code base.
-//
-// We also prefix them with nhsuk- to prevent clashing with
-// other colours in existing code bases.
-//
-// We use the word color, not colour, for variables.
-//
-
-/* stylelint-disable color-no-hex */
+////
+/// NHS colour palette
+///
+/// Colours are prefixed with color_ to make them easier to
+/// search for within the code base.
+///
+/// We also prefix them with nhsuk- to prevent clashing with
+/// other colours in existing code bases.
+///
+/// We use the word color, not colour, for variables.
+///
+/// @group settings
+////
+
+// stylelint-disable color-no-hex
$color_nhsuk-blue: #005eb8;
$color_nhsuk-white: #ffffff;
@@ -25,9 +23,7 @@ $color_nhsuk-dark-pink: #7c2855;
$color_nhsuk-red: #d5281b;
$color_nhsuk-yellow: #ffeb3b;
-//
-// Secondary colours
-//
+/// Secondary colours
$color_nhsuk-pale-yellow: #fff9c4;
$color_nhsuk-warm-yellow: #ffb81c;
@@ -35,9 +31,7 @@ $color_nhsuk-orange: #ed8b00;
$color_nhsuk-aqua-green: #00a499;
$color_nhsuk-pink: #ae2573;
-//
-// Greyscale
-//
+/// Greyscale
$color_nhsuk-grey-1: #4c6272;
$color_nhsuk-grey-2: #768692;
@@ -45,24 +39,23 @@ $color_nhsuk-grey-3: #aeb7bd;
$color_nhsuk-grey-4: #d8dde0;
$color_nhsuk-grey-5: #f0f4f5;
-/* stylelint-enable color-no-hex */
-//
-// RGB and alpha values
-//
-// Used to create drop/box shadows e.g. for search suggestions dropdown
-//
+// stylelint-enable color-no-hex
+
+/// RGB and alpha values
+///
+/// Used to create drop/box shadows e.g. for search suggestions dropdown
+///
$color_nhsuk-grey-1-rgb: rgb(66, 84, 98);
$alpha-transparency-50: 0.5;
-//
-// Functions for tint and shade
-//
-// Usage: tint(color, percentage)
-// tint($color_nhsuk-black, 10%)
-// shade(color, percentage)
-// shade($color_nhsuk-blue, 50%)
-//
+/// Functions for tint and shade
+///
+/// @example scss
+/// tint(color, percentage);
+/// tint($color_nhsuk-black, 10%);
+/// shade(color, percentage);
+/// shade($color_nhsuk-blue, 50%);
@function tint($color, $percentage) {
@return mix(white, $color, $percentage);
@@ -72,69 +65,68 @@ $alpha-transparency-50: 0.5;
@return mix(black, $color, $percentage);
}
-//
-// Primary colour variations
-//
-// 1. used for link :active states
-// 2. used for .is-active state on main navigation
-// 3. used for :hover states on main navigation
-// 4. used for :active states on main navigation
-// 5. used for primary button and action link icon :hover states
-// 6. used for primary button and action link icon :active states
-//
+/// Primary colour variations
+///
+/// 1. used for link :active states
+/// 2. used for .is-active state on main navigation
+/// 3. used for :hover states on main navigation
+/// 4. used for :active states on main navigation
+/// 5. used for primary button and action link icon :hover states
+/// 6. used for primary button and action link icon :active states
-$color_tint_nhsuk-black-10: tint($color_nhsuk-black, 10%); // [1] //
+$color_tint_nhsuk-black-10: tint($color_nhsuk-black, 10%); // [1]
-$color_shade_nhsuk-blue-20: shade($color_nhsuk-blue, 20%); // [2] //
-$color_shade_nhsuk-blue-35: shade($color_nhsuk-blue, 35%); // [3] //
-$color_shade_nhsuk-blue-50: shade($color_nhsuk-blue, 50%); // [4] //
+$color_shade_nhsuk-blue-20: shade($color_nhsuk-blue, 20%); // [2]
+$color_shade_nhsuk-blue-35: shade($color_nhsuk-blue, 35%); // [3]
+$color_shade_nhsuk-blue-50: shade($color_nhsuk-blue, 50%); // [4]
-$color_shade_nhsuk-green-35: shade($color_nhsuk-green, 35%); // [5] //
-$color_shade_nhsuk-green-50: shade($color_nhsuk-green, 50%); // [6] //
+$color_shade_nhsuk-green-35: shade($color_nhsuk-green, 35%); // [5]
+$color_shade_nhsuk-green-50: shade($color_nhsuk-green, 50%); // [6]
$color_transparent_nhsuk-white-20: rgba($color_nhsuk-white, 0.2);
$color_transparent_nhsuk-blue-50: rgba($color_shade_nhsuk-blue-50, 0.1);
-//
-// Colour aliases
-//
+/// Colour aliases
+
+/// Text
-// Text
$nhsuk-text-color: $color_nhsuk-black;
$nhsuk-secondary-text-color: $color_nhsuk-grey-1;
$nhsuk-print-text-color: $color_nhsuk-black;
+// stylelint-disable-next-line color-no-hex
$nhsuk-footer-link-text-color: #003087;
+// stylelint-disable-next-line color-no-hex
$nhsuk-footer-copyright-text-color: #231f20;
-// Links
+/// Links
+
$nhsuk-link-color: $color_nhsuk-blue;
$nhsuk-link-hover-color: $color_nhsuk-dark-pink;
$nhsuk-link-active-color: shade($nhsuk-link-color, 50%);
$nhsuk-link-visited-color: $color_nhsuk-purple;
-// Focus
+/// Focus
+
$nhsuk-focus-color: $color_nhsuk-yellow;
$nhsuk-focus-text-color: $color_nhsuk-black;
-// Border
+/// Border
+
$nhsuk-border-color: $color_nhsuk-grey-4;
$nhsuk-secondary-border-color: $color_transparent_nhsuk-white-20;
-// Box shadow
+/// Box shadow
+
$nhsuk-box-shadow: rgba(33, 43, 50, 0.16);
$nhsuk-box-shadow-color: $color_nhsuk-grey-1-rgb;
-//
-// Forms
-//
+/// Forms
$nhsuk-error-color: $color_nhsuk-red;
$nhsuk-form-border-color: $color_nhsuk-grey-1;
$nhsuk-form-element-background-color: $color_nhsuk-white;
-//
-// Buttons
-//
+/// Buttons
$nhsuk-button-color: $color_nhsuk-green;
$nhsuk-button-hover-color: shade($nhsuk-button-color, 20%);
diff --git a/packages/core/settings/_globals.scss b/packages/core/settings/_globals.scss
index 46c79b0ff..9f16e8624 100644
--- a/packages/core/settings/_globals.scss
+++ b/packages/core/settings/_globals.scss
@@ -1,15 +1,15 @@
-// ==========================================================================
-// SETTINGS / #GLOBALS
-// ==========================================================================
-
-//
-// Fonts
-//
-// 1. Fallback fonts if Frutiger fails to load
-//
-
-$nhsuk-font: Frutiger W01 !default;
-$nhsuk-font-fallback: Arial, Sans-serif !default; // [1] //
+////
+/// Globals
+///
+/// @group settings
+////
+
+/// Fonts
+///
+/// 1. Fallback fonts if Frutiger fails to load
+
+$nhsuk-font: "Frutiger W01" !default;
+$nhsuk-font-fallback: arial, sans-serif !default; // [1]
$nhsuk-font-family-print: sans-serif !default;
$nhsuk-font-bold: 600 !default;
$nhsuk-font-normal: 400 !default;
@@ -17,30 +17,22 @@ $nhsuk-font-light: $nhsuk-font-normal !default;
$nhsuk-fonts-path: "https://assets.nhs.uk/fonts/" !default;
$nhsuk-include-font-face: true !default;
-//
-// Font sizing and spacing
-//
+/// Font sizing and spacing
$nhsuk-base-font-size: 16px !default;
$nhsuk-base-line-height: 24px !default;
-//
-// Icon default sizing
-//
+/// Icon default sizing
$nhsuk-icon-size: 34px !default;
-//
-// Grid spacing
-//
+/// Grid spacing
$nhsuk-page-width: 960px !default;
$nhsuk-gutter: 32px;
$nhsuk-gutter-half: $nhsuk-gutter * 0.5;
-//
-// Border sizes
-//
+/// Border sizes
$nhsuk-border-width-inset-text: 8px !default;
$nhsuk-care-card-triangle-border: 16px !default;
@@ -49,15 +41,11 @@ $nhsuk-hero-border: 1px !default;
$nhsuk-border-table-header-width: 2px !default;
$nhsuk-border-table-cell-width: 1px !default;
-//
-// Border radius
-//
+/// Border radius
$nhsuk-border-radius: 4px !default;
-//
-// Box shadow
-//
+/// Box shadow
$nhsuk-box-shadow-spread: 4px !default;
$nhsuk-box-shadow-blur: 4px !default;
@@ -67,15 +55,11 @@ $nhsuk-box-expander: 4px !default;
$nhsuk-box-shadow-pagination: 16px !default;
$nhsuk-box-shadow-link: 4px !default;
-//
-// Header spacing
-//
+/// Header spacing
$nhsuk-header-spacing: 20px;
-//
-// Form elements
-//
+/// Form elements
$nhsuk-border-width-form-element: 2px !default;
$nhsuk-border-width-form-element-error: 2px !default;
diff --git a/packages/core/settings/_spacing.scss b/packages/core/settings/_spacing.scss
index da187c6ed..92be6bb29 100644
--- a/packages/core/settings/_spacing.scss
+++ b/packages/core/settings/_spacing.scss
@@ -1,13 +1,12 @@
-// ==========================================================================
-// SETTINGS / #SPACING
-// ==========================================================================
+////
+/// Spacing
+///
+/// @group settings
+////
-//
-// Single point spacing variables
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Single point spacing variables
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
$nhsuk-spacing-points: (
0: 0,
@@ -22,23 +21,19 @@ $nhsuk-spacing-points: (
9: 64px
) !default;
-// Responsive spacing map
-// ==========================================================================
-
-//
-// These definitions are used to generate responsive spacing that adapts
-// according to the breakpoints (see 'tools/spacing'). These maps should be
-// used wherever possible to standardise responsive spacing.
-//
-// You can define different behaviour on tablet and desktop. The 'null'
-// breakpoint is for mobile.
-//
-// Access responsive spacing with `nhsuk-responsive-margin` or
-// `nhsuk-responsive-padding` mixins.
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Responsive spacing map
+///
+/// These definitions are used to generate responsive spacing that adapts
+/// according to the breakpoints (see 'tools/spacing'). These maps should be
+/// used wherever possible to standardise responsive spacing.
+///
+/// You can define different behaviour on tablet and desktop. The 'null'
+/// breakpoint is for mobile.
+///
+/// Access responsive spacing with `nhsuk-responsive-margin` or
+/// `nhsuk-responsive-padding` mixins.
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
$nhsuk-spacing-responsive-scale: (
0: (
diff --git a/packages/core/settings/_typography.scss b/packages/core/settings/_typography.scss
index 81a693899..c866cf152 100644
--- a/packages/core/settings/_typography.scss
+++ b/packages/core/settings/_typography.scss
@@ -1,32 +1,30 @@
-// ==========================================================================
-// SETTINGS / #TYPOGRAPHY
-// ==========================================================================
-
-// Responsive typography font map
-// ==========================================================================
+////
+/// Typography
+///
+/// @group settings
+////
-//
-// This is used to generate responsive typography that adapts according to the
-// breakpoints.
-//
-// Font size and font weight can be defined for each breakpoint. You can define
-// different behaviour on tablet and desktop. The 'null' breakpoint is for
-// mobile.
-//
-// Line-heights will automatically be converted from pixel measurements into
-// relative values. For example, with a font-size of 16px and a line-height of
-// 24px, the line-height will be converted to 1.5 before output.
-//
-// You can also specify a separate font size and line height for print media.
-//
-// @prop {Number} $point.$breakpoint.font-size - Font size for `$point` at `$breakpoint`
-// @prop {Number} $point.$breakpoint.line-height - Line height for `$point` at `$breakpoint`
-// @prop {Number} $point.print.font-size - Font size for `$point` when printing
-// @prop {Number} $point.print.line-height - Line height for `$point` when printing
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
+/// Responsive typography font map
+///
+/// This is used to generate responsive typography that adapts according to the
+/// breakpoints.
+///
+/// Font size and font weight can be defined for each breakpoint. You can define
+/// different behaviour on tablet and desktop. The 'null' breakpoint is for
+/// mobile.
+///
+/// Line-heights will automatically be converted from pixel measurements into
+/// relative values. For example, with a font-size of 16px and a line-height of
+/// 24px, the line-height will be converted to 1.5 before output.
+///
+/// You can also specify a separate font size and line height for print media.
+///
+/// @prop {Number} $point.$breakpoint.font-size - Font size for `$point` at `$breakpoint`
+/// @prop {Number} $point.$breakpoint.line-height - Line height for `$point` at `$breakpoint`
+/// @prop {Number} $point.print.font-size - Font size for `$point` when printing
+/// @prop {Number} $point.print.line-height - Line height for `$point` when printing
///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
$nhsuk-typography-scale: (
64: (
@@ -157,17 +155,12 @@ $nhsuk-typography-scale: (
)
) !default;
-// Font weights
-// ==========================================================================
+/// Font weights
-//
-// Font weight for normal typography
-//
+/// Font weight for normal typography
$nhsuk-font-normal: 400 !default;
-//
-// Font weight for bold typography
-//
+/// Font weight for bold typography
$nhsuk-font-bold: 600 !default;
diff --git a/packages/core/styles/_icons.scss b/packages/core/styles/_icons.scss
index a05fa7ceb..8d2e8a09d 100644
--- a/packages/core/styles/_icons.scss
+++ b/packages/core/styles/_icons.scss
@@ -1,15 +1,17 @@
-/* ==========================================================================
- STYLES / #ICONS
- ========================================================================== */
+////
+/// Icons
+///
+/// @group styles
+////
-// Default icon size
+/// Default icon size
.nhsuk-icon {
height: $nhsuk-icon-size;
width: $nhsuk-icon-size;
}
-// Default icon colours
+/// Default icon colours
.nhsuk-icon__search {
fill: $color_nhsuk-blue;
@@ -58,6 +60,7 @@
.nhsuk-icon__chevron-up {
fill: $color_nhsuk-blue;
+
path {
fill: $color_nhsuk-white;
}
@@ -77,7 +80,7 @@
fill: $color_nhsuk-blue;
}
-// Icon size adjustments
+/// Icon size adjustments
.nhsuk-icon--size-25 {
height: $nhsuk-icon-size * 1.25;
diff --git a/packages/core/styles/_lists.scss b/packages/core/styles/_lists.scss
index 07556cccc..540534e2f 100644
--- a/packages/core/styles/_lists.scss
+++ b/packages/core/styles/_lists.scss
@@ -1,20 +1,20 @@
-/* ==========================================================================
- STYLES / #LISTS
- ========================================================================== */
-
-// The % (silent class) allows code to be extended (@extend) to other elements
-// without bloating the code.
-//
-// @example scss
-// .foo {
-// @extend %nhsuk-section-break--xl;
-// }
-
-/**
- * 1. 'Random number' used to align ul and ol left with content.
- * 2. 'Random number' used to give sufficient spacing between text and icon.
- * 3. 'Random number' used to align icon and text.
- */
+////
+/// Lists
+///
+/// The % (silent class) allows code to be extended (@extend) to other elements
+/// without bloating the code.
+///
+/// 1. 'Random number' used to align ul and ol left with content.
+/// 2. 'Random number' used to give sufficient spacing between text and icon.
+/// 3. 'Random number' used to align icon and text.
+///
+/// @group styles
+///
+/// @example scss
+/// .foo {
+/// @extend %nhsuk-section-break--xl;
+/// }
+////
%nhsuk-list {
@include nhsuk-typography-responsive(19);
@@ -41,7 +41,7 @@
%nhsuk-list--bullet {
list-style-type: disc;
- padding-left: 20px; /* [1] */
+ padding-left: 20px; // [1]
}
.nhsuk-list--bullet {
@@ -50,7 +50,7 @@
%nhsuk-list--number {
list-style-type: decimal;
- padding-left: 20px; /* [1] */
+ padding-left: 20px; // [1]
}
.nhsuk-list--number {
@@ -75,12 +75,12 @@ ol {
.nhsuk-list--cross {
list-style: none;
margin-top: 0;
- padding-left: 40px; /* [2] */
+ padding-left: 40px; // [2]
position: relative;
svg {
- left: -4px; /* [3] */
- margin-top: -5px; /* [3] */
+ left: -4px; // [3]
+ margin-top: -5px; // [3]
position: absolute;
}
}
diff --git a/packages/core/styles/_section-break.scss b/packages/core/styles/_section-break.scss
index b599d363f..a274a07ea 100644
--- a/packages/core/styles/_section-break.scss
+++ b/packages/core/styles/_section-break.scss
@@ -1,22 +1,20 @@
-/* ==========================================================================
- STYLES / #SECTION-BREAK
- ========================================================================== */
-
-// The % (silent class) allows code to be extended (@extend) to other elements
-// without bloating the code.
-//
-// @example scss
-// .foo {
-// @extend %nhsuk-section-break--xl;
-// }
-
-/**
- * 1. Extended the section-break--l code for usage of a semantic with
- * no class name.
- *
- * Original code taken from GDS (Government Digital Service)
- * /~https://github.com/alphagov/govuk-frontend
- */
+////
+/// Section break
+///
+/// The % (silent class) allows code to be extended (@extend) to other elements
+/// without bloating the code.
+///
+/// 1. Extended the section-break--l code for usage of a semantic with
+/// no class name.
+///
+/// @group styles
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
+/// @example scss
+/// .foo {
+/// @extend %nhsuk-section-break--xl;
+/// }
+////
%nhsuk-section-break {
border: 0;
@@ -63,7 +61,7 @@
}
hr {
- /* [1] */
+ // [1]
@extend %nhsuk-section-break;
@extend %nhsuk-section-break--l;
@extend %nhsuk-section-break--visible;
diff --git a/packages/core/styles/_typography.scss b/packages/core/styles/_typography.scss
index bbb6a04a2..8bd21b08a 100644
--- a/packages/core/styles/_typography.scss
+++ b/packages/core/styles/_typography.scss
@@ -1,16 +1,20 @@
-/* ==========================================================================
- STYLES / #TYPOGRAPHY
- ========================================================================== */
-
-/* Headings */
-
-// The % (silent class) allows code to be extended (@extend) to other elements
-// without bloating the code.
-//
-// @example scss
-// .foo {
-// @extend %nhsuk-heading-xl;
-// }
+////
+/// Typography
+///
+/// @group styles
+////
+
+///
+/// Headings
+///
+/// The % (silent class) allows code to be extended (@extend) to other elements
+/// without bloating the code.
+///
+/// @example scss
+/// .foo {
+/// @extend %nhsuk-heading-xl;
+/// }
+////
%nhsuk-heading-xl {
@include nhsuk-typography-responsive(48);
@@ -102,7 +106,7 @@ h6,
@extend %nhsuk-heading-xxs;
}
-/* Captions to be used inside headings */
+/// Captions to be used inside headings
.nhsuk-caption-xl {
@include nhsuk-font(26);
@@ -132,7 +136,7 @@ h6,
margin-top: nhsuk-spacing(1);
}
-/* Body (paragraphs) */
+/// Body (paragraphs)
%nhsuk-body-l {
@include nhsuk-typography-responsive(24);
@@ -181,17 +185,16 @@ address {
font-style: normal;
}
-/**
- * Lede text
- *
- * 1. Apply lede text styling to p and ul within the lede element
- * 2. Reduces the spacing between the page heading and the lede text
- */
+/// Lede text
+///
+/// 1. Apply lede text styling to p and ul within the lede element
+/// 2. Reduces the spacing between the page heading and the lede text
.nhsuk-lede-text {
@include nhsuk-font(24);
@include nhsuk-responsive-margin(7, "bottom");
- /* [1] */
+
+ // [1]
p,
ul {
@include nhsuk-font(24);
@@ -203,22 +206,19 @@ address {
@include nhsuk-responsive-margin(5, "bottom");
}
-/* [2] */
+// [2]
h1 + .nhsuk-lede-text,
h1 + .nhsuk-lede-text--small {
margin-top: -(nhsuk-spacing(2));
}
-/**
- * Contextual adjustments
- *
- * Add top padding to headings that appear directly after paragraphs.
- *
- * 1. Removes the padding-top because of the lede-text's increased margin-bottom
- *
- * Original code taken from GDS (Government Digital Service)
- * /~https://github.com/alphagov/nhsuk-frontend
- */
+/// Contextual adjustments
+///
+/// Add top padding to headings that appear directly after paragraphs.
+///
+/// 1. Removes the padding-top because of the lede-text's increased margin-bottom
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
%nhsuk-body-l + %nhsuk-heading-l {
padding-top: nhsuk-spacing(1);
@@ -247,12 +247,12 @@ h1 + .nhsuk-lede-text--small {
}
}
-/* [1] */
+// [1]
.nhsuk-lede-text + %nhsuk-heading-l {
padding-top: 0;
}
-/* Font weight for and */
+/// Font weight for and
strong,
b {
@@ -290,6 +290,7 @@ b {
}
h1 {
+ // stylelint-disable-next-line declaration-no-important
margin-bottom: 15pt !important;
}
diff --git a/packages/core/tools/_all.scss b/packages/core/tools/_all.scss
index 1c70b587e..9eef9fb66 100644
--- a/packages/core/tools/_all.scss
+++ b/packages/core/tools/_all.scss
@@ -1,6 +1,6 @@
-// ==========================================================================
-// #TOOLS
-// ==========================================================================
+////
+/// Tools
+////
@import "exports";
@import "functions";
diff --git a/packages/core/tools/_exports.scss b/packages/core/tools/_exports.scss
index 3e8c9ed3f..90fdad75c 100644
--- a/packages/core/tools/_exports.scss
+++ b/packages/core/tools/_exports.scss
@@ -1,30 +1,29 @@
-// ==========================================================================
-// TOOLS / #EXPORTS
-// ==========================================================================
+////
+/// Exports
+///
+/// @group tools
+///
+/// Exports are used to ensure that the modules of CSS we define throughout Frontend
+/// are only included in the generated CSS once, no matter how many times they
+/// are included e.g. by individual components.
+///
+/// 1. List of modules which have already been exported
+/// 2. If the mixin is not in the list of modules already exported...
+/// 3. then add it to the list
+/// 4. ... and output the CSS for that module
+/// 5. The next time exports is called for the module of the same name,
+/// it will be found in the list and so nothing will be outputted.
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+////
-//
-// Exports are used to ensure that the modules of CSS we define throughout Frontend
-// are only included in the generated CSS once, no matter how many times they
-// are included e.g. by individual components.
-//
-//
-// 1. List of modules which have already been exported
-// 2. If the mixin is not in the list of modules already exported...
-// 3. then add it to the list
-// 4. ... and output the CSS for that module
-// 5. The next time exports is called for the module of the same name,
-// it will be found in the list and so nothing will be outputted.
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
-
-$imported-modules: () !default; // [1] //
+$imported-modules: () !default; // [1]
@mixin govuk-exports($name, $warn: true) {
- @if (index($imported-modules, $name) == null) {
- // [2] //
- $imported-modules: append($imported-modules, $name) !global; // [3] //
- @content; // [4] //
- } // [5] //
+ @if not index($imported-modules, $name) {
+ // [2]
+ $imported-modules: append($imported-modules, $name) !global; // [3]
+ @content; // [4]
+ }
+ // [5]
}
diff --git a/packages/core/tools/_focused.scss b/packages/core/tools/_focused.scss
index c64b85c8b..6293383a8 100644
--- a/packages/core/tools/_focused.scss
+++ b/packages/core/tools/_focused.scss
@@ -1,13 +1,13 @@
-// ==========================================================================
-// TOOLS / #FOCUSED
-// ==========================================================================
+////
+/// Focused
+///
+/// @group tools
+////
-//
-// Focused text
-//
-// Provides an outline to clearly indicate when the target element is focused.
-// Used for interactive text-based elements.
-//
+/// Focused text
+///
+/// Provides an outline to clearly indicate when the target element is focused.
+/// Used for interactive text-based elements.
@mixin nhsuk-focused-text {
background-color: $nhsuk-focus-color;
@@ -33,7 +33,7 @@
@mixin nhsuk-focused-input {
border: 2px solid $nhsuk-focus-text-color;
box-shadow: inset 0 0 0 2px;
- outline: $nhsuk-focus-width solid $nhsuk-focus-color; /* 1 */
+ outline: $nhsuk-focus-width solid $nhsuk-focus-color; // [1]
outline-offset: 0;
}
@@ -67,7 +67,7 @@
border: 0;
box-shadow: 0 $nhsuk-focus-width 0 0 $nhsuk-focus-text-color;
color: $nhsuk-focus-text-color;
- outline: $nhsuk-focus-width solid transparent; /* 1 */
+ outline: $nhsuk-focus-width solid transparent; // [1]
outline-offset: $nhsuk-focus-width;
.nhsuk-icon {
diff --git a/packages/core/tools/_functions.scss b/packages/core/tools/_functions.scss
index d64a1c0ba..30b9f05e5 100644
--- a/packages/core/tools/_functions.scss
+++ b/packages/core/tools/_functions.scss
@@ -1,43 +1,42 @@
-// ==========================================================================
-// TOOLS / #FUNCTIONS
-// ==========================================================================
-
-// Convert pixels to em
-// ==========================================================================
-
-//
-// A quick way to convert px into em
-// Usage: nhsuk-em(20px, $nhsuk-base-font-size);
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+////
+/// Functions
+///
+/// @group tools
+////
@use "sass:math";
+/// Convert pixels to em
+///
+/// A quick way to convert px into em
+///
+/// @example scss
+/// nhsuk-em(20px, $nhsuk-base-font-size);
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+
@function nhsuk-em($value, $context-font-size) {
- @if (unitless($value)) {
+ @if unitless($value) {
$value: $value * 1px;
}
- @if (unitless($context-font-size)) {
+ @if unitless($context-font-size) {
$context-font-size: $context-font-size * 1px;
}
@return math.div($value, $context-font-size) * 1em;
}
-// Convert pixels to rem
-// ==========================================================================
-
-//
-// A quick way to convert px into rem
-// Usage: nhsuk-px-to-rem(20px);
-//
-// The $nhsuk-base-font-size (defined in settings/_globals.scss)
-// must be configured to match the font-size of your root (html) element
-//
+/// Convert pixels to rem
+///
+/// A quick way to convert px into rem
+///
+/// @example scss
+/// nhsuk-px-to-rem(20px);
+///
+/// The $nhsuk-base-font-size (defined in settings/_globals.scss)
+/// must be configured to match the font-size of your root (html) element
@function nhsuk-px-to-rem($value) {
- @if (unitless($value)) {
+ @if unitless($value) {
$value: $value * 1px;
}
diff --git a/packages/core/tools/_grid.scss b/packages/core/tools/_grid.scss
index dfcd6f8c8..ac9bb5e7b 100644
--- a/packages/core/tools/_grid.scss
+++ b/packages/core/tools/_grid.scss
@@ -1,33 +1,28 @@
-// ==========================================================================
-// TOOLS / #GRID
-// ==========================================================================
+////
+/// Grid
+///
+/// @group tools
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+////
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+@use "sass:math";
-// Map of grid column widths
-// ==========================================================================
+/// Map of grid column widths
$_nhsuk-grid-widths: (
- one-quarter: 25%,
- one-third: 33.3333%,
- one-half: 50%,
- two-thirds: 66.6666%,
- three-quarters: 75%,
+ one-quarter: math.percentage(math.div(1, 4)),
+ one-third: math.percentage(math.div(1, 3)),
+ one-half: math.percentage(math.div(1, 2)),
+ two-thirds: math.percentage(math.div(2, 3)),
+ three-quarters: math.percentage(math.div(3, 4)),
full: 100%
) !default;
-//
-// Grid width percentage
-//
-// @param {String} $key - Name of grid width (e.g. two-thirds)
-// @return {Number} Percentage width
-// @throw if `$key` is not a valid grid width
-//
-// Usage:
-//
+/// Grid width percentage
+///
+/// @param {String} $key - Name of grid width (e.g. two-thirds)
+/// @return {Number} Percentage width
+/// @throw if `$key` is not a valid grid width
@function grid-width($key) {
@if map-has-key($_nhsuk-grid-widths, $key) {
@@ -37,20 +32,17 @@ $_nhsuk-grid-widths: (
@error "Unknown grid width `#{$key}`";
}
-//
-// Generate grid row styles
-//
-// Creates a grid row class with a standardised margin.
-//
-// @param {String} $class [govuk-grid-row] CSS class name
-//
-// @example scss - Default
-// @include govuk-grid-row;
-//
-// @example scss - Customising the class name
-// @include govuk-grid-row("app-grid");
-//
-//
+/// Generate grid row styles
+///
+/// Creates a grid row class with a standardised margin.
+///
+/// @param {String} $class [govuk-grid-row] CSS class name
+///
+/// @example scss - Default
+/// @include govuk-grid-row;
+///
+/// @example scss - Customising the class name
+/// @include govuk-grid-row("app-grid");
@mixin govuk-grid-row($class: "nhsuk-grid-row") {
.#{$class} {
@@ -60,35 +52,33 @@ $_nhsuk-grid-widths: (
}
}
-//
-// Generate grid column styles
-//
-// Creates a cross browser grid column with a class of '.govuk-grid-column' by
-// default, and a standardised gutter between the columns.
-//
-// Common widths are predefined above as keywords in the `$grid-widths` map.
-//
-// By default their width changes from 100% to specified width at the 'tablet'
-// breakpoint, but that can be configured to be any other breakpoint by using
-// the `$at` parameter.
-//
-// @param {String} $class [govuk-grid-column] CSS class name
-// @param {String} $width [full] one-quarter | one-third | one-half | two-third | three-quarters | full
-// @param {String} $float [left] left | right
-// @param {String} $at [tablet] - mobile | tablet | desktop | any custom breakpoint in px or em
-//
-// @example scss - Default
-// @include govuk-grid-column(two-thirds)
-//
-// @example scss - Customising the class name
-// @include govuk-grid-column(one-half, $class: "test-column");
-//
-// @example scss - Customising the breakpoint where width percentage is applied
-// @include govuk-grid-column(one-half, $at: desktop);
-//
-// @example scss - Customising the float direction
-// @include govuk-grid-column(one-half, $float: right);
-//
+/// Generate grid column styles
+///
+/// Creates a cross browser grid column with a class of '.govuk-grid-column' by
+/// default, and a standardised gutter between the columns.
+///
+/// Common widths are predefined above as keywords in the `$grid-widths` map.
+///
+/// By default their width changes from 100% to specified width at the 'tablet'
+/// breakpoint, but that can be configured to be any other breakpoint by using
+/// the `$at` parameter.
+///
+/// @param {String} $class [govuk-grid-column] CSS class name
+/// @param {String} $width [full] one-quarter | one-third | one-half | two-third | three-quarters | full
+/// @param {String} $float [left] left | right
+/// @param {String} $at [tablet] - mobile | tablet | desktop | any custom breakpoint in px or em
+///
+/// @example scss - Default
+/// @include govuk-grid-column(two-thirds)
+///
+/// @example scss - Customising the class name
+/// @include govuk-grid-column(one-half, $class: "test-column");
+///
+/// @example scss - Customising the breakpoint where width percentage is applied
+/// @include govuk-grid-column(one-half, $at: desktop);
+///
+/// @example scss - Customising the float direction
+/// @include govuk-grid-column(one-half, $float: right);
@mixin govuk-grid-column($width: full, $float: left, $at: desktop, $class: "nhsuk-grid-column") {
.#{$class}-#{$width} {
diff --git a/packages/core/tools/_ifff.scss b/packages/core/tools/_ifff.scss
index dae1c141a..f7ea1634b 100644
--- a/packages/core/tools/_ifff.scss
+++ b/packages/core/tools/_ifff.scss
@@ -1,18 +1,16 @@
-// ==========================================================================
-// TOOLS / #ifff
-// ==========================================================================
-
-//
-// Syntactic sugar around Sass' built-in `if` function that does not require
-// you to pass a value for `$if-false`.
-//
-// @param {Boolean} $condition - Whether to return the value of `$if-true`
-// @param {Mixed} $if-true - Value to return if `$condition` is truthy
-// @return {Mixed} Value of `$if-true` if `$condition` is truthy, else null
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+////
+/// Ifff
+///
+/// Syntactic sugar around Sass' built-in `if` function that does not require
+/// you to pass a value for `$if-false`.
+///
+/// @group tools
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
+/// @param {Boolean} $condition - Whether to return the value of `$if-true`
+/// @param {Mixed} $if-true - Value to return if `$condition` is truthy
+/// @return {Mixed} Value of `$if-true` if `$condition` is truthy, else null
+////
@function iff($condition, $if-true) {
@return if($condition, $if-true, null);
diff --git a/packages/core/tools/_links.scss b/packages/core/tools/_links.scss
index 678151d3c..cad03beb2 100644
--- a/packages/core/tools/_links.scss
+++ b/packages/core/tools/_links.scss
@@ -1,12 +1,13 @@
-// ==========================================================================
-// TOOLS / #LINKS
-// ==========================================================================
+////
+/// Links
+///
+/// @group tools
+////
-//
-// Default link styling
-//
-// Usage: @include nhsuk-link-style-default;
-//
+/// Default link styling
+///
+/// @example scss
+/// @include nhsuk-link-style-default;
@mixin nhsuk-link-style-default {
color: $nhsuk-link-color;
@@ -21,7 +22,7 @@
}
&:focus {
- @include nhsuk-focused-text();
+ @include nhsuk-focused-text;
&:hover {
text-decoration: none;
@@ -41,11 +42,10 @@
}
}
-//
-// White link styling, used in the footer.
-//
-// Usage: @include nhsuk-link-style-white;
-//
+/// White link styling, used in the footer.
+///
+/// @example scss
+/// @include nhsuk-link-style-white;
@mixin nhsuk-link-style-white {
color: $color_nhsuk-white;
@@ -71,11 +71,10 @@
}
}
-//
-// Default link hover only styling
-//
-// Usage: @include nhsuk-link-style-hover;
-//
+/// Default link hover only styling
+///
+/// @example scss
+/// @include nhsuk-link-style-hover;
@mixin nhsuk-link-style-hover {
&:hover {
@@ -100,7 +99,6 @@
/// @include nhsuk-link-style-default;
/// @include nhsuk-link-style-no-visited-state;
/// }
-///
@mixin nhsuk-link-style-no-visited-state {
&:link {
@@ -137,7 +135,6 @@
/// @include nhsuk-link-style-default;
/// @include nhsuk-link-style-text;
/// }
-///
@mixin nhsuk-link-style-text {
&:link,
diff --git a/packages/core/tools/_mixins.scss b/packages/core/tools/_mixins.scss
index bc903f864..7b95dc531 100644
--- a/packages/core/tools/_mixins.scss
+++ b/packages/core/tools/_mixins.scss
@@ -1,41 +1,43 @@
-// ==========================================================================
-// TOOLS / #MIXINS
-// ==========================================================================
+////
+/// Mixins
+///
+/// @group tools
+////
-//
-// Clearfix mixin
-//
-// Usage: @include clearfix();
-// See utilities/clearfix
-//
+/// Clearfix mixin
+///
+/// @see utilities/clearfix
+///
+/// @example scss
+/// @include clearfix();
@mixin clearfix() {
- &:after {
+ &::after {
clear: both;
content: "";
display: block;
}
}
-//
-// Reading width mixin, add a maximum width
-// to large pieces of content
-//
-// Usage: @include reading-width();
-// See utilities/reading-width
-//
+/// Reading width mixin, add a maximum width
+/// to large pieces of content
+///
+/// @see utilities/reading-width
+///
+/// @example scss
+/// @include reading-width();
@mixin reading-width() {
max-width: 44em;
}
-//
-// Visually hidden mixin, used for hiding
-// content visually but keeping it in the DOM
-//
-// Usage: @include visually-hidden();
-// See utilities/visually-hidden
-//
+/// Visually hidden mixin, used for hiding
+/// content visually but keeping it in the DOM
+///
+/// @see utilities/visually-hidden
+///
+/// @example scss
+/// @include visually-hidden();
@mixin visually-hidden() {
// Absolute positioning has the unintended consequence of removing any
@@ -63,15 +65,15 @@
width: 1px;
}
-//
-// Visually shown mixin, used for displaying
-// content visually that has previously been hidden
-// by visually-hidden
-// Differences between mobile and desktop views
-// Use $display-property to assign display
-//
-// Usage: @include visually-shown(table-header-group);
-//
+/// Visually shown mixin, used for displaying
+/// content visually that has previously been hidden
+/// by visually-hidden
+///
+/// Differences between mobile and desktop views
+/// Use $display-property to assign display
+///
+/// @example scss
+/// @include visually-shown(table-header-group);
@mixin visually-shown($display-property) {
clip: auto;
@@ -84,32 +86,33 @@
width: auto;
}
-//
-// Top and bottom margin mixin, remove
-// the top and bottom margin spacing
-//
-// Usage: @include top-and-bottom();
-// See utilities/top-and-bottom
-//
+/// Top and bottom margin mixin, remove
+/// the top and bottom margin spacing
+///
+/// @see utilities/top-and-bottom
+///
+/// @example scss
+/// @include top-and-bottom();
@mixin top-and-bottom() {
& > *:first-child {
margin-top: 0;
}
+
& > *:last-child {
margin-bottom: 0;
}
}
-//
-// Panel mixin
-//
-// Usage: @include panel-with-label($color_nhsuk-blue, $color_nhsuk-white);
-// See components/_panel
-//
+/// Panel mixin
+///
+/// See components/_panel
+///
+/// @example scss
+/// @include panel-with-label($color_nhsuk-blue, $color_nhsuk-white);
@mixin panel($panel-background-color, $panel-text-color) {
- @include top-and-bottom();
+ @include top-and-bottom;
@include nhsuk-responsive-margin(7, "bottom");
@include nhsuk-responsive-margin(7, "top");
@include nhsuk-responsive-padding(5);
@@ -123,56 +126,57 @@
}
}
-//
-// Panel with label mixin, inherits panel styling
-// and removes padding top for the label positioning.
-//
-// Used in-conjunction with @mixin heading-label
-//
-// Usage: @include panel-with-label($color_nhsuk-blue, $color_nhsuk-white);
-// See components/_warning-component
-//
+/// Panel with label mixin, inherits panel styling
+/// and removes padding top for the label positioning.
+///
+/// Used in-conjunction with @mixin heading-label
+///
+/// @see components/_warning-component
+///
+/// @example scss
+/// @include panel-with-label($color_nhsuk-blue, $color_nhsuk-white);
@mixin panel-with-label($panel-background-color, $panel-text-color, $panel-border-color) {
@include panel($panel-background-color, $panel-text-color);
border: 1px solid $panel-border-color;
- padding-top: 0 !important; /* stylelint-disable-line declaration-no-important */
+ // stylelint-disable-next-line declaration-no-important
+ padding-top: 0 !important;
}
-//
-// Heading label mixin, adds a tab heading to
-// warning callout, do and don't lists and panel.
-//
-// Used in-conjunction with @mixin panel-with-label
-//
-// Usage: @include heading-label($color_nhsuk-blue, $color_nhsuk-white);
-// See components/_warning-component
-//
-// 1. Background colour to be set on the @include.
-// 2. Text colour to be set on the @include.
-// 3. Display inline-block so it does not take up the full width.
-// 4. Margin -24px left and right aligns the heading to the box.
-// 5. Top positioning set to minus to make the heading
-// sit just outside the box.
-//
+/// Heading label mixin, adds a tab heading to
+/// warning callout, do and don't lists and panel.
+///
+/// Used in-conjunction with @mixin panel-with-label
+///
+/// @see components/_warning-component
+///
+/// 1. Background colour to be set on the @include.
+/// 2. Text colour to be set on the @include.
+/// 3. Display inline-block so it does not take up the full width.
+/// 4. Margin -24px left and right aligns the heading to the box.
+/// 5. Top positioning set to minus to make the heading
+/// sit just outside the box.
+///
+/// @example scss
+/// @include heading-label($color_nhsuk-blue, $color_nhsuk-white);
@mixin heading-label($heading-background-color, $heading-text-color) {
@include nhsuk-typography-responsive(24);
- background-color: $heading-background-color; // [1] //
- color: $heading-text-color; // [2] //
- display: inline-block; // [3] //
+ background-color: $heading-background-color; // [1]
+ color: $heading-text-color; // [2]
+ display: inline-block; // [3]
margin: nhsuk-spacing(0) nhsuk-spacing(0) nhsuk-spacing(2) -33px;
padding: nhsuk-spacing(2) nhsuk-spacing(5);
position: relative;
- top: -16px; // [5] //
+ top: -16px; // [5]
@include mq($until: tablet) {
margin-left: -25px;
margin-right: 0;
padding: nhsuk-spacing(2) nhsuk-spacing(4);
- top: -8px; // [5] //
+ top: -8px; // [5]
}
@include mq($media-type: print) {
@@ -182,13 +186,13 @@
}
}
-//
-// Care card mixin, used for creating
-// different coloured care cards.
-//
-// Usage: @include care-card($color_nhsuk-blue, $color_nhsuk-white, 4px);
-// See components/card/card
-//
+/// Care card mixin, used for creating
+/// different coloured care cards.
+///
+/// @see components/card/card
+///
+/// @example scss
+/// @include care-card($color_nhsuk-blue, $color_nhsuk-white, 4px);
@mixin care-card($heading-background-color, $heading-text-color, $print-border-size) {
.nhsuk-card--care__heading-container {
@@ -203,13 +207,13 @@
}
}
-//
-// Print colour mixin, sets the text print colour
-// warning callout, do and don't lists and panels.
-//
-// Usage: @include print-color($nhsuk-print-text-color);
-// See components/_care-card
-//
+/// Print colour mixin, sets the text print colour
+/// warning callout, do and don't lists and panels.
+///
+/// @see components/_care-card
+///
+/// @example scss
+/// @include print-color($nhsuk-print-text-color);
@mixin print-color($print-color) {
@include mq($media-type: print) {
@@ -224,12 +228,12 @@
}
}
-//
-// Print hide mixin, hides the element from print.
-//
-// Usage: @include print-hide();
-// See components/_care-card
-//
+/// Print hide mixin, hides the element from print.
+///
+/// @see components/_care-card
+///
+/// @example scss
+/// @include print-hide();
@mixin print-hide() {
@include mq($media-type: print) {
@@ -237,20 +241,20 @@
}
}
-//
-// Flex mixin
-// Usage: @include flex();
-//
+/// Flex mixin
+///
+/// @example scss
+/// @include flex();
@mixin flex() {
display: flex;
flex-wrap: wrap;
}
-//
-// Flex item mixin
-// Usage: @include flex-item();
-//
+/// Flex item mixin
+///
+/// @example scss
+/// @include flex-item();
@mixin flex-item() {
display: flex;
@@ -260,10 +264,9 @@
}
}
-//
-// Remove margin mobile mixin, removes left and right
-// margin at tablet breakpoint.
-//
+/// Remove margin mobile mixin
+///
+/// Removes left and right margin at tablet breakpoint
@mixin remove-margin-mobile() {
@include mq($until: tablet) {
diff --git a/packages/core/tools/_sass-mq.scss b/packages/core/tools/_sass-mq.scss
index 652363fe9..6b8bc6ca5 100644
--- a/packages/core/tools/_sass-mq.scss
+++ b/packages/core/tools/_sass-mq.scss
@@ -1,13 +1,12 @@
-// ==========================================================================
-// TOOLS / #SASS-MQ
-// ==========================================================================
-
-//
-// We use sass-mq module for media queries
-//
-// 1. Import sass-mq from our vendor dependencies folder opposed to node_modules
-// in case node_modules is not installed in the folder relative to the root folder
-//
+////
+/// Sass MQ
+///
+/// We use sass-mq module for media queries
+///
+/// 1. Import sass-mq from our vendor dependencies folder opposed to node_modules
+/// in case node_modules is not installed in the folder relative to the root folder
+///
+/// @group tools
$sass-mq-already-included: false !default;
@@ -15,16 +14,13 @@ $sass-mq-already-included: false !default;
$mq-show-breakpoints: ();
}
-@import "../vendor/sass-mq"; // [1] //
+@import "../vendor/sass-mq"; // [1]
$sass-mq-already-included: true;
-//
-// sass-mq helpers
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Helpers
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
@mixin govuk-media-query($args...) {
@include mq($args...) {
diff --git a/packages/core/tools/_shape-arrow.scss b/packages/core/tools/_shape-arrow.scss
index 7c620eff8..04eff6c36 100644
--- a/packages/core/tools/_shape-arrow.scss
+++ b/packages/core/tools/_shape-arrow.scss
@@ -1,20 +1,17 @@
-// ==========================================================================
-// TOOLS / #SHAPE-ARROW
-// ==========================================================================
+////
+/// Shape arrow
+///
+/// @group tools
+////
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
-// Calculate the height of an equilateral triangle
-// Multiplying half the length of the base of an equilateral triangle by the
-// square root of three gives us its height. We use 1.732 as an approximation.
-//
-// @param {Number} $base - Length of the base of the triangle
-// @return {Number} Calculated height of the triangle
-//
-
-/* stylelint-disable string-quotes, order/properties-alphabetical-order */
+/// Calculate the height of an equilateral triangle
+/// Multiplying half the length of the base of an equilateral triangle by the
+/// square root of three gives us its height. We use 1.732 as an approximation.
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
+/// @param {Number} $base - Length of the base of the triangle
+/// @return {Number} Calculated height of the triangle
@function _govuk-equilateral-height($base) {
$square-root-of-three: 1.732;
@@ -22,23 +19,21 @@
@return ($base * 0.5) * $square-root-of-three;
}
-//
-// Arrow mixin
-//
-// Generate Arrows (triangles) by using a mix of transparent (1) and coloured
-// borders. The coloured borders inherit the text colour of the element (2).
-//
-// Ensure the arrow is rendered correctly if browser colours are overridden by
-// providing a clip path (3). Without this the transparent borders are
-// overridden to become visible which results in a square.
-//
-// We need both because older browsers do not support clip-path.
-//
-// @param {String} $direction - Direction for arrow: up, right, down, left.
-// @param {Number} $base - Length of the triangle 'base' side
-// @param {Number} $height [null] - Height of triangle. Omit for equilateral.
-// @param {String} $display [block] - CSS display property of the arrow
-//
+/// Arrow mixin
+///
+/// Generate Arrows (triangles) by using a mix of transparent (1) and coloured
+/// borders. The coloured borders inherit the text colour of the element (2).
+///
+/// Ensure the arrow is rendered correctly if browser colours are overridden by
+/// providing a clip path (3). Without this the transparent borders are
+/// overridden to become visible which results in a square.
+///
+/// We need both because older browsers do not support clip-path.
+///
+/// @param {String} $direction - Direction for arrow: up, right, down, left.
+/// @param {Number} $base - Length of the triangle 'base' side
+/// @param {Number} $height [null] - Height of triangle. Omit for equilateral.
+/// @param {String} $display [block] - CSS display property of the arrow
@mixin govuk-shape-arrow($direction, $base, $height: null, $display: block) {
display: $display;
@@ -51,14 +46,14 @@
$perpendicular: $base * 0.5;
- @if ($height == null) {
+ @if not $height {
$height: _govuk-equilateral-height($base);
}
@if $direction == "up" {
clip-path: polygon(50% 0%, 0% 100%, 100% 100%); // 3
- border-width: 0 $perpendicular $height $perpendicular;
+ border-width: 0 $perpendicular $height;
border-bottom-color: inherit; // 2
} @else if $direction == "right" {
clip-path: polygon(0% 0%, 100% 50%, 0% 100%); // 3
diff --git a/packages/core/tools/_spacing.scss b/packages/core/tools/_spacing.scss
index 9dff39597..44c3e6f61 100644
--- a/packages/core/tools/_spacing.scss
+++ b/packages/core/tools/_spacing.scss
@@ -1,32 +1,30 @@
-// ==========================================================================
-// TOOLS - #SPACING
-// ==========================================================================
-
-// Single point spacing
-// ==========================================================================
-
-//
-// Returns measurement corresponding to the spacing point requested.
-//
-// @param {Number} $spacing-point - Point on the spacing scale (set in `settings/_spacing.sccs`)
-//
-// @returns {String} Spacing Measurement eg. 8px
-//
-// @example scss
-// .foo {
-// padding: nhsuk-spacing(5);
-// top: nhsuk-spacing(2) !important; // if `!important` is required
-// }
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+////
+/// Spacing
+///
+/// @group tools
+////
+
+/// Single point spacing
+///
+/// Returns measurement corresponding to the spacing point requested.
+///
+/// @param {Number} $spacing-point - Point on the spacing scale (set in `settings/_spacing.sccs`)
+///
+/// @returns {String} Spacing Measurement eg. 8px
+///
+/// @example scss
+/// .foo {
+/// padding: nhsuk-spacing(5);
+/// top: nhsuk-spacing(2) !important; // if `!important` is required
+/// }
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
@function nhsuk-spacing($spacing-point) {
$actual-input-type: type-of($spacing-point);
@if $actual-input-type != "number" {
@error "Expected a number (integer), but got a "
- + "#{$actual-input-type}."; /* stylelint-disable-line indentation */
+ + "#{$actual-input-type}.";
}
@if not map-has-key($nhsuk-spacing-points, $spacing-point) {
@@ -36,38 +34,35 @@
@return map-get($nhsuk-spacing-points, $spacing-point);
}
-// Responsive spacing
-// ==========================================================================
-
-//
-// Adds responsive spacing (either padding or margin, depending on `$property`)
-// by fetching a 'spacing map' from the responsive spacing scale, which defines
-// different spacing values at different breakpoints.
-//
-// To generate responsive spacing, use 'nhsuk-responsive-margin' or
-// 'nhsuk-responsive-padding' mixins
-//
-// @param {Number} $responsive-spacing-point - Point on the responsive spacing
-// scale, corresponds to a map of breakpoints and spacing values
-// @param {String} $property - Property to add spacing to (e.g. 'margin')
-// @param {String} $direction [all] - Direction to add spacing to
-// (`top`, `right`, `bottom`, `left`, `all`)
-// @param {Boolean} $important [false] - Whether to mark as `!important`
-// @param {Number} $adjustment [false] - Offset to adjust spacing by
-//
-// @example scss
-// .foo {
-// padding: nhsuk-spacing(5);
-// top: nhsuk-spacing(2) !important; // if `!important` is required
-// }
-//
-// 1. Make sure that the return value from `_settings/spacing.scss` is a map.
-// 2. Loop through each breakpoint in the map
-// 3. The 'null' breakpoint is for mobile.
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Responsive spacing
+///
+/// Adds responsive spacing (either padding or margin, depending on `$property`)
+/// by fetching a 'spacing map' from the responsive spacing scale, which defines
+/// different spacing values at different breakpoints.
+///
+/// To generate responsive spacing, use 'nhsuk-responsive-margin' or
+/// 'nhsuk-responsive-padding' mixins
+///
+/// @param {Number} $responsive-spacing-point - Point on the responsive spacing
+/// scale, corresponds to a map of breakpoints and spacing values
+/// @param {String} $property - Property to add spacing to (e.g. 'margin')
+/// @param {String} $direction [all] - Direction to add spacing to
+/// (`top`, `right`, `bottom`, `left`, `all`)
+/// @param {Boolean} $important [false] - Whether to mark as `!important`
+/// @param {Number} $adjustment [false] - Offset to adjust spacing by
+///
+/// @example scss
+/// .foo {
+/// padding: nhsuk-spacing(5);
+/// top: nhsuk-spacing(2) !important; // if `!important` is required
+/// }
+///
+/// 1. Make sure that the return value from `_settings/spacing.scss` is a map.
+/// 2. Loop through each breakpoint in the map
+/// 3. The 'null' breakpoint is for mobile.
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
@mixin _nhsuk-responsive-spacing(
$responsive-spacing-point,
@@ -83,25 +78,25 @@
@if not map-has-key($nhsuk-spacing-responsive-scale, $responsive-spacing-point) {
@error "Unknown spacing point `#{$responsive-spacing-point}`. Make sure you are using a point from the "
- + "responsive spacing scale in `_settings/spacing.scss`."; /* stylelint-disable-line indentation */
+ + "responsive spacing scale in `_settings/spacing.scss`.";
}
- $scale-map: map-get($nhsuk-spacing-responsive-scale, $responsive-spacing-point); // [1] //
+ $scale-map: map-get($nhsuk-spacing-responsive-scale, $responsive-spacing-point); // [1]
$actual-map-type: type-of($scale-map);
@if $actual-map-type != "map" {
@error "Expected a number (integer), but got a "
- + "#{$actual-map-type}. Make sure you are using a map to set the responsive spacing in `_settings/spacing.scss`)"; /* stylelint-disable-line indentation */
+ + "#{$actual-map-type}. Make sure you are using a map to set the responsive spacing in `_settings/spacing.scss`)";
}
@each $breakpoint, $breakpoint-value in $scale-map {
- // [2] //
+ // [2]
- @if ($adjustment) {
+ @if $adjustment {
$breakpoint-value: $breakpoint-value + $adjustment;
}
- @if $breakpoint == null {
- // [3] //
+ @if not $breakpoint {
+ // [3]
@if $direction == all {
#{$property}: $breakpoint-value iff($important, !important);
@@ -120,61 +115,55 @@
}
}
-// Responsive margin
-// ==========================================================================
-
-//
-// Adds responsive margin by fetching a 'spacing map' from the responsive
-// spacing scale, which defines different spacing values at different
-// breakpoints. Wrapper for the `_nhsuk-responsive-spacing` mixin.
-//
-// @see {mixin} _nhsuk-responsive-spacing
-//
-// @param {Number} $responsive-spacing-point - Point on the responsive spacing
-// scale, corresponds to a map of breakpoints and spacing values
-// @param {String} $direction [all] - Direction to add spacing to
-// (`top`, `right`, `bottom`, `left`, `all`)
-// @param {Boolean} $important [false] - Whether to mark as `!important`
-// @param {Number} $adjustment [false] - Offset to adjust spacing by
-//
-// @example scss
-// .foo {
-// @include nhsuk-responsive-margin(6, 'left', $adjustment: 1px);
-// }
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Responsive margin
+///
+/// Adds responsive margin by fetching a 'spacing map' from the responsive
+/// spacing scale, which defines different spacing values at different
+/// breakpoints. Wrapper for the `_nhsuk-responsive-spacing` mixin.
+///
+/// @see {mixin} _nhsuk-responsive-spacing
+///
+/// @param {Number} $responsive-spacing-point - Point on the responsive spacing
+/// scale, corresponds to a map of breakpoints and spacing values
+/// @param {String} $direction [all] - Direction to add spacing to
+/// (`top`, `right`, `bottom`, `left`, `all`)
+/// @param {Boolean} $important [false] - Whether to mark as `!important`
+/// @param {Number} $adjustment [false] - Offset to adjust spacing by
+///
+/// @example scss
+/// .foo {
+/// @include nhsuk-responsive-margin(6, 'left', $adjustment: 1px);
+/// }
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
@mixin nhsuk-responsive-margin($responsive-spacing-point, $direction: "all", $important: false, $adjustment: false) {
@include _nhsuk-responsive-spacing($responsive-spacing-point, "margin", $direction, $important, $adjustment);
}
-// Responsive padding
-// ==========================================================================
-
-//
-// Adds responsive padding by fetching a 'spacing map' from the responsive
-// spacing scale, which defines different spacing values at different
-// breakpoints. Wrapper for the `_nhsuk-responsive-spacing` mixin.
-//
-// @see {mixin} _nhsuk-responsive-spacing
-//
-// @param {Number} $responsive-spacing-point - Point on the responsive spacing
-// scale, corresponds to a map of breakpoints and spacing values
-// @param {String} $direction [all] - Direction to add spacing to
-// (`top`, `right`, `bottom`, `left`, `all`)
-// @param {Boolean} $important [false] - Whether to mark as `!important`
-// @param {Number} $adjustment [false] - Offset to adjust spacing
-//
-// @example scss
-// .foo {
-// @include nhsuk-responsive-padding(6, 'left', $adjustment: 1px);
-// }
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Responsive padding
+///
+/// Adds responsive padding by fetching a 'spacing map' from the responsive
+/// spacing scale, which defines different spacing values at different
+/// breakpoints. Wrapper for the `_nhsuk-responsive-spacing` mixin.
+///
+/// @see {mixin} _nhsuk-responsive-spacing
+///
+/// @param {Number} $responsive-spacing-point - Point on the responsive spacing
+/// scale, corresponds to a map of breakpoints and spacing values
+/// @param {String} $direction [all] - Direction to add spacing to
+/// (`top`, `right`, `bottom`, `left`, `all`)
+/// @param {Boolean} $important [false] - Whether to mark as `!important`
+/// @param {Number} $adjustment [false] - Offset to adjust spacing
+///
+/// @example scss
+/// .foo {
+/// @include nhsuk-responsive-padding(6, 'left', $adjustment: 1px);
+/// }
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
+///
@mixin nhsuk-responsive-padding($responsive-spacing-point, $direction: "all", $important: false, $adjustment: false) {
@include _nhsuk-responsive-spacing($responsive-spacing-point, "padding", $direction, $important, $adjustment);
diff --git a/packages/core/tools/_typography.scss b/packages/core/tools/_typography.scss
index d2a8b0924..39d22af3e 100644
--- a/packages/core/tools/_typography.scss
+++ b/packages/core/tools/_typography.scss
@@ -1,23 +1,19 @@
-// ==========================================================================
-// TOOLS / #TYPOGRAPHY
-// ==========================================================================
-
-//
-// These mixins allow us to quickly and consistently generate common text
-// patterns such as colours and font-weight
-//
+////
+/// Typography
+///
+/// These mixins allow us to quickly and consistently generate common text
+/// patterns such as colours and font-weight
+///
+/// @group tools
+////
@use "sass:math";
-// Text colour
-// ==========================================================================
-
-//
-// Sets the text colour, including a suitable override for print.
-//
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
-//
+/// Text colour
+///
+/// Sets the text colour, including a suitable override for print.
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
@mixin nhsuk-text-color {
color: $nhsuk-text-color;
@@ -27,42 +23,34 @@
}
}
-// Normal font weight
-// ==========================================================================
-
-//
-// @param {Boolean} $important [false] - Whether to mark declarations as
-// `!important`. Generally Used to create override classes.
-//
+/// Normal font weight
+///
+/// @param {Boolean} $important [false] - Whether to mark declarations as
+/// `!important`. Generally Used to create override classes.
@mixin nhsuk-typography-weight-normal($important: false) {
font-weight: $nhsuk-font-normal iff($important, !important);
}
-// Bold font weight
-// ==========================================================================
-
-//
-// @param {Boolean} $important [false] - Whether to mark declarations as
-// `!important`. Generally Used to create override classes.
-//
+/// Bold font weight
+///
+/// @param {Boolean} $important [false] - Whether to mark declarations as
+/// `!important`. Generally Used to create override classes.
@mixin nhsuk-typography-weight-bold($important: false) {
font-weight: $nhsuk-font-bold iff($important, !important);
}
-// Line height
-// ==========================================================================
-
-//
-// Convert line-heights specified in pixels into a relative value, unless
-// they are already unit-less (and thus already treated as relative values)
-// or the units do not match the units used for the font size.
-//
-// @param {Number} $line-height Line height
-// @param {Number} $font-size Font size
-// @return {Number} The line height as either a relative value or unmodified
-//
+/// Line height
+///
+///
+/// Convert line-heights specified in pixels into a relative value, unless
+/// they are already unit-less (and thus already treated as relative values)
+/// or the units do not match the units used for the font size.
+///
+/// @param {Number} $line-height Line height
+/// @param {Number} $font-size Font size
+/// @return {Number} The line height as either a relative value or unmodified
@function _nhsuk-line-height($line-height, $font-size) {
@if not unitless($line-height) and unit($line-height) == unit($font-size) {
@@ -76,49 +64,47 @@
@return $line-height;
}
-// Responsive typography
-// ==========================================================================
-
-//
-// Takes a 'font map' as an argument and uses it to create font-size and
-// line-height declarations for different breakpoints, and for print.
-//
-// Example font map:
-//
-// $my-font-map: (
-// null: (
-// font-size: 16px,
-// line-height: 20px
-// ),
-// tablet: (
-// font-size: 19px,
-// line-height: 25px
-// ),
-// print: (
-// font-size: 14pt,
-// line-height: 1.15
-// )
-// );\
-//
-// @example scss
-// .foo {
-// @include nhsuk-typography-responsive(19);
-// }
-//
-// .foo {
-// @include nhsuk-typography-responsive(36, $important: true);
-// }
-//
-// @param {Map} $font-map - Font map
-// @param {Number} $override-line-height [false] - Non responsive custom line
-// height. Omit to use the line height from the font map.
-// @param {Boolean} $important [false] - Whether to mark declarations as
-// `!important`.
-//
-// 1. Mark rules as !important if $important is true - this will result in
-// these variables becoming strings, so this needs to happen//after* they
-// are used in calculations
-//
+/// Responsive typography
+///
+/// Takes a 'font map' as an argument and uses it to create font-size and
+/// line-height declarations for different breakpoints, and for print.
+///
+/// Example font map:
+///
+/// $my-font-map: (
+/// null: (
+/// font-size: 16px,
+/// line-height: 20px
+/// ),
+/// tablet: (
+/// font-size: 19px,
+/// line-height: 25px
+/// ),
+/// print: (
+/// font-size: 14pt,
+/// line-height: 1.15
+/// )
+/// );\
+///
+/// @example scss
+/// .foo {
+/// @include nhsuk-typography-responsive(19);
+/// }
+///
+/// .foo {
+/// @include nhsuk-typography-responsive(36, $important: true);
+/// }
+///
+/// @param {Map} $font-map - Font map
+/// @param {Number} $override-line-height [false] - Non responsive custom line
+/// height. Omit to use the line height from the font map.
+/// @param {Boolean} $important [false] - Whether to mark declarations as
+/// `!important`.
+///
+/// 1. Mark rules as !important if $important is true - this will result in
+/// these variables becoming strings, so this needs to happen *after* they
+/// are used in calculations
+///
@mixin nhsuk-typography-responsive($size, $override-line-height: false, $important: false) {
@if not map-has-key($nhsuk-typography-scale, $size) {
@@ -136,12 +122,12 @@
$font-size: $font-size
);
- // [1] //
+ // [1]
$font-size: $font-size iff($important, !important);
$font-size-rem: $font-size-rem iff($important, !important);
$line-height: $line-height iff($important, !important);
- @if $breakpoint == null {
+ @if not $breakpoint {
font-size: $font-size;
font-size: $font-size-rem;
line-height: $line-height;
@@ -160,24 +146,21 @@
}
}
-// Font
-// ==========================================================================
-
-//
-// @example scss
-// .foo {
-// @include nhsuk-font(19);
-// }
-//
-// .foo {
-// @include nhsuk-font(36, $weight: bold);
-// }
-//
-// @param {Number} $size - Size of the font as it would appear on desktop -
-// uses the responsive font size map
-// @param {String} $weight [normal] - Weight: `bold` or `normal`
-// @param {Number} $line-height [false] - Line-height, if overriding the default
-//
+/// Font
+///
+/// @example scss
+/// .foo {
+/// @include nhsuk-font(19);
+/// }
+///
+/// .foo {
+/// @include nhsuk-font(36, $weight: bold);
+/// }
+///
+/// @param {Number} $size - Size of the font as it would appear on desktop -
+/// uses the responsive font size map
+/// @param {String} $weight [normal] - Weight: `bold` or `normal`
+/// @param {Number} $line-height [false] - Line-height, if overriding the default
@mixin nhsuk-font($size, $weight: normal, $line-height: false) {
@if $weight == normal {
diff --git a/packages/core/utilities/_clearfix.scss b/packages/core/utilities/_clearfix.scss
index 4ff536862..e826657c8 100644
--- a/packages/core/utilities/_clearfix.scss
+++ b/packages/core/utilities/_clearfix.scss
@@ -1,15 +1,13 @@
-/* ==========================================================================
- UTILITIES / #CLEARFIX
- ========================================================================== */
-
-/**
- * Automatically clear an elements
- * child elements
- *
- * Usage: class="nhsuk-u-clear"
- * See tools/mixins
- */
+////
+/// Clearfix
+///
+/// Automatically clear an elements
+/// child elements
+///
+/// @example html
+///
+////
.nhsuk-u-clear {
- @include clearfix();
+ @include clearfix;
}
diff --git a/packages/core/utilities/_display.scss b/packages/core/utilities/_display.scss
index e6b088feb..d8a5fefcc 100644
--- a/packages/core/utilities/_display.scss
+++ b/packages/core/utilities/_display.scss
@@ -1,8 +1,10 @@
-/* ==========================================================================
- UTILITIES / #DISPLAY
- ========================================================================== */
+////
+/// Display
+///
+/// @group utilities
+////
-/* stylelint-disable declaration-no-important */
+// stylelint-disable declaration-no-important
.nhsuk-u-display-block {
display: block !important;
diff --git a/packages/core/utilities/_float.scss b/packages/core/utilities/_float.scss
index 7c8f91497..26c81c669 100644
--- a/packages/core/utilities/_float.scss
+++ b/packages/core/utilities/_float.scss
@@ -1,8 +1,10 @@
-/* ==========================================================================
- UTILITIES / #FLOAT
- ========================================================================== */
+////
+/// Float
+///
+/// @group utilities
+////
-/* stylelint-disable declaration-no-important */
+// stylelint-disable declaration-no-important
.nhsuk-u-float-left {
float: left !important;
diff --git a/packages/core/utilities/_grid-widths.scss b/packages/core/utilities/_grid-widths.scss
index 7eae77eac..1bf6c27e8 100644
--- a/packages/core/utilities/_grid-widths.scss
+++ b/packages/core/utilities/_grid-widths.scss
@@ -1,64 +1,65 @@
-/* ==========================================================================
- UTILITIES / #GRID
- ========================================================================== */
+////
+/// Grid widths
+///
+/// Force grid widths on all screen sizes
+///
+/// By default all grid elements will go to 100% width
+/// on screen sizes below tablet, these utilities can force
+/// custom widths on all screen sizes
+///
+/// @group utilities
+///
+/// @example html
+///
+////
@use "sass:math";
-/**
- * Force grid widths on all screen sizes
- * By default all grid elements will go to 100% width
- * on screen sizes below tablet, these utilities can force
- * custom widths on all screen sizes
- *
- * Usage: class="nhsuk-u-one-half"
- */
-
// Utility classes are allowed to use !important;
// so we disable stylelint for that rule
-/* stylelint-disable declaration-no-important */
+// stylelint-disable declaration-no-important
.nhsuk-u-one-half {
float: left;
- width: percentage(1 * 0.5) !important;
+ width: math.percentage(math.div(1, 2)) !important;
}
.nhsuk-u-one-third {
float: left;
- width: percentage(math.div(1, 3)) !important;
+ width: math.percentage(math.div(1, 3)) !important;
}
.nhsuk-u-two-thirds {
float: left;
- width: percentage(math.div(2, 3)) !important;
+ width: math.percentage(math.div(2, 3)) !important;
}
.nhsuk-u-one-quarter {
float: left;
- width: percentage(1 * 0.25) !important;
+ width: math.percentage(math.div(1, 4)) !important;
}
.nhsuk-u-three-quarters {
float: left;
- width: percentage(3 * 0.25) !important;
+ width: math.percentage(math.div(3, 4)) !important;
}
-/**
- * Force grid widths on screen sizes on tablet
- * and above
- *
- * By default all grid elements will go to 100% width
- * on every screen size, these utilities can force
- * custom widths on screen sizes on tablet
- * and above
- *
- * Usage: class="nhsuk-u-one-half-tablet"
- */
+/// Force grid widths on screen sizes on tablet
+/// and above
+///
+/// By default all grid elements will go to 100% width
+/// on every screen size, these utilities can force
+/// custom widths on screen sizes on tablet
+/// and above
+///
+/// @example html
+///
.nhsuk-u-one-half-tablet {
width: 100% !important;
@include mq($from: tablet) {
float: left;
- width: percentage(1 * 0.5) !important;
+ width: math.percentage(math.div(1, 2)) !important;
}
}
@@ -66,7 +67,7 @@
width: 100% !important;
@include mq($from: tablet) {
float: left;
- width: percentage(math.div(1, 3)) !important;
+ width: math.percentage(math.div(1, 3)) !important;
}
}
@@ -74,7 +75,7 @@
width: 100% !important;
@include mq($from: tablet) {
float: left;
- width: percentage(math.div(2, 3)) !important;
+ width: math.percentage(math.div(2, 3)) !important;
}
}
@@ -82,7 +83,7 @@
width: 100% !important;
@include mq($from: tablet) {
float: left;
- width: percentage(1 * 0.25) !important;
+ width: math.percentage(math.div(1, 4)) !important;
}
}
@@ -90,6 +91,6 @@
width: 100% !important;
@include mq($from: tablet) {
float: left;
- width: percentage(3 * 0.25) !important;
+ width: math.percentage(math.div(3, 4)) !important;
}
}
diff --git a/packages/core/utilities/_link-nowrap.scss b/packages/core/utilities/_link-nowrap.scss
index 4f695dd6c..036c4ff53 100644
--- a/packages/core/utilities/_link-nowrap.scss
+++ b/packages/core/utilities/_link-nowrap.scss
@@ -1,13 +1,14 @@
-/* ==========================================================================
- UTILITIES / #LINK-NOWRAP
- ========================================================================== */
-
-/**
- * Prevent long anchor links from line breaking
- * on smaller screens
- *
- * Usage: class="nhsuk-u-nowrap"
- */
+////
+/// Link nowrap
+///
+/// Prevent long anchor links from line breaking
+/// on smaller screens
+///
+/// @group utilities
+///
+/// @example html
+///
+////
.nhsuk-u-nowrap {
@include mq($until: tablet) {
diff --git a/packages/core/utilities/_list-border.scss b/packages/core/utilities/_list-border.scss
index 0b447e34e..8b078b0e4 100644
--- a/packages/core/utilities/_list-border.scss
+++ b/packages/core/utilities/_list-border.scss
@@ -1,12 +1,16 @@
-// ==========================================================================
-// COMPONENTS / #LIST-BORDER
-// ==========================================================================
-
-/**
- * Adds a grey border to the bottom of an
tag
- *
- * Usage: class="nhsuk-list--border"
- */
+////
+/// List border
+///
+/// Adds a grey border to the bottom of an
tag
+///
+/// @group utilities
+///
+/// @example html
+///
+///
Item 1
+///
Item 2
+///
+////
.nhsuk-list--border li {
border-bottom: 1px solid $color_nhsuk-grey-4;
diff --git a/packages/core/utilities/_reading-width.scss b/packages/core/utilities/_reading-width.scss
index 225c4ff89..59d68c382 100644
--- a/packages/core/utilities/_reading-width.scss
+++ b/packages/core/utilities/_reading-width.scss
@@ -1,15 +1,14 @@
-/* ==========================================================================
- UTILITIES / #READING-WIDTH
- ========================================================================== */
-
-/**
- * Reading width mixin, add a maximum width
- * to large pieces of content
- *
- * Usage: class="nhsuk-u-reading-width"
- * See tools/mixins
- */
+////
+/// Reading width
+///
+/// Adds a maximum width to large pieces of content
+///
+/// @group utilities
+///
+/// @example html
+///
+////
.nhsuk-u-reading-width {
- @include reading-width();
+ @include reading-width;
}
diff --git a/packages/core/utilities/_spacing.scss b/packages/core/utilities/_spacing.scss
index 46241e4ce..afdd02d67 100644
--- a/packages/core/utilities/_spacing.scss
+++ b/packages/core/utilities/_spacing.scss
@@ -1,41 +1,43 @@
-// ========================================================================== //
-// UTILITIES / #SPACING
-// ========================================================================== //
+////
+/// Spacing
+///
+/// @group utilities
+////
-// Directions for spacing
-// Original code taken from GDS (Government Digital Service)
-// /~https://github.com/alphagov/govuk-frontend
+/// Directions for spacing
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
$_spacing-directions: ("top", "right", "bottom", "left") !default;
-// Spacing override classes
-//
-// Generate spacing override classes for the given property (e.g. margin)
-// for each point in the spacing scale.
-//
-// @param {String} $property - Property to add spacing to (e.g. 'margin')
-//
-// @example scss
-// .nhsuk-u-margin-0 {
-// margin: 0;
-// }
-//
-// .nhsuk-u-margin-top-1 {
-// margin-top: [whatever spacing point 1 is...]
-// }
-//
-// 1. For each point in the spacing scale (defined in settings), create an
-// override that affects all directions...
-// 2. ... and then an override for each individual direction
+/// Spacing override classes
+///
+/// Generate spacing override classes for the given property (e.g. margin)
+/// for each point in the spacing scale.
+///
+/// @param {String} $property - Property to add spacing to (e.g. 'margin')
+///
+/// @example scss
+/// .nhsuk-u-margin-0 {
+/// margin: 0;
+/// }
+///
+/// .nhsuk-u-margin-top-1 {
+/// margin-top: [whatever spacing point 1 is...]
+/// }
+///
+/// 1. For each point in the spacing scale (defined in settings), create an
+/// override that affects all directions...
+/// 2. ... and then an override for each individual direction
@mixin _nhsuk-generate-spacing-overrides($property) {
- // [1] //
+ // [1]
@each $scale-point, $scale-map in $nhsuk-spacing-responsive-scale {
.nhsuk-u-#{$property}-#{$scale-point} {
@include _nhsuk-responsive-spacing($scale-point, $property, "all", true);
}
- // [2] //
+ // [2]
@each $direction in $_spacing-directions {
.nhsuk-u-#{$property}-#{$direction}-#{$scale-point} {
@include _nhsuk-responsive-spacing($scale-point, $property, $direction, true);
diff --git a/packages/core/utilities/_text-align.scss b/packages/core/utilities/_text-align.scss
index 2ac25b45e..4609f4593 100644
--- a/packages/core/utilities/_text-align.scss
+++ b/packages/core/utilities/_text-align.scss
@@ -1,8 +1,10 @@
-/* ==========================================================================
- UTILITIES / #TEXT-ALIGN
- ========================================================================== */
+////
+/// Text align
+///
+/// @group utilities
+////
-/* stylelint-disable declaration-no-important */
+// stylelint-disable declaration-no-important
.nhsuk-u-text-align-left {
text-align: left !important;
diff --git a/packages/core/utilities/_typography.scss b/packages/core/utilities/_typography.scss
index b562f6c86..a12134e9c 100644
--- a/packages/core/utilities/_typography.scss
+++ b/packages/core/utilities/_typography.scss
@@ -1,19 +1,18 @@
-/* ==========================================================================
- UTILITIES / #TYPOGRAPHY
- ========================================================================== */
+////
+/// Typography
+///
+/// @group utilities
+////
// Utility classes are allowed to use !important;
// so we disable stylelint for that rule
-/**
- * Font size and line height
- *
- * Generate typography override classes for each responsive font map in the
- * typography scale eg .nhsuk-u-font-size-48
- *
- * Original code taken from GDS (Government Digital Service)
- * /~https://github.com/alphagov/govuk-frontend
- */
+/// Font size and line height
+///
+/// Generate typography override classes for each responsive font map in the
+/// typography scale eg .nhsuk-u-font-size-48
+///
+/// @link /~https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
@each $size in map-keys($nhsuk-typography-scale) {
.nhsuk-u-font-size-#{$size} {
@@ -21,13 +20,13 @@
}
}
-/* Weights
- ========================================================================== */
-
-/**
- * Generate font weight override classes for normal and bold
- * eg .nhsuk-u-font-weight-normal
- */
+/// Weights
+///
+/// Generate font weight override classes for normal and bold
+///
+/// @example html
+///
+ 