Skip to main content

Contribute a component

Allium contains a collection of components and patterns that express the TELUS brand. Components are reusable, visual, and functional building blocks. They help create consistent experiences, across our digital products and applications.

Our teams design and code each component to solve specific interactions or UI needs. They're designed to work seamlessly with other components. And you can assemble them in various combinations for a cohesive experience.

The effort to contribute depends on the complexity of the component and availability. It's important to collaborate so that the community can benefit from the efforts of a few. We encourage everyone to contribute what they can, when they can, and in whatever way they can.

  1. Before you contribute
  2. Prepare your component contribution
  3. Follow the contribution process

Before you start​

Before you design new components, add new features, and create patterns, keep in mind the following pre-flight activities:

  1. Learn the designer and developer standards
  2. Communicate early
  3. Collaborate openly

Learn the designer and developer standards​

Communicate early​

  • Avoid duplicate effort and similar features
    • Make sure to check the backlog to see that your request doesn't already exist
    • If it does exist, it may introduce new concepts for consideration or add yours to the conversation
  • Start a conversation
  • Get feedback early and often

Collaborate in the open​

  • Avoid working too deep without taking into account other considerations and use cases
    • Sometimes re-work can create complexity and delays
  • Working openly helps make sure that you're supported throughout the process
    • Others can get context and help pick up the work when needed
    • Others can contribute to solutions, help with designs and code
    • Others can provide additional or missing context on previous or similar efforts
  • Different roles can add their perspective
    • Designers can see how their own product can benefit from your proposal
    • Developers can provide guidance on implementation and identify constraints to watch out for
    • Content practitioners can advise on meaningful content hierarchy and reading order
    • Everyone can recommend accessiblity and usability improvements

Anatomy of a component contribution​

There are typically 5 distinct parts to a component contribution: rationale, design specifications, Figma component, code component, and component documentation. Each area may include a description or link to other resources. Some components are more complex than others and may need more supporting content.

info

When the contribution process begins, you may not have all these completed or even started. And that's okay. As the component moves through each phase of the contribution process, you'll get more feedback and support to complete the necessary parts of the component contribution. Adding as much content and assets will help complete the component documentation which is important for everyone to begin using the new component.

  1. Rationale
  2. Design specifications
  3. Figma component
  4. Code component
  5. Component documentation

Rationale​

  • Explain what the component does
  • What does it do?
  • How does it work?
  • What problem is it trying to solve?

Design specifications​

  • Provide designs, assets, and prototypes that will help a developer code the component
  • Include sizing and styling, and accessibility annotations
  • Use the appropriate Allium typography, size, colour, layer, and shadow styles as they map to design tokens
  • Describe expected user interface interactions
  • Include states, variants, and responsive examples

Figma component​

  • Provide a link to the Figma component
  • New or enhancements to components can be designed in your Figma file and moved to the appropriate library for publishing
  • Depending on the component it may need to be added to different libraries
    • Core component will need a maintainer to add to the Allium component library
    • Community components can be added to the Allium community component library
    • Product-specific components can be published through their team-specific component library
  • Follow the icon contribution process, it must be added to the Allium icon library by a maintainer

Code component​

  • The component must be functionally complete
  • Features, state, variants and screen sizes tested and confirmed complete on web
  • Accessibility tested on a range of devices (including but not limited to):
    • Resized text
    • Screen zoom
    • Reduced motion
    • Touch screens
    • Keyboard navigation
    • Screen readers
    • Learn more about our accessibility requirements
  • Unit tests (covering as many cases as reasonably possible)

Check out our guide to developing a component.

Component documentation​

  • Component API
  • Usage guidelines
  • Examples of each variant
  • Limitations (if any)
  • Security implications (if any)
  • Accessiblity guidelines and implementation
  • Usability and content guidelines

Component contribution process​

info

We're currently working to update our community practice and processes. Have a look at our component flow diagrams in Miro. Please share your feedback with comments in Miro or message us in the #dpa-community Slack channel.

There are many paths to component contribution. It depends on what you want to contribute, who is contributing, and which library the component will stay. We recommend that you involve the Allium community as early as you can so that you can get the right kind of help throughout the process.

Use this process if you are:

  • Creating or updating a component for a domain library
  • Creating or updating a component for Allium core or community library
  • Creating a component or a block for Site Builder

The following describes the typical steps of a component contribution:

  1. Propose a new component or update to an existing component
    • Submit a Github issue
    • Open a discussion in #dpa-community
    • Present in a DPA community Wednesday meeting
  2. Review with the community
    • Review with art direction, accessibility, and DPA community
    • Apply changes as necessary
  3. Create the component
    • Code the new component or enhancement
    • Design the Figma component
    • Write the documentation
  4. Publish the component
    • Domain library (product-specific library such as Home Solutions, Mobility)
      • Maintained by product teams (only product team members can accept PRs)
      • Components with very specific use-case
      • Figma component published in product team's library
    • Allium community library
      • Maintained by the Allium team and DPA (only team members and trusted committers can accept PRs)
      • Component functionality is reusable for different products
      • Figma component published in community library
    • Allium core library
      • Maintaned by the Allium team (only team members can accept PRs)
      • Limited to basic components for maximum reusability
      • Figma component published in Allium library by Allium team member
  5. Create a Site Builder block
    • Import components from domain library, community, or core library
info

We highly recommend to follow this process when creating Site Builder components or blocks. Publish components in a product-specific library, Allium community or core library before creating a component or block in Site Builder.

Benefits:

  • Use existing channels and touchpoints for reviews
  • Make sure designs are aligned with art direction and accessibility
  • Create awareness of components and blocks available in Site Builder
  • Maximize reusability
  • Improve maintenance (updates to components in their respective library can then be imported in Site Builder)
  • Mitigate duplicate work or re-work (takes more manual effort to audit custom Site Builder blocks)