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.
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.
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?
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 (https://react-bootstrap.github.io/ ) 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 https://github.com/edx/brand-edx.org, but we’ll get into the specifics of this in the Deploy section of this handbook.
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.
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.
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!
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.
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.
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.