@fairfx/fuji

🗻
Fuji

This is FairFX's design system. It includes React components, design tokens and other styles used for creating apps and websites

• Install @fairfx/fuji
  • Documentation
• React components
  • Usage
  • List of imports & components
    • Design Tokens
    • Components
    • Import usage
  • Demo playground
  • Component development
• Design Tokens
  • Modifying/Updating tokens
    • Example usage
• Development
  • Run Storybook development environment
  • Anatomy of a component directory
  • Build scripts
  • Testing
    • Run tests
    • Writing tests
      • We use two types of tests to test our components
      • Unit test example
      • Snapshot test example
• Linting
  • JavaScript linting
  • CSS linting
• Publishing and Deploying
  • Package release process
  • Continuous Integration

Install @fairfx/fuji

https://www.npmjs.com/package/@fairfx/fuji

To add this package to your react application, run

yarn add @fairfx/fuji

# or use npm instead
npm install --save @fairfx/fuji

Documentation

A proper documentation solution is still being researched. In the meantime, each component/file should have their own readme, so navigate to the component directory for more info.

React components

The React components included with Fuji are all styled with styled-components. See a full list of all the components and their imports below.

Usage

Import components that you want from the library and use them like so:

import { Button, ButtonSecondary } from '@fairfx/fuji';

const Actions = () => (
  <div>
    <Button onClick={this.save}>Save changes</Button>
    <ButtonSecondary onClick={this.clear}>Clear</ButtonSecondary>
  </div>
);

List of imports & components

Design Tokens

• tokens
• globalStyles

Components

• Atoms
  • Badge
  • Button
  • Checkbox
  • Container
  • Fieldset
  • FormActions
  • Icon
  • IconCircle
  • Image
  • InputCaption
  • InputText
  • InputTextInner
  • Label
  • LabelInner
  • Link
  • Loader
  • Logo
  • Radio
  • RichText
  • Spacer
  • Table
  • ToggleButton
  • Typography
  • Well
• Molecules
  • BalanceValue
  • CurrencyFlag
  • DataTable
  • HorizontalList
  • InputControl
  • InputGroup
  • InputGroupInner
  • List
  • MenuItem
  • Modal
  • Navigation
  • NavProfile
  • PopOver
  • SearchableList
  • SideNav
  • Tabs
  • ServiceLinks
• Organisms
  • Header
  • Footer

Import usage

import {
  FujiTypes, // Various Typescript types
  tokens, // design tokens
  globalStyles, // globalStyles

  // Fonts
  // fonts hosted on cdn.fairfx.com
  // with the @font-face declarations
  Effra, // all fonts
  EffraLight, // only Effra Light
  EffraRegular, // only Effra Regular
  EffraMedium, // only Effra Medium
  EffraBold, // only Effra Bold
  EffraHeavy, // only Effra Heavy

  // Components
  Badge,
  BadgeColour,
  BadgeSize,
  BalanceValue,
  Button,
  ButtonSecondary,
  ButtonGhost,
  withLoadingButton,
  Categories,
  CenterPlaceHolder,
  Checkbox,
  CurrencyFlag,
  ExpandableDirection,
  Fieldset,
  Footer,
  FormActions,
  Chevron,
  ChevronDown,
  ChevronOrientation,
  Container,
  DataTable,
  Header,
  HorizontalList,
  Icons,
  IconCircle,
  Image,
  InputControl,
  InputGroup,
  InputGroupInner,
  InputGroupPair,
  InputPassword,
  InputPasswordInner,
  InputText,
  InputTextInner,
  Label,
  LeftPlaceHolder,
  Link,
  List,
  Loader,
  Logo,
  MenuItem,
  Modal,
  Navigation,
  NavProfile,
  NavExpandable,
  NotificationItem,
  P,
  PopOver,
  SearchableList
  SideNav,
  SideNavCategory,
  SideNavLink,
  SideNavSeparator,
  SiteTitle,
  PageTitle,
  SectionTitle,
  SectionSubtitle,
  SectionSubTitleMedium,
  Radio,
  RichText,
  SearchableList,
  Select,
  ServiceLinks,
  Spacer,
  Tabs,
  Tab,
  ToggleButton,
  Well,
} from '@fairfx/fuji';

Demo playground

Try the demo on CodeSandbox.

Component development

• styled-components is used for component styling.
• design-system-utils is used in conjunction with the design tokens (see below).
• styled-is is a small utility used to improve styling when passing flag/boolean props to a component

See a list of all dependencies here

Design Tokens

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development. Think of them like your Sass variables.

Our design tokens rely on design-system-utils, a micro framework that makes it easy to get values from your tokens file.

Modifying/Updating tokens

The main tokens file can be found here. It uses the base structure that design-system-utils requires, but beyond that, there are no other restrictions.

Example usage

import { tokens } from '@fairfx/fuji';

const Box = styled.div`
  font-size: ${tokens.fs('l')};
  background-color: ${tokens.color('primary')};
  border-radius: ${tokens.get('borderRadius')};
`;

Development

First you should install dependencies:

yarn install

Components can be developed and visually tested using Storybook. Each component should have a *.story.js file in the same directory.

Run Storybook development environment

Storybook creates an area to preview each component in isolation.

yarn storybook

Then open https://localhost:9001

Anatomy of a component directory

E.g. A Button "atom" found in the /src/components/atoms directory.

.
├── Button.tsx // < component code
├── README.md // < component documentation
├── Button.story.tsx // < component story
├── Button.test.tsx // < component tests
├── __snapshots__
│   └── Button.test.tsx.snap // < auto-generated snapshot code
└── index.ts // < component entry file

Build scripts

• yarn storybook: Run Storybook development environment
• yarn build: Compile a production build with Rollup
• yarn watch: Compile/watch with Rollup. This is useful in conjuction with yarn link.
• yarn format: Format all JS with Prettier
• yarn lint: Lint JS and CSS-in-JS
• yarn lint:js: Lint JS with TSLint
• yarn lint:css: Lint CSS-in-JS with Stylelint
• yarn size: Test the file size of the build
• yarn size:why: Analyse the the build
• yarn test: Run all tests (test:js & test:visualregression)
• yarn test:js: Run all JS tests with Jest
• yarn test:visualregression: Run visual regression tests with ChromaticQA
• yarn test:coverage: Run a code coverage test with Jest
• yarn test:watch: Run test suite while watching for changes

Testing

Tests are run using Jest. We use react-testing-library with Jest to encourage good test practices.

Run tests

yarn test

or run tests and rerun tests after files have been modified:

yarn test:watch

Writing tests

Create a *.test.js in the same directory as your component.

We use two types of tests to test our components

• Unit tests test functional units of your code
• Snapshot tests are a very useful tool whenever you want to make sure your UI does not change unexpectedly. We capture a specific a rendered version of the component with specific markup, if the component is modified, the snapshot test will fail. In order for the test to pass, the snapshot has to be updated, this can normally be done by pressing the u key after the test has run. Find out more here

Unit test example

import React from 'react';
import { render, fireEvent, cleanup } from 'react-testing-library';
import 'jest-dom/extend-expect';

import { Button } from './index';

// automatically unmount and cleanup DOM after the test is finished.
afterEach(cleanup);

test('Render a button', () => {
  // Arrange
  const { getByText } = render(<Button>This is a button</Button>);

  // Act
  fireEvent.click(getByText('This is a button'));

  // Assert
  expect(getByText('This is a button')).toHaveTextContent('This is a button');
});

Snapshot test example

import React from 'react';
import 'jest-dom/extend-expect';
import 'jest-styled-components';

import { Button } from './index';

// automatically unmount and cleanup DOM after the test is finished.
afterEach(cleanup);

test('Button snapshot', () => {
  const tree = render(<Button>This is a button</Button>); // render a button
  expect(tree).toMatchSnapshot(); // check if the rendered button matches the snapshot
});

Linting

JavaScript linting

TSLint is used to lint our Typescript code.

CSS linting

Stylelint is used to lint all styled-components styles. There are some specific changes/additions needed when working with styled-components, these are specifically related to interpolation; please read the docs here: styled-components.com/docs/tooling#interpolation-tagging. Below is an example of what is needed for Stylelint to understand this syntax:

From this:

import { Button } from '@fairfx/fuji';

const Wrapper = styled.div`
  ${Button} {
    color: red;
  }
`;

To this:

import { Button } from '@fairfx/fuji';

const Wrapper = styled.div`
  ${/* sc-selector */ Button} {
    color: red;
  }
`;

Please read the docs so you understand this fully.

Publishing and Deploying

The project follows Semantic Versioning. Each new release to npm needs a version bump, read on for package release instructions.

Package release process

TBC

Continuous Integration

• CircleCI is used to automate our tests and compile our code for each release
• ChromaticQA tests for visual regressions on each PR