@syns-platform/perspective-design-components-react

Perspective Design System

Welcome to the Perspective Design System component libary v1

📚 Documentation

Note that perspecive-design-system is a private npm package so you will need an npm account and invitation to the Synspective organization or a .npmrc file at the root of the project with a valid token.

For more information on this see Docbase

🛠 Install

npm i @syns-platform/perspective-design-components-react

Or if you perfer yarn

yarn add @syns-platform/perspective-design-components-react

Finally you will also need these peer dependencies installed in your project

npm install @carbon/icons-react @styled-system/css react react-dom styled-components styled-system rc-slider react-flatpickr yarn add @carbon/icons-react @styled-system/css react react-dom styled-components styled-system rc-slider react-flatpickr

and the types if using typescript

npm install -D @types/styled-components @types/styled-system__css

You will then also want to add a gloabal type for inline styling.

Add a @types folder in the src folder.

Then add the following in index.d.ts

import type { SystemStyleObject } from '@styled-system/css';
declare global {
    type StyleType = SystemStyleObject;

    type StyleObjectType = {
        [index: string]: StyleType;
    };
}

🎨 Adding a theme

You will also need a theme. You can use your own based off a styled-system specification but it's much easier to use our theme.

npm install --save @types/styled-components @types/styled-system__css

💻 Usage

💅 Set up the Theme

Wrap the app in a styled-components theme provider and supply your theme. Here we are using the dark theme from our theme library but you can create your own one too if needed.

import { ThemeProvider } from 'styled-components';
import { darkTheme } from '@syns-platform/perspective-theme';

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

🛠 Import components

Then you should be able to use any component by importing it

import { Button } from '@syns-platform/perspective-design-components-react';

<Button
    variant="primary"
    onClick={() => console.log('click')}
>
    Click Me!
</Button>

Icons

We use carbon icons so install the package and it's types if you are using typescript

npm install @carbon/icons-react npm install --save @types/carbon__icons-react

Usage with react-hook-form

On the platform team we use this the react-hook-form for handling forms. Most components should work by default but there are a few that requre use of the Controller component.

Here is an example using the <Combobox /> component

import { useForm, Controller } from 'react-hook-form';
import { Combobox } from '@syns-platform/perspective-design-components-react';

const App: React.FC = () => {
    const {
        formState: { errors },
        control,
    } = useForm();

return (
    <Controller
        name="comboboxController"
        control={control}
        rules={{ required: true }}
        render={({ field }) => (
            <Combobox
                {...field}
                id="combobox"
                items={itemList}
                placeholder="Search by name"
                titleText="Select Item"
                invalid={!!errors.comboboxController}
                invalidText="You need to select an item"
            />
        )}
    />
)}

Overriding styles

Ovridding specific styles can be done in 2 ways.

Theme Override

import { ThemeProvider } from 'styled-components';
import { darkTheme } from '@syns-platform/perspective-theme';

// Define what props.theme will look like
const myTheme = {
  ...darkTheme,
  colors: {
    ...darkTheme.colors,
    ui: {
      ...darkTheme.colors.ui,
      background: 'pink',
      '01': 'orange',
      '02': 'green',
    },
  }
};

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

sx prop

Many components have a sx prop that allow you to write some inline css that has access to the theme. For more information see the next section.

Custom components

The <Box /> component can be used to create any addional custom component you might need.

The advantage of using the <Box /> over a regular <div /> is that it has build in access to the theme using the sx prop.

import { Box } from '@syns-platform/perspective-design-components-react';

const App: React.FC = () => {

return (
    <Box
        sx={{
            width: '100px',
            backgroundColor: 'ui.01'
            padding: 'spacing05'
        }}
    />
)}

You can also set it to be any type of html element using the as prop.

import { Box } from '@syns-platform/perspective-design-components-react';

const App: React.FC = () => {

return (
    <Box
        as='img'
        src="example.jpg"
        alt="Not useful alt content"
        width="500"
        height="600"
        sx={{
            border: '1px solid red'
        }}
    />
)}