___ ___ ___ ___ ___
/\ \ /\ \ /\ \ /\ \ /\ \
/::\ \ /::\ \ /::\ \ /::\ \ /::\ \
/:/\:\ \ /:/\:\ \ /:/\:\ \ /:/\:\ \ /:/\:\ \
/:/ \:\ \ /::\~\:\ \ /:/ \:\__\ /::\~\:\ \ /::\~\:\ \
/:/__/ \:\__\ /:/\:\ \:\__\ /:/__/ \:|__| /:/\:\ \:\__\ /:/\:\ \:\__\
\:\ \ \/__/ \:\~\:\ \/__/ \:\ \ /:/ / \/__\:\/:/ / \/_|::\/:/ /
\:\ \ \:\ \:\__\ \:\ /:/ / \::/ / |:|::/ /
\:\ \ \:\ \/__/ \:\/:/ / /:/ / |:|\/__/
\:\__\ \:\__\ \::/__/ /:/ / |:| |
\/__/ \/__/ ~~ \/__/ \|__|
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
- Install Jekyll 2.5.x with
sudo gem install jekyll -v '>= 2.5'
- Windows: See "Run Jekyll on Windows"
- Install Rouge with
sudo gem install rouge
- Install Node with
brew install node
- From the project root directory, run
npm install
to install the project's Node dependencies
Usage
- From the project root directory, run
npm run build-docs
to build the site - Run
jekyll serve
to start a local dev server - 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:
- Install CasperJS
- Build docs and start your jekyll server
- From the project root directory, run
npm run test-ui
in the command line* - 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