Skip to main content

Developer's guide to contributing to Allium

Allium is a community supported design system and all developers in the TELUS community are encouraged to contribute features, bug fixes and components. This guide covers everything you need to know to begin working in the Allium monorepo.

info

Before you begin

Set up your local development environment​

Start by cloning the repo and installing the required dependencies. At the moment we use yarn as our package manager instead of npm but this may change in the near future.

# clone the repo
git clone git@github.com:telus/allium-design-system.git

# cd into it
cd allium-design-system

# install dependencies
yarn

Get oriented​

The Allium monorepo is currently made up of five packages. With the exception of docs-allium, all packages are distributed publicly on NPM with the @telus-uds/ prefix.

─ packages
    ├── palette-allium      # Allium design token palette
    ├── theme-allium        # Allium theme for UDS Base Components
    ├── ds-allium           # Allium core component library
    ├── ds-allium-community # Allium community component library
    └── docs-allium         # Allium documentation site

palette-allium​

This package exports a json file of design token that represents the smallest, most atomic design decisions that make up the TELUS brand.

theme-allium​

This package dictates the rules that apply the tokens from the palette to the UDS Base Components.

ds-allium​

This package contains the core components that are built specifically for the Allium brand. It uses the palette to ensure that styling decisions in the component library adhere to TELUS' brand standards. This package also imports and re-exports all UDS Base Components so that it can act as a single point of entry for all developers building with Allium.

ds-allium-community​

This package is similar to ds-allium but is limited to components that are maintained exclusively by the community.

docs-allium​

This is our documentation website. It uses docusaurus to convert the .md and .mdx files located inside the package into a static website.

Start your local dev tools​

Because the different packages are tightly coupled to each other, we need to watch for code changes in the various packages and rebuild local versions of the distributions so that other packages can consume these changes.

You can use storybook as a tool for viewing, editing, and building components in isolation in your local environment.

You can also spin up a local version of the documentation site to help make changes to the docs.

To do all this, run the following scripts from the monorepo's root directory in separate terminal windows and keep them running while you make your changes.

# watch for changes and rebuild packages
yarn dev

# run storybook
yarn storybook

# run documentation site
yarn docs

Create a local branch and make your changes​

Create a local development branch off of main to make your changes and commit them. Before you push your branch up for review, you need to add change files that describe your changes and inform what semantic versioning bump they require. There's a helpful CLI that will automatically create these files for you and commit them to your branch.

yarn change

Submit a PR​

After pushing up your local branch, submit a PR to the main branch of the allium-design-system repo on GitHub and wait for a member of the Allium team or a trusted reviewer to approve your request.

Note that packages are not automatically published to npm after your PR is merged. Releases are triggered manually by the Allium team, so get in touch with us if you would like to expedite a new release.