- Notifications
You must be signed in to change notification settings - Fork2
A CLI toolkit for aiding design tokens adoption.
License
michaelmang/tempera
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A CLI toolkit for aiding design tokens adoption.
$npm install -g tempera$yarn add global tempera
Note: This package is experimental. You may have better success by running the command locally:
USAGE $ git clone https://github.com/michaelmang/tempera.git $ yarn install $ ./bin/run [COMMAND]
Gather metrics around the adoption of a design system.
USAGE $ tempera scorecard -s https://www.figma.com/developers -t ./tokens.jsOPTIONS -s, --site=site site url to analyze -t, --tokens=tokens relative path to tokens file -j, --json=json (optional) flag to enable printing output as a JSON blob; requires -o, --output to be set -o, --output=output (optional) relative path for a JSON file to output; requires -j, --json to be enabledDESCRIPTION ... Scorecard analyzes a web app or web page, collecting design system adoption metrics and insights for adoption.
Design tokens are key-value pairs that represent a specification (aka "spec") of a design system.
If you are new to design tokens,here's a good place to start.
Tempera'sscorecard command expects these tokens to be in thejavascript/es6 format which you can generate using Style Dictionary except exported as CommonJS modules.
In other words, flat CommonJS modules in PascalCase are expected.
Example:
module.exports.ColorBackgroundBase="#ffffff";module.exports.ColorBackgroundAlt="#fcfcfcfc";
Support for tokens in ES6 format is on the roadmap.
Thescorecard command expects the tokens to match against one of the following matchers after being transformed to kebab case:
module.exports.BORDER_RADIUS=/border-radius/g;module.exports.BREAKPOINT=/max-width/g;module.exports.COLOR=/color/g;module.exports.DELAY=/delay/g;module.exports.DURATION=/duration/g;module.exports.FONT_FAMILY=/font-family/g;module.exports.FONT_SIZE=/font-size/g;module.exports.FONT_WEIGHT=/font-weight/g;module.exports.LINE_HEIGHT=/line-height/g;module.exports.SPACING=/margin|padding/g;module.exports.TIMING=/timing/g;
You can learn more about the underlyingcss-types package that utilizes these matchers.
Useful for creating custom reporters and tooling.
USAGE $ tempera scorecard -s https://www.figma.com/developers -t ./tokens.js -j -o report.json
{"unofficial":[{"type":"border-radius","attribute":"border-radius","unofficialValue":"0.500rem","nearestOfficialValue":"0.375rem"},// ...],"summary":[{"category":"Font Family","correct":0,"incorrect":79,"percentage":"0.00"},{"category":"Color","correct":159,"incorrect":195,"percentage":"44.92"},{"category":"Font Size","correct":73,"incorrect":104,"percentage":"41.24"},{"category":"Spacing","correct":264,"incorrect":322,"percentage":"45.05"},{"category":"Max Width","correct":1,"incorrect":25,"percentage":"3.85"},{"category":"Line Height","correct":112,"incorrect":14,"percentage":"88.89"},{"category":"Border Radius","correct":16,"incorrect":13,"percentage":"55.17"},{"category":"Font Weight","correct":78,"incorrect":2,"percentage":"97.50"}],"total":{"correct":703,"incorrect":754,"percentage":"48.25","grade":"F"}}
$tempera --help [COMMAND]USAGE $ tempera COMMAND
🤠 Howdy, developer! Thanks for being willing to contribute!
- Fork and clone the repo
- Run
yarn installto install dependencies - Create a branch for your PR with
git checkout -b pr/your-branch-name - Run
.bin/run/ [COMMAND]in the root of the repo to run commands locally
Tip: Keep your
masterbranch pointing at the original repository and makepull requests from branches on your fork. To do this, run:git remote add upstream https://github.com/michaelmang/tempera.gitgit fetch upstreamgit branch --set-upstream-to=upstream/master master
There are currently no tests but please document manual testing on PRs with your changes.
Please checkout thethe open issues.
Also, please watch the repo and respond to questions/bug reports/featurerequests! Thanks!
In addition to a CLI, Tempera offers other tools to improve design tokens adoption.
A Stylelint plugin that helps avoid the adoption of unofficial design specifications.
yarn add @tempera/stylelint-tokens
InstallStylelint and update your configuration file to utilize the plugin.
// stylelint.config.jsconsttokens=require("./fixtures/example-tokens");module.exports={// ...plugins:["@tempera/stylelint-tokens"],rules:{"@tempera/official-specs":tokens,},};
The plugin expects these tokens to be in thejavascript/es6 format which you can generate using Style Dictionary except exported as CommonJS modules.
In other words, flat CommonJS modules in PascalCase are expected.
Example:
module.exports.ColorBackgroundBase="#ffffff";module.exports.ColorBackgroundAlt="#fcfcfcfc";
Support for tokens in ES6 format is on the roadmap.
The underlying packages that support Tempera are publicly accessible.
You are welcome and encouraged to use these packages directly should you need a custom solution.
🚀Contributing to these packages is also welcome.
Utilities to categorize your CSS.
yarn add @tempera/css-types
const{// Example: matchers.SPACING// Contains a list of regex matchers to help match common types in CSS matchers,// example: getMatcher(postcssProperty)// Returns a regex matcher fitting for the provided property getMatcher,// Example: types.SPACING// Contains a list of common types in CSS types,// Example: getType(postcssProperty)// Returns a common type fitting for the provided property getType,}=require("@tempera/css-types");
A PostCSS plugin that exposes hooks into design token adoption validation.
yarn add @tempera/postcss-scorecard
constpxToRem=require("postcss-pxtorem");constexpandShorthand=require("postcss-shorthand-expand");awaitpostcss().use(pxToRem()).use(expandShorthand).use(scorecard({onInvalid:(score)=>{// do something when CSS property is not an official spec},onValid:(score)=>{// do something when CSS property is an official spec},onFinished:()=>{// do something after validation finishes}, specs,// the official design tokens})).process(css,{from:undefined});
The plugin expects these specs/tokens to be in thejavascript/es6 format which you can generate using Style Dictionary except exported as CommonJS modules.
In other words, flat CommonJS modules in PascalCase are expected.
Example:
module.exports.ColorBackgroundBase="#ffffff";module.exports.ColorBackgroundAlt="#fcfcfcfc";
Support for tokens in ES6 format is on the roadmap.
An API that generates a Tailwind configuration from a set of design tokens.
yarn add @tempera/tailwind-config
importgetTailwindConfigfrom"@tempera/tailwind-config";consttailwindConfig=getTailwindConfig(tokens);// do something with the tailwind config
The plugin expects these specs/tokens to be in thejavascript/es6 format which you can generate using Style Dictionary.
In other words, flat modules in PascalCase are expected.
Example:
exportconstColorPrimary=blue;exportconstColorSecondary=yellow;
An API that generates a Twind instance from a set of design tokens.
yarn add @tempera/twind
importgetTwindfrom"@tempera/twind";const{ tw}=getTwind(tokens);functionDemo(){return(<divclassName={tw`text-primary`}> );}
The plugin expects these specs/tokens to be in thejavascript/es6 format which you can generate using Style Dictionary.
In other words, flat modules in PascalCase are expected.
Example:
exportconstColorPrimary=blue;exportconstColorSecondary=yellow;
An API that generates twind/style shapes from a set of design tokens.
yarn add @tempera/stitches
importgetStitchesfrom'@tempera/stitches';importgetTwindfrom'@tempera/twind';import{style}from'twind/style';importtokensfrom'./tokens';conststitches=getStitches(tokens);const{ tw}=getTwind(tokens);functionDemo(){constbutton=style(stitches.button);return(<div><buttonclassName={tw(button())}>Base Button</button><buttonclassName={tw(button({variant:'secondary'}))}> Secondary Button</button></div>);}
The plugin expects these specs/tokens to be in thejavascript/es6 format which you can generate using Style Dictionary.
In other words, flat modules in PascalCase are expected.
The tokens should follow the following format:
// base formatexportconstComponent[COMPONENT]Base[LONGHAND_CSS_PROPERTY];// size formatexportconstComponent[COMPONENT][SIZE][LONGHAND_CSS_PROPERTY];// variant formatexportconstComponent[COMPONENT][VARIANT][UI_STATE][LONGHAND_CSS_PROPERTY];
Examples:
exportconstComponentButtonBaseFontSize='1rem';exportconstComponentButtonBaseColor='red';exportconstComponentButtonSmallFontSize='0.75rem';exportconstComponentButtonSecondaryDefaultBackgroundColor='red';exportconstComponentButtonSecondaryDefaultColor='white';exportconstComponentButtonSecondaryDefaultFontSize='0.875rem';exportconstComponentButtonSecondaryHoverFontSize='0.75rem';exportconstColorPrimary='red';exportconstColorWhite='white';exportconstFontSizeTiny='0.75rem';exportconstFontSizeSmall='0.875rem';exportconstFontSizeMedium='1rem';exportconstLineHeightTiny='1rem';exportconstLineHeightSmall='1.25rem';exportconstLineHeightMedium='1.5rem';
About
A CLI toolkit for aiding design tokens adoption.