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 gatsby-theme-carbon and click the
```
Fork
```
button in the top-right corner.
After it’s finished, click on the
```
Clone or Download
```
button and copy the contents.
In your terminal, clone the repo into your directory of choice

git clone [PASTE_URL_HERE]
cd gatsby-theme-carbon
Copy to clipboard

When you clone your forked repo the
```
origin
```
is set to your fork by default. You’ll want to add a remote that points to the upstream repo.

git remote add upstream git@github.com:carbon-design-system/gatsby-theme-carbon.git
Copy to clipboard

In your terminal, verify that the remotes have been set

git remote -v
Copy to clipboard

Development

We use yarn and yarn workspaces to develop the Carbon Gatsby theme. This allows us to have a development environment that’s closely linked to the theme with minimal setup. Run

yarn install

to install all of the projects dependencies.

This project has two packages: the actual theme package (

gatsby-theme-carbon

) and the

example

package. The example package emulates a project which uses the theme. Its only dependencies are Gatsby, React, and the adjacent theme package. The

example

package also serves as the theme’s documentation and website; it’s deployed on every merge to main.

New theme development will happen in the theme package while documentation and testing of that change will occur through changes in the example directory.

Development scripts

```
yarn dev
```
– start the development environment
```
yarn dev:clean
```
– clear cache and restart dev
```
yarn format
```
– format your code with prettier
```
yarn lint
```
- check for errors in your javascript
```
yarn test:prefix
```
– build and serve with a path prefix

Work in a branch

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

git checkout main
git pull upstream main
git checkout -b my-branch-name
Copy to clipboard

Commit messages

For commit messages we use Angular commit conventions to dictate whether a commit is for a feature, fix, docs, etc. You need to prefix your commits with one of the following:

feat (feature)
fix (bug fix)
docs (documentation)
style (formatting, missing semi colons, …)
refactor
test (when adding missing tests)
chore (maintain)

git commit -m "chore: this is a test commit message"
Copy to clipboard

Opening a Pull request

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

git push origin my-branch-name
Copy to clipboard

You’ll get a message in your terminal with a URL to open up a pull request in the upstream repository. Navigate to that URL and 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 {
  color: $text-01;
}
Copy to clipboard

import { treeView } from './style.css';

const TreeView = (props) => <div className={treeView} />;
Copy to clipboard

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.

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} />;
};
Copy to clipboard

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

:global(.cds--grid) .codeBlock {
  @include 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

{
  "editor.formatOnSave": true,
  "[javascript]": {
    "editor.formatOnSave": false
  },
  "[javascriptreact]": {
    "editor.formatOnSave": false
  },
  "eslint.autoFixOnSave": true,
  "prettier.disableLanguages": ["javascript", "javascriptreact"]
}
Copy to clipboard

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

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint:js",
      "problemMatcher": "$eslint-stylish"
    },
    {
      "type": "npm",
      "script": "lint:scss",
      "problemMatcher": {
        "owner": "stylelint",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": [
          {
            "regexp": "^([^\\s].*)$",
            "file": 1
          },
          {
            "regexp": "^\\s+(\\d+):(\\d+)\\s+(✖|warning)\\s+(.*)\\s\\s+(.*)$",
            "line": 1,
            "column": 2,
            "severity": 3,
            "message": 4,
            "code": 5,
            "loop": true
          }
        ]
      }
    }
  ]
}
Copy to clipboard

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.

Publishing

Pull the latest from the main branch, usually by running
```
git pull upstream main
```
on your local machine.
From the root of the package run
```
yarn release
```
.
Follow the prompts accordingly.
In the project’s release tab, edit the new release to include a summary of new changes.

Edit this page on GitHub

Page last updated: 27 January 2020

Gallery

Guides: Authoring MDX

Contributions