Developing for Palette

When working with Palette there are a number of things to be aware of, be it adding new components, modifying the theme or updating docs. Read on to learn how it's done.

Overview

- During development most of your time will be spent in packages/palette, the main Palette library. Here you'll write new components inside of the elements folder, add tests, and define storybook stories for each.

- If adding or changing a component, make sure to update the docs in packages/palette-docs.

- If needing to modify the theme, see packages/palette-tokens.

- New package versions are published by attaching appropriate semver github labels to PRs; by default, all PRs have minor automatically assigned. When a PR is merged, a new version goes out.

- If only updating docs, remove the default minor label and attach a docs label. This will skip the npm publish step.

- To publish a canary version to NPM to test in other apps, add the canary label. Once CircleCI is done running, view the auto/publishing-canary job output to see the npm version number and then update the consuming app accordingly.

- Alternatively, you can use yarn link to test your changes in Force, or any other app. Run

cd packages/palette
yarn link
yarn watch

And then back in your app, run

yarn link @artsy/palette
yarn start

Note: When yarn link'ing Palette, there are some issues with type-checking that can be confusing and lead to false-positives. Also, when done, be sure to run yarn unlink @artsy/palette && yarn --check-files to re-install the latest version of Palette from NPM; many a dev has fallen down the rabbit hole of trying to fix type errors that aren't actually errors due to forgetting that Palette is currently yarn link'd.

Relevant Commands

yarn storybook
yarn docs
yarn test
yarn type-check

See packages/<package-name>/package.json for complete list.

Monorepo Structure

Palette is a monorepo that is composed of a number of sub-packages:

  • palette-tokens
  • palette
  • palette-docs
  • palette-charts

palette-tokens

Starting at palette-tokens, we can see the theme that powers all of Palette. This is a simple object with keys such as breakpoints, space and color, and is read in by the main palette lib as well as Eigen, our React Native mobile app.

palette

The palette package is where all of our components are defined. See the elements folder for the complete list.

palette-docs

This is a where our docs are created, built on top of Gatsby. Docs are written in .mdx (Markdown React) which allows us to create live, interactive code examples using real Palette components.

palette-charts

This is where our charting components live, built on top of D3.js.

On this page
Overview
Relevant Commands
Monorepo Structure
palette-tokens
palette
palette-docs
palette-charts