cypress-plugin-designTokens

This project will allow you to check / verify designTokens assigned to css properties in the project

Description

This is a custom Cypress command that allows you to get the design tokens used for a specific CSS property on a given element. It searches through all the stylesheets in the document and returns an array of the design tokens used for the given CSS property on the element.

The cy.getDesignTokensByCssProperty command takes two arguments:

• subject: A jQuery element that you want to search for design tokens on.
• cssProperty: The name of the CSS property that you want to get design tokens for. Note - If no design tokens are found for the given CSS property on the element, an error will be thrown.

Installation

To use cy.getDesignTokensByCssProperty, you can copy the code for the command into your project's Cypress commands file (cypress/support/commands.{js|ts} by default). Alternatively, you can import the command from a separate JavaScript module.

Usage

You can then use the command like this:

Examples

import "@dlgshi/cypress-plugin-designtokens";

cy.get("#my-element").getDesignTokensByCssProperty("color").then((tokens) => {
  // Do something with the tokens
});

Get the design tokens for the color property on an element with ID my-element:

cy.get("#my-element").getDesignTokensByCssProperty("color").then((tokens) => {
  // Do something with the tokens
});

Get the design tokens for the margin property on all button elements:

cy.get("button").getDesignTokensByCssProperty("margin").then((tokens) => {
  // Do something with the tokens
});

Get the design tokens for the background-color property on an element with class my-class:

cy.get(".my-class").getDesignTokensByCssProperty("background-color").then((tokens) => {
  // Do something with the tokens
});

If the matching CSS rules use only one design token, the command returns a single-element array. If the rules use more than one token, the command returns an array of all the token names.

cy.get('button').getDesignTokensByCssProperty('color').then((tokens) => {
  // `tokens` is an array of design token names, or an empty array if no tokens were found
  console.log('Design tokens used in button color:', tokens);
});

To retrieve the first token name in the array, you can use array destructuring like this:

cy.get('button').getDesignTokensByCssProperty('color').then(([token]) => {
  // `token` is the first design token name used in the matching CSS rules, or `undefined` if no tokens were found
  console.log('First design token used in button color:', token);
});

If you're using TypeScript, you can import the DesignToken type from the @your-org/design-tokens package and use it to annotate the return type of the getDesignTokensByCssProperty command:

import type { DesignToken } from '@your-org/design-tokens';

declare global {
  namespace Cypress {
    interface Chainable {
      getDesignTokensByCssProperty(
        cssProperty: string
      ): Chainable<DesignToken[] | [DesignToken] | []>;
    }
  }
}

Example usage

cy.get('button').getDesignTokensByCssProperty('color').then((tokens) => {
  // `tokens` is an array of `DesignToken` objects, or an empty array if no tokens were found
  console.log('Design tokens used in button color:', tokens);
});

TypeScript support

In most cases, types work just by installing plugin, but you can add the types to your tsconfig.json

{
  "types": ["@dlgshi/cypress-plugin-designtokens"]
}

Dependencies

cy.getDesignTokensByCssProperty depends on the jQuery and Cypress libraries, and assumes that the design tokens used in the CSS styles are defined as CSS variables in the document's stylesheets.