Chakra UI v3.7.0自定义zIndex、borderWidths Token失效求助

问题描述 #

使用Chakra UI v3.7.0时，自定义zIndex和borderWidths Token后无法生效，其余Token（如colors、fonts等）正常，浏览器中--chakra-z-index-modal这类CSS变量显示为undefined。

解决步骤 #

1. 修正Token的value类型
   Chakra UI v3对zIndex Token的类型有要求，需使用数字类型而非字符串。将zIndex的value从字符串改为数字，borderWidths的value保持字符串（如'1px'）即可。

修正后的tokens示例：

export const tokens = defineTokens({
  borderWidths: {
    thin: { value: '1px' },
    thick: { value: '2px' },
    medium: { value: '1.5px' },
  },
  colors: colorsToken,
  fonts: fontsToken,
  fontSizes: fontSizesToken,
  fontWeights: fontWeightsToken,
  radii: radiiToken,
  sizes: sizesToken,
  spacing: spacingToken,
  zIndex: {
    hide: { value: -1 },
    base: { value: 0 },
    docked: { value: 10 },
    dropdown: { value: 1000 },
    sticky: { value: 1100 },
    banner: { value: 1200 },
    overlay: { value: 1300 },
    modal: { value: 1400 }, // 改为数字类型
    popover: { value: 1500 },
    skipNav: { value: 1600 },
    toast: { value: 1700 },
    tooltip: { value: 1800 },
    max: { value: 2147483647 },
  },
})

2. 正确合并配置
   直接通过createSystem(defaultConfig, customConfig)可能导致配置合并优先级异常，改用Chakra提供的mergeConfig工具确保自定义Token正确覆盖默认值：

import { mergeConfig } from '@chakra-ui/system'

const customConfig = defineConfig({
  theme: {
    tokens: tokens,
    // 其他主题配置...
  },
})

const finalConfig = mergeConfig(defaultConfig, customConfig)
const system = createSystem(finalConfig)

3. 清除缓存并重启服务
   开发环境中缓存可能导致Token未更新，重启开发服务器并清除浏览器缓存，确保新配置生效。

4. 验证Token引用方式
   在组件中使用Token时，确保通过Chakra的样式属性或useToken钩子正确引用：

// 组件中使用zIndex Token
<Box zIndex="modal">...</Box>

// 或通过useToken获取
const zIndexModal = useToken('zIndex', 'modal')

内容的提问来源于stack exchange，提问作者Tuhin