Implementation
Adding icons using our Design System
Our Design System provides a streamlined way to add icons to your web pages. Here are step-by-step instructions:
Step 1: add SVG element
Start by adding an SVG (Scalable Vector Graphics) element to your HTML. This is where the icon will be displayed.
<svg>
<!-- Icon will be loaded here -->
</svg>
Step 2: apply classes for styling and size
There are 2 classes you should add to the SVG element:
- qld__icon: this class is necessary for the basic visual appearance of the icon, it also tell the icon what colour to be depending on if it sits within a link element and also based on what background it appears on
- qld__icon--size: this class determines the size of the icon. Replace size with one of the following: sx, s, m, l, xl, xxl.
<svg class="qld__icon qld__icon--xxl">
<!-- Icon will be loaded here -->
</svg>
Step 3: add an aria-label and role for accessibility
Inside the SVG element, add role="img" and an aria-label that describes the icons function. This is important for accessibility, however it should only be added if:
- the icon has a function
- the aria label does not duplicate any text used alongside the icon
If an icon is decorative it does not need an aria-label.
<svg class="qld__icon qld__icon--xxl" role="img" aria-label="Opens profile settings">
<!-- Icon will be loaded here -->
</svg>
Step 4: use e
In the example below, icon-Profile is the ID of the icon. Make sure to replace it with the ID of the icon you want to use.
<svg class="qld__icon qld__icon--xxl" role="img" aria-label="Opens profile setting">
<use href="./?a=169317:dist/mysource_files/img/QLD-icons.svg#profile"></use>
</svg>
Adding icons associated with text or links
When incorporating icons that are closely associated with text or links, the following steps should be taken.
Step 1: add SVG element inside the link element
Similar to the standalone icons, you’ll add an SVG element. But in this case, the SVG element will be nested inside an anchor <a> element.
Step 2: apply the appropriate classes for positioning
Along with the previously mentioned classes, you need to use one additional class to determine the position of the icon with respect to the text.
- qld__icon--lead: use this class if the icon is placed before the text.
- qld__icon--trail: use this class if the icon is placed after the text.
Step 3: add role and aria label if necessary
In most situations a functional icon will always be accompanied by text describing its action. In these situations you do not need to add any additional labels or alt text as this would cause duplicate text being read out by screen readers.
In the first example below, the icon is used as a leading element before the text "Close". The SVG has the class qld__icon--lead which ensures it's placed before the text. The icon does not require an aria label describing its action.
In the second example, the icon is used alone without supporting text. In this situation the word "Close" is included in the aria-label for the icon. The role "img" is added to the icon to ensure it is identified correctly.
<!-- Functional icon with supporting text -->
<a href="#" class="qld__text-link">
<svg class="qld__icon qld__icon--lg qld__icon--lead">
<use href="./?a=169317:dist/mysource_files/img/QLD-icons.svg#alert-cancel"></use>
</svg>Close
</a>
<br/></br>
<!-- Functional Icon without supporting text -->
<a href="#">
<svg class="qld__icon qld__icon--lg qld__icon--lead" role="img" aria-label="Close">
<use href="./?a=169317:dist/mysource_files/img/QLD-icons.svg#alert-cancel"></use>
</svg>
</a>
Accessibility consideration
When icons are used alongside text or within actionable elements like links or buttons, no aria-label is necessary. This is because you want to ensure screen readers don't read out an action twice. The text next the icon should be sufficient for understanding the action.
When adding icons that are associated with text or links, it’s essential to ensure they're positioned correctly using qld__icon--lead or qld__icon--trail, and that they don't interfere with the accessibility of the text.
Leading icons are for reinforce the meaning of a label or button, indicating what action will be performed, such as a "play" icon before a "Play" button. Leading icons also guide the user's attention and establish a visual hierarchy, making it easier to scan lists or menus. This is especially useful in navigation menus where icons can represent categories.
Trailing icons are often used to suggest that more options are available or that the content will lead somewhere else.
Classes, variables and icon IDs
Classes and variables
| Name | Description |
|---|---|
qld__iconCopy | Applied to SVGs this sets the default styles for icons. |
qld__icon--leadCopy | Class that sets element to small font size and heading weight. |
qld__icon--trailCopy | Class that sets element to medium font size and heading weight. |
qld__icon--smCopy | Sets icon to 20px in size. |
qld__icon--mdCopy | Sets icon to 24px in size. |
qld__icon--lgCopy | Sets icon to 32px in size. |
qld__icon--xlCopy | Sets icon to 48px in size. |
qld__icon--xxlCopy | Sets icon to 64px in size. |
qld__icon--featureCopy | Defines the style of feature icons. |
--QLD-color-light-headingCopy | Variable that defines colour of descriptive icons. |
--QLD-color-dark-headingCopy | Variable that defines colour of descriptive icons on dark backgrounds. |
--QLD-color-light-alt-buttonCopy | Variable that defines colour of icons that are associated with links on light backgrounds. |
--QLD-color-light-alt-button__hoverCopy | Variable that defines hover colour of icons that are associated with links on light backgrounds. |
--QLD-color-dark-alt-buttonCopy | Variable that defines colour of icons that are associated with links on dark backgrounds. |
--QLD-color-dark-alt-button__hoverCopy | Variable that defines hover colour of icons that are associated with links on dark backgrounds. |