Overview

Open edX needs shared "reference" design files that serve as a source of truth for active projects. We should establish a process for UX/UI Core Contributors to serve as core design maintainers when collaborating on product and design improvements. This will standardize our design practices, enhance collaboration, eliminate duplicate work, and prevent design and engineering planning mistakes.

Design collateral has maintenance cost, like code repositories. Shared code repositories offer Open edX engineers tools to architect, develop, share, and merge proposed code changes. We are proposing a similar workflow for UX/UI Core Contributors.

Problem

1. Siloed design assets

Currently, Open edX contributors and partners face significant challenges in collaboration due to siloed design assets. Without a centralized, shared repository for design collateral, teams often duplicate work, create inconsistent user experiences, and struggle to maintain design system cohesion across the platform. This fragmentation leads to increased development costs and slower feature delivery. Additionally, the lack of standardized design asset management makes it difficult for new design contributors to effectively participate in the Open edX design ecosystem.

A new designer who wants to propose an improvement to the studio layout might have to recreate the layout from scratch, likely using 2U/EdX-themed rather than Open edX-themed Paragon components, before proposing some variant. This work is currently duplicated across many providers, and shared design collateral would allow Open edX design teams to work more efficiently.

2. Missing design collateral maintenance

There is not currently a designated shared set of design collateral for core product areas such as Studio and the LMS, with open files and shared governance. This issue has surfaced as designers and engineers in the ecosystem consider tradeoffs between default platform theme options, since the lack of shared design collateral makes it more difficult to generate mockups and reference designs to make specific design comparisons between themes.

Use Cases

Key use cases for a shared design collateral system include:

• Partner agencies developing new features can access and contribute to up-to-date design assets, ensuring consistency with platform guidelines

• Design core contributors can implement design system updates across all shared components simultaneously

  • Can include maintainers from multiple groups, not necessarily a single owner/maintainer per file (one per feature, or one owner / many contributors)

  • Engineering core contributors can easily implement and test changes by referencing standardized components and patterns in both design files and code repositories

  • When a design maintainer for an upstream design library file like Paragon updates components, those changes can be published and applied to other design collateral downstream (such as shared course and library authoring design collateral)

• New contributors can quickly onboard by referencing standardized design patterns and components

Experiments So Far

Open EdX Mobile

The Open edX mobile design file has been designed to allow community members across providers to contribute directly and view the current status of all ongoing current and proposed Open edX mobile design work. At Schema, we are using this file to model a cross-organizational open design approach that allows any designer in the community to request edit access to work in their own project page, or make a copy of the entire file for more substantial changes.

We track file versions, archive old designs, and separate in-progress design work from “current” and “proposed” reference screens and workflows. The typical lifecycle for a design project is:

1. A new project page contains early work-in-progress, current reference screens, and anything else useful for the active design team. We provide header, status, and documentation components to allow new designers to get working and stay up-to-date on other project pages.

2. When designs approach completion, after open review at relevant working groups, designers move their final proposed components, screens, and workflows to the “proposed” sections within the relevant page(s) for account, dashboard, course, or sequence-level designs.

3. Designers make updates to reflect any changes as engineers build the new features. Once the features merge, design maintainers (currently Schema) archive the “current” components, screens, and workflows.

Ideally, this means that:

1. Any difference between the “current” screens/workflows and implemented software is either missing design documentation in Figma, or a bug in code.

2. Any difference between “current” screens/workflows and “proposed” screens/workflows is a deliberate, documented change.

Paragon

Ideally, we should have one shared up-to-date Paragon file with the current Open edX theme, to serve as a shared source of truth, and it should be maintained in sync with the React components maintained by the frontend and Paragon WGs. Currently, the Paragon file is owned by 2U/edX, it does not seem to be fully maintained, and it only shows the 2U/edX theme.

At Schema, we have done some experiments to assess the feasibility of “forking” the 2U-maintained Paragon Figma file, and the UX/UI WG discussed the possibility of handing off design maintainership to some existing organization (something designers at 2U have expressed interest in). At this time, we believe it would be feasible to gradually make improvements to bring the Paragon Figma library in line with the Open edX theme, but it will require a significant initial effort and potentially additional resourcing.

Shared Library and Course Authoring Collateral

As part of this proposal, Schema is now building and sharing a single cohesive Figma file usable as a library with authoring components, screens, and workflows. This shared authoring collateral is usable already, and we will continue to build improvements to content libraries and course authoring in the open. We would love additional collaboration, feedback, and especially any suggestions for managing current/proposed components/screens/workflows for such a complex product and project file.

Supporting Market Data

Inconsistencies between design systems and siloed project files have caused engineering issues and increased complexity for implementers, who have to distinguish between deliberate product changes and design happenstance. This issue is especially clear for complex projects like the new Content Libraries implementation.

Last year, as the new Content Libraries sidebar was implemented, the product and design team shared reference designs and mockups built using Paragon components: Library Components: Component sidebar · Issue #1045 · openedx/frontend-app-authoring . Several times in implementation between that early stage and now, mockups built using the only existing Paragon design collateral have caused issues at handoff.

Open

As one small example, consider this mockup, which was built using components from the current (formerly 2U/edX-maintained) Paragon collateral. An engineer implementing this design has to consider that:

1. The sharp-cornered buttons in the sidebar are not a deliberate design decision, and that the default Open edX-themed Paragon buttons should be used instead.

2. The colors selected for all buttons, dropdowns, and search boxes are largely not deliberate design decisions, and that the default Open edX-themed Paragon controls should be used instead.

3. The colors selected for icon buttons within each component card are deliberate design decisions, which diverge from Paragon, and are chosen to match the color-coding while maintaining WCAG 2.2 compliance.

4. The Library Info and Add Content buttons include some deliberate design changes that are intended to be implemented, such as the sharp corners and sizing.

Tracking these differences requires designers and product managers to hand off extremely specific details that are not specifically relevant to product improvements. Engineers have to maintain a clear model of the 2U/edX theme vs. the Open edX theme for Paragon, note differences between the design collateral and the 2U/edX theme, and refer to spec or communicate to clarify points of confusion.

While some mixup in design handoff is inevitable, these four specific issues led to misunderstandings during the design/engineering handoff that would have been avoided if designs could be built using Paragon design collateral matching the true implemented designs.

Discovery Approach

• Modeling initial maintainer approach on Core Contributor software maintainer model

• Discussions at UX/UI WG

• Gathering best practices from community members

• Experimenting with improved process documentation for course/libraries authoring designs

Remaining Questions

• Licensing: Figma is working on improved licensing approaches to offer open-source / cross-company projects ways of working together. We will need to figure out a shared software licensing approach to move forward.

• Resourcing: maintaining shared design collateral may require additional resourcing, and/or a model for UX/UI core contributor time to support design maintenance.

• Shared governance: similar to open-source contribution and maintenance models, designers will need to solve for shared-governance questions. File access, permissions, and decision-making around when and whether to merge proposed improvements should be managed openly through the UX/UI WG and other working groups.

• Handoff and source-of-truth: design-focused working groups will need to collaborate closely with the Paragon, frontend, and other working groups to ensure that design collateral continues to be a source of truth. This may require additional handoff practices and cross-working-group collaboration to ensure changes are followed-through.

• Product-side shared tracking / aligning design collateral to planned product priorities across different providers.

• Documentation/onboarding: how to introduce new users to component structure / maintenance and contribution process. Could include added collaboration with the Paragon WG.

Next Steps

As a result of this proposal we would like to propose some next steps:

Completed Next Steps

• share with relevant working groups (Paragon, maybe frontend-engineering)

• develop a design maintainership model

• request the creation of an Axim-owned Open edX Figma instance so that files can be owned centrally, even if maintained and managed by providers

• enumerate the first 3-5 areas of the platform that have shared community interest

  • for now: mobile and libraries/course authoring (Schema maintaining), Paragon (not yet underway)

Remaining Next Steps

• Stage 1: Request UX/UI WG community members help determine a process to designate certain platform areas to have a source of truth file

  • Consider a shared directory on some platform (Confluence? GitHub? Notion? Google Doc?) for community to track status and maintainership of these files

  • Model process with initial design collateral, draft rules for inclusion/maintainership/ownership/archiving process

  • Pending designated Figma instance process or updates to Figma licensing model, likely owned by community members for now, process for approving changes

• Stage 2: templates and patterns at Figma level that encourage collaboration, communication, improved ways of working together etc.

• Stage 3: Design maintainership developed by key contributors

• Stage 3.5: Potentially begin archiving designated file versions

• Stage 4: Consider shared Figma instance / alternate Figma licensing models