Installation
Install @curve-technology/web-ds
and its peerDependencies
$ yarn install @curve-technology/web-ds theme-ui @emotion/core
Package entrypoints
The package exposes different entrypoints for each sub-package. Below are all the possible entrypoints that can currently be used.
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
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 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 resetfontFace
: The @font-face
directive for use with Helvetica NowresponsiveFontSizing
: 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
├── README.md
├── CookieBanner.story.tsx
├── CookieBanner.test.tsx
├── CookieBanner.models.ts
├── __snapshots__
└── index.ts
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
- Compilation/Bundling
- Linting & formatting
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 buildyarn build:dev
: Compile a development buildyarn storybook
: Run Storybook development environmentyarn format
: Format all JS with Prettieryarn lint
: Lint JSyarn size
: Test the file size of the buildyarn test
: Run all testsyarn test:js
: Run all JS tests with Jestyarn test:coverage
: Run a code coverage test with Jestyarn test:watch
: Run test suite while watching for changesyarn 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 👨🔬