This project contains cross-platform "design constants" for the
Swarm Design System, generated
using style-dictionary
;
Documentation is generated from properties/
and published on github pages:
- CSS Custom Properties
- More TK
See the dist/
directory for platfrom-specific distributions.
This project uses style-dictionary
and follows conventions of style-dictionary
.
This project follows these steps to create distributions:
- Read all JSON files in
properties/
. The properties defined in these files are known as "style properties". style-dictionary
transforms keys and properties from JSON into an intermediate format, a plain JS object referred to as "dictionary".style-dictionary
then can generate distributions from the "dictionary" object based on formats/templates specified inconfig.json
- On pushes to
master
, Travis builds a release and publishes an npm package containing adist/
directory. Thedist/
directory of the published package is a build artifact ofstyle-dictionary
.
Command | Result |
---|---|
yarn run build |
Compiles distributions |
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]
.
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.
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
:
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)"
Converts color values to android 8 digit hex
// Matches: color category properties
// Returns:
"#ff2e3e48"
"#ffffffff"
Returns a style property name as a CSS custom property definition name.
// Matches: all
// Returns:
"--c-blue"
"--c--textPrimary"
"--space-1"
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 }
}
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 }
}
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
:
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)';
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);
...
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)',
...
}
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
]
}
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;