Skip to main content

Developing a component

Allium is a community supported designed system and all developers in the TELUS community are encouraged to contribute components. There are two Allium libraries that teams can choose to contribute to. Both libraries are open for community contribution, though we envision that most components that are contributed by the community will begin their life in @telus-uds/ds-allium-community.

@telus-uds/ds-allium​

TELUS' core component library for the Allium Design System. These components are:

  • highly reusable for teams across the organization
  • should have a relatively stable API
  • actively maintained and supported by the Allium team

@telus-uds/ds-allium-community​

TELUS' community component library for the Allium Design System. These components are:

  • reusable by teams across the organization
  • may see regular API changes
  • maintained and supported by the community
info

Before you begin

How to develop a component​

Set up your local development environment​

Before you can build a new component you will need to set up your local development environment and get oriented to the Allium monorepo. Check out this guide to learn everything you need to know to begin working in the Allium monorepo.

Scaffold your component​

We provide easy scripts to generate the basic scaffolding of a component. From the root directory of the monorepo, you can run one of the two following scripts with the name of your component passed as the only argument.

# scaffold core component
yarn create-component:ds-allium ComponentName

# scaffold community component
yarn create-component:ds-allium-community ComponentName

These scripts will:

  • Add a component folder with a component .jsx file and an index file to export it
  • Add test folder and file with a sample test
  • Add a Storybook file with a default story of your component
  • Add a component documentation .mdx file
  • Update the main package index to export your component

Build Your Component​

It's now time to start coding! You can build your component as you would any react component, but there are a few things to keep in mind.

Styling​

Use styled-components for styling your component. Keep in mind that you should import styles that are defined in the palette instead of hardcoding them.

import palette from '@telus-uds/palette-allium/build/web/palette'
import styled from 'styled-components'

const {
  size: { size4, size8 },
  color: { purpleEminence },
  radius: { radius4 }
} = palette

const Container = styled.div`
  display: flex;
  justify-content: center;
  background: ${purpleEminence};
  padding: ${size4} ${size8};
  border-radius: ${radius4};
`

Component composition​

As much as possible your component should be composed of the existing UDS base and Allium components. If you're building your component in ds-allium you can import any base component from @telus-uds/components-base. If you're building in ds-allium-community you can import any base or Allium component from @telus-uds/ds-allium.

Component standards​

Check out our guide on component standards to ensure that your component meets all the criteria

Test and document your component​

Write extensive test coverage using @testing-library/react for all behaviour and variants of your component.

Add stories that showcase the different variants of your component.

Use the scaffolded template as a starting point to add complete documentation of your component. Don't forget to add your component to the Community section of the component _sidebar.js menu file.