orca - orchestrated design system with React Components

Getting Started

Clone repo

git clone https://github.com/orchestrated-io/orca-design-system.git

Install dependencies

npm install or yarn

Run the style guide

Start development server

npm start or yarn start

View style guide

Open http://localhost:6060 to view it in the browser.

All library files are located inside /lib

Publish style guide

• npm version patch

• git push --follow-tags

Testing

npm run test or yarn test

Onboard your project to Orca design system

• cd to your react app root folder

• npm i orca-design-system

• you will need to also use styled-components package to be able to use this design system

npm i styled-components or yarn add styled-components

then at top of file add import styled from 'styled-components';

• Ensure the colours and theme provider is included in your application like below:

  import { colours } from "orca-design-system";
  import {ThemeProvider} from "styled-components";

  ...

  <ThemeProvider theme={colours}>
    <App/>
  </ThemeProvider>

• You will also need to add the icon library that we are using (which is Font Awesome). To do this, 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

And then install and import the correct packages:

import { library } from '@fortawesome/fontawesome-svg-core'
import {fal} from '@fortawesome/pro-light-svg-icons'
import {far} from '@fortawesome/pro-regular-svg-icons'
import {fas} from '@fortawesome/pro-solid-svg-icons'
library.add(fal, far, fas);

• If you want to use the app layout/navigation elements from the design system, like header, mobile nav and sidebar, you need to ensure you structure your app the following way so these all function correctly:

  <MobileNav>...</MobileNav>
  <Header>...</Header>
  <main>
    <Sidebar>...</Sidebar>
    <section>
      Put your main page content here
    </section>
  </main>

Upgrading your app to use the latest version of the design system

When you use the design system, it will use the particular git hash that has been added/installed. If you want to upgrade to the latest hash, you need to run the following command: npm update --save orca-design-system or yarn upgrade orca-design-system

How to use components from the design system

• To use a component, refer to http://styleguide.orchestrated.io/ to see list of components and examples of how to use.

Simple components

• Make sure you import that component e.g.:

import { Button } from 'orca-design-system';

• Then you can use that component like so:

<Button>Click me</Button>

• And you can customise the look using the props which you can see in the examples on the link above. For example the following will give you a large green button:

<Button large secondary>Click me</Button>

Sub-components

• Some components are made up of multiple sub-components, for example, Typography. To use these typographic elements you need to reference the component and then sub-component, like so:

• Import the component:

import { Typography } from 'orca-design-system';

  <Typography.H1>Page title</Typography.H1>
  <Typography.P>Page description</Typography.P>

Multi-components

• Some components are made up of multiple components that are intended to work together. In this case you need to use exactly as specified in the design system; the markup structure and attributes should be the same.

• One example is the tabs component input http://styleguide.orchestrated.io/#tabs, which if you refer to the design system example needs to be used like so:

  import { Tabs } from 'orca-design-system';

  <Tabs.Container>
    <Tabs.Tab active>Tab one</Tabs.Tab>
    <Tabs.Tab>Tab two</Tabs.Tab>
  </Tabs.Container>

  <Tabs.Content active>
    Place whatever child content you like here
  </Tabs.Content>

  <Tabs.Content>
    Place whatever child content you like here
  </Tabs.Content>

• There are other more complicated components like the sidebar, but as long as examples are followed these should be easy enough to implement.

Icons

• To use icons you need to ensure you are importing the library (as outlined above in onboarding section). Import the Icon component and then reference them like this:

import { Icon } from 'orca-design-system';

<Icon icon={["far", "user"]} />

• To see a full list of icons and their names visit https://fontawesome.com/icons?d=listing. Note: depending on if you want to use a light, regular or solid icon, your icon must be prefixed with either 'fal', 'far' or 'fas' as shown above.

• You can also alter the size and colour of icons, see http://styleguide.orchestrated.io/#icon for examples.

<Icon icon={["far", "calendar"]} size="2x" color={colours.blue} />

Creating custom components or styles in your app

• If you need to create a custom component that is specific for your app, this should be done and styled using the same method as this design system, which uses styled-components. For examples, view this design system's source code (have a look at various components in the /lib/components folder to see how they are constructed) and for documentation see: https://www.styled-components.com/.

• To keep certain variables and colours consistent across your app, it is advised to use the ones defined in this design system. To view these, see /lib/colours.js and /lib/variables.js.

• To implement these in your app you first need to import colours and variables like so: import {colours, variables} from "orca-design-system"; and then you can use like so in your styling:

const customComponent = styled.div`
  padding: ${variables.defaultSpacing};
  background-color: ${colours.primaryLight};
`

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