# ORCS: TeamForm's Design System
## featuring Styled System + Styled Components
[GitHub repository](https://github.com/orchestrated-io/orcs-design-system) | [Deployed on GitHub Pages](https://orchestrated-io.github.io/orcs-design-system/)
[](https://badge.fury.io/js/orcs-design-system)  [](https://github.com/orchestrated-io/orcs-design-system/blob/master/LICENSE)
[](https://app.fossa.io/projects/git%2Bgithub.com%2Forchestrated-io%2Forcs-design-system?ref=badge_large)
## Getting Started
Clone repository:
```
git clone https://github.com/orchestrated-io/orcs-design-system.git
```
Install dependencies:
```
npm install
```
### Run the ORCS Storybook
Start the ORCS development server:
```
npm run storybook
```
A new browser window will open with a random localhost port. ORCS runs [Storybook 7](https://github.com/storybookjs/storybook/releases).
## Working with ORCS
All library components and files are located in `/lib`. Static files are located in `/assets`.
### Viewing local orcs changes in other projects (with hot reloading)
1. `cp .env.example .env`
2. OPTIONAL: Update `WORKING_DIR` in `.env` if orcs resides in a different working directory to your project. Else-wise Orcs will assume the project is one level up from itself.
3. Add any projects to `CONSUMERS` in `.env` separated by ',' e.g. `CONSUMERS=my-app,your-app,our-app`
4. IF APPLICABLE: Add the following to your webpack configuration
```
...
snapshot: {
managedPaths: [/^(.+?[\\/]node_modules)[\\/]((?!orcs-design-system)).*[\\/]*/]
}
...
```
5. Run `npm run dev`.
Now you can make any changes in orcs and it will build and then copy the es from the build into your project's node_modules. Run `npm install` in your project dir if you want to revert to the npm installation.
### Publishing changes
In order to publish a new version, bump the version in your PR branch before merging. The master branch is locked to direct pushes, so the version must be updated in your branch/PR.
```
npm version patch
git push
```
This will bump the patch version and create a commit. Push to your branch so the version is included in your PR. When the PR is merged to master, GitHub Actions will publish the new version to npm using the version in `package.json`.
**Note:** When publishing to public npm, the version is automatically deprecated with a migration message directing users to GitHub Packages. This ensures all users see the deprecation warning when installing.
### Deploying to GitHub Pages
ORCS automatically deploys to GitHub Pages when a new version is published and merged to master. To manually deploy:
```
npm run deploy-storybook
```
## Using ORCS in a project
### GitHub Packages (Recommended)
For internal repositories, use the GitHub Packages version `@orchestrated-io/orcs-design-system`. This package is published in parallel with the public version and uses your existing GitHub authentication.
**Setup:**
1. Add `.npmrc` to your repository root with the following content:
```ini
@orchestrated-io:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```
2. Update `package.json` to use npm aliases (no code changes needed):
```json
{
"dependencies": {
"orcs-design-system": "npm:@orchestrated-io/orcs-design-system@^3.4.1"
}
}
```
3. Install: `npm install`
**Note:** In GitHub Actions, `GITHUB_TOKEN` is automatically available. For local development, set `GITHUB_TOKEN` as an environment variable with a Personal Access Token (with `read:packages` permission).
**Why use an alias?** By using `npm:@orchestrated-io/orcs-design-system`, you can keep your existing imports unchanged. You'll continue importing as `orcs-design-system` instead of having to update all files to use `@orchestrated-io/orcs-design-system`.
Your imports remain the same:
```javascript
import { Box } from 'orcs-design-system';
```
For detailed setup instructions, see [DOWNSTREAM_SETUP.md](./DOWNSTREAM_SETUP.md).
### Public Package (Deprecated)
> **⚠️ DEPRECATED**: The public npm package (`orcs-design-system`) is deprecated and being retired. The public npm version will be removed.
>
> **All versions are marked as deprecated on npm** - users will see a deprecation warning when installing.
>
> **For internal users:** See [DOWNSTREAM_SETUP.md](./DOWNSTREAM_SETUP.md) for migration to GitHub Packages.
### Using components
Once ORCS is installed, you can directly import components. For example, for `Box`:
```
import { Box } from "orcs-design-system"
...
...
```
The [ORCS Storybook](https://orchestrated-io.github.io/orcs-design-system) contains documentation for each component, including code examples and props tables.
### Using Styled System props
The design system components are built with [Styled System](https://github.com/styled-system/styled-system) props. Generally, components can access the `space` and `layout` prop categories, with additional prop categories on a per-component basis. Check the _Properties_ section in a component's documentation to see what props it can use. Custom props will be listed in the props table.
As a guide to using these props, see the [Styled System reference table](https://github.com/styled-system/styled-system/blob/master/docs/table.md).
The design system's theme scales are contained in [systemtheme](https://github.com/orchestrated-io/orcs-design-system/blob/master/packages/orcs-design-system/lib/systemtheme.js).
You may also find it useful to install the following Styled System utilities: theme-get and css.
```
npm i @styled-system/theme-get
npm i @styled-system/css
```
### Theming
This design system uses styled-components `ThemeProvider` and comes with a default theme, `systemtheme` that uses styled-system arrays. To apply the theme to your app, you can use `systemtheme` or your own theme object.
```
import { ThemeProvider } from "styled-components"
```
Variables can be referenced using `theme.arrayName.variableAlias`. When using Styled System props, components refer to the theme field associated with the prop as set out in the [reference table](https://styled-system.com/table).
### Styled Components v6
This design system uses **styled-components v6**. When creating or updating styled components, **always use the `&` prefix for pseudo-selectors** (e.g., `&:checked`, `&:focus`, `&:hover`) to ensure proper CSS specificity. See component documentation (e.g., Checkbox, Toggle) for examples.
### Using icons
You will need to add the icon library that we are using (which is Font Awesome). To do this, install the Font Awesome packages:
```
npm i @fortawesome/react-fontawesome
npm i @fortawesome/fontawesome-svg-core
npm i @fortawesome/free-regular-svg-icons
npm i @fortawesome/free-solid-svg-icons
```
Then add this to the top of your root app file:
```
import { library } from '@fortawesome/fontawesome-svg-core'
import {far} from '@fortawesome/free-regular-svg-icons'
import {fas} from '@fortawesome/free-solid-svg-icons'
library.add(far, fas);
```
Alternatively, you can use the full icon packages if you purchase Font Awesome Pro license.
Once you have purchased a license you need to add your Font Awesome NPM token as an environment variable in a .npmrc file at the root of your app in the following format:
```
@fortawesome:registry=https://npm.fontawesome.com
//npm.fontawesome.com/:_authToken=FONT_AWESOME_NPM_TOKEN_GOES_HERE
```
For further usage guidelines for the Icon component, [see the Icon docs](http://localhost:55322/?path=/docs/components-icon--default-icon).
## Sandbox environment for playing with orcs, via [playroom](https://github.com/seek-oss/playroom):
Playroom allows you to simultaneously design across a variety of themes and screen sizes, powered by JSX and your own component library.
Playroom allows you to create a zero-install code-oriented design environment, built into a standalone bundle that can be deployed alongside your existing design system documentation.
To run playroom, use this command: `npm run playroom`
## Browser/device support
This design system is intended to work correctly on all modern desktop and mobile browsers.
---
> "A design system is a living, funded product with a roadmap and backlog, serving an ecosystem." — Nathan Curtis
## Security vulnerability checks
The `audit-ci` command runs to detect any **high** and **critical** severity security vunerabilities. Currently this runs:
- as a part of the 'ci' github action before publishing a package (ci.yml)
- as part of the PR and push workflow (pr.yml)
This means we effectively stop the line for any high or critical security issues.
To run locally:
```
npm run audit-ci
```
or
```
npx audit-ci
```
This uses the default configuration file [audit-ci.json](audit-ci.json).
### Addressing security issues
More information on the specific vunerabilities can be found by adding the `--report` flag.
`npm run audit-ci -- --report`
or
`npx audit-ci --report`
The built in `npm audit` command provides a useful output too but will not use the [audit-ci.json](audit-ci.json) configuration file so `npm audit fix` will fix everything it can rather than a single vunerability.
You may find it easier to update issues invidually or by using `npm update DEP_NAME --depth nnn` or simlar.
### Allow list configuration
Presently we have a number of high-criticality security issues in the allow list (see [audit-c.json](audit-ci.json).
**TODO** Add more information on the allowed vunerabilities as comments in the config file.
### Strict mode checking
We have an additional 'strict' mode check that allows us to run a full audit including medium or low severity issues. With suitable user permissions, this can be run from a github action:
Triggering the GH action directly on a specific branch (including master):
```
gh workflow run security.yml --ref BRANCH_NAME
```
(add -f mode=notstrict to make it run the default audit-ci config if you wish)
Or locally:
```
npm run audit-ci:strict
```
This gives a fuller view of the vunerabilities relevant to the codebase.