Cedar's purpose & parts

Meet Cedar

Cedar is REI’s open-source design system for digital products and experiences, based on REI’s visual language. Its purpose is simple: to help people create consistent, unified user interfaces. We do this by simplifying common design decisions and providing reusable resources, freeing folks to focus on groundbreaking work.

Cedar’s main benefit as a design system is in the reusability of its code, which increases our overall consistency and design and development efficiency. By distributing flexible design system elements (Vue components, design tokens, CSS styles) we provide teams with all the tools necessary to create functional reusable components aligned with our brand.

How to participate

Our REI community is made up of developers and designers of all kinds. Your participation is what makes Cedar possible as a sustainable, growing system.

There are many ways to participate:

  • Suggesting a bug fix, whether it’s in Cedar’s design, code or documentation (external contributors are welcome here!)
  • Adopting a new release 
  • Offering an answer in the #cedar-user-support Slack channel 
  • Taking our biannual survey and offering suggestions for improvement 
  • Sharing ideas for process improvements within the Cedar ecosystem 

To recognize your support, we’ll plant trees on your behalf via donations to American Forests.

To learn more about how improving Cedar, check out how REI employees can contribute ideas for possible additions and changes to the system.

Open source

Cedar is aligned with our values as a co-op built on community. While Cedar is primarily focused on serving teams building experiences for REI, the system is also available as an open-source project in GitHub and NPM. For those outside REI, feel free to use Cedar's code for your own projects and extend it to suit your needs.

Sometimes there are exceptions to our open source rule. For example, fonts used in Cedar are licensed and proprietary to REI, and are not for common use unless approved.

We encourage you to explore Cedar! For more information or questions regarding Cedar’s support for external consumers using the open-source project, reach out to cedar@rei.com.

Cedar's parts

Cedar provides a set of reusable components, style variables, design assets and guidance for teams to efficiently build high-quality and accessible user interfaces.

Designer toolkit

The Cedar UI toolkit is distributed through shared libraries in Figma and includes all published components and foundational styles.

Documentation site

Documentation for each component and foundational style includes design guidelines, dos and don’ts, considerations for accessibility, and API instructions for developers. This is the site you’re on right now—bookmark it for easy reference while working.

Design tokens

Design tokens are special variables used to maintain a scalable visual system for UI development and brand consistency. Cedar design tokens store the visual design attributes that define the foundation of REI’s visual language, including color, typography, and spacing.

Components

Components use Cedar’s tokens and design foundations to distribute code templates that extend basic HTML elements and encapsulate reusable code. These custom markup elements represent specific portions of the user interface. When used in your application, they will help ensure the UI remains consistent with REI’s digital display standards.

For example:

<CdrLink href="https://www.rei.com">
  CdrLink Component
</CdrLink>

Component variables

Component variables are available for a subset of Cedar components. These SCSS or LESS mixins extend design tokens and define additional specific variables that are used to display Cedar components.

For example: cdr-link-base-mixin would be used to style an element like a CdrLink component.

Patterns

Patterns are common interfaces, behaviors, flows or component combinations across REI’s ecosystem. They provide guidance to common design problems at REI. For example, the alert pattern gives design and development guidance for various alert scenarios, while the form input types pattern offers common form types like street address.

Creating with Cedar

Cedar provides the core elements for creating consistent products and applications at REI. At times, you may have a specific use case and find Cedar doesn’t offer the customization or elements to meet your requirements. That’s normal—all design systems have limits to what they can support. They’re not intended to distribute business logic, domain-specific styling, or more complex UI elements. But that doesn’t mean you have to limit your ideas on what to create.

So, what to do?

  1. Reach out to the Cedar team on Slack: Contact us at #cedar-user-support or join our office hours to get 1:1 support. We’ll evaluate the issue and can help make changes in our system to better support you. This is the first and best option.
  2. Design a new component: After talking with us, we may find the Cedar design system elements don’t satisfy the requirements for your application. At this point you may need to override Cedar directly or replace those elements with entirely new ones.

Overriding Cedar

If you feel you have a case for overriding Cedar, check in with the Cedar team. We can guide you through additional considerations and risks, such as:

  • The need to manually update your component as the design system evolves. You’ll no longer be able to simply update your Cedar version to gain access to the latest changes
  • Your team will need to handle accessibility implementation and testing for your component. For some elements, especially background colors, this may have a high cost. For example, every Cedar element is guaranteed to have accessible contrast levels when rendered on our primary and secondary background colors, but we cannot make that same guarantee for arbitrary background colors
  • If you override internal Cedar logic like markup or CSS classes your code may break, even with a patch release of Cedar. We can only semantically version the public API of the elements we distribute
  • Other teams may copy what you are doing without knowing that they are diverging from the design system. You’ll need to ensure any overrides are well documented