Cross-platform design constants for Swarm Design System
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis
doc/customProperties
properties
scripts
templates
.editorconfig
.eslintrc
.gitignore
.npmignore
.travis.yml
CHANGELOG.md
Makefile
README.md
config.json
package.json
yarn.lock

README.md

swarm-constants

npm version Build Status

This project contains cross-platform "design constants" for the Swarm Design System, generated using style-dictionary;

Table of Contents


Documentation

Documentation is generated from properties/ and published on github pages:

Using swarm-constants in your application

See the dist/ directory for platfrom-specific distributions.

Development

This project uses style-dictionary and follows conventions of style-dictionary.

Overview

This project follows these steps to create distributions:

  1. Read all JSON files in properties/. The properties defined in these files are known as "style properties".
  2. style-dictionary transforms keys and properties from JSON into an intermediate format, a plain JS object referred to as "dictionary".
  3. style-dictionary then can generate distributions from the "dictionary" object based on formats/templates specified in config.json
  4. On pushes to master, Travis builds a release and publishes an npm package containing a dist/ directory. The dist/ directory of the published package is a build artifact of style-dictionary.

Scripts

Command Result
yarn run build Compiles distributions

Modifying or adding values

Edit json files in properties/. Please use the "Category/Type/Item" convention for object structure. Colors should be expressed as an rgba array, [R,G,B,A].

Adding distributions

The style-dictionary library uses a config.json file to configure distributions. You can use one of the built in formats provided by style-dictionary, you can register your own format, or use one of the custom formats documented below.


Custom transforms

A transform is a function that is used to transform a value or key name from JSON. For example, transforming an [r,g,b,a] array into a hex or CSS color. swarm-constants uses a few custom transforms that are not provided by style-dictionary:

color/optimizedRGBA

Converts color values to optimized CSS rgba(). If alpha channel is 1, uses rgb().

// Matches: color category properties
// Returns:
"rgba(84, 96, 107, 0.6)"
"rgb(53, 62, 72)"

color/androidHex8

Converts color values to android 8 digit hex

// Matches: color category properties
// Returns:
"#ff2e3e48"
"#ffffffff"

name/cti/customProperty

Returns a style property name as a CSS custom property definition name.

// Matches: all
// Returns:
"--c-blue"
"--c--textPrimary"
"--space-1"

attribute/colorValues

Adds calculated color values to dictionary object properties.

// Matches: style properties in `color` category
// adds a `colorValues` object to each property of the dictionary
{
	colorValues: { rgba, hex, hsv, hsl, androidHex8 }
}

attribute/colorVarNames

Adds calculated color var names to dictionary object properties.

// Matches: style properties in `color` category
// adds a `colorVarNames` object to each property of the dictionary
{
	colorVarNames: { android, sass, js, customProperty }
}

Custom formats

A format is essentially a script or template to control the formatting of output for a given distribution. swarm-constants uses a few custom formats that are not defined in style-dictionary:

javascript/commonJS

Creates a JS file exporing all color values (using commonJS modules).

Example

exports.C_WHITE = 'rgb(255, 255, 255)';
exports.C_LIGHTGRAY = 'rgb(246, 247, 248)';
exports.C_MEDIUMGRAY = 'rgb(117, 117, 117)';

css/customProperties

Creates a file containing valid CSS custom property definitions.

Example

:root {
	--c-white: rgb(255, 255, 255);
	--c-lightGray: rgb(246, 247, 248);
	--c-mediumGray: rgb(117, 117, 117);
	...

js/JSObjectCustomProperties

Creates a JS file that exports an object with CSS custom property names as keys, and style property values as values. This is used to populate our PostCSS loader with fallback values for custom properties in style modules.

Example

customProperties: {
	'--c-white': 'rgb(255, 255, 255)',
	'--c-lightGray': 'rgb(246, 247, 248)',
	'--c-mediumGray': 'rgb(117, 117, 117)',
	...
}

javascript/colorAttributes

Creates a JS file that exports a list of objects containing meta info for each color property. This is used for generating documentation.

Example

   {
      "name": "white",
      "type": "base",
      "colorValues": {
         "rgba": "rgb(255, 255, 255)",
         "hex": "#ffffff",
         "hsv": "hsv(0, 0%, 100%)",
         "hsl": "hsl(0, 0%, 100%)",
         "androidHex8": "#ffffffff"
      },
      "colorVarNames": {
         "android": "color_base_white",
         "sass": "$C_white",
         "js": "C_WHITE",
         "customProperty": "var(--c-white)"
      },
      "originalValue": [
         255,
         255,
         255,
         1
      ]
   }

scss/variablesCustom

Formats Sass variables, following our naming conventions. Does not include style properties in the responsive category, as those are handled by CSS custom properties.

Example

$C_white: rgb(255, 255, 255);
$space-1: 16px;