npm package: @smartbear/design-system
Description: Presentational components implementing the SmartBear Design System
Author: Aslak Hellesøy
Latest version: 0.9.1

[![Node.js CI](https://github.com/SmartBear/design-system/workflows/Node.js%20CI/badge.svg)](https://github.com/SmartBear/design-system/actions?query=workflow%3A%22Node.js+CI%22)

# SmartBear Design System

This repository contains presentational components implementing the
[SmartBear Design System](https://smartbear.atlassian.net/wiki/spaces/UT/pages/804225780/Quick+Start).

See a [live demo](https://smartbear.github.io/design-system/) based on [StoryBook](https://storybook.js.org/).

## Frameworks

Currently only React is supported. If you need support for a different framework please submit a pull request.

## Installation

First, make sure you add the following snippet to your `<head>` element in your HTML

```html
<link
  href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;400;500;600;700&display=swap"
  rel="stylesheet"
/>
```

This is because the SmartBear design system registers `Open Sans` as the default `sans` font.

Second, install the design system using one of the following mechanisms:

- [Quick and Dirty](#quick-and-dirty)
- [Node.js](#nodejs)

### Quick and Dirty

Just add the CSS directly to your `<head>` element:

```html
<!-- Replace VERSION with the version you want -->
<link
  href="https://cdn.jsdelivr.net/npm/@smartbear/design-system@VERSION/dist/style.css"
  rel="stylesheet"
/>
```

While this is quick and makes it easy to try out, it is not recommended for production use, as the stylesheet
is very large, and you will only be able to use the [CSS Components](#css-components).

The [HTML Components](#html-components) are only available if you install it with [Node.js](#nodejs)

### Node.js

Install the npm module as a runtime dependency:

    npm install --save @smartbear/design-system

You can now use [React Components](#react-components) as well as the [Tailwind CSS Plugin](#tailwind-css-plugin)

#### Tailwind CSS Plugin

It's highly recommended you install [Tailwind CSS](https://tailwindcss.com/).

Add the plugin to your Tailwind config:

```javascript
// tailwind.config.js
module.exports = {
  plugins: [require('@smartbear/design-system').tailwindPlugin],
}
```

## Contribute

We would love pull requests from people in SmartBear to improve this library. Start by cloning this repo and
fire up Storybook to see existing components:

    # Force the use of PostCSS 8 to avoid Storybook problems
    npx npm-force-resolutions

    # Install dependencies
    npm install

    # View components in Storybook
    npm run storybook

## Defining components

We follow the tailwindcss guidelines for [Extracting Components](https://tailwindcss.com/docs/extracting-components/).
This design system provides CSS components and Example components.

When you define a new component you should always start by creating a new `stories/*/MyComponent.stories.tsx` file.

While you're experimenting you can define the component in the same file, and when you're happy with it, extract it
to a CSS Component or HTML Component.

### CSS Components

Components that only require a single HTML element are defined as [CSS Components](https://tailwindcss.com/docs/extracting-components/#extracting-css-components-with-apply).
To create a new CSS Component:

- Create a new `src/molecules/*.css` file.
- Run `npm run build-css-components`. This will generate a [CSS-in-JS .js](https://tailwindcss.com/docs/plugins#css-in-js-syntax) file.
- Register the component with `addComponents` in `src/tailwindPlugin.js`
- `@import` the file in `stories/index.css` (otherwise it won't be loaded in StoryBook)

### HTML Components

Components that require two or more HTML elements are defined as [HTML components](https://tailwindcss.com/docs/extracting-components/#extracting-html-components).

This library currently uses React to define HTML Components. Support for additional UI libraries are welcome!

#### React Components

To create a new React Component just create a new `src/{molecules,organism}/*.tsx` file.

### SmartBear theme

Because tailwindcss is centred around utility classes, the SmartBear theme is implemented by overriding and adding utilities to
the standard set of utilities. This is described in more detail in [Customizing Your Design System](https://tailwindcss.com/course/customizing-your-design-system).

The theme defines the following values:

- Colours (using design system specific names)
- Spacing (padding, margin, width and height)

The theme is defined in `src/tailwindPlugin.js`.

## Releasing

Before you release, update dependencies:

    npx npm-check-updates --upgrade
    npm install

Verify that everything still looks ok in Storybook.

Update the version number in `standalone-example.html`
Update `CHANGELOG.md` and commit. Now you can release:

    npm version [major|minor|patch]
    npm publish --access public && npm run deploy-storybook
    git push && git push --tags