Skip to main content

Overriding Styles

The architecture that enables the theming of most Allium components also makes it relatively easy to customize their styling. The UDS Base components are built independently of specific styling decisions. Instead, their look and feel is defined by a series of design tokens that are made available to the components by a theme provider. As such, it is possible to pass alternative tokens to a component to modify its visual styling.

Disclaimer​

Just because it is technically possible to change the styling of a component doesn't mean that you should. Deviating from the default styling likely means that your implementation of the component is no longer in line with TELUS' brand standards. This should only be done as a conscious decision by both designers and developers to support a niche use-case or requirement.

As a developer, if you are provided designs that are not achievable within the constraints of the default styling of a component, consider the following before proceeding to override those styles:

  • Are you misinterpreting the designs? In trying to follow the designs as closely as possible you may be misconstruing the intentions of the designer. Remember that pixel perfect design is not fully achievable when building for responsive devices. The sizing and spacing of component may not align exactly with how you see it in the designs depending on the size of your device's viewport.
  • Have you confirmed with the designer that they intended to deviate from the default styling? Designers can make mistakes. They may have accidentally modified a component in Figma, or used a mobile version of a component in a desktop design. Communicate to them that their designs are not possible with the default styling and ensure that this was their intention.
  • Can other teams benefit from this customization? If you think that this variation of a component would be beneficial for other teams, propose a new variant so that others can use it in their applications.
danger

After reading the above, are you sure that overriding styles is necessary, and won't cause your product to be flagged as off-brand?

If unsure, you can check your designs and intended overrides by presenting them to DPA.

How to modify the styling of a UDS Base Component​

All UDS Base components feature a tokens prop. This prop accepts an object of design tokens that will override the tokens which are defined in the Allium theme. You can find a list of every token that a component accepts on their documentation page.

Here's an example of how to override a specific token. You can change the background color of a button by passing a new colour value to backgroundColor.

<Button tokens={{ backgroundColor: '#0000FF' }}>Click me</Button>

Generally speaking, you should not hardcode a specific colour like this. Instead, ensure that your customizations are informed by the Allium palette. Import the palette and use an approved brand colour.

import palette from '@telus-uds/palette-allium'

...

<Button tokens={{ backgroundColor: palette.color.amber }}>Click me</Button>