Arrow Design System

React Design System for Aptible products

Using Arrow UI

Storybook for latest stable release. We don't publish storybook for alpha or beta builds.

yarn add @aptible/arrow-ds

Contributing to Arrow Design System

Developing locally

Setting the correct Node version

Arrow uses an .nvmrc config file to use the latest LTS version. To install the latest LTS version, run nvm install --lts and then nvm use.

If you’re not using NVM, it’s highly recommended. See (Installing and Updating)[https://github.com/nvm-sh/nvm#installing-and-updating] in the NVM docs.

Installing dependencies and running Storybook

yarn
yarn run storybook

Linking to comply-ui (or any other repo) locally

Install yalc globally:

yarn global add yalc

In this repo:

yalc publish

In the consuming repo:

yalc add @aptible/arrow-ds
yarn

Note: This will change the consuming repo's package.json (replacing @aptible/arrow-ds's version number with a local path). Make sure you revert that before committing!

Generating a new component

This project uses Plop to make it easy to generate new components.

1. Run yarn generate or yarn generate <component name>
2. Follow the prompt and give the component a name; the plopfile will convert the name to Pascal case
3. The component will be created in packages/components/

Adding a new component

1. Add the component's export to the root index.ts
2. If the component has its own stylesheet, add it to src/css/components.css.

Writing CSS

Arrow uses Tailwind v2 to compose styles for components. At the moment, we are using the PostCSS 7 compatibility build since Storybook has not yet upgraded to PostCSS 8. Once they do, we can switch to the latest tailwindcss v2 release on npm (2.0.1 as of this writing).

In many cases, each component should have their own index.css file. The naming convention follows SUIT CSS using the ads prefix.

ads-ComponentName
ads-ComponentName--modifierName
ads-ComponentName-descendentName
ads-ComponentName.is-stateOfComponent

Writing documentation

Documentation is written in MDX which is a combination of Markdown + JSX.

Each MDX file must end with .story.mdx for it to be picked up by storybook.

All documentation exists within the src directory of this repo. If it applies to the design system as a whole, it should live in the src/docs directory. Component documentation is included inside each component directory.

Each MDX file should start with importing the Meta component and passing a title to it:

import { Meta } from "@storybook/addon-docs/blocks";

<Meta title="Arrow Design System/Introduction" />

### [ write markdown here ]

In this example, we're creating a new page called "Intro" that will be organized into the "Arrow Design System" section in the storybook sidebar.

Check out MDX files in src/docs or component directories for more examples.

For designers (or anyone else who isn't super familiar with git)

The easiest way to make changes to documentation is through the GitHub interface. Just navigate to the MDX file you'd like to change and click the pencil icon in the top right. After making your changes, you'll be prompted to open a pull request that will be reviewed by UXE. To create a brand new MDX file, just navigate (again, in GitHub) to the directory you want it to live and click the "Create new file" button in the top right.

If you'd prefer to create a fork and run Storybook locally, there are instructions on the wiki.

Publishing @aptible/arrow-ds (npm)

New releases of Arrow Design System are triggered automatically by semantic-release. It uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.

Note: No version number is committed to package.json. Instead, semantic-release adds it automatically before publishing to npm.

Arrow Design System uses commitlint to enforce conventional commits. Attempting to make a commit with a message that doesn't adhere to that format will result in an error. Use yarn commit to run commitizen which will help format your commit message.

Here is an example of the release type that will be done based on a commit messages:

| Commit message | Release type | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | | fix(pencil): stop graphite breaking when too much pressure applied | Patch Release | | feat(pencil): add 'graphiteWidth' option | ~~Minor~~ Feature Release | | perf(pencil): remove graphiteWidth optionBREAKING CHANGE: The graphiteWidth option has been removed.The default graphite width of 10mm is always used for performance reasons. | ~~Major~~ Breaking Release |

Full list of commit types:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing or correcting existing tests
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Alpha and beta releases

To make an alpha or beta release, you'll need to merge your code to the alpha or beta branch. Semantic-release should take care of the rest.