At the moment this project is out-of-date and unmaintained. I hope to revisit it soon though... This is a boilerplate for you to create your own design system in React. It has everything setup to allow you to focus on what it is you care about: creating awesome, reusable components.
Docs TODO:
To clone and run this application, you'll need Git and Node.js (which comes with npm) installed on your computer. From your command line:
# Clone this repository
$ git clone https://github.com/mrmartineau/react-design-system-starter.git
# Go into the repository
$ cd react-design-system-starter
# Install dependencies
$ yarn install
# That's it, now create your own design system 🎉
Theme UI provides a constraint-based approach to component creation and themeing. 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.
Create a theme object to include custom color, typography, and layout values. Read more about this in the Theme UI docs.
// example themeUiTheme.js
export const theme = {
fonts: {
body: 'system-ui, sans-serif',
heading: '"Avenir Next", sans-serif',
monospace: 'Menlo, monospace',
},
colors: {
text: '#000',
background: '#fff',
primary: '#33e',
},
}
Add the theme to your application with the ThemeProvider
, passing in the theme object as a prop.
// basic usage
import React from 'react'
import { ThemeProvider } from 'theme-ui'
import { theme } from 'your-design-system/tokens'
export default props => (
<ThemeProvider theme={theme}>{props.children}</ThemeProvider>
)
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'
export default props => (
<h1
sx={{
color: 'primary',
fontFamily: 'heading',
}}
>
Hello
</h1>
)
The optional @theme-ui/components
package 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. The main highlight, in my opinion, is the Box
component that so flexible I predict you will use it almost everywhere.
import { Box } from '@theme-ui/components'
export const SomeComponent = (
<Box p={4} color="white" bg="primary">
Beep
</Box>
)
Find out more in the Theme UI component docs.
Design tokens are an important part of any design system, so this repo has been setup with 2 ways for your components to make use of these tokens: design-system-utils 👩🎨 and Theme UI.
Theme UI takes care of tokens using it's theme object and is the basis for your components and applications consuming your components.
design-system-utils is used when you need access to specific values from your tokens from anywhere in, or indeed outside, your application. It makes it really easy to store your design tokens in an organised way and reference them in your components.
All tokens-related files can be found in the src/tokens
directory.
.
├── colorPalette.ts
├── index.ts
├── themeUiTheme.ts
├── tokens.models.ts
├── tokens.stories.ts
└── tokens.ts
design-system-utils 👩🎨 has already setup with this design system.
src/tokens/tokens.ts
is the entry point used with design-system-utils. Please read the design-system-utils docs to find out all about this very useful library, or see below for a few simple examples:
tokens.get('radii')
This is a basic view of the project's directory. All React components are located in the src/components
directory. Your design tokens, which are managed by design-system-utils.
.
├── build // the directory for compiled files
├── jest.config.js
├── playroom.config.js
├── src
│ ├── buttons.ts // an example entry file for a subset of
│ ├── components
│ │ ├── Button
│ │ │ ├── Button.stories.tsx
│ │ │ ├── Button.test.tsx
│ │ │ ├── Button.ts
│ │ │ ├── README.md
│ │ │ └── index.ts
│ │ └── index.ts
│ ├── index.ts // this is the main project entry file
│ ├── intro.story.mdx
│ └── tokens
│ ├── colorPalette.ts
│ ├── index.ts
│ ├── themeUiTheme.ts
│ ├── tokens.models.ts
│ ├── tokens.stories.ts
│ └── tokens.ts
├── types
└── yarn.lock
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.
E.g. a Button
found in the /src/components
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
yarn build
: Compile a production build with Rollup
yarn watch
: Compile/watch with Rollup. This is useful in conjunction with yarn link
.yarn storybook
: Run Storybook development environmentyarn playroom
: Run Playroomyarn format
: Format all JS with Prettier
yarn lint
: Lint JS and CSS-in-JSyarn lint:js
: Lint JS with ESLint
yarn lint:css
: Lint CSS-in-JS with Stylelint
yarn size
: Test the file size of the buildyarn size:why
: Analyse the the buildyarn test
: Run all testsyarn test:js
: Run all JS tests with Jest
yarn test:coverage
: Run a code coverage test with Jestyarn test:watch
: Run test suite while watching for changesThe boilerplate 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.
There is a pre-build script that is be run by npm when you publish (npm run prebuild
)
Made by Zander ⚡