@betty-blocks/design v29.19.5

Betty Blocks Design

This is the design system of Betty Blocks. The goal of this design system is to make creating Betty Blocks interfaces as easy as possible. This design system will replace @betty-blocks/design-system eventually.

What's in our design system?

Our design system exists out of several parts. This section explains them and states how to use them.

Grommet

We chose to base our design system on the Grommet component library. That's why we export all Grommet components directly from our design system. Use them like this:

import { Box, Heading } from '@betty-blocks/design';

function HelloWord(): JSX.Element {
  return (
    <Box>
      <Heading>Hello world</Heading>
    </Box>
  );
}

In this example we use the Box and Heading component from Grommet. Check the Grommet documentation on how to use these components.

NOTE: Grommet components should be the first you reach for when building a user interface. Check the What to use section on how to decide what you should use when building a user interface.

Icons

To be consistent we chose to use the same interface for icons like Grommet does. All Grommet icons are exported from our design system.

NOTE: We postfixed all icons with Icon. This means that when you want to import the Grommet Add icon you need to import AddIcon.

Usage

import { AddIcon, Button } from '@betty-blocks/design';

function IconButton(): JSX.Element {
  return (
    <Button label="Add" icon={<AddIcon size="large" color="brand" />} />
  );
}

Add custom icons

To add a custom icon, add a new file to src/icons/icons, name it and add it to src/icons/index.ts. A new icon file looks as follows:

/* eslint-disable react/jsx-props-no-spreading */
import React from 'react';

import { IconProps } from 'grommet-icons';

import { StyledIcon } from '../StyledIcon';

// eslint-disable-next-line import/prefer-default-export
export function Data(props: IconProps): JSX.Element {
  return (
    <StyledIcon viewBox="0 0 .. .." a11yTitle="Data" {...props}>
      ...
    </StyledIcon>
  );
}

The StyledIcon component does the following:

• It wraps your svg code into an <svg> HTML element.
• It applies styling according to the values of the size and color properties.
• It accepts all accepted svg attributes via its properties.

NOTE: In the sketch files created by our UX Designers all icons are based on a 0 0 16 16 viewbox. When adding new icons try to keep to this.

DesignSystemProvider

To use a Grommet theme you need to wrap your components in a Grommet component like this:

import { Grommet, Button } from 'grommet';
import theme from './theme';

function App(): JSX.Element {
  return (
    <Grommet theme={theme}>
      // Button's appearance will be according to theme
      <Button label="foo" />
    </Grommet>
  );
}

However we don't want to worry about the theme. We just want is to be there. That's why we created the DesignSystemProvider component. It contains the Grommet component together with our theme and you can use it as follows:

import { Button, DesignSystemProvider } from '@betty-blocks/design';

function App(): JSX.Element {
  return (
    <DesignSystemProvider>
      // Button's appearance will be according to theme
      <Button label="foo" />
    </DesignSystemProvider>
  );
}

NOTE: We wrapped the DesignSystemProvider around the entire application inside the IDE repository. You don't need to worry about this when working inside this repository.

Custom components

When you want to add a new component to our design system, add a new file in src and export it in src/index.ts.

How to use

The set up of the design system is based on the rules below. The rules explain how and when to use this design system. When deciding on what to use for your interface walk through the following steps in order.

1. Grommet

The first thing to reach for is Grommet. Grommet offers lots of components with build-in functionality. For the base of most interfaces these components should be sufficient. As our theme will expand and get better over time you will get functionality and the Betty Blocks style for free.

When no Grommet component suits your needs, decide whether the component you need is for one time use or will be reused multiple times throughout the project. If it will be used on time go to step 2. Otherwise skip step 2 and go to step 3.

2. Use a component once

For one time use you have two approaches.

1. Extend the styles of a Grommet component.
2. Don't use the design system and create your own component in place.

As Grommet is based on styled components you can use this to extend the style:

import styled from 'styled-components';
import { Button } from '@betty-blocks/design';

const StyledButton = styled(Button)`
  // Custom css goes here...
`;

function CustomButton():JSX.Element {
  return (
    <StyledButton label="foo" />
  );
}

TYPESCRIPT NOTE: You will probably have to include an import for extra type or styled components might not work. If you get a typescript error with css missing in type you can solve it by the solution below.

You will need to include this once in your project. For some projects this already works by default because of some dependency inclusions that also does this.

import type {} from 'styled-components/cssprop';

NOTE: The Box component of Grommet is really powerful and can create almost any layout you can think of except for layouts which are pulled from the DOM. Please make sure you know how to apply Grommet in interfaces effectively before extending a component.

3. Use a component multiple times

When the component you want to create will be used multiple times please consider the following things before adding it to the design system:

• Will it be used outside the package you are currently working on?
• Is the component you need an atom? Read about atoms here.

Is you question to the question above yes? Add the component to the design system. Otherwise, solve it at the package your are working on.

Contribute

To contribute make your changes and open a merge request to master. Once code is merged to master a new release of the design system will be released automatically.

When developing on components in the design system you can choose to use either storybook or playroom.

Storybook

To run storybook:

1. Install dependencies:

$ yarn

2. Run storybook

$ yarn storybook:start

3. Storybook is now running at: http://localhost:6006/

Playroom

To run playroom:

1. Install dependencies:

$ yarn

2. Run playroom

$ yarn playroom:start

3. Playroom is now running at: http://localhost:8111/

Storybook with playroom

It is also possible to run Playroom inside Storybook as an addon. This do this:

1. Install dependencies:

$ yarn

2. Run storybook and playroom

$ yarn storybook-playroom:start

3. Storybook is now running at: http://localhost:6006/

Build

To build to project, execute the following steps:

1. Install dependencies:

$ yarn

2. Build

$ yarn build