Search

Measure color usage

Vinh
Vinh
  • Updated

You are able to analyze the usage of non-token colors in your codebase using a command line tool. This data is then sent to zeroheight and can help give an overview of where increased token use could help conform to your design system.

How to get set up

Requirements

To get the best experience, you'll need to ensure you have the following:

  • Familiarity with the terminal
  • Node = 20

Using the CLI

Getting access

You can access @zeroheight/adoption-cli on the NPM registry.

Authenticate zh-adoption with zeroheight

You will need to authenticate to import the results into your zeroheight account. These can be created in your organization settings if you did not create them during the Adoption setup flow. You must grant the access level of "zeroheight CLI - read and write".

  1. Authenticate the CLI with zeroheight 
    npx @zeroheight/adoption-cli auth
  2. You will be asked for a Client ID and an Access Token.

You are now ready to send color usage to zeroheight.

How to track color usage

  1. Run the following command in the repository you wish to get insight into: 
    npx @zeroheight/adoption-cli analyze
  2. You will then be presented with the component usage analyze flow, this is optional to complete.
  3. When you are asked if you want to scan files to learn about color usage, you should press Y and then Enter
  4. You will be asked if you want to see more details, this is optional
  5. Once analysis is complete, you can then press Y then Enter to send the color usage data to zeroheight
  6. The first time you run the command, you will be asked to name the repository you are in, so that you can identify it in zeroheight

Viewing in zeroheight

Head over to the Adoption tab in your account and you should see two charts of how non-token colors are being used within your projects.

You can dig further into the overall usage of color to see how it changes over time. You can filter down to see usage within each repo over a range of the past 7, 30 or 90 days.

You are able to see which colors are being used the most and within with repositories.

You can then further dig into the individual colors to see how they are being used and if there are similar colors that are being used in different formats

FAQ

Which frameworks are supported by the color usage feature?

Color usage scans codebases for use of color values in the following formats:

This means it is compatible with all frameworks that use these color formats—this includes all major web formats.

It is not currently compatible with mobile code, but this is something we might add support for in future.

What data is sent to zeroheight?

Currently, the zh-adoption CLI only sends usage information about the values of the colors being used as well as the name of the file they are located in. We do not send the entire codebase to zeroheight.

How do I install and run the CLI in a project?

If you prefer to install the CLI into a specific project instead of using npx, you can do the following:

  1. In your terminal, run: npm i @zeroheight/adoption-cli
  2. Authenticate with zh-adoption auth (this only has to be done once)
  3. Analyze a project by running zh-adoption analyze within the project directory you wish to analyze color usage.

Where can I view the documentation for the CLI?

You can view the documentation in the README on NPM at @zeroheight/adoption-cli

Was this article helpful?