Restricting colour tokens per property

[loicplaire]

Hi, thanks for Panda CSS, it has been great to work with so far!

I have colour tokens that are roughly structured like this:

{
  "grey-50": { "value": "#ffffff", "type": "color" },
  "grey-500": { "value": "#dfe0e6", "type": "color" },
  "purple-900": { "value": "#3d1cba", "type": "color" },

  "surface-color": {
    "value": "{grey-50}",
    "type": "color",
  },
  "surface-color-accent": {
    "value": "{purple-900}",
    "type": "color",
  },

  "border-color": {
    "value": "{grey-500}",
    "type": "color",
  },
  "border-color-accent": {
    "value": "{purple-900}",
    "type": "color",
  },

  "text-color": {
    "value": "#1e163c",
    "type": "color",
  },
  "text-color-danger": {
    "value": "{red-900}",
    "type": "color",
  }
}

Ideally I would like:

• background CSS properties to only accept surface-* tokens
• border properties to only accept border-* tokens
• text colour to only accept text-* tokens
• etc.

For example:

// valid 
css({
  backgroundColor: 'surface-color',
  borderColor: 'border-color',
  color: 'text-color',
})

// not allowed 
css({
  backgroundColor: 'border-color',     // would like this to fail at type level
})

css({
  color: 'surface-color', // would like this to fail at type level
})

Is this kind of per property restriction currently possible in Panda, based on the token name or group? Or are all colour tokens always treated as part of a single colours space?

Thanks a lot for your help!

[segunadebayo]

This is an interesting idea that might be worth implementing.

[anubra266]

Thinking along this lines:

/**
 * Creates a function that filters color tokens by prefix
 * @param prefix - The prefix to filter by (e.g., 'surface', 'border', 'text')
 * @returns A PropertyValues function that returns filtered tokens
 */
const createColorTokenFilter = (prefix: string): PropertyValues => {
  return (tokens) => {
    const allColors = tokens('colors') || {}
    const filtered: Record<string, string> = {}

    // Filter tokens that start with the specified prefix
    Object.keys(allColors).forEach(tokenName => {
      if (tokenName.startsWith(`${prefix}-`)) {
        filtered[tokenName] = allColors[tokenName]
      }
    })
    console.log({ filtered })

    return filtered
  }
}

/**
 * Predefined filter for text color tokens (text-*)
 */
const textColors = createColorTokenFilter('text')

export default defineConfig({
  utilities: {
    extend: {
      color: {
        className: 'c',
        values: textColors,
        group: 'Color',
      },
    }
  },
})

[zslabs]

That's exactly what I've been doing 💪 What would be nice for Panda CSS to provide, would be "grouped" utilities that could label something related to specific attributes so we don't need to construct or keep up with this list ourselves:

const utilities: UtilityConfig = {
  // --- Background-like colors ---
  backgroundColor: colorUtility('bg-c', backgroundLikeColors),
  fill: colorUtility('fill', backgroundLikeColors),
  gradientFrom: colorUtility('grad-from', backgroundLikeColors),
  gradientTo: colorUtility('grad-to', backgroundLikeColors),
  gradientVia: colorUtility('grad-via', backgroundLikeColors),
  boxShadowColor: colorUtility('bx-sh-c', backgroundLikeColors),
  scrollbarColor: colorUtility('scr-bar-c', backgroundLikeColors),

  // --- Text-like colors ---
  color: colorUtility('c', textLikeColors),
  textDecorationColor: colorUtility('td-c', textLikeColors),
  caretColor: colorUtility('ca-c', textLikeColors),
  accentColor: colorUtility('ac-c', textLikeColors),

  // --- Border-like colors ---
  borderColor: colorUtility('bd-c', borderLikeColors),
  borderTopColor: colorUtility('bd-t-c', borderLikeColors),
  borderBottomColor: colorUtility('bd-b-c', borderLikeColors),
  borderLeftColor: colorUtility('bd-l-c', borderLikeColors),
  borderRightColor: colorUtility('bd-r-c', borderLikeColors),
  borderInlineStartColor: colorUtility('bd-s-c', borderLikeColors),
  borderInlineEndColor: colorUtility('bd-e-c', borderLikeColors),
  borderInlineColor: colorUtility('bd-x-c', borderLikeColors),
  borderBlockColor: colorUtility('bd-y-c', borderLikeColors),
  borderBlockStartColor: colorUtility('bd-bs-c', borderLikeColors),
  borderBlockEndColor: colorUtility('bd-be-c', borderLikeColors),
  outlineColor: colorUtility('ring-c', borderLikeColors),
  stroke: colorUtility('stk', borderLikeColors),
  ...

[segunadebayo]

Interesting idea! We're considering supporting dot-paths in the utility values config to scope tokens per property. It would look like this:

First, structure your tokens by intent:

export default defineConfig({
  theme: {
    tokens: {
      colors: {
        surface: {
          default: { value: '#ffffff' },
          accent: { value: '#3d1cba' },
        },
        border: {
          default: { value: '#dfe0e6' },
          accent: { value: '#3d1cba' },
        },
        text: {
          default: { value: '#1e163c' },
          danger: { value: '#c00' },
        },
      },
    },
  },
})

Then scope utilities to specific token groups:

export default defineConfig({
  utilities: {
    backgroundColor: {
      values: 'colors.surface',
    },
    borderColor: {
      values: 'colors.border',
    },
    color: {
      values: 'colors.text',
    },
  },
})

With strictTokens: true, TypeScript would only autocomplete and accept tokens from the scoped group — backgroundColor would suggest surface and surface.accent but reject border.default.

This encourages organizing tokens by intent rather than by visual property, which tends to scale better for design systems. Would this approach work for your use case? @loicplaire @zslabs

[zslabs]

Yep, that sounds useful! In my use-case, we have three layers:

1. Palette colors
2. Named variations based off of those palette colors
3. Semantic tokens based off of each of those for team-specific usage, collab.header.background

Do you see a path where Panda could handle "tagging" the different areas like I mentioned above -- where backgroundColor and boxShadowColor would be in the same bucket, or just more awareness on configuring these properties to our liking? It'd be great to expose that property strictness in types we could apply to semantic tokens as well if that's not too much in the weeds.

One suggestion as well; if values can accept an array, that'd be helpful for grouping different color categories together.

[segunadebayo]

One suggestion as well; if values can accept an array, that'd be helpful for grouping different color categories together.

Could you elaborate on what you mean by this?

[zslabs]

Sure! So in the example you shared:

export default defineConfig({
  utilities: {
    backgroundColor: {
      values: ['colors.surface', colors.palettes']
    },
    ...
  },
})

Just in case we have things structured a bit different within the colors object itself.