___           ___           ___           ___           ___
    /\  \         /\  \         /\  \         /\  \         /\  \
   /::\  \       /::\  \       /::\  \       /::\  \       /::\  \
  /:/\:\  \     /:/\:\  \     /:/\:\  \     /:/\:\  \     /:/\:\  \
 /:/  \:\  \   /::\~\:\  \   /:/  \:\__\   /::\~\:\  \   /::\~\:\  \
/:/__/ \:\__\ /:/\:\ \:\__\ /:/__/ \:|__| /:/\:\ \:\__\ /:/\:\ \:\__\
\:\  \  \/__/ \:\~\:\ \/__/ \:\  \ /:/  / \/__\:\/:/  / \/_|::\/:/  /
 \:\  \        \:\ \:\__\    \:\  /:/  /       \::/  /     |:|::/  /
  \:\  \        \:\ \/__/     \:\/:/  /        /:/  /      |:|\/__/
   \:\__\        \:\__\        \::/__/        /:/  /       |:|  |
    \/__/         \/__/         ~~            \/__/         \|__|

REI Cedar Style Framework!

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 and have applied many of the concepts from Semantic-ui. 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.

The goal, at this point, is to generate multiple themed CSS resources that different web properties can consume. In time, we will explore more atomic theming that will allow page creators to mix and match themes: essentially becoming a theme generator.

This project will work in conjunction with an upcoming component framework that is in the works. Stay tuned for that!

Build

To build the CSS bundle, run npm run build. The built bundle(s) will appear in target/*.css

Docs

To generate the documentation site locally, follow these steps: (We are looking to move away from Jekyll as a documentation generator in the future.)

Installation

1. Install Jekyll 2.5.x with sudo gem install jekyll -v '>= 2.5'
   • Windows: See "Run Jekyll on Windows"
2. Install Rouge with sudo gem install rouge
3. Install Node with brew install node
4. From the project root directory, run npm install to install the project's Node dependencies

Usage

1. From the project root directory, run npm run build-docs to build the site
2. Run jekyll serve to start a local dev server
3. Open http://localhost:9002 in your browser, and voilà!

Accessibility Audits and Testing

** Note: The following in currently in development.**

Accessibility audits can be performed against the generated documentation or on the templates used for the documentation. We plan to following the rules defined within https://www.w3.org/TR/WCAG20/.

• npm run accessibility:audit-templates will audit the template files.
• npm run accessibility:audit-docs will audit the generated documentation.

Additional Audits

In addition to a11y, we have added audits using pa11y. These audits offer more coverage, but with some limitation. pa11y offers a lot more coverage, but does not include DOM references to correct errors. And it cannot audit local static files.

• gulp accessibility:audit-pa11y

Experimental automated visual regression testing

This testing currently uses PhantomCSS and CasperJS. Together these tools allows us to catch visual regressions. Currently there will only a few pages that tag their examples with data attributes ([data-example-id]). To run these tests, follow the steps below:

1. Install CasperJS
2. Build docs and start your jekyll server
3. From the project root directory, run npm run test-ui in the command line*
4. Make a change to the markup or css and re-run npm run test-ui

Folder Structure

├── main.js        # Test runner for all the docs
├── failures       # Contains screenshots of failed test
└── screenshots    # Contains baseline screenshots; last good state

Screenshot Files

Screenshots are all named with the value from the example's data attribute, data-example-id. They are also prefixed with the section it came from.

components-panel-with-heading_138.png
# Page: /components
# data-example-id: panel-with-heading

Road Map

• Make it faster; the entire suite currently takes 11 minutes to complete.
• Add more documentation pages that have examples with [data-example-id].
• Update test runner to also test mobile breakpoints.
• Allow these tests to be run without a web server (jekyll).

*The initial test run will not actually test anything, and will only create baseline images.

TODO

• Remove generated files from git
• Port all Grunt tasks to gulp

See Also

REI Cedar is a living, working project and will continue to grow, and change. Just like any healthy tree, this one will lose limbs and may change direction at times.

We would like to thank the creators and contributors of the following tools that we have pulled inspiration from.

The following frameworks have been used / referenced thus far

• Bootstrap,
• Semantic-ui,
• Pattern lab The following tools have been used / referenced thus far UI testing:
• PhantomCSS Accessibility testing:
• Pa11y
• A11y