Digital Design System (DDS)

Design Tokens

Design tokens are platform agnostic and semantic variables that are communicated across applications within a Design System. The tokens represent intended and common design attributes and scope and allows for the maintenance and scaling of consistent visuals within a Design System.

By employing the use of a build system (we use Style Dictionary), design tokens can be defined once in a platform agnostic format (we use JSON), but made available for any platform or language to consume.

Usage

You can install the package like a normal NPM (Nexus) dependency. Design Tokens can be imported from the package /themes folder into your project and used as variables in both build-time or run-time.

npm install olly_design-tokens

Example with React and Styled Components

You can inject Design Tokens as themes into all styled components through the use of a ThemeProvider, via the context API.

app.tsx:

import { ThemeProvider } from 'styled-components'
import OLLY_LIGHT_BASE_BASE from "olly_design-tokens/themes/olly_light_base_base/json/nested/tokens.json"

const Box = styled.div`
  color: ${props => props.theme.theme.color.neutral.110};
`

<ThemeProvider theme={OLLY_LIGHT_BASE_BASE}>
  <Box>I'm slate-110!</Box>
</ThemeProvider>

As a bonus, you may extend type definitions for styled-components with the Design Tokens structure.

styled.d.ts:

import "styled-components"
import OLLY_LIGHT_BASE_BASE from "olly_design-tokens/themes/olly_light_base_base/json/nested/tokens.json"

import type { DefaultTheme } from "styled-components"

type CustomTheme = typeof OLLY_LIGHT_BASE_BASE

declare module "styled-components" {
  export interface DefaultTheme extends CustomTheme {}
}

Supported themes

| Name | Brand | Polarity | Contrast | Scale | Status | | ------------------------- | ------- | -------- | -------- | ----- | --------------- | | olly_light_base_base | olly | light | base | base | In progress | | olly_light_high_base | olly | light | high | base | Not started | | olly_dark_base_base | olly | dark | base | base | In progress | | olly_dark_high_base | olly | dark | high | base | Not started | | themeblue_light_base_base | themeblue | light | base | base | In progress | | themeblue_light_high_base | themeblue | light | high | base | Not started | | themeblue_dark_base_base | themeblue | dark | base | base | In progress | | themeblue_dark_high_base | themeblue | dark | high | base | Not started | | themebronzelight_base_base | themebronze | light | base | base | In progress | | themebronzelight_high_base | themebronze | light | high | base | Not started | | themebronzedark_base_base | themebronze | dark | base | base | In progress | | themebronzedark_high_base | themebronze | dark | high | base | Not started |

Supported formats

| Format | Type | Source | | ------ | ------ | ----------------------------------------------------------- | | JSON | Nested | olly_design-tokens/themes/{theme}/json/nested/tokens.json | | JSON | Flat | olly_design-tokens/themes/{theme}/json/flat/tokens.json | | JS | | olly_design-tokens/themes/{theme}/js/tokens.js | | CSS | | olly_design-tokens/themes/{theme}/css/tokens.css | | SCSS | | olly_design-tokens/themes/{theme}/css/tokens.scss |

Design token structure

In the DDS we've defined our design tokens in 2 main types: declarative and semantic tokens.

Declarative tokens

Declarative tokens are primitive; they have no semantic value. They represent common/general design attributes (e.g. typography, colors, etc.) and are useful for governing what token values are permissible for use within a specific scope. The two categories of declarative tokens we've defined are foundation and theme tokens.

| Category | Description | | ------------ | -------------------------------------------------------------------------------------------------------- | | foundation | Contains all permissible token values within the Design System. | | theme | Contains a customisable subset of token values specific to a theme (e.g. light-mode, dark-mode, etc.). |

Structure

{category}.{property}.{item}.{variant} = token value
e.g. foundation.color.slate.10 = "#f5f7f9"

Semantic tokens

Semantic tokens are intentional and specific. They represent design attributes used in describing objects (e.g. components, patterns, etc.) in the Design System. They are useful for maintaining consistent visuals across applications. The only category of semantic tokens we've defined is component tokens.

| Category | Description | | ----------- | -------------------------------------------------------------------------- | | component | Contains token values describing the specific component it is named after. |

Structure

{category}.{item}.{variant}.{scale}.{state}.{property} = token value
e.g. component.button.primary.default.default.color = "#ffffff"

Build system structure

.
└───data
│   │
│   └───foundation
│   │   │   typography.tokens.json
│   │   │   space.tokens.json
│   │   │   color.tokens.json
│   │   │   surface.tokens.json
│   │   │   motion.tokens.json
│   │
│   └───themes
│   │   │   default.tokens.json
│   │   │   {theme}.tokens.json
│   │
│   └───components
│       └───alert
│       │   │   default.alert.tokens.json
│       │   │   {theme}.{item}.tokens.json
│       │
│       └───{item}
│
│
└───themes
│   └───default
│   └───{theme}
│
│ ...

• Source files contain authored source design token files
• {theme} files within data/themes/ determine how many sets are generated

Credits

Khalil Stemmler - Node + Typescript starter

• https://khalilstemmler.com/blogs/typescript/node-starter-project/
• https://khalilstemmler.com/blogs/typescript/eslint-for-typescript/
• https://khalilstemmler.com/blogs/tooling/prettier/
• https://khalilstemmler.com/blogs/tooling/enforcing-husky-precommit-hooks/