Skip to content

Commit

Permalink
Update README.md for better organization
Browse files Browse the repository at this point in the history
  • Loading branch information
@jasonbasuil
jasonbasuil authored Aug 20, 2024
1 parent 3fe2f5f commit 2796341
Showing 1 changed file with 63 additions and 113 deletions.
176 changes: 63 additions & 113 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,92 +1,104 @@
# User Interviews Design System
# Synthesis Design System

![User Interviews Logo](https://user-images.githubusercontent.com/37383785/214649126-a2d75ddc-cf6d-4be0-8636-5f6182a3bc41.png)
![Synthesis Design System](https://github.com/user-attachments/assets/28a8a899-c05e-48f6-ab15-f17d6414d868)


# 🌤️ What is the goal of the design system?
Synthesis is the official design system of [User Interviews](https://www.userinterviews.com/). It offers design guidelines and reusable components to streamline the creation of product features, focusing on usability, accessibility, and efficiency while enhancing teamwork.

The goal of the design system is to achieve visual and experiential consistency throughout the User Interviews app while streamlining the design and implementation process. The design system should contain all reusable components, one-off variations, and guidelines that are used to build up the existing and future screens of our application. It should direct us to be mindful of when we're consciously diverging from the established system.
[Public Storybook Documentation](https://docs.userinterviews.com/)

[Synthesis Figma](https://www.figma.com/design/dmmTbSjuPXqt9m82YaewXO/Synthesis-Design-System?node-id=5-3&t=ohykAoJ8olM5Y95z-0)

## Contributing

The Design System tech lead and Product Designers are the main decision makers & implementers for the system, but we welcome everyone's contributions or suggestions. We meet on a weekly basis and are continuously prioritizing updates while also supporting the needs of our product teams.
## Table of Contents
- [Getting started](#getting-started)
- [Initial setup](#initial-setup)
- [Available scripts](#available-scripts)
- [Developing against rails-server](#developing-against-rails-server)
- [Pull requests](#pull-requests)
- [Contributing](#contributing)
- [Slack channels](#slack-channels)
- [Open a Linear issue](#open-a-linear-issue)
- [Flag @user-interviews/design-system](#flag-user-interviews/design-system)
- [Storybook development (Under construction 🚧)](#storybook-development)
- [Chromatic visual testing (Under construction 🚧)](#chromatic-visual-testing)
- [Release process](#release-process)

## Storybook Documentation
## Getting started

<a href='https://docs.userinterviews.com/?path=/story/intro--page'>
<img src='https://img.shields.io/badge/storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white' alt='Storybook logo'/>
</a>

- For every component, we typically illustrate common use cases for different variants or states of a component.
- Documentation lives in `Component.mdx` which references stories defined in `Component.stories.jsx`. See documentation style here in [Stories with arbitrary MDX](https://github.com/storybookjs/storybook/blob/master/addons/docs/docs/recipes.md#csf-stories-with-arbitrary-mdx).
- Check out our [Storybook Notion Doc](https://www.notion.so/userinterviews1/Storybook-9a3585db57514ec783e39c78518ad5e6) for examples. You can find our current documentation template that we try to follow for all of our `mdx` files in that Notion doc.
- We encourage all contributors to the Design System (engineers, designers, product) to add to our documentation.
### Initial Setup
After cloning the repo, obtain a `.npmrc` file from another developer. This file contains authorization tokens for any private
node packages.

### Available Scripts
In the project directory, you can run:

## Steps to update any documentation file
`yarn storybook`
Launches the Storybook server.

### `yarn install`
`yarn install`
Installs all yarn dependencies.

Installs all yarn dependencies
`yarn test`
Runs the jest test suite.

### `git checkout -b chore/UIDS-###-update-some-component-documentation`
`yarn lint`
Runs ESLint to report on any style violations

In your terminal, check out a new branch locally for you to make changes. You should have a Github issue to track that corresponds to the branch name.
### Developing against `rails-server`

### `yarn storybook`
It is often helpful to see how new updates on the design system are consumed in-app by locally linking the two repositories.

Launches the Storybook server.<br />
Add `RAILS_SERVER_PATH` to a `.env` of this application
_This will be the path to rails-server in your local machine._

- In the code editor of your choice, navigate to the Component library found under src `ui-design-system/src`
- Open any `Component.mdx` file (e.g. `Alert.mdx`) that you want to edit. These are markdown files. See [markdown docs](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for additional how-to.
- While Storybook is running, you should be able to view any changes you make to the `mdx` file after saving your changes.
- Push your changes to Github and submit for a review / pull request.
`yarn rs:link`
_Creates symlinks for packages needed to develop/debug against our `rails-server` repository._

If you need any help with setup or have questions about the process of writing documentation, feel free to reach out to a developer or a member of the Design System team.
`yarn rs:link:watch`
_Trigger a production build when files are changed._

`yarn rs:unlink`
_Remove symlinked packages when you're finished._

# Developer Resources
### Pull requests

## Initial Setup
After cloning the repo, obtain a `.npmrc` file from another developer. This file contains authorization tokens for any private
node packages.
We merge directly into `main` and your branch name should correspond to a Linear issue on the [UI Design System Updates](https://linear.app/user-interviews/project/ui-design-system-updates-4cb25d4fd32e/overview) project. You will need at least 1 approval from a senior engineer or an engineer on the core team. Be sure to also loop in your product designer if there are user facing changes.

## Available Scripts
In the project directory, you can run:

### `yarn storybook`
## Contributing

Launches the Storybook server.
The design system teams consists of engineers and product designers work together to make decisions and implement changes for Synthesis. We meet regularly to continuously prioritize updates while also supporting the needs of our product teams. We welcome everyone to share their feedback about the design system and make contributions to this repository. Below are some ways you can help!

### `yarn install`
### How you can help

Installs all yarn dependencies
#### Slack channels

### `yarn test`
We have a couple Slack channels where you can discuss all things design system or share your feedback
- [#dev-design-system](https://userinterviews.slack.com/archives/C06J56K92EL) _General channel for design system topics_
- [#ds-gardening](https://userinterviews.slack.com/archives/G01P02LNJTF) _Core design system team channel. All are welcome!_

Runs the jest test suite
#### Open a Linear issue

### `yarn lint`
We use Linear as our project management tool to track all our design system issues.

Runs ESLint to report on any style violations
Whether you're adding an issue to our [UI Design System Updates](https://linear.app/user-interviews/project/ui-design-system-updates-4cb25d4fd32e/overview) Linear board, or any other project on Linear, be sure to add the tag `Design system` on any issue you open up so that our team has visibility and can provide guidance if needed.

### `yarn rs:link`
#### Flag @user-interviews/design-system

Creates symlinks for packages needed to develop/debug against our `rails-server` repository.
If you want to flag anything design system related on any PR you're working on or have questions/suggestions, you can tag @user-interviews/design-system and we will help out!

### `yarn rs:link:watch`

Trigger a production build when files are changed.
## Storybook development (Under construction 🚧)

### `yarn rs:unlink`
<a href='https://docs.userinterviews.com/?path=/story/intro--page'>
<img src='https://img.shields.io/badge/storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=white' alt='Storybook logo'/>
</a>

Remove symlinked packages.
## Chromatic visual testing (Under construction 🚧)

## Chromatic visual testing & live feedback
We use [Chromatic](https://www.chromatic.com/) for visual testing and gathering UI feedback.

To join Chromatic for 'ui-design-system', ask Jason for the join link.
To join Chromatic for 'ui-design-system', ask the design system lead for the join link.

If you are a Product Designer or wanting to view changes on a particular feature branch, a developer can provide a link to that specific Chromatic build.

Expand All @@ -95,33 +107,6 @@ If you are a Developer and want to trigger a Chromatic build,
2. Go to the Manage tab for 'ui-design-system' > Configure > Find the project token.
3. In your terminal, run `npx chromatic --project-token <projectToken>`. Use this command when you want to create a build and share with a stakeholder to gather UI feedback. You will be able to find the build on the Chromatic builds dashboard. We currently run automatic nightly builds for Chromatic via Github Actions.

## Pull requests

Our branch names consist of 3 parts:
1. The type of task we are working on (one of the list below)
* bug
* chore
* feature
* hotfix
* research
1. The Github issue number prefixed with UIDS (e.g. UIDS-123)
1. A short description of the task to be done (e.g. improve-documentation)

An example of this would be `feature/UIDS-123-improve-documentation`

When you are ready for feedback:
* Request a review from at least one senior developer.
* Request a review from at least one designer if your PR has user-facing changes.
* Anyone should feel free to leave feedback on any PR, even if your review was not specifically requested.
* As the developer who opened the PR, please be sure to respond to all feedback, even if just to say that you had considered it but did not make a corresponding change.

## Merge process

Once your pull request has been approved by all parties, you may begin the merge process:
* Merge in the latest `main` and resolve any conflicts if needed.
* Run `yarn lint` to ensure no new styling errors are returned.
* Run `yarn test` to ensure tests are passing.
* Click the Squash and merge button on your pull request and edit your commit message to a concise description of your changes.

## Release process

Expand All @@ -134,39 +119,4 @@ To create a new release off of `main`:
* Select the version you want to release
* This will build the project and create a new release off of the latest `main`

## Manual Release steps

If you are not able to or choose not to use the github actions described above, the following is the process to manually create a new release. Once you have commits ready to bundle you may begin the release process:
* Update the "version" field in package.json.
* Run `yarn build` to compile the source files and write out to the lib directory.
* Run `npm pack` to archive all of the source files. Note: you can run `npm pack --dry-run` to see a list of files that will be included in the package. This is useful to double check a new component is being added or to see the size of the package/individual files.
* Run `npm publish` to publish the package to Github's registry.
* Draft a new release in the Github [repo](https://github.com/user-interviews/ui-design-system/releases).
* Use the version number from package.json in the "Tag version" field.
* Run `git log $(git describe --tags --abbrev=0)..HEAD --oneline` to get a list of all commits since the latest release and copy these into the "Describe this release" field.
* Upload the binary that was created from running `npm pack`.
* Publish release.

## Developing against the Rails Server repo

### Starting up development

1. Add `RAILS_SERVER_PATH` to a `.env` of this application
*this will be the path to rails-server in your local machine*
1. Run these commands inside the root of the DS repo:

````bash
yarn rs:link
# or using nodemon
yarn rs:link:watch
````

💡 at this point you should see a nodemon process running

### Wrapping up development

1. Run these commands inside the root of the DS repo:

````bash
yarn rs:unlink
````
By this point, the updates should be published to Storybook and you will be able to consume the package on `rails-server`. You can grab the package by clicking on "Releases" tab and double-clicking on the package (e.g. user-interviews-ui-design-system-3.5.0.tgz) and copying the link.

0 comments on commit 2796341

Please sign in to comment.