{"id":14985541,"url":"https://github.com/orchestrated-io/orcs-design-system","last_synced_at":"2025-04-11T22:02:52.067Z","repository":{"id":37829405,"uuid":"146369360","full_name":"orchestrated-io/orcs-design-system","owner":"orchestrated-io","description":"TeamForm Design System - ORCS","archived":false,"fork":false,"pushed_at":"2024-05-23T01:59:12.000Z","size":21432,"stargazers_count":9,"open_issues_count":2,"forks_count":4,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-05-23T06:36:18.784Z","etag":null,"topics":["design-system","orcs","react","storybook","styled-components","styled-system","teamform"],"latest_commit_sha":null,"homepage":"https://styleguide.orchestrated.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orchestrated-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-ci-strict.json","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-28T00:24:28.000Z","updated_at":"2024-08-07T07:00:39.324Z","dependencies_parsed_at":"2022-06-23T04:54:29.348Z","dependency_job_id":"cf76f6d6-cc1f-45a7-93af-691e30c487e2","html_url":"https://github.com/orchestrated-io/orcs-design-system","commit_stats":{"total_commits":1331,"total_committers":24,"mean_commits":"55.458333333333336","dds":0.5454545454545454,"last_synced_commit":"8d2fa1990380054a792167348ce339f5d11a281e"},"previous_names":[],"tags_count":507,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrated-io%2Forcs-design-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrated-io%2Forcs-design-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrated-io%2Forcs-design-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orchestrated-io%2Forcs-design-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orchestrated-io","download_url":"https://codeload.github.com/orchestrated-io/orcs-design-system/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239785299,"owners_count":19696751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-system","orcs","react","storybook","styled-components","styled-system","teamform"],"created_at":"2024-09-24T14:11:10.411Z","updated_at":"2025-02-20T05:32:05.925Z","avatar_url":"https://github.com/orchestrated-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ORCS: TeamForm's Design System\n\n## featuring Styled System + Styled Components\n\n[GitHub repository](https://github.com/orchestrated-io/orcs-design-system) | [Deployed on GitHub Pages](https://orchestrated-io.github.io/orcs-design-system/)\n\n[![npm version](https://badge.fury.io/js/orcs-design-system.svg)](https://badge.fury.io/js/orcs-design-system) ![GitHub last commit](https://img.shields.io/github/last-commit/orchestrated-io/orcs-design-system) [![GitHub license](https://img.shields.io/github/license/orchestrated-io/orcs-design-system.svg)](https://github.com/orchestrated-io/orcs-design-system/blob/master/LICENSE)\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Forchestrated-io%2Forcs-design-system.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Forchestrated-io%2Forcs-design-system?ref=badge_large)\n\n## Getting Started\n\nClone repository:\n\n```\ngit clone https://github.com/orchestrated-io/orcs-design-system.git\n```\n\nInstall dependencies:\n\n```\nnpm install\n```\n\n### Run the ORCS Storybook\n\nStart the ORCS development server:\n\n```\nnpm run storybook\n```\n\nA new browser window will open with a random localhost port. ORCS runs [Storybook 7](https://github.com/storybookjs/storybook/releases).\n\n## Working with ORCS\n\nAll library components and files are located in `/lib`. Static files are located in `/assets`.\n\n### Viewing changes in PM / TD.\n\nAs an alternative to `npm link` you can run `npm run dist` and then copy the `es` folder directly into TD or PM:\n\n`cp -R es/ ../../../team-directory/node_modules/orcs-design-system/`\n\n**_This has now been been made easier with using Nodemon and a custom script. Read on for how to set this up._**\n\n### Working with orcs locally (hot reloading).\n\n1. `cp .env.example .env`\n2. 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.\n3. Add any projects to `CONSUMERS` in `.env` separated by ',' e.g. `CONSUMERS=my-app,your-app,our-app`\n4. IF APPLICABLE: Add the following to your webpack configuration\n\n```\n...\nsnapshot: {\n    managedPaths: [/^(.+?[\\\\/]node_modules)[\\\\/]((?!orcs-design-system)).*[\\\\/]*/]\n}\n...\n```\n\n5. Run `npm run dev`.\n\nNow 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.\n\n### Symlinking with `npm link`\n\n##### We haven't had much success with this recently\n\nIf you need to do `npm link` in your local environment you might encounter the following issues:\n\n- https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react\n- https://github.com/styled-components/styled-components/issues/2379\n\nBoth 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.\n\nIn `orcs-design-system` folder:\n\n```\nnpm link {PATH_APP_REPO}/node_modules/react\nnpm link {PATH_APP_REPO}/node_modules/styled-components\nnpm link\n```\n\nIn `{PATH_APP_REPO}`:\n\n```\nnpm i orcs-design-system\nnpm link orcs-design-system\nnpm start\n```\n\n### Testing\n\n```\nnpm run test\n```\n\n### Publishing changes\n\nIn order to publish a new version, you will have to patch and push your changes.\nAfter your changes have been merged to master, from your master branch:\n\n```\nnpm version patch\ngit push\n```\n\n### Deploying to GitHub Pages\n\nORCS automatically deploys to GitHub Pages when a new version is published. To manually deploy:\n\n```\nnpm run deploy-storybook\n```\n\n## Using ORCS in a project\n\nIn your project's root, install ORCS and styled-components:\n\n```\nnpm i orcs-design-system\nnpm i styled-components\n```\n\n### Using components\n\nOnce ORCS is installed, you can directly import components. For example, for `Box`:\n\n```\nimport { Box } from \"orcs-design-system\"\n...\n\u003cBox\u003e\n...\n\u003c/Box\u003e\n```\n\nThe [ORCS Storybook](https://orchestrated-io.github.io/orcs-design-system) contains documentation for each component, including code examples and props tables.\n\nFor components with subcomponents, each subcomponent must be imported. For example, to use `Tabs`:\n\n```\nimport { TabsContainer, Tab } from \"orcs-design-system\"\n```\n\n### Using Styled System props\n\nThe design system components are built with [Styled System](https://styled-system.com/) 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.\n\nAs a guide to using these props, see the [Styled System reference table](https://styled-system.com/table).\n\nThe 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).\n\nYou may also find it useful to install the following Styled System utilities: theme-get and css.\n\n```\nnpm i @styled-system/theme-get\nnpm i @styled-system/css\n```\n\n### Theming\n\nThis 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.\n\n```\nimport { ThemeProvider } from \"styled-components\"\n\u003cThemeProvider theme={theme}\u003e\n\u003cApp /\u003e\n\u003c/ThemeProvider\u003e\n```\n\nVariables 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).\n\n### Using icons\n\nYou will need to add the icon library that we are using (which is Font Awesome). To do this, install the Font Awesome packages:\n\n```\nnpm i @fortawesome/react-fontawesome\nnpm i @fortawesome/fontawesome-svg-core\nnpm i @fortawesome/free-regular-svg-icons\nnpm i @fortawesome/free-solid-svg-icons\n```\n\nThen add this to the top of your root app file:\n\n```\nimport { library } from '@fortawesome/fontawesome-svg-core'\nimport {far} from '@fortawesome/free-regular-svg-icons'\nimport {fas} from '@fortawesome/free-solid-svg-icons'\nlibrary.add(far, fas);\n```\n\nAlternatively, you can use the full icon packages if you purchase Font Awesome Pro license.\n\nOnce 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:\n\n```\n@fortawesome:registry=https://npm.fontawesome.com\n//npm.fontawesome.com/:_authToken=FONT_AWESOME_NPM_TOKEN_GOES_HERE\n```\n\nFor further usage guidelines for the Icon component, [see the Icon docs](http://localhost:55322/?path=/docs/components-icon--default-icon).\n\n## Sandbox environment for playing with orcs, via [playroom](https://github.com/seek-oss/playroom):\n\nPlayroom allows you to simultaneously design across a variety of themes and screen sizes, powered by JSX and your own component library.\n\nPlayroom 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.\n\nTo run playroom, use this command: `npm run playroom`\n\n## Browser/device support\n\nThis design system is intended to work correctly on all modern desktop and mobile browsers.\n\n---\n\n\u003e \"A design system is a living, funded product with a roadmap and backlog, serving an ecosystem.\" — Nathan Curtis\n\n## Security vulnerability checks\n\nThe `audit-ci` command runs to detect any **high** and **critical** severity security vunerabilities. Currently this runs:\n\n- as a part of the 'ci' github action before publishing a package (ci.yml)\n- as part of the PR and push workflow (pr.yml)\n\nThis means we effectively stop the line for any high or critical security issues.\n\nTo run locally:\n\n```\nnpm run audit-ci\n\n```\n\nor\n\n```\nnpx audit-ci\n```\n\nThis uses the default configuration file [audit-ci.json](audit-ci.json).\n\n### Addressing security issues\n\nMore information on the specific vunerabilities can be found by adding the `--report` flag.\n\n`npm run audit-ci -- --report`\nor\n`npx audit-ci --report`\n\nThe 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.\n\nYou may find it easier to update issues invidually or by using `npm update DEP_NAME --depth nnn` or simlar.\n\n### Allow list configuration\n\nPresently we have a number of high-criticality security issues in the allow list (see [audit-c.json](audit-ci.json).\n\n**TODO** Add more information on the allowed vunerabilities as comments in the config file.\n\n### Strict mode checking\n\nWe 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:\n\nTriggering the GH action directly on a specific branch (including master):\n\n```\ngh workflow run security.yml --ref BRANCH_NAME\n\n```\n\n(add -f mode=notstrict to make it run the default audit-ci config if you wish)\n\nOr locally:\n\n```\nnpm run audit-ci:strict\n```\n\nThis gives a fuller view of the vunerabilities relevant to the codebase.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forchestrated-io%2Forcs-design-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forchestrated-io%2Forcs-design-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forchestrated-io%2Forcs-design-system/lists"}