Skip to main content

Beginner's guide for developers

Welcome to the developer documentation for Allium Design System! This guide will help you get set up to create great customer experiences with Allium.

Using Allium​

Prerequisites​

  • Node 14 minimum support We test all UDS and Allium code against node v14 and v16 only. If you are currently using Node v12 we strongly recommend you upgrade anyway, as it will soon be out of maintenance
  • React 17 Allium is only compatible with React 17. TDS is compatible with both 16 and 17 so we suggest you upgrade to 17 first, and then upgrade to UDS afterwards
  • React Router v5 or above Allium Link components are only tested with React Router v5 and v6. If you are using an older version of React Router it is likely you will still be able to use Allium, but we won't be able to offer the same level of support.
  • Browser support is defined by our browserslist config (learn more about browserslist here). This package is also published to npm and teams are encouraged to reuse this config when building with UDS and Allium. Note that this means No IE 11 support. IE 11 officially reaches end-of-life on June 15 2022.
  • Compilers, Transpilers, and Bundlers We use ES2020 in our source code and in transpiled modules. This works fine with all modern transpilers and bundlers (e.g swc, babel). However older tooling which relies on acorn v6 (for example webpack v4) won't work out of the box with Allium. If you are using an older bundler, we recommend upgrading your tooling before upgrading to use Allium. If that is not an option, you may need to transpile @telus-uds-scoped packages using something like babel-loader, and set a target that matches the ECMAScript version supported by your tooling. Feel free to reach out to the Allium team if you need any help with this.

Installing​

Allium is distributed as a single component library. You can install it using npm:

npm i @telus-uds/ds-allium
info

If you are using yarn or npm v6 or below, you will need to manually install peer dependencies as well:

yarn add @telus-uds/ds-allium @telus-uds/palette-allium react-native-web styled-components

Usage​

All Allium components are exported as named exports from root. Allium components must be wrapped in an AlliumProvider. We recommend you include the Allium provider just once at the root of your application (e.g. in App.jsx).

import { AlliumProvider, Button } from '@telus-uds/ds-allium'
...
  <AlliumProvider>
    ...
    <Button onPress={() => {}}>Hello World!</Button>
    ...
  </AlliumProvider>
...

Using the library with React Native​

If you are targeting multi-platform with Expo and/or React Native, you can still use the same package, but keep in mind that only multi-platform components will be available in this case.

Another important thing to remember is that in addition to the peer dependencies mentioned above, you'll also have to install react-native-svg:

yarn add react-native-svg

The rest is essentially the same as on web: all you need is to have your Allium components wrapped in AlliumProvider.

Assets​

Font and icon assets are distributed as part of the Allium palette via the @telus-uds/palette-allium package. This package leverages style-dictionary to build distributions specific to a platform or technology. There are both web (web) and React Native (rn) distributions, in general you should use the one that matches your target platform/technology.

Fonts​

If you're building a react web application we recommend you use the CDN font distribution. @telus-uds/palette-allium provides a css snippet to load these fonts for use with Allium, assuming you have a css loader set up for your project you can simply include the following snippet:

import '@telus-uds/palette-allium/build/web/fonts/fonts-cdn.css'
caution

If you are using the Isomorphic Starter Kit and handle your styling via Styled Components, you may experience some issues with the aforementioned method. In this case, you may need to load the fonts with Styled Components' createGlobalStyle helper:

import { createGlobalStyle } from 'styled-components'
import * as alliumFonts from '@telus-uds/palette-allium/build/web/fonts/fonts-cdn.css'

...

createGlobalStyle(`
  ...
  ${alliumFonts}
  ...
`)

You can find out more about how fonts are handled in UDS in the UDS docs.

Icons​

Icon SVGs are made available as React components via the palette.

import { Award } from '@telus-uds/palette-allium/build/web/icons'

Icons usage is documented in more detail in the Icon component documentation.

Where to get help​

We have a dedicated Help & Support page, so you should find everything you need over there.

Get involved​

Allium (and UDS as a whole) is intended to be a community-driven project. It’s success depends on your contribution. We need your help!

Please get in touch if you’d like to discuss anything to do with design systems at TELUS, problems you are facing or suggestions to help make things better.