CSS ComponentThe latest version of this package is: 17.0.30-alpha.0, Opens in new window

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

This component provides .css, .styl, .less and .scss -files.

To be able to install this component, please refer to the Project Setup documentation.

View repository, Opens in new windowView package, Opens in new window
$ npm i @ids-core/utils@17.0.30-alpha.0

Table of Contents

Edit this section, Opens in new window

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, Opens in new window

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, Opens in new window

Hidden

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

Usage

This is hidden from xxs-breakpoint and up This is hidden from xs-breakpoint and up This is hidden from smlr-breakpoint and up This is hidden from sm-breakpoint and up This is hidden from md-breakpoint and up This is hidden from lg-breakpoint and up This is hidden from xl-breakpoint and up This is hidden from xxl-breakpoint and up This is hidden from huge-breakpoint and up This is hidden from huger-breakpoint and up This is hidden from xxs-breakpoint and down This is hidden from xs-breakpoint and down This is hidden from smlr-breakpoint and down This is hidden from sm-breakpoint and down This is hidden from md-breakpoint and down This is hidden from lg-breakpoint and down This is hidden from xl-breakpoint and down This is hidden from xl-breakpoint and down This is hidden from huge-breakpoint and down This is hidden from huger-breakpoint and down 
<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
>

Implementation

Edit this section, Opens in new window

Tokens

All of the tokens can be used as preprocessor variables or as CSS variables! For more information about token usage, view the Design Token documentation or the App development section.

Borders

Name Value
$ids-color-border-1
 rgba(110,98,94,0.2)
$ids-color-border-2
 rgba(110,98,94,0.3)
$ids-color-border-3
 rgba(110,98,94,0.5)
$ids-color-border-base
 rgb(110, 98, 94)
$ids-size-border-1
 0.0625rem
$ids-size-border-2
 0.125rem
$ids-size-border-3
 0.1875rem
$ids-size-border-radius-none
 0
$ids-size-border-radius-sm
 0.25rem
$ids-size-border-radius-md
 0.375rem
$ids-size-border-radius-lg
 0.75rem

Size

These tokens are not meant to be used for gutters, margins or paddings.
Name Value Pixels Example
$ids-size-2 0.125rem 2px
$ids-size-4 0.25rem 4px
$ids-size-8 0.5rem 8px
$ids-size-12 0.75rem 12px
$ids-size-16 1rem 16px
$ids-size-18 1.125rem 18px
$ids-size-20 1.25rem 20px
$ids-size-24 1.5rem 24px
$ids-size-28 1.75rem 28px
$ids-size-32 2rem 32px
$ids-size-36 2.25rem 36px
$ids-size-40 2.5rem 40px
$ids-size-44 2.75rem 44px
$ids-size-48 3rem 48px
$ids-size-52 3.25rem 52px
$ids-size-56 3.5rem 56px
$ids-size-60 3.75rem 60px
$ids-size-64 4rem 64px
$ids-size-68 4.25rem 68px
$ids-size-72 4.5rem 72px
$ids-size-76 4.75rem 76px
$ids-size-80 5rem 80px
$ids-size-84 5.25rem 84px
$ids-size-88 5.5rem 88px
$ids-size-92 5.75rem 92px
$ids-size-96 6rem 96px
$ids-size-100 6.25rem 100px
$ids-size-104 6.5rem 104px
$ids-size-120 7.5rem 120px

Spacing

These tokens are only used for gutters,margins and paddings.
Name Value Pixels Example
$ids-size-spacing-2 0.125rem 2px
$ids-size-spacing-4 0.25rem 4px
$ids-size-spacing-8 0.5rem 8px
$ids-size-spacing-12 0.75rem 12px
$ids-size-spacing-16 1rem 16px
$ids-size-spacing-18 1.125rem 18px
$ids-size-spacing-24 1.5rem 24px
$ids-size-spacing-32 2rem 32px
$ids-size-spacing-40 2.5rem 40px
$ids-size-spacing-48 3rem 48px
$ids-size-spacing-56 3.5rem 56px
$ids-size-spacing-64 4rem 64px
$ids-size-spacing-88 5.5rem 88px
$ids-size-spacing-120 7.5rem 120px
$ids-size-spacing-largest 5.5rem 88px
$ids-size-spacing-larger 4rem 64px
$ids-size-spacing-large 2.5rem 40px
$ids-size-spacing-default 2rem 32px
$ids-size-spacing-small 1.5rem 24px
$ids-size-spacing-smaller 1rem 16px
$ids-size-spacing-smallest 0.75rem 12px
$ids-size-spacing-xs 0.5rem 8px
$ids-size-spacing-xxs 0.25rem 4px
$ids-size-spacing-xxxs 0.125rem 2px

Z-index

Name Value Description
$ids-depth-z-index-deep -999999 Deep z-index is used to stack something behind everything else.
$ids-depth-z-index-default 1 The default z-index for components and elements inside components.
$ids-depth-z-index-masked 100 Default z-index for elements that are beeing masked.
$ids-depth-z-index-mask 200 Default z-index for elements that are used as a mask.
$ids-depth-z-index-sticky 300 Default z-index for sticky interface elements.
$ids-depth-z-index-global-header 400 Default z-index for the Global Header.
$ids-depth-z-index-toast 500 Default z-index for toast messages.
$ids-depth-z-index-dropdown 600 Default z-index for dropdowns which makes sure the dropdown stacks above toasts and sticky elements.
$ids-depth-z-index-overlay 700 Default z-index for modal and popup overlays.
$ids-depth-z-index-loader 800 Default z-index for loaders, stacking on top of overlay.
$ids-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.
$ids-depth-z-index-popover 950 Default z-index for popover that stacks on top of all other elements.

Opacity

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

Box shadow

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

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: @ids-core/utils/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 '@ids-core/utils/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: @ids-core/utils/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, Opens in new window

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, Opens in new window

Code

JavaScript Library

Utility JavaScript library.

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

Install

$ npm install @ids-core/util-js

Or for Yarn:

$ yarn add @ids-core/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, Opens in new window

Changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

14.22.2 (2022-05-03)

Miscellaneous chores

  • package locks: update package locks (813eac7)

14.20.1 (2022-04-19)

Features

  • 🎸 Add more mixins for borders (387121b)

Miscellaneous chores

  • changelog: regenerate all CHANGELOG.md files (64ab385) , closes #586342
  • changelog: regenerate all changelogs after updating changelog generation (70789c9) , closes #587270

14.19.0 (2022-04-13)

Documentation Updates

  • ✏️ Update documentation elements to prepare for Dark Mode (7b0b859) . We are utilizing some of the IDS components when documenting our components, and these elements needed to be updated with the .ids-doc CSS flag so we can add themes to them. In the same change, we also ammended some of the documentation to be more up to speed with current state.

14.18.3 (2022-04-13)

Bug Fixes

  • changelog: generate new CHANGELOG.md files for root and packages (349fda4) , closes #586063 . We regenerate the files to include all relevant commits and to use conventional-commits at 100%

14.16.0 (2022-04-07)

Bug Fixes

  • 🐛 Add missing imports for global CSS Variables (fbf6f06) , closes #582437

Code Refactoring

  • 💡 Add aliases for smaller spacings (7997f7c)

14.14.0 (2022-04-07)

Bug Fixes

  • Set opacity when overlay is open (f9d77a3)

14.13.0 (2022-04-06)

Bug Fixes

  • 🐛 Encode data-value in design token documentation (85737c6)

14.9.0 (2022-03-03)

Miscellaneous chores

14.8.0 (2022-02-21)

Code Refactoring

  • Use css vars for focus mixin (6a5994c)

reinstall (d425056)

14.7.1 (2022-02-18)

Code Refactoring

  • use CSS vars for focus mixins (17bf158)

bootstrap (9a713df)

merge (2b1c5f1)

reinstall (5221600)

14.5.0 (2022-02-15)

Code Refactoring

14.4.0 (2022-02-11)

Bug Fixes

  • Make sure CSS variables are imported separately (507ad37)

Code Refactoring

  • Include CSS vars correctly from css inside preprocessor files (abd2bdd)

reinstall (147df55)

14.3.0 (2022-02-09)

Features

  • 🎸 Add abstract spacing tokens (3d66013)

  • 🎸 Add new design token structure, add border tokens (19c1a05)

  • 🎸 Automatically generate abstract spacing helpers (83ee2ab)

  • Add mixin for position sticky (a4a5646)

Bug Fixes

  • 🐛 Fix correct token references (20898f3)

  • 🐛 Fix token generation (9eae801)

  • 🐛 Fix token generation (6b351f7)

  • Generate px when we say we generate px (4ec7a85)

  • Use correct value for pixel tokens (6f645cd)

Code Refactoring

  • 💡 Move utils specific transforms to utils (8bd7adc)

  • 💡 Split mixins to more manageable pieces (6c16f86)

  • 💡 Use a global transform instead of local (5867490)

  • Get rid of unneeded global tranforms (0f6f2fd)

  • Let CSS variables be included via variables (b4d6e08)

  • Move helper template string outside of loop (9c959ed)

  • Use CSS variables instead of preprocessor variables (f991663)

Miscellaneous chores

  • 🤖 And include the helper files (3769c4d)

  • 🤖 Update comments for masked/mask element z-index (b8d1f89)

  • Add engines for all packages (e95dfff)

build (23cabca)

reinstall (afce1f2)

reinstall (67f3140)

Reinstall (a2abf51)

14.2.2 (2021-12-10)

Code Refactoring

  • 💡 Change focus styles, remove whatinput (75fd31b) , closes #505205

  • Add vars for focus border (44c1a94)

  • Separate out focus mixins (e7dd09a)

14.2.0 (2021-12-08)

Code Refactoring

  • 💡 Use 0.0625rem instead of 1pt (ba9a21c)

  • rebuild and reinstall (f9fb687)

reinstall (885c74b)

  • fix changelogs manually (b1232b4)

reinstall (545a069)

reinstall (e149c2c)

13.12.3 (2021-11-09)

⚠ BREAKING CHANGES

  • 🧨 The scope for If Design System npm packages has now changed from @if-design-system to @ids-core. We have also renamed the repository from if-design-system to ids-core

Bug Fixes

  • Fix token generation issue (e13ce35)

Documentation Updates

  • ✏️ Adjust documentation (8e77c36)

  • move spacing guidelines to core package (d5f215d)

Code Refactoring

  • 💡 Rename scope and repository (3ea5423)

  • fix all old references to util (d57bf17)

  • Install missing prettier (e229f7a)

reinstall (1caf5ef)

Edit this section, Opens in new window
Contact us, Opens in new window