# 
## [MS Teams](https://teams.microsoft.com/l/channel/19%3ac2273990484947eb8d38819f59708da9%40thread.tacv2/Fabric%2520UI%2520-%2520Build%2520Noise?groupId=bc3c203b-9502-46d7-99f7-928468491641&tenantId=570057f4-73ef-41c8-bcbb-08db2fc15c2b)
> react components & styles for fanatical interfaces [https://particles.janus.team/](https://particles.janus.team/)
In Depth docs:
- [Changelog](https://github.com/racker/janus-particles/blob/master/CHANGELOG.md)
- [Contributing Guide](https://github.com/racker/janus-particles/blob/master/CONTRIBUTING.md)
- [Vision](https://github.com/racker/janus-particles/blob/master/docs/vision.md)
- [FAQ](https://github.com/racker/janus-particles/blob/master/docs/faq.md)
- [Divergences with Helix](https://github.com/racker/janus-particles/blob/master/docs/divergences.md)
- [Hindsight](https://github.com/racker/janus-particles/blob/master/docs/hindsight.md)
Readme Contents:
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Vision](#vision)
- [Local Development](#local-development)
- [Feedback](#feedback)
## Missing Something? Something Broken?
Please [create an issue](https://github.com/racker/janus-particles/issues/new) and let us know.
We will use issues as a way to track things found by ourselves and by
others and eventually convert those into cards to be worked on for our backlog.
Of course you're also welcome to [submit a PR and make the changes yourself](https://github.com/racker/janus-particles/blob/master/CONTRIBUTING.md).
## Semantic Versioning
`janus-particles` adheres to the usual semver guidelines:
- major version bumps for (most - except previously announced deprecation cases) breaking changes.
- minor version bumps for new features or significant improvements or (some - previously announced deprecation) breaking changes.
- revision version bumps for bugfixes or small improvements.
#### Pre/Alpha/Beta/RC releases
`janus-particles` does not officially support nor endorse the usage of any non-final releases. By non-final release we mean anything with a `-` suffix in the version number (e.g.: `5.0.0-alpha001`).
We _internally_ do use extensively releases with `-rc/alpha/beta/pre` suffixes for the purposes of extensive testing, but we do not recommend ever using any of those in a production environment, nor to rely that anything in any such release will ever stay the same in the final release.
## Quick Start
### Install with npm or yarn
```sh
npm i @janus.team/janus-particles
# or
yarn add @janus.team/janus-particles
```
#### Peer dependencies
```sh
yarn add\
@janus.team/janus-particles@^4.16\
@janus.team/janus-copilot@^3.1.1\
@formatjs/intl-pluralrules\
@formatjs/intl-relativetimeformat@^4.4.0\
@sentry/browser@^5.7.1\
@tippy.js/react@^3.1.1\
classnames@^2.2.5\
crypto@^1.0.1\
downshift@^3.2.10\
font-awesome@^4.7.0\
intl\
intl-format-cache@^4.2.2\
intl-locales-supported\
intl-messageformat-parser@^3.2.1\
intl-messageformat@^7.3.2\
js-cookie@^2.2.0\
lodash@^4.17.11\
moment-timezone@^0.5.21\
moment@^2.18.1\
object-assign@^4.1.1\
prop-types@^15.5.10\
qs@^6.7.0\
react-datetime@^2.11.1\
react-intl@^3.3.2\
react-router-dom@^4.3.1\
react-tippy@^1.2.3\
uuid@^3.3.2\
verror@^1.10.0\
victory@^0.24.1
# yes, this is a lot - sorry. we are not happy about it either : (
```
### Usage
#### Javascript
```js
import { Button } from '@janus.team/janus-particles';
...
```
#### CSS
Add the particles css to your build.
```js
import 'font-awesome/css/font-awesome.css';
import 'react-tippy/dist/tippy.css';
import '@janus.team/janus-particles/dist/particles.css';
```
#### Jest
You need `react-scripts@3.2` (at least).
Add this to your `package.json`:
```js
"jest": {
"transformIgnorePatterns": [
"(?!.*janus.*)(?!.*@babel/runtime.*)node_modules"
]
}
```
## Documentation
Complete docs available in the [particles storybook](https://particles.janus.team/).
**Where are prop tables and story source code?!**
As of version `5.0.0` we made the hard decision to no longer support those features (in that format at least). There has been an extensive set of problems with the `@storybook/addon-info` that powers both of those pieces and we decided to no longer use it.
The good news, however, is that the `storybook` team itself agrees that a better approach was necessary and have started to rollout `@storybook/addon-docs` that should cover both source code for stories and prop tables in a more sane way. We envision particles making heavy use of these new features in the near future (backfilling docs for old components) and using it as the default for new development.
We ask for your understanding and patience in this transition period, and meanwhile we suggest [reading the source](https://github.com/racker/janus-particles) as a stopgap measure to understand how the code behind a story looks or to read comments around props in a component.
## Vision
This project aims to help scale the development of Janus frontend applications through the use of reusable and self contained react components.
- This is a single, centralized place to share our teams' frontend development best practices.
- Including particles in your app should never interfere with any other styles or behavior, it is meant to be consumed by real world production applications without disrupting anything around it. All styles are opt-in by design and components are independent.
- This aims to provid a reduced the time to ship new features, through:
- documentation for components
- copy/paste examples
- versioned components
- clarification around approaches to state management
#### Particles vs Helix
- the Helix design is the look and feel for Rackspace, any discrepancy from it in particles will be considered as a bug unless explicitly listed in the [known divergences doc](https://github.com/racker/janus-particles/blob/master/docs/divergences.md).
- if something in particles looks different than helix, here are your (non-mutually-exclusive) options:
- ask around in [#janus-ux](https://rackspace.slack.com/archives/GCCRCSGLX) and/or [#rss-eng](https://rackspace.slack.com/archives/CPAR76ZUH).
- change your code with extra CSS to match helix.
- open a PR to particles to change it to match helix.
- open an issue to particles to ask for changes to match helix.
- open a PR to particles to add to the known list of divergences if you think that particles is more correct.
- talk to the [helix team in #helix](https://rackspace.slack.com/archives/C1ZPBPYKZ) if you think helix itself should change.
- the helix ui toolkit is a particular implementation of the helix design system and can be seen as an alternative (less janus opinionated) to particles. We strongly **disencourage using both** the helix toolkit and particles in the same project.
You can [read a lot more about it here](https://github.com/racker/janus-particles/blob/master/docs/vision.md) if you want an extensive description about this history.
#### Success Measurements
- Pages look and feel the same accross multiple Janus UIs, be it the legacy `janus-ui` or any micro/mini UIs developed under the Janus UI Platform.
- Potential expansion outside of the Janus tribe (e.g.: RSS org).
- Alignment with the look and feel of the helix design framework.
## Local Development
[Install yarn](https://yarnpkg.com/en/docs/install)
- Install lib dependencies with `yarn install`
- Run tests with `yarn test` (if you have an issue on OSX Sierra+ with watchman, try `brew install watchman`)
- Lint with `yarn lint`
- Build components with `yarn build`
#### Preview Documentation
### Storybook
We use [react storybook](https://storybook.js.org/) to document components. To launch the local development server, run:
```
yarn start
```
### Table of Contents
The table of contents found at the root of our documentation site is built with [create-react-app](https://github.com/facebookincubator/create-react-app). To preview this locally, run:
```
cd docs
yarn start
```
Then visit [localhost:3000](http://localhost:3000) on your browser of choice.
#### Export documentation
You can export the documentation site to a static build with:
```
yarn run build:docs
```
To build older versions of documentation, update `docs/versions.json` with the tagged versions to build. Then run `yarn build:doc-versions`. To publish these versions to S3, grab the AWS credentials for the environments dev and prod. You can deploy to the desired enviroment via: `yarn publish:doc-versions `. Example deploy to dev: `yarn publish:doc-versions dev`.
During build in jenkins, docs are automatically published:
- [particles.janus.team/versions/master/index.html](https://particles.janus.team/versions/master/index.html) & [particles.dev.janus.team/versions/master/index.html](https://particles.dev.janus.team/versions/master/index.html) (for master branch builds)
- `https://particles.dev.janus.team/versions/{sha}/index.html` - 6 character git commit sha
- `https://particles.janus.team/versions/{tag}/index.html` - tagged release
## Feedback
Check us out on slack at [#janus-ux](https://rackspace.slack.com/archives/GCCRCSGLX) and/or [#rss-eng](https://rackspace.slack.com/archives/CPAR76ZUH).