# Arrow Design System React Design System for Aptible products ## Using Arrow UI [Storybook](https://aptible.github.io/arrow-ds/) for latest stable release. We don't publish storybook for alpha or beta builds. ```bash 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`](https://github.com/aptible/comply-ui) (or any other repo) locally #### Install [yalc](https://github.com/whitecolor/yalc) globally: ```bash yarn global add yalc ``` #### In this repo: ```bash yalc publish ``` #### In the consuming repo: ```bash 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](https://plopjs.com) to make it easy to generate new components. 1. Run `yarn generate` or `yarn generate ` 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](https://tailwindcss.com) to compose styles for components. At the moment, we are using the [PostCSS 7 compatibility build](https://tailwindcss.com/docs/installation#post-css-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](https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md) using the `ads` prefix. ```css ads-ComponentName ads-ComponentName--modifierName ads-ComponentName-descendentName ads-ComponentName.is-stateOfComponent ``` ## Writing documentation Documentation is written in [MDX](https://mdxjs.com/getting-started) 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: ```mdx import { Meta } from "@storybook/addon-docs/blocks"; ### [ 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](https://github.com/aptible/arrow-ds/wiki/GitHub-Guide-for-Designers). ## Publishing `@aptible/arrow-ds` (npm) New releases of Arrow Design System are triggered automatically by [semantic-release](https://github.com/semantic-release/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](https://commitlint.js.org/#/) to enforce [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). 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](https://github.com/commitizen/cz-cli) 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 option`

`BREAKING 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.