Use this guide to contribute to the theme. We’ll show you how to get the development environment set up as quickly as possible so you can start contributing.

Project setup

Go to waterfall-website.
Click on the Clone or Download button and copy the contents.

In your terminal, clone the repo into your directory of choice

git clone git@github.com:dv01-inc/waterfall-website.git
cd waterfall-website
Copy to clipboard

Install the necessary packages using npm.
```
npm install
Copy to clipboard
```

Run the local development to see any changes made.

gatsby develop
Copy to clipboard

Development

tktktk

This project uses the theme package (gatsby-theme-carbon) . Its only dependencies are Gatsby, React, and the adjacent theme package. The gatsby-theme-carbon theme’s documentation is located on this website.

Work in a branch

You should always start a new project by pulling changes into master and then creating a new branch. This workflow ensures you don’t accidentally commit anything to your master branch and get stuck when trying to open a pull request.

git checkout master
git pull origin master
git checkout -b my-branch-name
Copy to clipboard

When you’re ready to open a pull request, push to origin remote.

git push origin my-branch-name
Copy to clipboard

Be sure to give a detailed summary of your pull request in the title and body section of the form.

Sass and CSS Modules

For internal theme components we use Sass and CSS Modules. This allows us to take advantage of the Carbon Design System resources while not worrying about className collisions. By default, each .scss file will be supplied with all of the Carbon Sass variables: color, spacing, theme, and motion, as well as type and layout mixins, are imported automatically.

You should colocate your stylesheet with the component(s) that import it. If the component is TreeView then the stylesheet should be TreeView.module.scss. All contained within the TreeView directory.

CSS Modules

You don’t need to prefix your classes as CSS Modules will generate unique class names for you. Import the class from the .scss file.

TreeView.module.scss
Copy to clipboard
.treeView {
  color: $text-01;
}

TreeView.js
Copy to clipboard
import { treeView } from './style.css';

const TreeView = props => <div className={treeView} />;

For conditionally applying class names, use the classname library. Note how we’re using a computed property name for the property being based to cx. That’s because the className isn’t literally "long" it’s a value generated by CSS Modules and placed in the long variable.

TreeView.js
Copy to clipboard
import cx from 'classname';
import { treeView, long } from './style.css';

const TreeView = props => {
  const className = cx(treeView, {
    [long]: props.long,
  });
  const TreeView = props => <div className={className} />;
};

If you need to target a global class not processed by CSS Modules, you can do so with the global selector.

:global(.bx--grid) .codeBlock {
  @include carbon--type-style('code-01');
}
Copy to clipboard

VS Code

To get linting error feedback while writing javascript and SCSS in VS Code, install the stylelint and ESlint extensions. We use ESLint’s Prettier rules to format and lint all of our JavaScript in one pass. To get your code to format properly on save, add the following to a .vscode/settings.json in the root of your project

.vscode/settings.json
Copy to clipboard
{
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.formatOnSave": false
  },
  "[javascriptreact]": {
    "editor.formatOnSave": false
  },
  "eslint.autoFixOnSave": true,

To lint the entire project and get errors in your Problems tray, you can add the following to a .vscode/tasks.json file in the root of your project. You can run these tasks with cmd+shift+d

.vscode/tasks.json
Copy to clipboard
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint:js",
      "problemMatcher": "$eslint-stylish"
    },
    {

Test pages

If you want to add examples of what you are working on or see changes you’ve made, you can add an MDX file to packages/src/pages/test that will be visible at (your-server-name)/test/(added-file) during development. If you do add a page to the /test directory, update the below list with the file you added and its purpose to be included with your pull request.

Spacing audit: use this page to test spacing around components when combined in common patterns.

Edit this page on GitHub

Components: Tooltip