1
1
mirror of https://github.com/primer/css.git synced 2024-12-25 07:03:35 +03:00
css/docs/stories/Contributing.mdx
Jon Rohan e1b3f4f4bd
Remove yarn in favor of npm (#2443)
* Remove yarn in favor of npm

* Create tame-turkeys-laugh.md

* Check in package-lock

* Revert

* Use auto commit action instead

* Cache and run npm ci

* Change node version to 18

* config legacy-peer-deps

* Update node version

* Also legacy peer deps in docs

* Ignore yarn.lock

* no-audit no-fund

* I dont know

* re-yarn the docs folder

* Update pakage-lock.json

* package lock

* Removing yarn from docs again

* Remove docs preview

* don't depend on deploy

* put back

---------

Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com>
2023-07-13 16:40:26 -07:00

44 lines
3.9 KiB
Plaintext

While this contributing guide is for GitHub employees, all contributions from the community are welcome.
## Adding new utilities
Utilities do one thing well and one thing only. These styles are immutable and therefore often use the `!important` tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions:
- How does this new utility fit within our existing set of utilities? If it is an addition to an existing set then it should follow the same naming convention.
- Is it for a property that would likely need to be changed at different breakpoints? If so it may need responsive options.
- If this style is part of a family of properties, do we need to consider adding the full set? Reasons for adding a full set could be that the other property values are often used, or that there would be a need to switch the property on and off (such as display or visibility).
- Does introducing this new utility cause any clashes or potential confusion with the use of existing utilities? If so, what steps can we take to avoid those issues.
- Does the utility have a connection with a set of variables? If so do the corresponding variables need to be updated?
## Step-by-step instructions for adding new styles
### Step 1: Open an issue
It's usually better to open an issue before investing time in spiking out a new pattern. This gives the design systems team a heads up and allows other designers to share thoughts. Here's an outline of what's helpful to include in a new style issue:
1. What the pattern is, and how it's being used on GitHub.com. Post screenshots and/or URLs whenever possible. If you need help identifying where the pattern is used, call that out in the issue.
2. Why you think a new pattern is needed (this should answer the relevant questions above).
3. If you intend to work on these new styles yourself, let us know what your timeline and next steps are. If you need help and this is a dependency for shipping another project, please make that clear here and what the timeline is.
### Step 2: Design and build the new styles
- When you're ready, spike out a branch and build out your new utility according to the style guide principles, ensuring you follow our naming convention for each of the styles.
- Refactor parts of the product where you think those new styles could be used to test they work for each use case. This does not mean for every instance, but enough of the key use cases to be sure the styles are flexible enough. To avoid blowing out your initial pull request we recommend you do larger amounts of refactoring in an additional branch.
- When you're ready for review, change your pull request from "Draft" to "Ready for review"
## Storybook
We use [Storybook](https://storybook.js.org/) to document and test our CSS. You can run Storybook locally by running `npx storybook` and visiting the localhost server that is automatically started.
Stories are written with React for better compatibility with Storybook. Each utility should have a story that demonstrates its use. Stories are located in the `stories` directory.
### Versioning
Primer CSS follows [semantic versioning](http://semver.org/) conventions. This helps others know when a change is a patch, minor, or breaking change.
To understand what choice to make, you'll need to understand semver and know if one of the changes shown is a major, minor, or patch. Semver is confusing at first, so we recommend reviewing [semver](http://semver.org/) and/or asking the team by [opening an issue](#step-1-open-an-issue).
[semantic versioning]: https://semver.org
[script/test-deprecations.js]: https://github.com/primer/css/tree/main/script/test-deprecations.js
[deprecations.js]: https://github.com/primer/css/tree/main/deprecations.js