TGAM Pattern Library Documentation

Introduction

This website documents how to work with the Globe and Mail’s UI pattern library, which serves as the “single source of truth” for how our brand is represented across all of our digital properties. It’s purpose is as follows:

Distributing and synchronizing our UI component code

All of our UI component code (CSS, JavaScript, HTML, fonts, images, etc.) is housed within the pattern library codebase, and we distribute it via NPM. Outside projects are then able to import it as a dependency. The advantages of this are twofold:

1. NPM’s semantic versioning allows us to keep our code synchronized across all of the products that consume it, while also allowing each product to upgrade at its own pace. When a new version of the pattern library code is released, products are able to upgrade immediately, or continue using an older version for as long as they require.
2. Product developers are unable to edit the code directly, from within their own codebases (because it’s housed inside the node_modules directory). This safeguards against “code rot”, which inevitably occurs when multiple developers start with the same code, copy it into their respective projects, then alter it for their own purposes until each copy becomes unrecognizable from the another. This divergent code leads to visual inconsistencies between products and makes it increasingly difficult to maintain a common set of user interface components. Instead of “forking” the code like this, distributing it via NPM encourages developers to collaborate with other teams in order to craft and refine a single set of UI components that can be shared across the entire organization.

Documenting and showcasing our UI components in action

The pattern library codebase uses an application called Panther to transform our UI component code into a static website. This website provides a place for us to document, organize and showcase our user interface design patterns in action, in the form of “living” HTML components. Designers, developers and other stakeholders can huddle around the website to discuss ideas, play with existing components and test out experimental components before integrating them into their products. Documenting our design system in this manner encourages us to establish a shared vocabulary across the organization and fosters interdisciplinary collaboration.

Throughout this documentation, we’ll be referring to this generated website as our “pattern library website”.