Welcome to the REI Digital Design System presentation framework. A home for modular components based on our evolving design patterns.
darintrimillos Merge pull request #541 from rei/update/readmes
docs(component readmes): add link to Cedar Docs in component readme
Latest commit b70553e Dec 12, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
backstop_data/engine_scripts update backstop, add focus testing, add some tests for focus states Jan 24, 2018
build refactor(component-css): add finished message Dec 6, 2018
config chore(build): restore build for prod process Jun 4, 2018
docs Start organizing/documenting css with sections/toc Aug 22, 2017
src docs(icon): add inherit-color prop to api documentation in component … Dec 11, 2018
static feat(assets): remove tokens from assets Nov 28, 2018
styleguide WIP(button component): first pass at bringing the button component up… Apr 5, 2018
styles feat(styles): create a standalone, component styles only, non module … Dec 4, 2018
templates chore(test-utils): update test-utils and fix tests that broke Oct 17, 2018
test chore(tests): change from jest to mocha, cleanup, fix tests May 16, 2018
.babelrc feat(grid): move col and row to single package May 16, 2018
.commitlintrc.js Merge branch 'cedar2' into fix/grid-gutters Feb 27, 2018
.eslintignore chore(webpack): update to vue-loader 15 May 3, 2018
.eslintrc.js chore(dependencies): update patch dependencies May 14, 2018
.gitignore Merge branch 'next' of https://github.com/rei/rei-cedar into feat/tabs Sep 4, 2018
.stylelintignore chore(test-utils): update test-utils and fix tests that broke Oct 17, 2018
.stylelintrc chore(build): clean up more files for css-modules May 4, 2018
.travis.yml chore(dependency-verification): update gitignore, add script to travi… Aug 20, 2018
CHANGELOG.md docs(changelog): update changelogs to refelect changes from now to la… Nov 17, 2018
LICENSE Add copyright per MIT licence spec Feb 3, 2016
README.md docs(readme): add it.only example to readme Sep 27, 2018
backstop.js test(backstop): fix backstop errors Aug 22, 2018
check-version.js chore(dependency-verification): update gitignore, add script to travi… Aug 20, 2018
generator.js feat(styles): create a standalone, component styles only, non module … Dec 4, 2018
index.html refactor(examples): refactor for consistent testing Nov 30, 2018
lerna.json chore(dependency-checker): revert lerna/commitlint changes, add funct… Aug 17, 2018
node Configuring card Vue component to use an optimized and consolidated w… Oct 18, 2017
package-lock.json feat(icon accordion): bump version Dec 6, 2018
package.json feat(styles): create a standalone, component styles only, non module … Dec 4, 2018
postcss.config.js refactor(postcss config): adjust dynamic plugin inclusion Dec 5, 2018
styleguide.config.js test: added keydown test so build will pass May 2, 2018

README.md

REI Cedar Style Framework!

Build Status Commitizen friendly

Welcome to REI's style framework! The overall goals of this project are to provide a common scaffolding for UI elements, and a set of themes that build on this scaffolding. We started this project in 2015 as a fork of Bootstrap. The project has evolved into what it is today, and will continue to grow to fit our expanding needs. Feel free to watch the Cedar grow and learn from what we are doing, or jump in and provide some recommendations.

Getting Started

Install

Clone the project.

npm install

npm i -g lerna

Install Lerna globally. Lerna helps manage projects with multiple packages.

Run

npm run start

Bootstraps all the seaparate component dependencies.

npm run dev

Runs locally for development. Has hot reloading, linting, and other nice things related to development.

NOTE: If you have FEBS set up locally to run the REI.com Monolith on a mac, make sure to remove any reference to: ~/code/rei.com/scripts/mac/.reirc in your terminal configuration files, e.g., .bash_profile or .bashrc. Also make sure your system PATH does not contain febs/bin

Build System

The webpack build system is taken largely from the Vue webpack template which has its own set of docs that are a good reference.

Documentation Site

The API documentation for Cedar components is built inside the rei-cedar repository by running the following scripts:

Builds the JSON data object for the APIs of each component individually

npm run build:docs

Collects all of the individual component data objects into one large Cedar Data Object at src/cedar-data.json

npm run build:archive

Transfers the Cedar Data Object from the rei-cedar repository to the rei-cedar-docs repository on your local machine

npm run build:transfer

Outputs a standalone app to styleguide/build that can be hosted somewhere (like gh-pages).

Testing

Code Tests

npm run test

Runs karma unit tests. We're using avoriaz to help with Vue component testing (Vue is working on their official testing tools with the guy who made this).

npm run e2e

Runs Nightwatch end-to-end tests.

npm run unit:watch

Runs unit tests. Keeps mocha active to watch for changes and re-runs tests. Use it.only() to watch just a single test.

it.only('returns true', () => {
  expect(1).toEqual(1);
});

This includes running Tenon a11y tests.

Visual Regression Testing

Check backstop for general configuration questions.

Our visual regressions audits can be performed against all patterns documented within the project's component proving grounds. To do so, follow the steps below:

  1. Run the project locally with npm run dev
  2. npm run reference will create a base set of images providing coverage for all defined patterns. Ensure this is run against a clean build prior to any edits.
  3. npm run compare after making changes to the markup or css. This will create another set of test images and compare them against those generated in the previous step.
  4. Review the generated report that should open in your browser. Make sure all changes are what you expect.
  5. npm run approve if everything looks good. This will promote the latest test images to be the new reference images that future tests will be compared against.

Notes about our backstop configuration

We’re aliasing the backstop commands to use npm run <command> just to abstract away supplying the config option since we are using a javascript based backstop config file to dynamically generate most of it. By using the js format instead of the standard json, we can avoid having a monolithic config file and instead have more localized, manageable configs that can remove some repetition and allow for different stateful tests, like hover, more easily.

The config (backstop.js) looks through src/ for all *.backstop.js and generates a proper backstop scenario object for each.

If you want to test hover statyes you can create another array of selectors hoverSelectors. These selectors will use an onReadyScript (hover.js) to simulate a mouse moving and hovering. This engine script uses chromy. This is a custom config option we've added to allow for adding hover tests for an array of selectors easily.

Engine scripts live in backstop_data > engine_scripts

*.backstop.js files will export an array of objects that are standard backstop scenario objects and support all the same options noted in the docs with the following exceptions:

  1. url is assumed to be localhost:8080 (running the project locally) and you don’t need to define that for each object.
  2. readyEvent is set to null for each scenario.
  3. hoverSelectors is a custom option we've added (as noted above).

Javascript

TODO: Notes about js, eslint

  • Babel for transpiling js so use es6.
  • Aim to have 0 dependencies, don’t use jquery.
  • Eslint using airbnb config

Design system Integration

TODO: Notes about DDS, design tokens, integrations Tokens are stored in the REI-Cedar-tokens project, and new tokens will need to be created there.

CSS

TODO: Notes about css, postcss, stylelint

  • Using postcss. Config for it lives in postcss.config.js
  • SCSS style variables ($variable). Don't use mixins/other logic. Keep it simple.
  • Components styles are in the same directory and imported into style tags in the component file.
  • main.postcss (.postcss so webpack uses the correct loader - others are .pcss and just need to be imported here to be processed)
  • Component css is output as a file separate from main.postcss.
  • Imported into entry files (dev.js and main.js so webpack processes it)
  • ITCSS inspired file structure.
  • CSS needs to be written with cdr- namespace prefix.
  • Auto prefixer settings is in package.json under "browserslist"
  • safari >= 4 used for backstop (phantomjs engine) issues with flexbox issue here
  • Build with variable configs for theming (want to hook these into theo/sketch/something for theming).
  • Stylelint using stylelint-config-standard for base but we have customizations on top of it. Not following stylelint guidelines will throw errors in build (need to lock down rules still).

Components

TODO: Notes about Vue, components

  • Using Vue.js single file components. They have excellent docs.
  • Import them into the _index.js.
  • Write the component name prefixed/namespaced with cdr-.
  • Horizontal theming with css-modules, dynamically binding classes based on theme

Commits

This project is Commitizen friendly. when creating a pull request run git cz rather than git commit and follow the prompts.

This projects Changlogs are generated. To output the latest changelog files you will need to create a new repository release. This is done with calendar versioning in the following format YY.MM.(iterator)

  • Generate the root Changelog: standard-changelog.
  • Generate the component Changelogs: lerna-semantic-release post.