ORCS: TeamForm's Design System

featuring Styled System + Styled Components

GitHub repository | Deployed on GitHub Pages

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.

Working with ORCS

All library components and files are located in /lib. Static files are located in /assets.

Viewing changes in PM / TD.

As an alternative to npm link you can run npm run dist and then copy the es folder directly into TD or PM:

cp -R es/ ../../../team-directory/node_modules/orcs-design-system/

This has now been been made easier with using Nodemon and a custom script. Read on for how to set this up.

Working with orcs locally (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.

Symlinking with npm link

We haven't had much success with this recently

If you need to do npm link in your local environment you might encounter the following issues:

• https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react
• https://github.com/styled-components/styled-components/issues/2379

Both react and styled-components cause duplicate instance issue after npm link, to fix that we need to ensure both app project and lib project are sharing the same instance of them.

In orcs-design-system folder:

npm link {PATH_APP_REPO}/node_modules/react
npm link {PATH_APP_REPO}/node_modules/styled-components
npm link

In {PATH_APP_REPO}:

npm i orcs-design-system
npm link orcs-design-system
npm start

Testing

npm run test

Publishing changes

In order to publish a new version, you will have to patch and push your changes. After your changes have been merged to master, from your master branch:

npm version patch
git push

Deploying to GitHub Pages

ORCS automatically deploys to GitHub Pages when a new version is published. To manually deploy:

npm run deploy-storybook

Using ORCS in a project

In your project's root, install ORCS and styled-components:

npm i orcs-design-system
npm i styled-components

Using components

Once ORCS is installed, you can directly import components. For example, for Box:

import { Box } from "orcs-design-system"
...
<Box>
...
</Box>

The ORCS Storybook contains documentation for each component, including code examples and props tables.

For components with subcomponents, each subcomponent must be imported. For example, to use Tabs:

import { TabsContainer, Tab } from "orcs-design-system"

Using Styled System props

The design system components are built with 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.

The design system's theme scales are contained in systemtheme.

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"
<ThemeProvider theme={theme}>
<App />
</ThemeProvider>

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.

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.

Sandbox environment for playing with orcs, via 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.

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 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.

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.