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

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.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,
+);

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

@@ -1,3 +1,8 @@
+@forward "./_icons.variables";
+@use "./_icons.list" as *;
+@use "./icons.sizes" as *;
+@use "../../../css/mixins" as m;
+
 /* @TODO: Remove lines in between once all the icons within the components have been synced with new icons.  */
 :root {
   //Define global icons as CSS variables
@@ -9,23 +14,6 @@
 }
 
 .qld-icon {
-  //Shared icon styles
-  display: inline-block;
-  width: 1.25rem;
-  height: 1.25rem;
-  background-position: center center;
-  background-repeat: no-repeat;
-  mask-position: center center;
-  -webkit-mask-position: center center;
-  mask-repeat: no-repeat;
-  -webkit-mask-repeat: no-repeat;
-
-  //Default color
-  background: var(--#{$prefix}icon-color);
-
-  //Change color at component level... e.g. on cards.css, use:
-  // .card { --#{$prefix}icon-color: purple; }
-
   &.icon-dot-grid {
     mask-image: escape-svg(var(--icon-dot-grid));
     -webkit-mask-image: escape-svg(var(--icon-dot-grid));
@@ -50,69 +38,33 @@
 }
 /* @TODO: Remove all lines above once all the icons within the components have been synced with new icons.  */
 
-@import "./_icons.variables";
-@import "./_icons.list";
-@import "./_icons-multicolours.list";
-
-$prefixIcon: $prefix + "icon-"; // Prefix for icon classes, based on global prefix in main.scss
-$prefixIconQgds: "--qgds-icon-"; // This QGDS variable could be moved to the token or tolkien repo.
-
-// Ensure SVGs inherit the current text color
-// Comment out to use the "fill" attribute inside svg element instead
-/*
-svg {
-	fill: currentColor;
-} */
-
-// List of icon sizes
-$icon-sizes: (
-  "xs": 1rem,
-  "sm": 1.25rem,
-  "md": 1.5rem,
-  "lg": 2rem,
-  "xl": 2.5rem,
-  "xxl": 3rem,
-);
-
 // Loop through the icon names and create utility class for each
 .qld-icon {
-  display: inline-block;
-  width: 1.25rem;
-  height: 1.25rem;
-  background-position: center center;
-  background-repeat: no-repeat;
-  mask-position: center center;
-  mask-repeat: no-repeat;
-  mask-size: contain;
-  background-color: var(--#{$prefix}body-color); // Default icon color
+  @include m.make-icon();
+
+  &:where(svg) {
+    background-color: transparent;
+  }
 
   // Utility classes for icons
   // Note: mask-image is the preferred method for icons that are single colour, as it allows for easy colour changes using CSS variables.
   // The background-image method is used for SVG icons with multiple fill colours.
   @each $icon in $icon-names {
-    @if index($icons-multicolour, $icon) {
-      // Only use background-image for multi colours icons.
-      &.#{$prefixIcon}#{$icon} {
-        background-image: var(#{$prefixIconQgds}#{$icon});
-        -webkit-background-image: var(#{$prefixIconQgds}#{$icon});
-        background-color: transparent;
-      }
-    } @else {
-      &.#{$prefixIcon}#{$icon} {
-        mask-image: var(#{$prefixIconQgds}#{$icon});
-        -webkit-mask-image: var(#{$prefixIconQgds}#{$icon});
-      }
+    &-#{$icon} {
+      @include m.make-icon($name: $icon, $include-base: false);
+    }
+  }
+
+  // Loop through the icon sizes and create utility class for each size.
+  // Independent from the icon base class to allow sizing on inline SVG icons as well as CSS icons.
+  @each $key, $value in $icon-sizes {
+    &-#{$key} {
+      --icon-size: #{$value};
     }
   }
-}
 
-// Loop through the icon sizes and create utility class for each size.
-// Independent from the icon base class to allow sizing on inline SVG icons as well as CSS icons.
-@each $size, $value in $icon-sizes {
-  .#{$prefixIcon}#{$size} {
-    width: $value;
-    height: $value;
-    mask-size: $value;
-    background-size: $value;
+  // Better alignment for icons inline with text
+  &.is-inline {
+    @include m.make-icon($include-base: false, $is-inline: true);
   }
 }

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

@@ -1,29 +1,10 @@
 import iconNames from "./_icons.list.js";
-import { Card } from '../card/Card.js';
-import iconUsageHtml from './story-icon-usage.html?raw';
-import iconSizingHtml from './story-icon-sizing.html?raw';
+import storyInlineWithTextHtml from "./stories/storyInlineWithText.html?raw";
+import storyFlexContainerHtml from "./stories/storyFlexContainer.html?raw";
+import storySizesHtml from "./stories/storySizes.html?raw";
 
-const defaultdata = {
-  "title": "Card title",
-  "description": "Card body text",
-  "date": "",
-  "variantClass": "default",
-  "image": "",
-  "imageAlt": "",
-  "iconClasses": "",
-  "iconPosition": "icon-top",
-  "action": "no",
-  "link": "",
-  "arrow": false,
-  "feature": false,
-  "featureImagePosition": "",
-  "video": false,
-  "videoDuration": "",
-  "footer": "",
-  "equalHeight": false,
-};
-const SPRITE_PATH = './assets/img/icons-sprite.svg';
-const PREFIX_QGDS = 'qgds-icon-';
+const SPRITE_PATH = "./assets/img/icons-sprite.svg";
+const PREFIX_QGDS = "qgds-icon-";
 
 // Helper function to remove the prefix from icon names
 function _removePrefixQGDS(name) {
@@ -33,48 +14,42 @@ function _removePrefixQGDS(name) {
   return name;
 }
 
-
 // Default export for Storybook
 export default {
   tags: ["autodocs"],
   title: "1. Core Styles/Iconography",
-  render: () => {
-    return iconUsageHtml + `<hr>` + iconSizingHtml;
-  },
   parameters: {
     layout: "padded",
     docs: {
       title: "Iconography in default",
-    // page: null, // To disable autodocs 
+      // page: null, // To disable autodocs
     },
   },
 };
 
-// Exports default as Overview, in order to avoid another "Default" menu in Storybook
-export const Overview = {};
-
 // Story for displaying all icons as SVGs
 export const SvgIcons = () => {
   return `
     <div class="container">
     <div class="row row-cols-sm-2 row-cols-lg-4 row-cols-xl-5 g-4">
       ${iconNames
-    .map(name => 
-    {
-      return new Card({
-        ...defaultdata,
-        title: ``,  // Overrides card title to empty string
-        description: `
-                <div class="mb-4">
-                  <svg class="qld-icon-xl" aria-label="${_removePrefixQGDS(name)} icon" role="img" width="32" height="32" viewBox="0 0 32 32" focusable="false">
+        .map((name) => {
+          return `
+          <div class="col">
+            <div class="card">
+              <div class="card-body" style="text-align: center">
+                <div class="mt-12 mb-4">
+                  <svg class="qld-icon qld-icon-xl" aria-label="${_removePrefixQGDS(name)} icon" role="img" width="32" height="32" viewBox="0 0 32 32" focusable="false">
                     <use href="${SPRITE_PATH}#${PREFIX_QGDS}${name}" />
                   </svg>
                 </div>
                 <small>${_removePrefixQGDS(name)}</small><br><code style="font-size: 0.75rem"> #${PREFIX_QGDS}${name}</code>
-                `,
-      }).html
-    })
-    .join('')}
+              </div>
+            </div>
+          </div>
+          `;
+        })
+        .join("")}
     </div>
     </div>
   `;
@@ -87,26 +62,28 @@ export const CssIcons = () => {
     <div class="container">
     <div class="row row-cols-sm-2 row-cols-lg-4 row-cols-xl-5 g-4">
       ${iconNames
-    .map(name => new Card({
-      ...defaultdata,
-      title: ``,  // Override card title to empty string
-      description: `
-                <div class="mb-4">
+        .map((name) => {
+          return `
+          <div class="col">
+            <div class="card">
+              <div class="card-body" style="text-align: center">
+                <div class="mt-12 mb-4">
                   <span class="qld-icon qld-icon-xl qld-icon-${name}"></span>
                 </div>
                 <small>${_removePrefixQGDS(name)}</small><br><code style="font-size: 0.75rem">qld-icon-${name}</code>
-                `,
-      iconClasses: ``,
-    }).html)
-    .join('')}
+              </div>
+            </div>
+          </div>`;
+        })
+        .join("")}
     </div>
     </div>
   `;
 };
 CssIcons.storyName = "CSS Icons";
 
-// Story for displaying icon sizing variations
-export const Sizes = () => {
-  return iconSizingHtml;
-};
+export const Sizes = () => storySizesHtml;
+
+export const FlexContainer = () => storyFlexContainerHtml;
 
+export const InlineWithText = () => storyInlineWithTextHtml;

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

@@ -0,0 +1,112 @@
+import { Sizes } from "../icons.stories";
+import { Story } from "@storybook/blocks";
+
+## Sizes
+
+We have 6 preset sizes for icons ranging from extra small (xs) to extra
+extra large (xxl) and a dedicated feature size for large or detailed icons.
+Feature icons use a background shade to help make it stand out from other
+elements on the page.
+
+This size range allows for flexibility and adaptability in various design
+contexts while maintaining visual harmony and balance. These predefined
+sizes ensure that icons are proportionate and legible, enhancing their
+effectiveness and the overall aesthetic of the site.
+
+<Story of={Sizes} />
+
+#### Usage
+
+Combine base class <code>qld-icon</code> with specific icon name and size
+class as listed here to set the icon size.
+
+<table class="table table-responsive">
+  <thead class="table-light">
+    <tr>
+      <th scope="col">Class</th>
+      <th scope="col">REM size</th>
+      <th scope="col">Pixel size</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>.qld-icon-xs</code>
+      </td>
+      <td>
+        <pre>1rem</pre>
+      </td>
+      <td>
+        <pre>16x16</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>.qld-icon-sm</code>
+      </td>
+      <td>
+        <pre>1.25rem</pre>
+      </td>
+      <td>
+        <pre>20x20</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>.qld-icon-md</code>
+      </td>
+      <td>
+        <pre>1.5rem</pre>
+      </td>
+      <td>
+        <pre>24x24</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>.qld-icon-lg</code>
+      </td>
+      <td>
+        <pre>2rem</pre>
+      </td>
+      <td>
+        <pre>32x32</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>.qld-icon-xl</code>
+      </td>
+      <td>
+        <pre>2.5rem</pre>
+      </td>
+      <td>
+        <pre>40x40</pre>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>.qld-icon-xxl</code>
+      </td>
+      <td>
+        <pre>3rem</pre>
+      </td>
+      <td>
+        <pre>48x48</pre>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<h5 class="mt-5">Example code:</h5>
+
+{/* prettier-ignore-start */}
+```html
+<span class="qld-icon qld-icon-xxl qld-icon-design" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-xl qld-icon-design" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-lg qld-icon-design" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-md qld-icon-design" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-sm qld-icon-design" aria-hidden="true"></span>
+<span class="qld-icon qld-icon-xs qld-icon-design" aria-hidden="true"></span>
+```
+{/* prettier-ignore-end */}