[ARCHIVE] Transforming Paragon into a Design System

This page and all its children are old. They are preserved here for historical context





@Adam Butterworth (Deactivated) @Eugene Kang @Gabriel Weinberg

@Lael Birch (Deactivated) @Sree Lenhart (Deactivated) @Marco Morales (Deactivated) @Ange Romanska (Deactivated) @Adam Stankiewicz @Alasdair Swan (Deactivated) @Ben Warzeski (Deactivated) @Jeff Witt (Deactivated)



Create a design system that provides cross-functional product delivery teams the tools they need to build high-quality user interfaces faster.


[Approach] Developing Paragon into a design system


Design System Kickoff

Key outcomes

  • edX products that use Paragon feel more usable, more consistent and more pleasurable to use for customers.

  • Squads launch features more quickly by leveraging an ever growing library of common design patterns and React components.

  • Engineers and designers are able to contribute to Paragon with ease.


in progress


Problem Statement

Paragon contains too few components and is under-documented. Due to a lack of design and technical documentation, teams struggle to expand the library and often create bespoke UI components in their projects. Due to a lack of contributions over time, Paragon UI components don’t reflect the visual quality we expect from edX as a brand.

We believe that an investment to reinvigorate and transform Paragon into a design system will improve its usefulness of Paragon for squads creating new features. We’ll know we’ve succeeded when engineers and designer using Paragon report higher satisfaction with the library and squads qualitatively believe that Paragon is increasing their team velocity.

Key Questions (TBD Metrics)

  1. How will we know if new components are enabling teams to create more usable and beautiful user experiences? (https://openedx.atlassian.net/browse/PAR-60 )

  2. How will we know if we’re increasing the velocity of cross-functional teams?

Jira Roadmap

See also: UX - Paragon (PAR) Kanban Board




This work is planned in roughly four phases. Extra milestones have been added to help this work aid rebranding efforts.





Phase 1: Create new design patterns.

Define new design patterns using the new visual identity and brand. This phase contains 1A and 1B in order to aid with low effort re-theming for rebrand efforts.


Week ending Jul 31, 2020

Week ending Sep 4, 2020

Week ending Sep 11, 2020

Week ending Sep 18, 2020 => Sep 22, 2020

  • Sep 15, 2020 => Sep 20, 2020 Brand Identity Delivered

Week ending Sep 29, 2020 No review this week.

Week ending Oct 6, 2020

  • Finalize

Phase 2: Update base SCSS to reflect the new design patterns

Create a new edX SCSS theme to reflect the design source of truth for existing patterns. Publish a new version of Paragon containing the new theme with a migration path.


Rebranding specific efforts in phase 2:


Phase 3: Implement new patterns in React library

Update existing components in the React library to match new design patterns and expand the library to include all new ones. Publish new versions of Paragon iteratively.



Phase 4: Improve our processes and workflows

Identify barriers in contributing to Paragon and find ways to remove them. Create onboarding material for designers and developers and evangelize design patterns throughout edX.


Reference materials