@oqton/design-system

Design System

What should go into the Design System?

• Theme declaration
• React Components
• Helper Functions

What shouldn't go into the Design System?

• Application specific variables
• Application specific logic

Naming conventions

• Whenever matching a standard html attribute, props should stay consistent with existing w3 conventions. For example a button should use disabled, not isDisabled.

Static Assets

Static assets are stored in the public folder. These include things such as static images.

Design System Structure

The design system is split into the following categories:

• About
• Foundations
• Components
• Theme
• Locales
• Utils

About

A design system is a set of interconnected patterns and shared practices.

Patterns are the repeating elements that we combine to create the product: things like user flows, interactions, buttons, text fields, icons, colors, typography, microcopy, all of it. If it’s reusable, it goes in the system.

Practices are how we choose to create, capture, share and use those patterns.

Principles provide directions that help make decisions for the system.

Foundations

This is where we define the attributes for our design-system's theme. It is broken into the following sections:

• Breakpoints
• Colors
• Elevation
• Radii
• Spacing
• Typography

A theme is constructed from these foundations and then consumed by our code via styled-components and styled-system. See more on themes here

In order to implement components, responsive components, and layouts, we need a tool for managing spacing. For this, we use the following foundational components There are 5 components used for managing our spacing:

• Absolute: A div with position: absolute
• Box: A div with position: relative
• Fixed: A div with position: fixed
• Flex: A div with display: flex
• Sticky: A div with position: sticky

All design system components should inherit from these foundational components when declaring any sort of margin, padding, width, height, or flex amount.

Components

Components are used to as the building blocks to create the applications interface.

Each design system component should consist of the following files:

• Component - <component>.js

  • Imports and utilizes all styled components from <component>Styles.js
  • In charge of managing component-level state (may also be a stateless component)
  • In charge of declaring prop-types
  • Should declare default props wherever possible
  • Should include jsdoc comments for every unique (non-inherited) prop
  • Should add comments where appropriate to explain if extending prop functionality from another component (for example Flex should explain that it is extending props from the Box component)

• Style declarations - <component>Styles.js

  • Use styled-components to declare styles for every html element that will be used in the base component
  • Should use styled-system wherever possible
  • Should use our theme wherever possible
  • Should extend sibling design components wherever possible

• Storybook - <component>.stories.js

  • Should create stories to match UX's Sketch artboard for the corresponding component
  • Should create stories with the component and a knob for every prop that should be tuneable

• Tests - ./__tests__/<component>.test.js

  • If component has state, should test transition between states
  • Should test population of each proptype
  • Should utilize @testing-library/react to test calling all props that are functions

Theme

Full theming support by exporting a wrapper component. Also need to use utils.createTheme() to create or merge in any other themes.

import {Theme, utils} from '@oqton/design-system';

<Theme theme={utils.createTheme()} />

If you need to merge in another theme:

<Theme theme={utils.createTheme(anotherTheme)} />

This component provides a theme to all React components underneath itself via the context API. In the render tree all components will have access to the provided theme, even when they are multiple levels deep.

Workflows

Under development

Workflows try to capture the experience of a user during the interaction with the product.

Utils

Utility functions are organised here Each utility function should have a corresponding test suite to describe functionality

Scripts

"start-docz"

This will start docz on port 3001 in development mode

yarn start-docz

Your docz instance will be running on http://localhost:3001.

To view an online Docz site from the develop branch, visit: http://design-system.oqton.ai This instance is updated automatically upon merging into develop.

"test"

Run the tests

yarn test

"lint"

Run lint

yarn lint

"fix-lint"

Run lint and attempt to automatically fix issues

yarn fix-lint

"check-formatting"

Run formatting check

yarn check-formatting

"fix-formatting"

Run formatter

yarn fix-formatting