You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
7
7
8
-
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.
-[Storybook development (Under construction 🚧)](#storybook-development)
23
+
-[Chromatic visual testing (Under construction 🚧)](#chromatic-visual-testing)
24
+
-[Release process](#release-process)
12
25
13
-
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.
26
+
## Getting started
14
27
15
-
## Storybook Documentation
28
+
### Initial Setup
29
+
After cloning the repo, obtain a `.npmrc` file from another developer. This file contains authorization tokens for any private
- For every component, we typically illustrate common use cases for different variants or states of a component.
22
-
- 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).
23
-
- 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.
24
-
- We encourage all contributors to the Design System (engineers, designers, product) to add to our documentation.
35
+
`yarn storybook`
36
+
_Launches the Storybook server._
25
37
38
+
`yarn install`
39
+
_Installs all yarn dependencies._
26
40
27
-
## Steps to update any documentation file
41
+
`yarn test`
42
+
_Runs the jest test suite._
28
43
29
-
### `yarn install`
44
+
`yarn lint`
45
+
_Runs ESLint to report on any style violations._
30
46
31
-
Installs all yarn dependencies
47
+
`bin/migrate-stack`
48
+
_Installs specific Node.js and Yarn versions with Volta, creates a .env file, and adds an FONTAWESOME_NPM_AUTH_TOKEN to it._
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.
52
+
It is often helpful to see how new updates on the design system are consumed in-app by locally linking the two repositories.
36
53
37
-
### `yarn storybook`
54
+
Add `RAILS_SERVER_PATH` to a `.env` of this application
55
+
_This will be the path to rails-server in your local machine._
38
56
39
-
Launches the Storybook server.<br />
57
+
`yarn rs:link`
58
+
_Creates symlinks for packages needed to develop/debug against our `rails-server` repository._
40
59
41
-
- In the code editor of your choice, navigate to the Component library found under src `ui-design-system/src`
42
-
- 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.
43
-
- While Storybook is running, you should be able to view any changes you make to the `mdx` file after saving your changes.
44
-
- Push your changes to Github and submit for a review / pull request.
60
+
`yarn rs:link:watch`
61
+
_Trigger a production build when files are changed._
45
62
46
-
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.
63
+
`yarn rs:unlink`
64
+
_Remove symlinked packages when you're finished._
47
65
66
+
### Pull requests
48
67
49
-
# Developer Resources
68
+
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.
50
69
51
-
## Initial Setup
52
-
After cloning the repo, obtain a `.npmrc` file from another developer. This file contains authorization tokens for any private
53
-
node packages.
54
70
55
-
## Available Scripts
56
-
In the project directory, you can run:
57
-
58
-
### `yarn storybook`
71
+
## Contributing
59
72
60
-
Launches the Storybook server.
73
+
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!
61
74
62
-
### `yarn install`
75
+
### How you can help
63
76
64
-
Installs all yarn dependencies
77
+
#### Slack channels
65
78
66
-
### `yarn test`
79
+
We have a couple Slack channels where you can discuss all things design system or share your feedback
80
+
-[#dev-design-system](https://userinterviews.slack.com/archives/C06J56K92EL)_General channel for design system topics_
81
+
-[#ds-gardening](https://userinterviews.slack.com/archives/G01P02LNJTF)_Core design system team channel. All are welcome!_
67
82
68
-
Runs the jest test suite
83
+
#### Open a Linear issue
69
84
70
-
### `yarn lint`
85
+
We use Linear as our project management tool to track all our design system issues.
71
86
72
-
Runs ESLint to report on any style violations
87
+
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.
73
88
74
-
###`yarn rs:link`
89
+
#### Flag @user-interviews/design-system
75
90
76
-
Creates symlinks for packages needed to develop/debug against our `rails-server` repository.
91
+
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!
77
92
78
-
### `yarn rs:link:watch`
79
93
80
-
Trigger a production build when files are changed.
## Chromatic visual testing (Under construction 🚧)
85
101
86
-
## Chromatic visual testing & live feedback
87
102
We use [Chromatic](https://www.chromatic.com/) for visual testing and gathering UI feedback.
88
103
89
-
To join Chromatic for 'ui-design-system', ask Jason for the join link.
104
+
To join Chromatic for 'ui-design-system', ask the design system lead for the join link.
90
105
91
106
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.
92
107
@@ -95,33 +110,6 @@ If you are a Developer and want to trigger a Chromatic build,
95
110
2. Go to the Manage tab for 'ui-design-system' > Configure > Find the project token.
96
111
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.
97
112
98
-
## Pull requests
99
-
100
-
Our branch names consist of 3 parts:
101
-
1. The type of task we are working on (one of the list below)
102
-
* bug
103
-
* chore
104
-
* feature
105
-
* hotfix
106
-
* research
107
-
1. The Github issue number prefixed with UIDS (e.g. UIDS-123)
108
-
1. A short description of the task to be done (e.g. improve-documentation)
109
-
110
-
An example of this would be `feature/UIDS-123-improve-documentation`
111
-
112
-
When you are ready for feedback:
113
-
* Request a review from at least one senior developer.
114
-
* Request a review from at least one designer if your PR has user-facing changes.
115
-
* Anyone should feel free to leave feedback on any PR, even if your review was not specifically requested.
116
-
* 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.
117
-
118
-
## Merge process
119
-
120
-
Once your pull request has been approved by all parties, you may begin the merge process:
121
-
* Merge in the latest `main` and resolve any conflicts if needed.
122
-
* Run `yarn lint` to ensure no new styling errors are returned.
123
-
* Run `yarn test` to ensure tests are passing.
124
-
* Click the Squash and merge button on your pull request and edit your commit message to a concise description of your changes.
125
113
126
114
## Release process
127
115
@@ -134,39 +122,4 @@ To create a new release off of `main`:
134
122
* Select the version you want to release
135
123
* This will build the project and create a new release off of the latest `main`
136
124
137
-
## Manual Release steps
138
-
139
-
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:
140
-
* Update the "version" field in package.json.
141
-
* Run `yarn build` to compile the source files and write out to the lib directory.
142
-
* 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.
143
-
* Run `npm publish` to publish the package to Github's registry.
144
-
* Draft a new release in the Github [repo](https://github.com/user-interviews/ui-design-system/releases).
145
-
* Use the version number from package.json in the "Tag version" field.
146
-
* 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.
147
-
* Upload the binary that was created from running `npm pack`.
148
-
* Publish release.
149
-
150
-
## Developing against the Rails Server repo
151
-
152
-
### Starting up development
153
-
154
-
1. Add `RAILS_SERVER_PATH` to a `.env` of this application
155
-
*this will be the path to rails-server in your local machine*
156
-
1. Run these commands inside the root of the DS repo:
157
-
158
-
````bash
159
-
yarn rs:link
160
-
# or using nodemon
161
-
yarn rs:link:watch
162
-
````
163
-
164
-
💡 at this point you should see a nodemon process running
165
-
166
-
### Wrapping up development
167
-
168
-
1. Run these commands inside the root of the DS repo:
169
-
170
-
````bash
171
-
yarn rs:unlink
172
-
````
125
+
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 commit comments