This document is a work in progress!!! Attempting to create a comprehensive guide that can be used for orienting developers new to edX or new to frontend development.

This handbook is meant to provide an overview of how we develop frontend features at edX. We’ll guide you through our four main phases of frontend development and provide checklists, tips, and tutorials in areas that you should aim to strengthen your skills in over time.

Pre-Development

What is pre-development? Pre-development is everything that goes on before you start coding. The things that happen in pre-development are mostly out of your hands, but as an engineer, there are things you should be aware of to make the development process more smooth.

The two main pieces of pre-development are product definition and design. In product definition, your Product Manager will define what is to be built (along with why/when/how). In product design, your Designer will provide a feature mockup through Figma. This is where your awareness as an engineer is important.

Pre-development checklist

When you’re given a mockup by a Designer, consider the items in the following checklist. If anything is missing, you’ll want to ask your Designer for clarity before starting development.

Were you given a Figma mock by a Designer?

All designs should come from the Design Team to maintain consistency across our platform.
All designs should use Figma in order to take advantage of our design system components and styling classes.

Were you provided a mobile mockup?

Is it clear how the design should change based on different screen sizes?

Was the mockup/feature discussed with Jeff Witt, our Accessibility Specialist, for feedback?

Do clickable items have the correct states defined?

If a design introduces a new clickable item that is not yet captured in Paragon, you should seek to understand what the design of the component is for the component’s focus state, hover state, active state, etc.

Were you provided the necessary microcopy for accessibility?

If your design includes images, links, or buttons, use this guide (Accessible microcopy in images, links, and buttons) to determine whether you’ll need to use alt text. If so, ask your Designer for their input on this microcopy.

Will any part of the design include a Paragon contribution?

It is important to clarify which elements of the design already exist in Paragon.
- If a component exists in Paragon, consider whether it needs to be updated to match the mock.
- If a component doesn’t exist in Paragon, consider whether it needs to be created and proposed to the Paragon Working Group.
- We also source all of our icons from Paragon! Make sure to check if your design is using any new icons that will need to be added to Paragon.
At this point you may be asking yourself, “What is Paragon?” Great question! We’ll describe what Paragon is, along with how Figma and Paragon work together in the following sections.

If you are an engineer in the Open edX community, you may be your own product manager and/or designer! While it isn’t necessary to use Figma when designing a new feature, consider how what you build fits into the Open edX design system. Additionally, ensure that you are following web accessibility guidelines. edX currently adheres to WCAG 2.2 AA standards.

This list is a starting point to make sure you have what you need to effectively develop your feature. We encourage you to collaborate with a Designer in answering these questions as early in the process as possible. If you can think of more common questions, please add to the checklist above.

What is Paragon?

Paragon is our open-source component library that reflects our design system. Using components (and other styling elements) from Paragon allows us to maintain consistency across our different platforms.

If you’re familiar with Bootstrap, Material UI, Semantic UI, or similar UI frameworks, you’ll get the hang of Paragon in no time! Paragon is comprised of components and styling utility classes that are based on React-Bootstrap (React Bootstrap | React Bootstrap ) under the hood.

Additionally, Paragon is a theme-ready library, so anyone using the library is able to override the default colors and typography with their own theme. We do this at edX to override the Open edX styling with our own branding through GitHub - edx/brand-edx.org, but we’ll get into the specifics of this in the Deploy section of this handbook.

Action item: Familiarize yourself with Paragon

Spend some time familiarizing yourself with Paragon’s documentation. Visit both the edX themed Paragon site and the Open edX themed Paragon site and observe the differences in colors and typography. Click through the components and visit the different https://paragon-edx.netlify.app/foundations/layout, Spacing, https://paragon-edx.netlify.app/foundations/icons/, and https://paragon-edx.netlify.app/foundations/css-utilities sections to understand what you have to work with.

How do we use Figma?

Figma is a really powerful design tool that allows designers to create mockups using our design system elements. Currently, our entire Paragon Design System is represented in Figma. This allows designers to pull components into their Figma mockups without having to re-invent the wheel.

Action Item: Bookmark these Paragon resources

Figma files for Paragon Design System

edX themed Paragon doc site

Open edX Paragon doc site

When you receive a design in Figma, it may be overwhelming to understand how to pull information from it and translate the styling to Paragon or CSS. Fortunately, we have a recorded workshop that aims to walk you through this process. We’ll talk a bit more about the do’s and don’ts of CSS in the following section.

Action item: Watch a Figma Training (58 min)

Watch the following video (58 minutes) for an introduction to Figma. This workshop covers navigating through Figma files and translating designs to Paragon/React/CSS.

https://openedx.atlassian.net/wiki/pages/createpage.action?spaceKey=UX&title=Figma%20Training%20for%20Engineers%20%28Spec%20to%20Implementation%29

Develop

Once you’ve gathered your requirements, it’s time to start coding! Frontend features will usually consist of most, if not all, of the following steps:

Using JavaScript, React, and Redux to build components,
styling using Sass/CSS and Paragon,
following accessibility (a11y) best practices,
and properly implementing internationalization (i18n).

React, and Redux, and Javascript, oh my!

React: All of our microfrontends (MFEs) are written using ReactJS. If you’re new to React, take a look at the following resources to familiarize yourself with the framework and best practices.

Quick Start – React
Tutorial: Tic-Tac-Toe – React
Beta React.js Tutorial: Quick Start – React

Action Item: Read through React Component Best Practices

Regardless of your familiarity with React, it’s important to understand the conventions we try to promote at edX to maintain clean code and consistency. Read through these React Component Design Tips & Tricks to get a sense for how we structure React components.

Redux: For state management in React, we use Redux. If you’re new to state management, the Redux documentation is a good place to start to understand how to think in Redux: Motivation | Redux.

Understanding and working with Redux can be overwhelming at first, so take time to familiarize yourself with the repo you’re working in. Some repos, like frontend-app-learning, have ADRs (architecture decision records) that describe the structure of the code. This ADR from frontend-app-learning talks about the structure of its model store which uses Redux. Try finding an ADR for the repo you’re working in, and when in doubt, ask a team member or the frontend community in Slack!

Javascript: If you’re new to JavaScript, or you’re looking to improve your mental model, this Just JavaScript course may be a good resource for you. In Just JavaScript, Dan Abramov breaks down core JavaScript concepts to fill in gaps and enhance your understanding of JavaScript’s underlying functionality.

Styling using SASS/CSS and Paragon

CSS Do’s and Don’ts

In terms of styling, it may take some time to get used to translating Figma designs to code. While you’re styling your components, you’ll want to ask yourself, “Can I achieve this styling using Paragon/Bootstrap utility classes?” We generally want to avoid building custom CSS solutions for things that can be achieved using our design system utility classes.

Leaning on our design system allows us to avoid creating tech debt because our branding can remain centralized. This way, if we decide to update a major color like $brand, we only have to update it in our theme files, rather than chasing it down and replacing it in a number of different CSS files across different repos.

Here are a few examples of CSS do’s and don’ts:

Don’t hardcode colors

.myText {
  background-color: #0A3055
  color: #00BBF9;
}

Do use the color variables in our design system

<span className="bg-primary text-accent-a">
  Welcome
</span>

Don’t hardcode font sizes, weight, etc.

.myText {
  line-height: 1.5rem;
  font-size: .875rem;
  font-weight: 400;
}

Do use the preset typography classes

<span className="small">
  Welcome
</span>

Avoid using custom pixels for padding and margins

div {
  padding: 12px 16px;
  margin-right: 24px;
}

Do lean on and defer to the preset spacing classes

<div className="py-2.5 px-3 mr-4">
  ...
</div>

When in doubt, search for what you’re attempting to style in Paragon’s list of CSS utility classes before creating custom CSS.

How to contribute to Paragon WIP

Things to include/consider:

Contribution Process

https://github.com/edx/paragon#contributing--development

https://openedx.atlassian.net/wiki/spaces/BPL/pages/2301756261

https://github.com/edx/paragon#2-create-new-component

Accessibility (a11y)

Hopefully in your time as an engineer you’ve been introduced to the concept of web accessibility (a11y) and its importance. A11y at edX is addressed throughout many pieces of the feature creation process. We capture best practices in our Paragon Design System, we implement our design system components with a11y in mind, and as engineers, we aim to advocate for a11y at every step of the frontend development lifecycle. We covered some concepts to be aware of in the pre-development phase, now let’s get into how a11y plays a role in the development phase.

As an engineer in the development phase, there’s plenty to address in order to be following a11y best practices. This section can’t possibly cover everything, which is why it’s important to familiarize yourself with a11y best practices. We aim to follow https://www.w3.org/TR/WCAG22/. This long list of guidelines may seem overwhelming at first, but it’s a pretty comprehensive list of what you’re expected to have in your tool belt as a frontend developer.

Fun fact: Paragon aims to be an accessible component library. So if you’re using Paragon components in your development, a11y of those components should already be taken care of

Fortunately, there are ways to automate verifying your code’s a11y so that you don’t have to memorize all of these guidelines (unless you want to!). We’ll get into automated a11y testing in the Testing section of this handbook. The baseline expectation is that you’re aware of a11y, and that you ask questions if you’re unsure about whether your code is accessible or even how to approach building something in an accessible way. Ask your questions in the #accessibility Slack channel (available in both edX and Open edX Slack workspaces).

Action Item: Familiarize yourself with a11y

As an edX engineer, you’ll automatically be enrolled in annual edX Accessibility Training course. You can find it on your course dashboard.

If you are not employed by edX, you will not have access to this training. Aim to familiarize yourself with web accessibility and WCAG. https://www.w3.org/WAI/tips/developing/

Internationalization (i18n)

edX uses a service called Transifex that sources translations from a volunteer based community and populates our repos with those translations. Your job as an engineer is to prepare all of the strings you use to be translated properly. This means using proper syntax and providing adequate context for the translators. Correctly formatting our strings for translation is crucial to avoid jeopardizing our user experience in different languages. For more on i18n, visit https://openedx.atlassian.net/wiki/spaces/LOC.

Action item: Familiarize yourself with string translation

Read through the following how-to guide for tips on how to format strings for translation.

https://openedx.atlassian.net/wiki/spaces/LOC/pages/3103293538/MFE+Translation+How+To+s

General resources and tutorials

React tutorials

Quick Start – React
Tutorial: Tic-Tac-Toe – React
Beta React.js Tutorial: Quick Start – React
React Component Design Tips & Tricks

CSS/Sass tutorials

Javascript tutorials

Just JavaScript

Accessibility

…

Test WIP

Writing Tests Using Jest

Accessibility Testing

https://openedx.atlassian.net/wiki/spaces/A11Y/overview#Desktop

Manual Testing

Things to cover in this section:

Jest/Enzyme
Snapshot debacle?
Testing manually on multiple browsers
a11y testing
https://openedx.atlassian.net/wiki/spaces/FEDX/pages/3118628865
https://openedx.atlassian.net/wiki/spaces/FEDX/pages/952865747
https://openedx.atlassian.net/wiki/spaces/FEDX/pages/3118792705
https://openedx.atlassian.net/wiki/spaces/FEDX/pages/1046512255

Deploy WIP

Creating a Pull Request

use conventional commit messages

include screenshots and/or videos

How to apply brand theming locally

When you’re developing in an MFE, all of the pages will be styled in the default Open edX theme. In order to apply a theme locally (for example, GitHub - edx/brand-edx.org ), follow these steps: https://github.com/openedx/frontend-build#local-module-configuration-for-webpack