Design Tokens

[sarina]

Abstract

Design tokens, a JSON schema, can be thought of as the single source of truth for style values representing various design decisions across the design system (e.g., colors, typography, spacing, etc.), with the idea being that you only need to change the design token value in one place and it propagates out automatically across the platform ecosystem.

Context & Background

A critical component of the Open edX platform is the ability to customize its visual styles to reflect the custom brand of its consumers in the Open edX community. Historically, the Open edX platform has supported a comprehensive theming system fulfilling the community's theming needs, including brand customization and functionality. However, as we've moved towards micro-frontends, the theming system is provided by the Paragon design system. Its current theming implementation has multiple drawbacks, including taking significant time to apply a new theme and not providing a way to theme mobile applications.

See Scaling Paragon's styles architecture with design tokens for more technical background

Scope & Approach

2U, in conjunction with Raccoon Gang, has spent time creating a first (“alpha”) version of this new theming system utilizing design tokens within the Paragon design system. This work needs further development and refinement in order to make it a production-ready system. Much work has been partially developed by the team at RG and simply needs to be completed and merged. After that, one micro-frontend will be updated with the new system, to prove its completeness and viability. Finally, all remaining micro-frontends will be updated, the Tutor build system will be updated so that deployments can make use of Design Tokens, and comprehensive documentation will be provided to the community.

Value & Impact

A revamp of Paragon theming gives us the opportunity to create a scalable way to define style properties that is orders of magnitude faster than the current implementation. One of the long-term visions for the Paragon design system is to be the source of truth for visual styles across the entire Open edX ecosystem. This includes the iOS and Android mobile applications, which currently define and manage their styles (e.g., colors, spacing, etc.) separately from the design system itself even though they share similar design principles.

Milestones and/or Epics

Four main pillars of work:

1. Pillar 1 | paragon - The goal of this piece of work would be to finish the work of making paragon.alpha reach master.

2. Pillar 2 | frontend-platform - This piece is about reviving the PR made by Adam Stankiewicz (frontend-platform/pull/440) and make it land on master.

3. Pillar 3 | mfe upgrades - Each and every MFE that is currently supported in the open release must update it's version of frontend-platform and build again testing that behavior does not break badly. In this scope we would not necessarily aim for a pixel-perfect upgrade but we should minimize the distortion if any.

4. Pillar 4 | tooling for tutor - The new theming must work with tutor; this means at least 3 angles must be covered.

https://docs.google.com/document/d/19w9rixVT_MjxCpWSdnM50r8W8D2DX9EDrQD7negz1w4/edit#heading=h.nl8sszi6b9zi

These milestones will be conducted iteratively. May-June 2024 will focus on Pillars 1 and 2, as well as upgrading one pilot MFE (TBD).

Named Release

Sumac or Teak

Timeline

We expect to have a pilot MFE utilizing Design Tokens by Sumac. We hope to have the whole implementation in Sumac, but since this is a sweeping change to MFE infrastructure, we won't sacrifice correctness or quality for a release deadline.

Proposed By

Axim (others involved include eduNEXT and RG, with 2U having historically kicked off this project)

Additional Info

• GitHub project board
• Design token technical explanation
• Description of 4 pillars of work
• #design-tokens-fc-52 in Slack

Project technical lead (Axim side) @brian-smith-tcril
Project secondary lead (Axim side) @sarina
Project point of contact (eduNEXT) @chris1tapia
Technical leads, past & present: @GlugovGrGlib @PKulkoRaccoonGang @adamstankiewicz

[github-actions]

Thanks for your submission, @openedx/open-edx-project-managers will review shortly.