@qld-gov-au/qgds-bootstrap5 2.0.1 → 2.0.3

package/src/components/bs5/directionLinks/directionLinks.scss

@@ -1,116 +1,63 @@
 // QGDS QOL Direction Links
 
 a.qld-dir-link {
-
-  --dir-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 448 512'%3E%3Cpath d='M443.7 266.8l-165.9 176C274.5 446.3 269.1 448 265.5 448c-3.986 0-7.988-1.375-11.16-4.156c-6.773-5.938-7.275-16.06-1.118-22.59L393.9 272H16.59c-9.171 0-16.59-7.155-16.59-15.1S7.421 240 16.59 240h377.3l-140.7-149.3c-6.157-6.531-5.655-16.66 1.118-22.59c6.789-5.906 17.27-5.469 23.45 1.094l165.9 176C449.4 251.3 449.4 260.7 443.7 266.8z'/%3E%3C/svg%3E");
-  --link-colour: var(--qld-light-action-primary);
-  --icon-colour: var(--qld-light-action-secondary);
-  --icon-colour-hover: var(--qld-light-action-secondary-hover);
+  --link-colour: var(--#{$prefix}light-action-primary);
+  --icon-colour: var(--#{$prefix}light-action-secondary);
+  --icon-colour-hover: var(--#{$prefix}light-action-secondary-hover);
 
   color: var(--link-colour);
   text-decoration-color: var(--link-colour);
   display: flex;
+  gap: 0.5rem;
   width: fit-content;
   justify-content: space-between;
   align-self: flex-start;
 
   &:focus {
     border-radius: 4px;
-    outline: 3px solid var(--qld-focus-color);
+    outline: 3px solid var(--#{$prefix}focus-color);
     outline-offset: 2px;
   }
 
-  &.small {
-    font-size: 0.875rem;
-    line-height: 1rem;
-
-    .icon {
-      &::after {
-        zoom: 0.7;
-        mask-position: 0;
-      }
-    }
-  }
-
-  .icon {
-    &::after {
-      content: "";
-      display: inline-block;
-      width: 1rem;
-      height: 1.25rem;
-      mask-image: var(--dir-icon);
-      mask-repeat: no-repeat;
-      mask-position: 0 0.25rem;
-      background-color: var(--icon-colour);
-      margin-inline: 0.5rem;
-    }
-  }
-
   &:hover {
-
-    .icon {
-      &::after {
-        background-color: var(--icon-colour-hover);
-      }
+    .qld-icon {
+      background-color: var(--icon-colour-hover);
     }
   }
-
-  &.up {
-    .icon {
-      transform: rotate(270deg);
-    }
-  }
-
-  &.down {
-    .icon {
-      transform: rotate(90deg);
-    }
-  }
-
-  &.left {
-    flex-direction: row-reverse;
-
-    .icon {
-      transform: rotate(180deg);
-    }
-  }
-
-  &.right {
-    .icon {
-      transform: rotate(0deg);
-    }
+}
+a[aria-disabled="true"] {
+  pointer-events: none;
+  color: var(--#{$prefix}hint-text-color-muted);
+  text-decoration-color: var(--#{$prefix}dark-grey-muted);
+  .qld-icon {
+    background-color: var(--#{$prefix}dark-grey-muted);
   }
 }
-
 .light,
 .alt {
   .qld-dir-link {
-    --link-colour: var(--qld-light-action-primary);
-    --icon-colour: var(--qld-light-action-secondary);
-    --icon-colour-hover: var(--qld-light-action-secondary-hover);
+    --link-colour: var(--#{$prefix}light-action-primary);
+    --icon-colour: var(--#{$prefix}light-action-secondary);
+    --icon-colour-hover: var(--#{$prefix}light-action-secondary-hover);
   }
 }
 
 .dark,
 .dark-alt {
   .qld-dir-link {
-    --link-colour: var(--qld-dark-text);
-    --icon-colour: var(--qld-dark-action-secondary);
-    --icon-colour-hover: var(--qld-dark-action-secondary-hover);
+    --link-colour: var(--#{$prefix}dark-text);
+    --icon-colour: var(--#{$prefix}dark-action-secondary);
+    --icon-colour-hover: var(--#{$prefix}dark-action-secondary-hover);
+  }
+  a[aria-disabled="true"] {
+    color: var(--#{$prefix}dark-text-lighter);
+    text-decoration-color: var(--#{$prefix}dark-text-lighter);
+    .qld-icon {
+      background-color: var(--#{$prefix}dark-text-lighter);
+    }
   }
 }
 
 li .qld-dir-link {
   width: auto;
 }
-
-a[aria-disabled="true"] {
-  pointer-events: none;
-  color: var(--qld-dark-grey-muted);
-
-  .icon {
-    &::after {
-      background-color: var(--qld-dark-grey-muted);
-    }
-  }
-}

package/src/components/bs5/directionLinks/directionLinks.stories.js

@@ -15,29 +15,21 @@ export default {
     <!-- Grid container -->
     <div class="container">
       <div class="row">
-        <div class="col">
-          
+        <div class="col">          
           <!-- Component HTML -->
-          ${new DirectionLinks({ ...args, class: "up", label: "Up" }).html}
-        
+          ${new DirectionLinks({ ...args, class: "up", label: "Up" }).html}        
           </div>
         <div class="col">
-          
           <!-- Component HTML -->
-          ${new DirectionLinks({ ...args, class: "down", label: "Down" }).html}
-        
+            ${new DirectionLinks({ ...args, class: "down", label: "Down" }).html}
         </div>
         <div class="col">
-          
           <!-- Component HTML -->
-          ${new DirectionLinks({ ...args, class: "left", label: "Left" }).html}
-        
+            ${new DirectionLinks({ ...args, class: "left", label: "Left" }).html}        
         </div>
-        <div class="col">
-          
+        <div class="col">          
           <!-- Component HTML -->
-          ${new DirectionLinks({ ...args, class: "right", label: "Right" }).html}
-        
+            ${new DirectionLinks({ ...args, class: "right", label: "Right" }).html}        
         </div>
       </div>
     </div>
@@ -59,6 +51,7 @@ export default {
     label: { control: "text" },
   },
   parameters: {
+    controls: { disable: true },
     design: {
       name: "QGDS Figma Reference",
       type: "figma",

package/src/components/bs5/footer/Footer.mdx

@@ -6,9 +6,7 @@ import defaultdata from "./footer.data.json";
 
 # Footer
 
-<Canvas>
-  <Story of={FooterStories.Default} />
-</Canvas>
+<Canvas of={FooterStories.Default} />
 
 ## Design resources
 

package/src/components/bs5/footer/footer.scss

@@ -41,6 +41,7 @@
   --#{$prefix}footer-color-alt-button__hover: var(
     --#{$prefix}core-default-color-brand-primary-light-green
   );
+  --#{$prefix}footer-color-social-icon: #{$core-default-color-neutral-black};
 
   // ------------------------------------------------------------------------------------------------------------------
   // 2. Colours
@@ -85,6 +86,7 @@
     --#{$prefix}footer-color-focus: var(
       --#{$prefix}color-default-color-dark-underline-default
     );
+    --#{$prefix}footer-color-social-icon: #{$core-default-color-neutral-white};
   }
   &.dark-alt {
     --#{$prefix}footer-color-background: var(
@@ -216,17 +218,6 @@
     &:last-child {
       margin-block-end: 0;
     }
-
-    .qld-icon {
-      --#{$prefix}icon-color: var(--#{$prefix}brand-accent);
-      --qld-brand-accent: var(--#{$prefix}footer-color-alt-button);
-      display: block;
-      background-color: var(--#{$prefix}icon-color);
-
-      &:hover {
-        --qld-brand-accent: var(--#{$prefix}footer-color-alt-button__hover);
-      }
-    }
   }
 
   //Crest Logo
@@ -280,6 +271,8 @@
           }
 
           .qld-icon {
+            --#{$prefix}icon-color: var(--#{$prefix}footer-color-social-icon);
+
             // max-height: unset;
             margin-block-end: 0;
 

package/src/components/bs5/formcheck/stories/checkbox/Checkbox.mdx

@@ -1,18 +1,19 @@
-import { Canvas, Meta, Story } from "@storybook/blocks"
-import * as FormCheckCheckboxStories from "./checkbox.stories"
+import { Canvas, Meta, Story } from "@storybook/blocks";
+import * as FormCheckCheckboxStories from "./checkbox.stories";
 
 <Meta of={FormCheckCheckboxStories} />
 
 # Form check (Checkbox)
-<Canvas>
-  <Story of={FormCheckCheckboxStories.Default} />
-</Canvas>
+
+<Canvas of={FormCheckCheckboxStories.Default} />
 
 ## Design resources
+
 - [Bootstrap component](https://getbootstrap.com/docs/5.3/forms/checks-radios/)
 
 ### Checkbox
+
 - [Component library (Figma)](https://www.figma.com/file/qKsxl3ogIlBp7dafgxXuCA/QLD-GOV-DDS?type=design&node-id=11185-257399&mode=design&t=9b0T06NG5P47amzB-4)
 - [Master component file (Figma)](https://www.figma.com/file/qKsxl3ogIlBp7dafgxXuCA/QLD-GOV-DDS?type=design&node-id=11056-321348&mode=design&t=9b0T06NG5P47amzB-0)
 - [Design System website](https://www.design-system.health.qld.gov.au/components/checkboxes)./formcheckRadio.stories
-../../formcheckCheckbox.stories./checkbox.stories
+  ../../formcheckCheckbox.stories./checkbox.stories

package/src/components/bs5/formcheck/stories/radio/Radio.mdx

@@ -1,17 +1,18 @@
-import { Canvas, Meta, Story } from "@storybook/blocks"
-import * as FormCheckRadioStories from "./radio.stories"
+import { Canvas, Meta, Story } from "@storybook/blocks";
+import * as FormCheckRadioStories from "./radio.stories";
 
 <Meta of={FormCheckRadioStories} />
 
 # Form check (Radio)
-<Canvas>
-  <Story of={FormCheckRadioStories.Default} />
-</Canvas>
+
+<Canvas of={FormCheckRadioStories.Default} />
 
 ## Design resources
+
 - [Bootstrap component](https://getbootstrap.com/docs/5.3/forms/checks-radios/)
 
 ### Radio
+
 - [Component library (Figma)](https://www.figma.com/file/qKsxl3ogIlBp7dafgxXuCA/QLD-GOV-DDS?type=design&node-id=6274-42582&mode=design&t=sWeMBpAnKzpGzmWI-4)
 - [Master component file (Figma)](https://www.figma.com/file/qKsxl3ogIlBp7dafgxXuCA/QLD-GOV-DDS?type=design&node-id=11056-321347&mode=design&t=9b0T06NG5P47amzB-0)
-- [Design System website](https://www.design-system.health.qld.gov.au/components/radio-buttons)
+- [Design System website](https://www.design-system.health.qld.gov.au/components/radio-buttons)

package/src/components/bs5/globalAlert/GlobalAlert.mdx

@@ -6,9 +6,7 @@ import defaultdata from "./globalAlert.data.json";
 
 # Global alert
 
-<Canvas>
-  <Story of={GlobalAlertStories.Critical} />
-</Canvas>
+<Canvas of={GlobalAlertStories.Critical} />
 
 ## Design resources
 

package/src/components/bs5/globalAlert/globalAlert.scss

@@ -118,6 +118,8 @@
   }
 
   &.global-alert-critical {
+    --#{$prefix}icon-color: #{$core-default-color-neutral-white};
+    //
     background-color: $qld-notify-warning;
     color: var(--#{$prefix}white);
     font-size: 0.875em;
@@ -153,6 +155,8 @@
   }
 
   &.global-alert-warning {
+    --#{$prefix}icon-color: #{$core-default-color-neutral-black};
+    //
     background-color: $qld-notify-alert;
     color: var(--#{$prefix}body-color);
     font-size: 0.875em;
@@ -165,6 +169,8 @@
   }
 
   &.global-alert-info {
+    --#{$prefix}icon-color: #{$core-default-color-neutral-black};
+    //
     background-color: $qld-general-info-alert;
     color: var(--#{$prefix}body-color);
     font-size: 0.875em;

package/src/components/bs5/header/Header.mdx

@@ -5,9 +5,7 @@ import * as HeaderStories from "./header.stories";
 
 # Header
 
-<Canvas>
-  <Story of={HeaderStories.MasterBrand} />
-</Canvas>
+<Canvas of={HeaderStories.MasterBrand} />
 
 ## Design resources
 

package/src/components/bs5/header/header.hbs

@@ -22,7 +22,7 @@
 
                             <svg aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"
                                 class="qld-header-dropdown-icon ">
-                                <use href="{{@root.assets.SVGSpritePath}}#qgds-icon-chevron-down"
+                                <use href="{{../assets.SVGSpritePath}}#qgds-icon-chevron-down"
                                     aria-hidden="true"></use>
                             </svg>
                         </a>
@@ -35,7 +35,7 @@
                                 <a class="qld-header-link dropdown-item " href="{{url}}" {{#if target}}target="{{target}}"{{/if}}>
                                     {{text}}
                                     <svg width="24" height="24" class="qld-header-icon qld-header-dropdown-item-icon">
-                                        <use href="{{@root.assets.SVGSpritePath}}#qgds-icon-arrow-right"
+                                        <use href="{{ ../../assets.SVGSpritePath }}#qgds-icon-arrow-right"
                                             aria-hidden="true"></use>
                                     </svg>
                                 </a>
@@ -66,7 +66,7 @@
                     <a class="qld-header-link" href="{{url}}">
                         {{#if icon}} 
                         <svg class="qld-header-link-icon">
-                            <use href="{{@root.assets.SVGSpritePath}}#qgds-icon-{{icon}}" aria-hidden="true"></use>
+                            <use href="{{ ../assets.SVGSpritePath }}#qgds-icon-{{icon}}" aria-hidden="true"></use>
                         </svg>{{/if}}{{{text}}}
                     </a>
                     {{/if}}
@@ -80,11 +80,8 @@
                 <button id="qld-header-toggle-search-button" aria-controls="qld-header-search"
                     class="qld-header-toggle-main-nav" aria-expanded="false">
                     <svg aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg">
-                        <use class="icon-search"
-                            href="{{@root.assets.SVGSpritePath}}#qgds-icon-search" aria-hidden="true"
-                            style="display: block;"></use>
-                        <use class="icon-close" href="{{@root.assets.SVGSpritePath}}#qgds-icon-close"
-                            style="display: none;"></use>
+                        <use class="icon-search" href="{{ assets.SVGSpritePath }}#qgds-icon-search" aria-hidden="true" style="display: block;"></use>
+                        <use class="icon-close" href="{{ assets.SVGSpritePath}}#qgds-icon-close" style="display: none;"></use>
                     </svg>
                     <span class="qld-header-toggle-main-nav-text">Search</span>
                 </button>
@@ -94,7 +91,7 @@
                     data-bs-toggle="collapse" data-bs-target="#main-nav" aria-controls="main-nav" aria-expanded="false"
                     aria-label="Open menu">
                     <svg aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg">
-                        <use href="{{@root.assets.SVGSpritePath}}#qgds-icon-menu" aria-hidden="true">
+                        <use href="{{assets.SVGSpritePath}}#qgds-icon-menu" aria-hidden="true">
                         </use>
                     </svg>
                     <span class="qld-header-toggle-main-nav-text">Menu</span>

package/src/components/bs5/header/header.scss

@@ -17,8 +17,7 @@
 
 .qld-header {
   @extend %header-variables;
-  color: var(--#{$prefix}header-color-text);
-  background: var(--#{$prefix}header-color-bg);
+
   font-size: 1rem;
 
   @include media-breakpoint-up(sm) {
@@ -262,6 +261,7 @@
     border-bottom: solid 1px var(--#{$prefix}header__CTA_border_color);
     padding: 1rem 1.75rem 1rem 0;
     line-height: 1.5;
+    white-space: normal; // allow text to wrap
 
     &:visited {
       color: var(--#{$prefix}header__CTA_text_color);
@@ -285,10 +285,14 @@
     color: var(--#{$prefix}header__cta-wrapper__cta-link-icon_color);
     position: absolute;
     right: 0;
+    top: 50%;
+    transform: translateY(-50%);
   }
 
   &-main {
     position: relative;
+    color: var(--#{$prefix}header-color-text);
+    background: var(--#{$prefix}header-color-bg);
   }
 
   &-brand {

package/src/components/bs5/icons/Icons.mdx

@@ -1,13 +1,173 @@
-import { Canvas, Meta, Story, Title, Subtitle, Description, Heading, Source } from "@storybook/blocks";
-import * as IconsStories from "./icons.stories.js";
+import { Canvas, Meta, Story, Markdown } from "@storybook/blocks";
+import * as IconStories from "./icons.stories.js";
+import IconsSizes from "./mdx/_IconsSizes.mdx";
 
-<Meta of={IconsStories} />
+<Meta of={IconStories} />
 
-{/* Show Overview Story only - text returned by export default render function */}
-<Canvas>
-  <Story of={IconsStories.Overview} />
-</Canvas>
+# Iconography
 
+The icons in QGDS can be used in multiple ways depending on your needs and environment. This guide covers the 4 primary methods as well as the sizing utilities:
+
+- **Inline SVG**
+- **CSS utility class**
+- **SCSS mixin**
+- **CSS variables**
+
+## Inline SVG (HTML Embed)
+
+This method allows for full control over the icon's appearance, eg: colour,
+size, stroke, etc. Recommended for developers and content editors embedding
+icons directly in HTML.
+
+Place the Symbol ID on to the `<use>` element within an `<svg>` tag. Example:
+
+<svg
+  className="qld-icon qld-icon-lg"
+  style={{ color: "#dd0000" }}
+  aria-label="Cancel alert"
+  role="img"
+>
+  <use href="./assets/img/icons-sprite.svg#qgds-icon-alert-cancel"></use>
+</svg>
+<svg
+  className="qld-icon qld-icon-lg"
+  style={{ color: "#ffa500" }}
+  aria-label="Warning alert"
+  role="img"
+>
+  <use href="./assets/img/icons-sprite.svg#qgds-icon-alert-warning"></use>
+</svg>
+<svg
+  className="qld-icon qld-icon-lg"
+  style={{ color: "#00dd00" }}
+  aria-label="Success alert"
+  role="img"
+>
+  <use href="./assets/img/icons-sprite.svg#qgds-icon-alert-success"></use>
+</svg>
+
+```html
+<svg className="qld-icon qld-icon-lg" aria-label="Cancel alert">
+  <use href="./assets/img/icons-sprite.svg#qgds-icon-alert-cancel"></use>
+</svg>
+```
+
+### Accessibility
+
+- Always include `role="img"` and `aria-label`
+  attributes to provide context for screen readers.
+
+- Use `aria-hidden="true"` when the icon is decorative
+
+## CSS Class
+
+This method is suitable for developers who want to apply icons in their stylesheets.
+
+Use the `qld-icon` + `qld-icon-{iconName}` utility class to render icons as CSS masked elements.
+Example:
+
+<div>
+  <span class="qld-icon qld-icon-lg qld-icon-home" aria-hidden="true"></span>
+  <span class="qld-icon qld-icon-lg qld-icon-search" aria-hidden="true"></span>
+  <span class="qld-icon qld-icon-lg qld-icon-menu" aria-hidden="true"></span>
+</div>
+
+{/* prettier-ignore-start */}
+```html
+<span class="qld-icon qld-icon-lg qld-icon-home" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-lg qld-icon-search" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-lg qld-icon-menu" aria-hidden="true"></span>
+```
+{/* prettier-ignore-end */}
+
+### Accessibility
+
+- This method is for decorative only. Use `aria-hidden="true"` to hide the icon from screen readers.
+- Ensure to use it alongside text or other elements that provide context for screen readers users.
+
+## SCSS mixin
+
+For developers with access to scss source code, and when it is not feasible to alter existing html markup, you can apply the `make-icon` mixin to any existing class.
+Using the mixin ensures consistent implementation and API with standard icon classes.
+
+```css
+/* @use - sass module system. Make sure the path is correct for your particular implementation. */
+@use "/../../css/mixins";
+
+.my-custom-class {
+  @include mixins.make-icon($name: "alert-cancel");
+}
+```
+
+### Mixin API
+
+<Markdown>
+  {`
+| Parameter         | Type    | Description                                                                                                               |
+| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| \`$name\`         | String  | The name of icon. eg "alert-cancel". Optional but recoommended.                                                           |
+| \`$size\`         | String  | The icon size, valid values are \`"xs"\`, \`"sm"\`(default), \`"md"\`, \`"lg"\`, \`"xl"\`, \`"xxl"\`.                     |
+| \`$pseudo\`       | String  | Optionally apply styles as a pseudo-element. Valid string values are \`"before"\`, \`"after"\`, \`null\`(default)         |
+| \`$is-inline\`    | Boolean | Applies extra styles to assist with vertical alignent when used inline with text. Default:\`false\`                      |
+| \`$include-base\` | Boolean | Apply all base styles. Set to false when creating modifier classes where base styles are already applied. Default:\`true\`|                                                                                              
+`}
+
+</Markdown>
+
+## CSS Variables
+
+As a last resort this method allows developers to create custom styles with any CSS property that accepts a URL, such as <code>mask-image</code> and <code>background-image</code>.
+Only use this method in custom CSS where you don't have access to precompiled scss.
+Example:
+
+```css
+.mysite-icon-cancel-payment {
+  mask-image: var(--qgds-icon-alert-cancel);
+}
+
+.abc-icon-login {
+  background-image: var(--qgds-icon-identity);
+}
+```
+
+### Accessibility
+
+- This method is for decorative only. Use `aria-hidden="true"` to hide the icon from screen readers.
+- Ensure to use it alongside text or other elements that provide context for screen readers users.
+
+<IconsSizes />
+
+## Working with color
+
+Assigning a value to the custom property `--qld-icon-color` to alter an icon's color.
+This ensures the same API between inline SVGs, CSS classes and SCSS mixin. An extra benefit is that custom property cascades, meaning icons will inherit whatever value is set on its ancestors.
+
+<span className="my-link-with-icon" style={{ "--qld-icon-color": "red" }}>
+  <span class="qld-icon qld-icon-alert-danger"></span> Custom properties rock!
+</span>
+
+{/* prettier-ignore-start */}
+```html
+<span class="my-link-with-icon" style="--qld-icon-color: red">
+  <span class="qld-icon qld-icon-alert-danger"></span>
+  Custom properties rock!
+</span>
+```
+{/* prettier-ignore-end */}
+
+## Vertical Alignment
+
+### Inline with text
+
+When using icons inline with text, add additional class `is-inline` to the icon to assist with vertical alignment.
+
+<Canvas of={IconStories.InlineWithText} />
+
+### Within a flex container
+
+Use flex utility classes when within a flex container, either `align-items-center` on the parent, or `align-self-center` on the icon itself.
+
+<Canvas of={IconStories.FlexContainer} />
 
 ## Design resources
 

package/src/components/bs5/icons/_icons.sizes.scss

@@ -0,0 +1,9 @@
+// List of icon sizes
+$icon-sizes: (
+  "xs": 1rem,
+  "sm": 1.25rem,
+  "md": 1.5rem,
+  "lg": 2rem,
+  "xl": 2.5rem,
+  "xxl": 3rem,
+);