Synthesis is the official design system of User Interviews. It offers design guidelines and reusable components to streamline the creation of product features, focusing on usability, accessibility, and efficiency while enhancing teamwork.
Public Storybook Documentation
- Getting started
- Contributing
- Storybook development (Under construction 🚧)
- Chromatic visual testing (Under construction 🚧)
- Release process
After cloning the repo, obtain a .npmrc file from another developer. This file contains authorization tokens for any private
node packages.
In the project directory, you can run:
yarn storybook
Launches the Storybook server.
yarn install
Installs all yarn dependencies.
yarn test
Runs the jest test suite.
yarn lint
Runs ESLint to report on any style violations.
bin/migrate-stack
Installs specific Node.js and Yarn versions with Volta, creates a .env file, and adds an FONTAWESOME_NPM_AUTH_TOKEN to it.
It is often helpful to see how new updates on the design system are consumed in-app by locally linking the two repositories.
Add RAILS_SERVER_PATH to a .env of this application
This will be the path to rails-server in your local machine.
yarn rs:link
Creates symlinks for packages needed to develop/debug against our rails-server repository.
yarn rs:link:watch
Trigger a production build when files are changed.
yarn rs:unlink
Remove symlinked packages when you're finished.
We merge directly into main and your branch name should correspond to a Linear issue on the UI Design System Updates 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.
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!
We have a couple Slack channels where you can discuss all things design system or share your feedback
- #dev-design-system General channel for design system topics
- #ds-gardening Core design system team channel. All are welcome!
We use Linear as our project management tool to track all our design system issues.
Whether you're adding an issue to our UI Design System Updates 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.
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!
We use Chromatic for visual testing and gathering UI feedback.
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.
If you are a Developer and want to trigger a Chromatic build,
- Join Chromatic for the 'ui-design-system' (ask Jason for the join link).
- Go to the Manage tab for 'ui-design-system' > Configure > Find the project token.
- 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.
This package uses Semantic versioning, which requires version numbers in MAJOR.MINOR.PATCH format. Any breaking changes to the API require an update to the MAJOR version. Backwards compatible changes only require an update to the MINOR version. Hotfixes and patches need only update the PATCH version.
To create a new release off of main:
- Run the "Create new release" github action found under "Actions"
- Click "Run workflow" and select the following:
- Choose
mainas the branch - Select the version you want to release
- Choose
- This will build the project and create a new release off of the latest
main
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.