@curve-technology/web-ds

Curve Atomic Design System for Web ✌️

Installation

Install @curve-technology/web-ds and its peerDependencies

$ yarn install @curve-technology/web-ds theme-ui @emotion/core

---

• Package entrypoints
  • Main entrypoint
  • Theme
    • Overview
    • Understanding Theme UI
      • Using the theme
      • Style your UI
    • Motion usage
    • Fonts
      • Helvetica Now (example)
      • Eloquent (example)
    • Theme UI components
  • Components
  • Tokens
  • Icons
  • Styles
  • Styleguide
• Code
  • Files and naming
  • Anatomy of a component directory
  • Core tools and technologies
  • Build and compilation
    • Build scripts and commands
    • Tooling
• Workflow
  • Commits and Pull Requests
  • Publishing new versions to npm
  • License

Package entrypoints

The package exposes different entrypoints for each sub-package. Below are all the possible entrypoints that can currently be used.

• @curve-technology/web-ds - main entrypoint for the design system theme
• @curve-technology/web-ds/tokens - only the design tokens
• @curve-technology/web-ds/icons - icons
• @curve-technology/web-ds/styles - global styles
• @curve-technology/web-ds/styleguide - styleguide components for use in other apps
• @curve-technology/web-ds/components - custom components

Main entrypoint

This entrypoint has most, but not all, of the exported components and variables from web-ds package.

• The most-used items will be made available in the main entrypoint, and rarely used and potentially large items, will be accessible from a sub-entrypoint.

import { theme } from '@curve-technology/web-ds'

Theme

The theme can be imported like so:

import { theme } from '@curve-technology/web-ds'

Source files are located in the src/theme directory.

Overview

The package is heavily reliant on Theme UI. Many of the components and styles need Theme UI in order to work.

Understanding Theme UI

Theme UI provides a constraint-based approach to component creation and theming. This allows you and your team to create a design system that supports the widest

To fully understand Theme UI and all that it provides, please read and understand the documentation at https://theme-ui.com/getting-started.

Using the theme

The theme matches Theme UI's specifications, so includes all the colour, font, sizing and spacing information that your app should need.

All theme-related files are located in the src/theme directory.

Add the theme to your application with the ThemeProvider, passing in the theme object as a prop.

import React from 'react'
import { ThemeProvider } from 'theme-ui'
import { theme } from '@curve-technology/web-ds'

export default (props) => (
  <ThemeProvider theme={theme}>{props.children}</ThemeProvider>
)

Style your UI

This is an example of how a new component could be created without using Emotion's styled.div syntax. Read more about this method in the Theme UI docs

/** @jsx jsx */
import { jsx } from 'theme-ui'
import { FunctionComponent } from 'react'

export const Title: FunctionComponent = ({ children }) => (
  <h1
    sx={{
      color: 'primary',
      fontFamily: 'heading',
    }}
  >
    {children}
  </h1>
)

If you're still using the `sx` prop and you need to customise either the property, timing function or duration, or all of them, use something like this:

```tsx
<Box
  sx={{
    transform: (theme): string =>
      `transform ${theme.motion.durations.long} ${
        theme.motion.easings.easeInOutQuad
      }`,
    // `transform 500ms cubic-bezier(0.45, 0, 0.55, 1)`
  }}
/>

If you're not using the sx prop or you're defining a transition another way, you can import the tokens directly and compose your transtion however you like:

import { motion } from '@curve-technology/web-ds/tokens'

const transition = `transform ${motion.durations.short} ${motion.easings.easeOutSine}`

Fonts

Two fonts should be used with this design system: "Helvetica Now" and "Eloquent".

Helvetica Now (example)

Helvetica Now's font files need to be self-hosted. Ensure that they are placed in the /fonts directory of your application's static directory when hosted. Use body as the value when using the sx prop, like so:

<div sx={{ fontFamily: 'body' }}>Normal text</div>

Eloquent (example)

Eloquent is the bold serif font used with Curve. Use fancy as the value when using the sx prop, like so:

<div sx={{ fontFamily: 'fancy' }}>Fancy text</div>

Ensure your application adds this link tag so that the font can be used:

<link rel="stylesheet" href="https://use.typekit.net/eld0ezk.css" />

Theme UI components

Theme UI includes pre-built UI components to make styling a page with Theme UI quicker. This package includes components for layouts, grids, buttons, form elements, and more.

import { Box } from 'theme-ui'

export const SomeComponent = (
  <Box p={4} color="white" bg="primary">
    Beep
  </Box>
)

Find out more in the Theme UI component docs.

Components

Source files are located in the src/components directory.

import { ArrowLink } from '@curve-technology/web-ds/components'

Tokens

Source files are located in the src/tokens directory.

Design tokens are an important part of any design system, so this repo exposes all of the "raw" design tokens so you can use them whenever you need to.

import {
  breakpoints,
  colors,
  fontFamilies,
  fontSizes,
  motion,
  radii,
  space,
  zIndices,
  shadows,
} from '@curve-technology/web-ds/tokens'

Theme UI takes care of tokens using it's theme object and is the basis for your components and applications consuming your components.

Icons

Source files are located in the src/icons directory.

import {
  CurveLogo,
  CurveBrandmark,
  ArrowEast,
} from '@curve-technology/web-ds/icons'

Theme UI's sx prop can be used to add extra styles and to change the colour of icons; this works because the underlying svg's fill or stroke value is set to currentColor. e.g.

<ArrowEast size="50" sx={{ color: 'accent' }} />

Styles

Source files are located in the src/styles directory.

These styles are to be used to add common, usually global styles to your applications. So far these styles are:

• reset: A CSS reset using the modern CSS reset
• fontFace: The @font-face directive for use with Helvetica Now
• responsiveFontSizing: When using rem unit for font-size and spacing, this set of styled increases the :root font-size so that these values increase based on the user's viewport width

They can be used in emotion's Global component, like so:

import { Global } from '@emotion/core'
import {
  reset,
  fontFace,
  responsiveFontSizing,
} from '@curve-technology/web-ds/styles'

export default class MyApp extends App {
  render(): JSX.Element {
    const { Component, pageProps } = this.props
    return (
      <ThemeProvider theme={theme}>
        <Global styles={[reset, fontFace, responsiveFontSizing]} />
        <Component {...pageProps} />
      </ThemeProvider>
    )
  }
}

Styleguide

Source files are located in the src/styleguide directory.

The styleguide entrypoint contains components are to be used inside a 3rd party app's Storybook config. They provide an example of what the theme's base components look like.

import {
  Styleguide,
  Tokens,
  ThemeConfig,
} from '@curve-technology/web-ds/styleguide'

The Styledguide component has examples for most base components, like typography, form elements and buttons.

The Tokens component displays all the tokens (colour palette, font-sizes, spacing values etc).

The ThemeConfig prints the entire theme onto the page. This is useful to see the raw values for the Theme UI theme that your app is using.

import React, { FunctionComponent } from 'react'
import {
  Styleguide,
  Tokens,
  ThemeConfig,
} from '@curve-technology/web-ds/styleguide'
import { theme } from '@curve-technology/web-ds'

export default {
  title: 'Design system',
}

export const styleguide: FunctionComponent = () => <Styleguide />
export const tokens: FunctionComponent = () => <Tokens />
export const themeConfig: FunctionComponent = () => (
  <ThemeConfig theme={theme} />
)

See an example of these in action here and here

---

Code

Files and naming

Test files use *.test.ts(x) or *.spec.ts(x)

Any file with *.story.tsx or *.stories.tsx, or *.story.mdx or *.stories.mdx can be used by Storybook. The *.mdx extensions are used for documentation.

Anatomy of a component directory

E.g. a Button found in the /src/components directory.

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

Core tools and technologies

• React
• TypeScript
• Components
  • Theme UI - Build consistent, themeable React apps based on constraint-based design principles.
  • Emotion - CSS-in-JS library used by Theme UI
• Component sandboxes
  • Storybook - Storybook is a tool for developing UI components in isolation. It makes building stunning UIs organized and efficient.
• Testing
  • Jest - testing framework
  • React Testing Library
  • Jest Axe - Custom Jest matcher for aXe for testing accessibility ♿️
• Compilation/Bundling
  • Preconstruct - Module bundler based on Rollup and various other technologies
  • Babel
• Linting & formatting
  • ESLint

Build and compilation

The package uses Preconstruct to bundle all its source code. Please consult their docs if you need to update/improve the build process.

Build scripts and commands

• yarn build: Compile a production build
• yarn build:dev: Compile a development build
• yarn storybook: Run Storybook development environment
• yarn format: Format all JS with Prettier
• yarn lint: Lint JS
• yarn size: Test the file size of the build
• yarn test: Run all tests
• yarn test:js: Run all JS tests with Jest
• yarn test:coverage: Run a code coverage test with Jest
• yarn test:watch: Run test suite while watching for changes
• yarn release: Publish a new package version to npm

Tooling

The design system uses various tools to ensure better code quality. Defaults have been set for linting and code style, but can easily be overridden according to your needs.

• Prettier
• Eslint
• Husky
• lint-staged

Workflow

Commits and Pull Requests

All git commits and pull request titles should follow the Conventional Commits method. This will allow our release script to correctly bump the package version number appropriately.

Publishing new versions to npm

Running yarn release while on an up-to-date and clean master branch will update the CHANGELOG and publish to npm.

License

MIT

---

Made by Curve's web scientists 👨‍🔬