css

This repo is a proof of concept for the Sanity Design System’s design tokens distribution.

At present, it demonstrates ingesting design tokens from a dataset in Content Lake (which uses a schema adhering to the the DTCG’s Design Tokens spec) and emitting DTCG compliant JSON tokens and CSS custom properties.

Usage

Install via npm:

npm i @sanity-labs/design-tokens

Then import what you need:

@import '@sanity-labs/design-tokens/css/color.css';

Project structure

src

Contains the fetchTokens function and associated tokenQueries used by that function. fetchTokens, as you'd expect, fetches design token documents from the Design Tokens dataset. Each tokenQuery (organized by token type) includes a Groq projection which returns token data in a {name, $type, $value} structure to facilitate ease of serialization to DTCG spec compliant JSON tokens.

scripts

Scripts for composing ingestion of design token documents and emission of JSON tokens and CSS custom properties.

The build-json script runs first. It takes the output of the fetchTokens function (which is an object of tokens keyed by token group, e.g. color, fontFamily…), and for each token group:

1. Sorts tokens alphabetically
2. Reformats the array of tokens into an object keyed by token name (thus returning a {tokenName: tokenContent} structure)
3. Writes the token group’s tokens to a new JSON file in dist/json

The build-css script operates on the JSON files written by build-json. It creates CSS custom properties for every JSON token by leveraging Style Dictionary with some minimal configuration. In particular, instead of Style Dictionary’s default output — a single CSS file containing every single design tokens as CSS custom properties — the file structure of the JSON tokens (organized by token group) is preserved, in order to keep the generated CSS clearly delineated and importable in small, categorized chunks. These are written to dist/css.

The build-css-manifest script handles enumerating the generated CSS files and preparing an index.css manifest file, which allows importing the entire CSS bundle in one go.

dist

JSON and CSS output is written to the dist directory.

Token definitions

Tokens are defined in Content Lake via the design tokens studio, which be accessed via the Sanity org’s dashboard.

Where can I go to discuss this?

Head to the #prj-design-system channel on Slack!