ACcepted 9/4/2020

Taxonomy is the organization of high-level categories of edX’s design system.

Category Name




  • Getting Started

  • Guides

  • Theming

  • Best practices on contribution and producing documentation

  • Help designers, engineers, contributors, PMs know how to use this tool AND how to contribute to it.

  • Outline processes

  • Library Principles

  • Requirements: (themeable)

  • Composability - components should be interoperable

  • Decision: More is not better

  • Contribution

  • Making new components or patterns

  • How to use

  • Feedback



edX Brand

  • Separate documentation

  • edX specific brand documentation.

  • Should not include foundations. Maybe it documents brand color, but not the color system.

  • Logo - MKTG

  • Brand Colors - MKTG

  • Brand Voice - MKTG

  • Social Media Asset Tools

  • Imagery style guide

  • Document this separately. Paragon docs should not reflect edX by default.


  • Base values (colors, pixels, etc) that are used throughout the system. These should be changeable, and are effectively the default “theme” of Paragon.

  • Color

  • Typography

  • Line-height

  • Type size ramp

  • Fonts

  • weights

  • Spacing

  • Radius

  • Sizing

  • Shadow

  • Time (animation)

  • Media Query

  • Grids/Layouts (num columns tokens) + components

  • Icon - svgs (tokens) and components

  • Borders


  • The building blocks of our UIs. These are the things you actually use.

  • Components can have variants supplied as attributes or multiple similar components (families)

  • Interaction Pattern is documented. Common assembly is defined with component. Related components at bottom of doc.

  • Search feature that searches Components and templates

  • All the stuff we love and expect

  • Toast

  • Usage guide: + stateful button

  • Wizard

  • Image?

  • Trust Bar

  • Course Hero

  • Contentful

  • Paginated Search



  • These are pre-assembled sets of components. Engineers or designers can copy-paste to get a place start from.


  • Program Detail Page

  • Login

  • Page Templates

  • course discovery

  • Data Browser

  • Settings Cards

  • Async

  • Form submissions

revisit when needs arise

Additional Tiers (Future)

  • Extensions

  • Library Add-ons

  • Experiences



  • Things we don’t believe are core enough to document with the rest of the system. Maybe they are for special needs.

  • Masters lead generation

  • Organization may need to change over time

  • By product line, device, audience, platform?

Initial Working Doc