Usage

Install#

$ npm install -g tempera
$ yarn add global tempera

Run Commands#

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]

Scorecard#

Gather metrics around the adoption of a design system.

USAGE
  $ tempera scorecard -s https://www.figma.com/developers -t ./tokens.js

OPTIONS
  -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 enabled

DESCRIPTION
  ...
  Scorecard analyzes a web app or web page,
  collecting design system adoption metrics
  and insights for adoption.

Tokens#

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's scorecard command expects these tokens to be in the javascript/es6 format which you can generate using Style Dictionary except exported as CommonJS modules.

In other words, flat CommonJS modules in PascalCase are expected.

Support for tokens in ES6 format is on the roadmap.

Example:

module.exports.ColorBackgroundBase = "#ffffff";
module.exports.ColorBackgroundAlt = "#fcfcfcfc";

The scorecard 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 underlying css-types package that utilizes these matchers.

Output#

JSON Report#

Useful for creating custom reporters and tooling.

USAGE
  $ tempera scorecard -s https://www.figma.com/developers -t ./tokens.js -j -o report.json

Output#

{
  "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" }
}

Using the command via an API#

Running the Example#

Checkout the examples/scorecard/api directory locally.
Provide a sample tokens.js file to the root of the project.
Install the dependencies.

yarn install

Run the test.

yarn test

The results will be in the output.json file at the root of the working directory.

Implementing the API#

Install the dependencies.

yarn add tempera
yarn add string-argv

Import the scorecard command from the tempera dependency.
Pass the --tokens, --site, --json, and --output flags using the parseArgsStringToArgv method.
Run the scorecard.run method with the generated argv parameter.
Read the generated scorecard from the JSON object in the specified output file.
Do something with the scorecard represented as a JSON object.

Example#

import { parseArgsStringToArgv } from "string-argv";
import scorecard from "tempera/src/commands/scorecard";

const SITE = "https://www.npmjs.com/package/string-argv";

function generateScorecard() {
  const argv = parseArgsStringToArgv(
    `--tokens tokens.js --site ${SITE} --json --output output.json`
  );
  scorecard.run(argv);
}

await generateScorecard();

// read the generated scorecard from the JSON output
const results = fs.readFileSync('./output.json', 'utf8');

// do something with scorecard results

View the example

Help#

$ tempera --help [COMMAND]
USAGE
  $ tempera COMMAND