Meta

Contributing

Edit this page✍

Welcome to Ray, and thank you for contributing. Let's get you setup!

iconsSetup

Clone the project and cd into the directory.

$ git clone git@github.com:WeWork/ray.git
$ cd ray

You will need to install Node.js and npm in order to run the project.

Then install dependencies and bootstrap Lerna.

$ yarn bootstrap

iconsStructure

Ray is a multi-package repository powered by Lerna. These packages can be found in packages/.

The primary packages are

PackageDescription
packages/core/CSS and JS that make up the design system
packages/docs-app/A documentation site built with Gatsby

iconsWorkflow

After following the setup instructions above, you can use these steps to begin your contributions to the design system.

  1. Start the development servers
# Spin up both the storybook and docs servers
$ yarn dev

# Run only the storybook server
$ yarn dev:core

# Run only the documentation server
$ yarn dev:docs
  1. Modify or create new SCSS/JS in the packages/core/src directory
  2. Modify or create new stories in the packages/core/stories/ directory
  3. Modify or create new documentation in the docs/ directory
  4. Test your changes (and write tests if applicable): yarn test
  5. Commit and push your changes to GitHub and create a pull-request.
  6. Wait for a review by the maintainers.

iconsStorybook

This is a playground for developers to build and test their HTML/CSS/JS. It runs React for ease of development.

We also use storybook in our continuous integration for visual regression testing. So it's key that stories exist for every component.

Open up localhost:6006 to find the storybook.

iconsDocumentation

Our documentation is built with GastbyJS, with content sourced from the markdown in docs/**/*.md.

Open up localhost:8000 to find the docs site.

iconsGuidelines

  • All components should be right-to-left (RTL) compatible
  • Strive to document all component permutations in storybook so they're visually tested
  • Keep HTML examples simple and follow best practices such as using proper a11y attributes where applicable
  • Keep SVGs in HTML examples simple so they code can be easily scanned
  • Put focus states and keyboard navigation effects behind the $ray-accessibility-class variable, search the codebase for examples
  • All custom JavaScript/CSS API must be documented