Skip to content

Utils13.10.5

A set of helper classes and mixins to work as an utility belt for your styling needs.


$ npm i @if-design-system/util@13.10.5

There is currently no documentation for this section yet.
Contact the Design System team for questions.

If you want to contribute, you can also add the documentation yourself!

Edit this section

Responsive

<span class="if u-responsive--[xs|sm|md|lg|xl]">
  This makes the container scroll horizontally from given breakpoint and down
</span>
Edit this section

Spacing

Design tokens

You can use the design tokens to accommodate for correct spacing according to the 4px/8px baseline grid. All design tokens are in the $size-spacing-NN format:

Stylus

.box
  padding $size-spacing-24

SCSS

.box {
  padding: $size-spacing-24;
}

LESS

.box {
  padding: @size-spacing-24;
}

Class helpers

To set some standard spacing, we also provide some classes for this usage.

Bare in mind, that most components and layouts have their predefined spacing set. Do not use these classes to override the spacing without thinking of the consequences.

Usage

<div class="if u-margin-(bottom|top|right|left)--[8|16|24|etc..]">...</div>
<div class="if u-padding-(bottom|top|right|left)--[8|16|24|etc..]">...</div>
Responsive spacing

If you want to use responsive spacing, we have a small set of helper classes that will shift its value based on the breakpoints.

For example, say you have a container:

<div class="if"></div>

That is required to have different margin right depending on preset breakpoints, so you can add the helpers like so:

<div class="if u-margin-sm-right--32 u-margin-xs-right--16"></div>

The same works for padding:

<div class="if u-padding-sm-right--32 u-padding-xs-right--16"></div>

Outtake form the styles:

@media screen and (min-width: 60rem) {
  .if.u-margin-sm-right--32 {
    margin-right: 2rem;
  }
}@media screen and (min-width: 25rem) {
  .if.u-margin-xs-right--16 {
    margin-right: 1rem;
  }
}

The responsive spacing helpers are for these breakpoints only:

Breakpoint Value Px
xs 25rem 400px
smlr 45rem 720px
sm 60rem 960px
md 75rem 1200px

The responsive spacing helpers are for these values only:

Token Value Px
$size-spacing-4 0.25rem 4px
$size-spacing-8 0.5rem 8px
$size-spacing-16 1rem 16px
$size-spacing-28 1.75rem 28px
$size-spacing-32 2rem 32px
$size-spacing-40 2.5rem 40px
$size-spacing-48 3rem 48px
$size-spacing-64 4rem 64px
none 0 0
<div class="if u-[padding|margin]-[breakpoint]-[top|right|bottom|left]--[size]"></div>

Usage with grid rows

A row with margin bottom
A row without margin bottom
A row without margin bottom
<div class="if row u-margin-bottom--56">
  <div class="if col-12--xs">A row with margin bottom</div>
</div>
<div class="if row">
  <div class="if col-12--xs">A row without margin bottom</div>
</div>
<div class="if row">
  <div class="if col-12--xs">A row without margin bottom</div>
</div>
Edit this section

Hidden

We provide easy to use classes to hide content on specific breakpoints.

Usage

  1. This is hidden from xxs-breakpoint and up
  2. This is hidden from xs-breakpoint and up
  3. This is hidden from smlr-breakpoint and up
  4. This is hidden from sm-breakpoint and up
  5. This is hidden from md-breakpoint and up
  6. This is hidden from lg-breakpoint and up
  7. This is hidden from xl-breakpoint and up
  8. This is hidden from xxl-breakpoint and up
  9. This is hidden from huge-breakpoint and up
  10. This is hidden from huger-breakpoint and up
  11. This is hidden from xxs-breakpoint and down
  12. This is hidden from xs-breakpoint and down
  13. This is hidden from smlr-breakpoint and down
  14. This is hidden from sm-breakpoint and down
  15. This is hidden from md-breakpoint and down
  16. This is hidden from lg-breakpoint and down
  17. This is hidden from xl-breakpoint and down
  18. This is hidden from xl-breakpoint and down
  19. This is hidden from huge-breakpoint and down
  20. This is hidden from huger-breakpoint and down

Implementation

<span class="if u-hidden-down--[xxs|xs|smlr|sm|md|lg|xl|xxl|huge|huger]"
  >This is hidden from given breakpoint and down</span
>
<span class="if u-hidden-up--[xxs|xs|smlr|sm|md|lg|xl|xxl|huge|huger]"
  >This is hidden from given breakpoint and up</span
>
Edit this section

Tokens

All of the tokens can be used as preprocessor variables

Size

Name Value Pixels Example
$size-4 0.25rem 4px
$size-8 0.5rem 8px
$size-12 0.75rem 12px
$size-16 1rem 16px
$size-20 1.25rem 20px
$size-24 1.5rem 24px
$size-28 1.75rem 28px
$size-32 2rem 32px
$size-36 2.25rem 36px
$size-40 2.5rem 40px
$size-44 2.75rem 44px
$size-48 3rem 48px
$size-52 3.25rem 52px
$size-56 3.5rem 56px
$size-60 3.75rem 60px
$size-64 4rem 64px
$size-68 4.25rem 68px
$size-72 4.5rem 72px
$size-76 4.75rem 76px
$size-80 5rem 80px
$size-84 5.25rem 84px
$size-88 5.5rem 88px
$size-92 5.75rem 92px
$size-96 6rem 96px
$size-100 6.25rem 100px
$size-104 6.5rem 104px

Spacing

These tokens are 1:1 similar to the global size tokens, for now. We are to prune these spacing tokens to pure spacing intervals.
Name Value Pixels Example
$size-spacing-4 0.25rem 4px
$size-spacing-8 0.5rem 8px
$size-spacing-12 0.75rem 12px
$size-spacing-16 1rem 16px
$size-spacing-20 1.25rem 20px
$size-spacing-24 1.5rem 24px
$size-spacing-28 1.75rem 28px
$size-spacing-32 2rem 32px
$size-spacing-36 2.25rem 36px
$size-spacing-40 2.5rem 40px
$size-spacing-44 2.75rem 44px
$size-spacing-48 3rem 48px
$size-spacing-52 3.25rem 52px
$size-spacing-56 3.5rem 56px
$size-spacing-60 3.75rem 60px
$size-spacing-64 4rem 64px
$size-spacing-68 4.25rem 68px
$size-spacing-72 4.5rem 72px
$size-spacing-76 4.75rem 76px
$size-spacing-80 5rem 80px
$size-spacing-84 5.25rem 84px
$size-spacing-88 5.5rem 88px
$size-spacing-92 5.75rem 92px
$size-spacing-96 6rem 96px
$size-spacing-100 6.25rem 100px
$size-spacing-104 6.5rem 104px

Z-index

Name Value Description
$depth-z-index-deep -999999 Deep z-index is used to stack something behind everything else.
$depth-z-index-default 1 The default z-index for components and elements inside components.
$depth-z-index-masked 100 Default z-index for masked interface elements.
$depth-z-index-mask 200 Default z-index for masking interface elements.
$depth-z-index-sticky 300 Default z-index for sticky interface elements.
$depth-z-index-global-header 400 Default z-index for the Global Header.
$depth-z-index-toast 500 Default z-index for toast messages.
$depth-z-index-dropdown 600 Default z-index for dropdowns which makes sure the dropdown stacks above toasts and sticky elements.
$depth-z-index-overlay 700 Default z-index for modal and popup overlays.
$depth-z-index-loader 800 Default z-index for loaders, stacking on top of overlay.
$depth-z-index-modal 900 Default z-index for modals that stacks on top of overlays and other elements, but still allows popovers to be visible.
$depth-z-index-popover 950 Default z-index for popover that stacks on top of all other elements.

Opacity

Name Value Example Description
$depth-opacity-hidden 0
Makes the element completely tranparent.
$depth-opacity-border 0.2
Gives 20% opacity to an element.
$depth-opacity-disabled 0.3
Gives 30% opacity to an element.
$depth-opacity-backdrop 0.4
Gives 40% opacity to an element.
$depth-opacity-visible 1
Makes an element completely visible.

Box shadow

Object Name Color Opacity Offset Blur Example
light $depth-shadow-light-100 LB 1, LIGHT BROWN 12% x: 0, y: 8px 8px
light $depth-shadow-light-200 LB 1, LIGHT BROWN 16% x: 0, y: 12px 16px
light $depth-shadow-light-300 LB 1, LIGHT BROWN 20% x: 0, y: 16px 24px
light $depth-shadow-light-400 LB 1, LIGHT BROWN 24% x: 0, y: 20px 32px
dark $depth-shadow-dark-100 BR 1, DARK BROWN 20% x: 0, y: 8px 8px
dark $depth-shadow-dark-200 BR 1, DARK BROWN 24% x: 0, y: 12px 16px
dark $depth-shadow-dark-300 BR 1, DARK BROWN 28% x: 0, y: 16px 24px
dark $depth-shadow-dark-400 BR 1, DARK BROWN 32% x: 0, y: 20px 32px
Edit this section

App development

For application development, we also expose tokens for native app development, like Android and IOS. We also expose tokens for JavaScript development.

JavaScript

We expose this file: @if-design-system/util/src/variables/js/variables.esm.js, in this format:

export const SizeSpacing88 = "5.5rem"; // 88px
export const SizeSpacing92 = "5.75rem"; // 92px
export const SizeSpacing96 = "6rem"; // 96px
export const SizeSpacing100 = "6.25rem"; // 100px
export const SizeSpacing104 = "6.5rem"; // 104px
export const SizeSpacing4px = 4; // 0.25rem
export const SizeSpacing8px = 8; // 0.5rem
export const SizeSpacing12px = 12; // 0.75rem
export const SizeSpacing16px = 16; // 1rem

This can be used like so:

import { SizeSpacing88 } from '@if-design-system/util/src/variables/js/variables.module.js';

const myTitle = ({title}) => (<h4 style={{marginBottom: SizeSpacing88}})>{title}</h4>);

Android

For Android development, you might be interested in this file: @if-design-system/util/src/variables/android/dimens.xml, in this format:

<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <dimen name="size_spacing_12">12.00dp</dimen><!-- 12px -->
  <dimen name="size_spacing_16">16.00dp</dimen><!-- 16px -->
  <dimen name="size_spacing_20">20.00dp</dimen><!-- 20px -->
  <dimen name="size_spacing_24">24.00dp</dimen><!-- 24px -->
  <dimen name="size_spacing_28">28.00dp</dimen><!-- 28px -->
  <dimen name="size_spacing_32">32.00dp</dimen><!-- 32px -->
  <dimen name="size_spacing_36">36.00dp</dimen><!-- 36px -->
  <!-- … -->
</resources>

IOS

For IOS development, we have IfDesignSystemSpacing.h and IfDesignSystemSpacing.m under src/variables/ios, and IfDesignSystem.swift and IfDesignSystemSpacing.swift under src/variables/ios-swift.

Flutter

We also have ifdesignsystem.dart under src/variables/flutter.

Edit this section

Text alignment

We provide easy to use classes to align text content.

Usage

For left, right, and center alignment on all breakpoints use non responsive classes.

Left aligned text on all breakpoints.

Center aligned text on all breakpoints.

Right aligned text on all breakpoints.

<p class="if u-text-left">Left aligned text on all breakpoints.</p>
<p class="if u-text-center">Center aligned text on all breakpoints.</p>
<p class="if u-text-right">Right aligned text on all breakpoints.</p>

For left, right, and center alignment, responsive classes are available, so the content can be aligned diferently on specific breakpoints.

Left aligned text on breakpoints sized XS or wider.

Center aligned center on breakpoints sized SMLR or wider.

Right aligned center on breakpoints sized SM or wider.

<p class="if u-text-left--xs">Left aligned text on breakpoints sized XS or wider.</p>
<p class="if u-text-center--smlr">Center aligned center on breakpoints sized SMLR or wider.</p>
<p class="if u-text-right--sm">Right aligned center on breakpoints sized SM or wider.</p>

Implementation

<span class="if u-text-left">
  This content is left aligned for all breakpoints.
</span>

<span class="if u-text-center">
  This content is center aligned for all breakpoints.
</span>

<span class="if u-text-right">
  This content is right aligned for all breakpoints.
</span>
<span class="if u-text-left--[xxs|xs|smlr|sm|md|lg|xl|xxl|huge|huger]">
  This content is left aligned from a given breakpoint and up.
</span>

<span class="if u-text-center--[xxs|xs|smlr|sm|md|lg|xl|xxl|huge|huger]">
  This content is center aligned from a given breakpoint and up.
</span>

<span class="if u-text-right--[xxs|xs|smlr|sm|md|lg|xl|xxl|huge|huger]">
  This content is right aligned from a given breakpoint and up.
</span>
Edit this section

Code

JavaScript Library

Utility JavaScript library.

This library is compatible with CommonJS, ESM (ES6 module) and UMD. See documentation examples below.

Install

$ npm install @if-design-system/util-js

Or for Yarn:

$ yarn add @if-design-system/util-js

Features

  • debounce
  • srSpeak
  • addClass
  • trapFocus
  • removeAllOccurencesOfValueInArray
  • formatCurrency

API

trapFocus(element, ctx)

Traps focus in given element.

Param Type Description
element Element Element to trap focus in
ctx Document/ShadowRoot Optional. Defaults to document. Should be any context we can use activeElement with, i.e document or this.shadowRoot
debounce(func, wait, immediate)

Debounces given function.

Param Type Description
func Function Function to debounce
wait Boolean Time in milliseconds to wait
immediate Number Do it immediately
srSpeak(text, [ariaLive, role, ariaRelevant , ariaAtomic] )

Why

In modern web development, updating discrete regions of a screen with JavaScript is common. The use of AJAX responses in modern JavaScript-based User Interfaces allows web developers to create beautiful interfaces similar to Desktop applications that don't require pages to reload or refresh.

JavaScript can create great usability improvements for most users – but when content is updated dynamically, it has the potential to introduce accessibility issues. This is one of the steps you can take to handle that problem.

What

When a portion of a page is updated with JavaScript, the update is usually highlighted with animation and bright colors, and is easy to see. But if you don't have the ability to see the screen, you don't know this has happened, unless the updated region is marked as an ARIA-live region.

If this isn't marked, there's no notification for screen readers. But it's also possible that all the region content will be announced after an update, if the ARIA live region is too large. You want to provide users with just a simple, concise message.

How

That's what srSpeak is meant for. It's a simple tool that creates and appends an ARIA live notifications area to the element where developers can dispatch text messages. Assistive technologies will automatically announce any text change in this area. This ARIA live region has an ARIA role of "status" so it has an implicit aria-live value of polite and an implicit aria-atomic value of true.

This means assistive technologies will notify users of updates but generally do not interrupt the current task, and updates take low priority. If you're creating an application with higher priority updates (such as a notification that their current session is about to expire, for example), then you'll want to create your own method with an aria-live value of assertive.

Let WordPress Speak: New in WordPress 4.2, @joedolson

Param Type Default
text String Text is mandatory
ariaLive String polite
role String log
ariaRelevant String additions
ariaAtomic Boolean false
formatCurrency(number, [locale, options])

Formats a number to a given locale currency with Intl.NumberFormat.

Default options are:

{
  currency: 'SEK',
  currencyDisplay: 'symbol',
  style: 'currency',
  minimumFractionDigits: 0
}
Param Type Default
number Number Number is mandatory
locale String se
options Object {}
addClass(el, className)

A shorthand function to add classes to an element.

Param Type Description
el HTMLElement The element you want to add classes to
className String A string with a class or several classes
removeAllOccurencesOfValueInArray(arr, value)

Removes all occurences of value in Array arr.

Param Type Description
arr Array Array to priune
value Any matchable type Any matchable value
Edit this section

Contact us