As a Developer

# Cedar + Vue

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

# About component packages

All components are available as a package on npm within the REI organization.

Each component is a separate NPM package. This ensures that you only have the essentials for your application - nothing more.

Terminal

npm install --save @rei/cdr-<component-name>

Once installed, files are located in the package‘s dist/ folder. Component packages often contain one JS file and one CSS file.

node_modules/@rei/cdr-<component-name>/dist/cdr-<component-name>.js
node_modules/@rei/cdr-<component-name>/dist/cdr-<component-name>.css

Some packages contain more (or fewer) than these two files which is noted in the package’s documentation.

# Setup a project

All components depend upon core style and font assets. Without these assets included, components may be styled incorrectly.

First, install the assets package:

Terminal

npm install --save @rei/cdr-assets

The cdr-assets package contains these files:

• cdr-core.css
• cdr-fonts.css

# Install required core styles

Cedar requires a core stylesheet to render components properly.

To include the stylesheet, import cdr-core.css:

main.js

import '@rei/cdr-assets/dist/cdr-core.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 cdr-assets package and mapped using the cdr-fonts.css file.

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

main.js

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

# Install a component

Examples below demo the CdrButton component.

Terminal

npm install --save @rei/cdr-button

# Including component-specific CSS

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

Here are a few common methods:

# Webpack (css-loader)

If using a bundler, import CSS into javascript and let loaders extract it.

main.js

import '@rei/cdr-button/dist/cdr-button.css';

# Postcss-import

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

cedar.postcss

import '@rei/cdr-button’;

# SCSS (or another pre-processor)

You can also import CSS from the node_modules folder.

cedar.scss

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

Note: Code snippets provided throughout the docs will demonstrate the webpack + css-loader method.

# Use a component

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

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

# Including component-specific CSS

1. Import the component within the script block.

local.vue

import { CdrButton } from '@rei/cdr-button';

2. Register the component in the components: object.

local.vue

components: {
  CdrButton
}

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/cdr-button';
export default {
  ...
  components: {
      CdrButton
  }
}
</script>

# Configure component props

Props are custom attributes registered on a component. For further information about props see Vue's prop documentation.

Most Cedar components provide props to configure component data, display, and logic. For example, the <cdr-button> 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 props.

# Bind dynamic data to the component

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

Prop names are also documented and referenced in javascript as camel case, but used in the template in 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 via 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. See Vue's documentation on slots for further information.

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>

# Customize components using token variables

Cedar provides a robust collection of design tokens corresponding to Cedar's foundations. Standard colors, typography mixins, space, size and other properties are available in the cdr-tokens package as Sass/SCSS variables. If you need them in a different format such as LESS or XML, please submit a feature request.

As you extend Cedar components and 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

Terminal

npm install --save @rei/cdr-tokens

# Use Cedar design tokens

The package contains files for using tokens in both CSS (as SCSS variables) and Javascript (as commonjs).

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/cdr-tokens.scss';

.myClass {
  @include redwood-display-10();
  color: $text-on-light;
}
</style>

# Accessibility

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

# 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/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>

Some components are more complex and have templates with multiple areas 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>

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