Implementation
Spacing variables and utilities
Controlling the site's vertical rhythm
Spacing within our design system is controlled globally by a set of variables categorised by their component or HTML element type. These variables define the core values that establish our vertical rhythm, ensuring consistent repetitive spacing and patterns that across all pages of a site. Using variables allows for easy updates to from a central location, making the design process more efficient and scalable.
Each variable's key-value comes from the base $QLD-space-map . The $QLD-space-map is a Sass map that defines a set of key-value pairs for consistent spacing values used throughout a design system, enabling uniform application of margins, padding, and other spacing-related properties across a website.
QLD-space-map
The QLD Space Map is a foundational element in our design system, providing a standardised set of spacing values that are applied consistently across all components and HTML elements. This Sass map is crucial for maintaining a cohesive vertical rhythm and ensuring consistent spacing throughout the user interface.
Purpose of the QLD-space-map
- Consistency: The QLD-space-map ensures that all spacing between elements, such as margins, paddings, and gaps, follows a consistent pattern. This consistency helps create a visually harmonious and predictable layout, enhancing the user experience.
- Scalability: By mapping specific spacing values to keywords or numbers, the space map allows for easy adjustments and scalability. Whether designing for mobile or desktop, the same spacing principles can be applied, ensuring the design scales gracefully across different screen sizes.
- Efficiency: The predefined spacing values reduce the need for ad-hoc spacing decisions during development, streamlining the design and implementation process. This leads to more efficient coding practices and reduces the likelihood of spacing-related issues
Example of code using variables and our space functions
It is essential that the correct variables are used when building or updating components, and that margins are always implemented using a combination of these variables and the "Lobotomised Owl" methodology.
Developers can use the function QLD-space for consistent spacing across elements on all browsers. This is done with a new unit we created, called unit , to allow designers and developers to be able to keep consistency. This function helps ensure that elements snap to our predefined 4-pixel-grid, which is set by the $QLD-unit variable.
1unit is the equivalent of 1rem , which by default is 16px .
The function QLD-space should be used to apply or padding and margin values.
Our space function is based on he Digital Transformation Agencies font and spacing functions.
/* Margin-top value * /
* + .qld__component-name {
@include QLD-space(margin-top, $QLD-margin__component--desktop);
}
/* Padding value * /
.qld__component-name {
@include QLD-space(padding, 1unit 0 1unit 0);
}
Variables
Each of these variables should be used as the margin top value for the relevant category.
Each category has a variable for:
- desktop spacing for screens wider than 992px, optimised for more screen real estate
- mobile spacing for screens narrower than 992px, adapted for smaller displays.
Margin top values for components, containers and sections
| Category | Viewport | Variable | Value | $QLD-space-map |
|---|---|---|---|---|
| Section elements | Mobile | $QLD-margin__section--mobile | 40px (2.5rem) | 9 |
| Desktop | $QLD-margin__section--desktop | 64px (4rem) | 12 | |
| Content blocks within a section | Mobile | $QLD-margin__content-block--mobile | 32px (2rem) | 7 |
| Desktop | $QLD-margin__content-block--desktop | 48px (3rem) | 10 | |
| Components | Mobile | $QLD-margin__component--mobile | 24px (1.5rem) | 6 |
| Desktop | $QLD-margin__component--desktop | 32px (2rem) | 7 |
Margin top values for headings, text elements paragraphs and list items
| Category | Viewport | Variable | Value | $QLD-space-map |
|---|---|---|---|---|
| H1 | Mobile | $QLD-margin__h1--mobile | 32px (2rem) | 7 |
| Desktop | $QLD-margin__h1--desktop | 56px (3.5rem) | 11 | |
| H2 | Mobile | $QLD-margin__h2--mobile | 32px (2rem) | 7 |
| Desktop | $QLD-margin__h2--desktop | 48px (3rem) | 10 | |
| H3 | Mobile | $QLD-margin__h3--mobile | 24px (1.5rem) | 7 |
| Desktop | $QLD-margin__h3--desktop | 36px (2.25rem) | 8 | |
| H4-H6 | Mobile | $QLD-margin__h4-h6--mobile | 20px (1.25rem) | 5 |
| Desktop | $QLD-margin__h4-h6--desktop | 32px (2rem) | 7 | |
| Between H and P tags | Mobile | $QLD-margin__text-element--mobile | 20px (1.25rem) | 5 |
| Desktop | $QLD-margin__text-element--desktop | 24px (1.5rem) | 6 | |
|
Paragraph spacing (Margin between two P tags) | Mobile | $QLD-margin__p--mobile | 16px (1rem) | 4 |
| Desktop | $QLD-margin__p--desktop | 16px (1rem) | 4 | |
| Between list items (close) | Mobile | $QLD-margin__li-close--mobile | 8px (0.5rem) | 2 |
| Desktop | $QLD-margin__li-close--desktop | 8px (0.5rem) | 2 | |
| Between list items (wide) | Mobile | $QLD-margin__li-wide--mobile | 12px (0.75rem) | 3 |
| Desktop | $QLD-margin__li-wide--desktop | 12px (0.75rem) | 3 | |
| Labels and form hint messages | Mobile | $QLD-margin__lables--mobile | 8px (0.5rem) | 2 |
| Desktop | $QLD-margin__lables--desktop | 8px (0.5rem) | 2 |
Section spacing
Section elements with background colours applied the the qld__body classes are unique in our design system, they are an essential part of our vertical rhythm however they use padding to create vertical space rather then margin top values. This is because using margin-top values for spacing would cause the backgrounds colours within sections stack incorrectly together on a page.
| Category | Viewport | Variable | Value | $QLD-space-map |
|---|---|---|---|---|
| Section elements | Mobile | $QLD-padding__section--mobileCopy | 40px (2.5rem) | 9 |
| Desktop | $QLD-padding__section--desktopCopy | 64px (4rem) | 12 |
Utility classes
We have a number of responsive classes that can be added to html elements to override or set margin values.
They are categorised by the type of element or component you are applying space to and are useful when crafting custom layouts.
In addition to setting margin-top values there are also utility classes to remove spacing and to apply row and column gap properties for flex-box layouts.
Margin and padding spacing classes
| Class name | Desktop value | Mobile value | Description |
|---|---|---|---|
qld__margin-t-sectionCopy | 64px (4rem) | 40px (2.5rem) | Applies section margin-top values |
qld__margin-t-content-blockCopy | 48px (3rem) | 32px (1.5rem) | Applies content blocks margin-top values |
qld__margin-t-componentCopy | 32px (2rem) | 24px (1.5rem) | Applies component margin-top values |
qld__margin-t-text-elementCopy | 24px (1.5rem) | 20px (1.25rem) | Applies text element margin-top values |
qld__margin-t-pCopy | 16px (1rem) | 16px (1rem) | Applies paragraph margin-top values |
qld__margin-t-li--smCopy | 8px (0.5rem) | 8px (0.5rem) | Applies close/tight list margin-top values |
qld__margin-t-li--lgCopy | 12px (0.75rem) | 12px (0.75rem) | Applies generous list margin-top values |
qld__margin-t-labelCopy | 8px (0.5rem) | 8px (0.5rem) | Applies label margin-top values |
qld__margin-t-noneCopy | 0px | 0px | Removes any existing margin top value |
qld__padding-t-noneCopy | 0px | 0px | Removes any existing padding top value |
Section spacing | qld__margin-t-section
Content block spacing | qld__margin-t-section
Component spacing | qld__margin-t-component
Text element spacing | qld__margin-t-text-element
Paragraph spacing | qld__margin-t-p
Label spacing | qld__margin-t-label
-
Wide list spacing | qld__margin-t-li--lg applied to ul
-
Wide list spacing | qld__margin-t-li--lg applied to ul
-
Wide list spacing | qld__margin-t-li--lg applied to ul
-
Close list spacing | qld__margin-t-li--sm applied to ul
-
Close list spacing | .qld__margin-t-li--sm applied to ul
-
Close list spacing | qld__margin-t-li--sm applied to ul
<section class="qld__margin-t-section">Section spacing example</section>
<div class="qld__margin-t-content-block">Content block spacing example</div>
<div class="qld__margin-t-component">Section spacing example</div>
<span class="qld__margin-t-text-element">Text elemment spacing example</span>
<p class="qld__margin-t-p">Paragraph spacing example</p>
<p class="qld__margin-t-label">Label spacing example</p>
<ul lass="qld__margin-t-li--lg">
<l>Close list spacing example</l>
<li>Close list spacing example</li>
<li>Close list spacing example</li>
</ul>
<ul class="qld__margin-t-li--sm">
<li>Wide list spacing example</li>
<li>Wide list spacing example</li>
<li>Wide list spacing example</li>
</ul>
Flex spacing classes
| Class name | Desktop value | Mobile value | Description |
|---|---|---|---|
qld__row-gap-content-blockCopy | 48px (3rem) | 32px (2rem) | Content block spacing gap between rows |
qld__row-gap-componentCopy | 32px (2rem) | 24px (1.5rem) | Component spacing gap between rows |
qld__row-gap-text-elementCopy | 24px (1.5rem) | 20px (1.25rem) | Text-element spacing gap between rows |
qld__row-gap-pCopy | 16px (1rem) | 16px (1rem) | Paragraph spacing gap between rows |
qld__row-gap-li--smCopy | 8px (0.5rem) | 8xp (0.5rem) | Close list spacing gap between rows |
qld__row-gap-li--lgCopy | 12px (0.75rem) | 12px (0.75rem) | Wide list spacing gap between rows |
qld__col-gap-content-block Copy | 48px (3rem) | 32px (2rem) | Content block spacing gap between columns |
qld__col-gap-component Copy | 32px (2rem) | 24px (1.5rem) | Component spacing gap between columns |
qld__col-gap-text-element Copy | 24px (1.5rem) | 20px (1.25rem) | Text-element spacing gap between columns |
qld__col-gap-p Copy | 16px (1rem) | 16px (1rem) | Paragraph spacing gap between columns |
qld__col-gap-li--sm Copy | 8px (0.5rem) | 8px (0.5rem) | Close list spacing gap between columns |
qld__col-gap-li--lgCopy | 12px (0.75rem) | 12px (0.75rem) | Wide list spacing gap between columns |