Getting Started/

As a Developer

Cedar + Vue

Cedar components are built using Vue and can only be used in Vue projects.

All components are available using an NPM package.

Terminal

npm install --save @rei/cedar

Once installed, you can import individual Cedar components from the main package into your project:

<script>
// import packages from Cedar
import { CdrText, CdrButton, CdrLink } from '@rei/cedar'

export default {
  name: 'ExampleComponent',
  // register your Cedar components
  components: {
    CdrText,
    CdrButton,
    CdrLink
  }
};
</script>

<template>
  // use the registered Cedar components in your template
  <cdr-text>Foo</cdr-text>
  <cdr-button>Bar</cdr-button>
  <cdr-link>Baz</cdr-link>
</template>

<style>
  // no need to import any Cedar related CSS here 
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Setting Up Projects

All components depend upon core style and font assets. Without these assets included, components will not render correctly. These files are distributed as part of the Cedar NPM package.

Install Required Core Styles

Cedar requires a core stylesheet to render properly. This stylesheet contains a CSS reset, component CSS, as well as global utility classes.

To include the stylesheet, import the cedar.css file:

main.js

import '@rei/cedar/dist/cedar.css';

Install Required Fonts

Cedar uses specific fonts – Roboto, Roboto Condensed, and Sentinel – that are required for your project.

Roboto and Roboto Condensed are available from Google Fonts (preselected for quick use).

Sentinel is available in the Cedar NPM package and mapped using the cdr-fonts.css file.

To include these fonts, import cdr-fonts.css:

main.js

import '@rei/cedar/dist/cdr-fonts.css';

Accessibility

REI requires 100% compliance with WCAG AA guidelines. Relevant guidelines are provided in each component's documentation.

Developing for Web

Install Vue Components Package

Terminal

npm install --save @rei/cedar

Include CSS

How you include CSS depends on your tech stack and varies from project to project.

Here are a few common methods:

Webpack

If using a bundler, import CSS into JavaScript and let loaders such as css-loader extract it.

main.js

import '@rei/cedar/dist/cdr-fonts.css';
import '@rei/cedar/dist/cedar.css';

1
2

PostCSS

Cedar packages include the unofficial style field supported by postcss-import.

cedar.postcss

import '@rei/cedar/dist/cdr-fonts.css';
import '@rei/cedar’;

1
2

SCSS

You can also import CSS from the node_modules folder such as SCSS or another pre-processor.

cedar.scss

import '~@rei/cedar/dist/cdr-fonts.css';
import '~@rei/cedar/dist/cedar.css';

1
2

Note: Code snippets provided throughout this documentation will demonstrate the webpack and css-loader method.

Using Components

The examples in our documentation demonstrate usage in a Single File Component. If you aren’t using SFCs, read the Vue.js documentation for registering components.

Examples below demonstrate the CdrButton component. Refer to each component’s documentation for a complete component API and advanced examples.

Loading a component in Vue

Import the component within the script block.

local.vue

import { CdrButton } from '@rei/cedar';

local.vue

components: {
  CdrButton
}

1
2
3

Add the component element, such as <cdr-button> into the template.

local.vue

<cdr-button>I'm a button</cdr-button>

Final file:

local.vue

<template>
    <cdr-button>I'm a button</cdr-button>
</template>

<script>
import { CdrButton } from '@rei/cedar';
export default {
  ...
  components: {
      CdrButton
  }
}
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13

Configure Component Props

Props are custom attributes registered on a component. For more information about props, read Vue's Props documentation.

Most Cedar components provide props to configure component data, display, and logic. For example, the CdrButton component provides a size prop to configure the button’s size.

<cdr-button size="large">I'm a large button</cdr-button>

Refer to each component’s API documentation for a full list of available properties.

Bind Dynamic Data to Components

Props can be static or dynamic. To provide dynamic data (or non-string data) add a colon (:) before the prop name.

Prop names are also documented and referenced in JavaScript as camel case, but used in the template as kebab-case.

In this example, the responsiveSize prop accepts an array of strings denoting size at different breakpoints. Note that responsiveSize is used as responsive-size in the template.

<cdr-button :responsive-size="['small@xs', 'large@sm']">I'm a responsive button</cdr-button>

Add Content Using Slots

Some components use slots for content distribution. Most components will have a single default slot; others will have named slots. Slots are listed as part of the API for all components. For more information about slots, read Vue's Slots documentation.

Adding content to a default slot

<cdr-button>I'm content in the default slot</cdr-button>

Adding content to a named slot

<my-component>
  <slot name="header">I'm content in the header slot</slot>

  <slot name="footer">I'm content in the footer slot</slot>
</my-component>

1
2
3
4
5

CSS Modules and Custom Class Names

Component CSS class names are CSS Modules that reflect the package version. For example, CdrButton@0.2.0 will have classes that end in ‘_0-2-0’. This allows the possibility of components at different versions to live together without having CSS class name collisions.

Never use Cedar class names within your own CSS or target them in JavaScript; they will change as you upgrade the package and break any functionality or styling you attach to them.

To target CSS, create custom selectors such as my-wrapper and my-selector in the following example…

<template>
  <div class="my-wrapper">
    <cdr-button class="my-selector">I'm a button</cdr-button>
  </div>
</template>

...

<style>
.my-wrapper > .my-selector {
 /* override button styles here */
}
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13

Some components are more complex and have templates with multiple areas where you may wish to add your own selectors. We try to be mindful of this and add props that will allow you to target your own classes to various elements.

For example with checkbox you may want to target both the label and the content areas.

<template>
  <cdr-checkbox label-class="my-label" content-class="my-content">My checkbox</cdr-checkbox>
</template>

...

<style>
.my-label {

}

.my-content {

}
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

If you find that a component needs to have a targeted prop class added, please create an issue and let us know.

Using Token Variables

Cedar provides a robust collection of design tokens corresponding to Cedar's foundations. Standard colors, typography, space, size and other properties are available in the cdr-tokens package. Outputs support web, iOS, and Android consumers.

As you create your own components, work with your designer to take advantage of this inventory in your custom classes. Using them this way will ensure your custom styles remain consistent with design guidelines.

Install Tokens Package

Resources are available within the CdrToken package:

SCSS variables at dist/scss/cdr-tokens.scss
LESS variables at dist/less/cdr-tokens.less
JS as both commonJS and ES module at dist/js. Also noted in package.json as main and module respectively
- dist/js/cdr-tokens.common.js
- dist/js/cdr-tokens.esm.js

To incorporate the required assets, use the following steps:

Install the CdrToken package using npm in your terminal:

Terminal

npm install --save @rei/cdr-tokens

Using Cedar Design Tokens

The package contains files for using tokens in both CSS (as SCSS and LESS variables) and JavaScript (as commonJS and ES modules).

Here we’re using a typography mixin and a color token to style .myClass from the SCSS tokens file.

local.vue

<template>
  <p class="myClass">I'm styled with tokens!</p>
</template>

<script>
export default {
  ...
}
</script>

<style lang="scss">
@import '~@rei/cdr-tokens/dist/scss/cdr-tokens.scss';

.myClass {
  @include cdr-text-default-body();
  color: $cdr-color-text-primary-lightmode;
}
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Developing for Mobile

Currently development for iOS and Android is through the usage of Cedar Tokens as documented below.

Our mobile development packages include fonts that are licensed and proprietary to REI. For more information or questions regarding Cedar’s support for external consumers using the mobile development packages on GitHub or NPM, please reach out to cedar@rei.com.

iOS

CocoaPods

The preferred way to consume Cedar for iOS is through CocoaPods. View www.cocoapods.org for more information.

To find out if Cocoapods is already installed, open the terminal and run:

Terminal

pod --version

If “command not found” is returned then Cocoapods in not installed.

To install Cocoapods:

Terminal

sudo gem install cocoapods

To set up Cocoapods from the project/workspace directory, run:

Terminal

pod init

The above command will create a Podfile in your current directory.

The Podfile must be modified with the following to include Cedar as a dependency:

1. Prior to the Targets Section of the Podfile:

Terminal

source 'https://git.rei.com/projects/CDR/repos/cedar-iosl/CedarPodSpec.git'

2. In the Targets Section of the Podfile:

Terminal

pod 'CedarTokens', '~> 0.2.0'

Full Podfile Example for Reference:

Terminal

project 'CedarIOSCocoaPodDemo.xcodeproj/'

platform :ios, '12.0'

source 'https://git.rei.com/projects/CDR/repos/cedar-ios-podspec/CedarPodSpec.git'

target 'CedarIOSCocoaPodDemo' do
  # Pods for CedarIOSCocoaPodDemo
  pod 'CedarTokens', '~> 0.2.0'

end

1
2
3
4
5
6
7
8
9
10
11

Manual Consumption

If you don’t use Cocoapods, you can manually import files into your iOS project/workspace.

Colors

Color Sets in a .xcasset file. Import the file by dragging the Cedar.xcassets > Colors folder into your project's asset folder.

You can set the colors in Interface Builder, or by:

Terminal

Button1.backgroundColor = UIColor(named: "cdr_color_text_primary_lightmode");

Text

The package includes Sentinel and Roboto font source files along with Swift Classes for applying Apple's Dynamic Type behavior to the font.

Importing the source font is done by creating a group under your target in xcode and dragging the font files into that group. Add the fonts to the info.plist under Fonts provided by application.

Finally, import the CedarFont.swift file along with the CedarTextStyles.plist. This will allow you to set the fonts by:

Terminal

  // Button Title 1 Style
  Button1.titleLabel?.font = CedarFont().getCedarFont(forTextStyle: .title1)
  Button1.titleLabel?.adjustsFontForContentSizeCategory = true;

1
2
3

Icons

Cedar provides icons in vector PDF format for iOS scaling. According to initial investigation, only one file per icon is needed in this format. There is no need for @1x, @2x, and @3x variants.

Android

Maven

The preferred way to consume Cedar Tokens on Android is to use Maven.

Add the following to the build.gradle file in your Android project:

Terminal

Implementation mvnrepos.rei.com:cedar-android.aar:0.2.0

Manual Consumption

If you don’t use Maven, you can import the Cedar Tokens into your Android project/workspace manually by dragging the resources into your project within Android Studio. The resources are located at the cedar-android repository on Bitbucket

As a Developer

# Cedar + Vue

# Setting Up Projects

# Install Required Core Styles

# Install Required Fonts

# Accessibility

# Developing for Web

# Install Vue Components Package

# Include CSS

# Webpack

# PostCSS

# SCSS

# Using Components

# Loading a component in Vue

# Configure Component Props

# Bind Dynamic Data to Components

# Add Content Using Slots

# CSS Modules and Custom Class Names

# Using Token Variables

# Install Tokens Package

# Using Cedar Design Tokens

# Developing for Mobile

# iOS

# CocoaPods

# Manual Consumption

# Colors

# Text

# Icons

# Android

# Maven

# Manual Consumption

Cedar + Vue

Setting Up Projects

Install Required Core Styles

Install Required Fonts

Accessibility

Developing for Web

Install Vue Components Package

Include CSS

Webpack

PostCSS

SCSS

Using Components

Loading a component in Vue

Configure Component Props

Bind Dynamic Data to Components

Add Content Using Slots

CSS Modules and Custom Class Names

Using Token Variables

Install Tokens Package

Using Cedar Design Tokens

Developing for Mobile

iOS

CocoaPods

Manual Consumption

Colors

Text

Icons

Android

Maven

Manual Consumption