@moxiworks/mds-styles

@moxiworks/mds-styles is a universal style dictionary for MoxiWorks. It uses Amazon's style-dictionary to create a common set of design tokens that can be shared across different platforms and applications.

By defining tokens in Style Dictionary, designers and developers can create a shared language for describing and implementing design properties, making it easier to maintain consistency and coherence in a design system.

Installation

Via npm

The published npm package exposes javascript, typescript, css and scss variables to be consumed by the user.

When using typescript, you'll have access to the types by default when importing the js.

1. Install package

npm

npm install @moxiworks/mds-styles

yarn

yarn add @moxiworks/mds-styles

2. Import file

Javascript/Typescript

// JS can be directly imported
import { ColorPrimary } from '@moxiworks/mds-styles';

CSS

<link rel="stylesheet" href="./node_modules/@moxiworks/mds-styles/variables.css">

SCSS/SASS

@import '@moxiworks/mds-styles/variables';

Developing Locally

Setup the monorepo locally following the steps in the main README.md of the monorepo

Building the Style Dictionary

To build the style dictionary, run the following command:

yarn build

This will generate a dist directory containing the compiled design tokens.

Cleaning the Build Directory

If you need to clean the build directory, run the following command:

yarn clean

The clean command is also ran before each build.

Modifying/Creating tokens

Tokens define the values for the style dictionary. We've chosen to store them as common js modules, as we hope to be able to incorporate typescript in the near future.

style-dictionary automatically finds all .cjs files in the tokens directory, and creates the variables based on their structure.

Config

We have completely gone off the books for how this project is structured. Instead of using the suggested style-dictionary cli, we are using ts-node. This allows our src/index.ts file to be in typescript, which is extremely helpful since the style-dictionary docs are pretty subpar.

This does have some downsides. As we define the project as a module based rather than commonjs, we have to import commonjs files as .cjs, not .js. So you will notice that the tokens have remained .cjs rather than a typescript file.

Adding new output

The src/index.ts allows you to define the different platforms that are built. Ensure the buildPath is the 'dist/' directory.

Here are some of the pre-defined formats - https://amzn.github.io/style-dictionary/#/formats?id=pre-defined-formats

We are following the flat dictionary structure for consistency. For example, the javascript files are output as

"ColorPrimaryLight": "#ff0000"

instead of

color: {
    primary: {
        light: {
            value: '#ff0000'
        }
    }
}

If adding a output that can be consumed via the npm package, ensure you add it to the exports in the package.json

The "mds" prefix

All token names should be prefixed with 'mds'. Ensure any new outputs include it.

The "base" keyword

If a design token has the name "base", we omit it from the name. For example:

color: {
    primary: {
        base: {
            value: '#ff0000'
        }
    }
}

Will be output as MdsColorPrimary, mds-color-primary ...etc

Contributing

Commits must follow Semantic Commit conventions.

See our contributing guidelines for more information, and ways to get started.