panda-plugin-ct

A Panda CSS plugin to create aliases to tokens without generating alias-level class names.

The plugin allows you to structure your tokens in a way makes sense to you, and does not need to adhere to Panda's token structure.

---

Installation

npm i panda-plugin-ct

// panda.config.ts

import { defineConfig } from '@pandacss/dev';
import { pluginComponentTokens } from 'panda-plugin-ct';

export default defineConfig({
  plugins: [
    pluginComponentTokens({
      alert: {
        background: 'red.500',
        text: 'gray.100',
      },
    }),
  ],
});

---

Usage

This plugin provides a fully-typed ct function to reference the aliases specified in your panda.config.ts file. These aliases exist outside of Panda's context and are replaced with the values you provide the plugin. These values can be anything that Panda works with, such as tokens, semantic tokens, objects with conditions, or raw values.

Example component styles:

// Component code

import { css, ct } from "../../styled-system/css";

<div className={css({
  display: 'flex',
  background: ct('alert.background')
})}>

Which will produce:

<!-- With ct -->
<div class="d_flex bg_red.500" />

<!-- With Panda's semanticTokens -->
<div class="d_flex bg_alert.background" />

/* With ct */
--colors-red-500: #ef4444;

/* With Panda's semanticTokens */
--colors-alert-background: var(--colors-red-500);

.d_flex {
  display: flex;
}

/* With ct */
.bg_red\.500 {
  background: var(--colors-red-500);
}

/* With Panda's semanticTokens */
.bg_alert\.background {
  background: var(--colors-alert-background);
}

---

Supported syntax

This plugin supports aliasing to Panda's object syntax via a value key, just as you would define semantic tokens in Panda's theme. Anything Panda supports will work, including raw values.

export default defineConfig({
  plugins: [
    pluginComponentTokens({
      alert: {
        background: {
          value: {
            base: 'red.500',
            lg: 'blue.500',
          },
        },
        text: {
          value: '#111',
        },
      },
    }),
  ],
});

<div className={css({
  background: ct('alert.background'),
  color: ct('alert.text'),
})}>

Produces:

<div class="bg_red.500 lg:bg_blue.500 text_#111" />

---

Further optimization

This plugin generates a performant JS runtime to map paths to their respective class names. This runtime can be completely removed using @pandabox/unplugin, with a transformer exported from this package. Your bundler's config will need to be modified to achieve this.

Example Next.js config:

import unplugin from '@pandabox/unplugin';
import { transform } from 'panda-plugin-ct';

// Your token object
// This should be the same as the object you supplied to the Panda plugin
const tokens = {};

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  webpack: (config) => {
    config.plugins.push(
      unplugin.webpack({
        transform: transform(tokens),
      }),
    );
    return config;
  },
};

export default nextConfig;

---

Acknowledgement

• Jimmy – for the idea and motivation behind the plugin
• Alex – for providing feedback with the plugin's internals and functionality