illegalCreed

中文

English

中文

English

Appearance

参考：Panda CSS API 速查 ​

基于 Panda CSS 1.11.4 · 核于 2026-07

速查 ​

  • 定位：构建期类型安全 CSS-in-JS 引擎，静态分析 → PostCSS 原子 CSS → codegen；Chakra 团队出品，@pandacss/dev 实测 1.11.4（MIT）。运行时不生成/不注入样式。
  • 核心链路：install @pandacss/dev → panda init -p → 配 include/PostCSS → 入口 CSS @layer reset,base,tokens,recipes,utilities; → panda codegen → 写 css()。
  • 运行期 API（来自 styled-system）：css/cva/sva/cx（/css）、token（/tokens）、配方函数（/recipes）、pattern 函数（/patterns）、styled/Box/splitCssProps（/jsx）。
  • 配置期 API（来自 @pandacss/dev）：defineConfig/defineRecipe/defineSlotRecipe/defineTokens/defineTextStyles/definePattern。
  • 级联层：@layer reset, base, tokens, recipes, utilities（右者优先级最高）。
  • 断点：sm/md/lg/xl/2xl；响应式用 { base, md, ... } 条件对象。
  • 官方资源：panda-css.com ｜ GitHub ｜ npm @pandacss/dev。

一、导入路径速查 ​

导入来源用途
css / cva / sva / cxstyled-system/css写样式 / 原子配方 / 插槽配方 / 拼类名
tokenstyled-system/tokens按路径读 token 值（token.var() 给 var()）
配方函数（如 button）styled-system/recipes消费配置配方
stack / grid / flex …styled-system/patterns布局原语（函数式）
styled / Box / Stack / splitCssPropsstyled-system/jsxJSX 工厂/组件（需 jsxFramework）
HTMLStyledProps / RecipeVariantPropsstyled-system/types类型工具
defineConfig / defineRecipe / defineTokens / defineTextStyles@pandacss/dev配置期 API

二、核心 API 速查 ​

API说明
css(obj[, obj2])样式对象 → 原子类名字符串；多参深合并、后者覆盖前者
cva({ base, variants, compoundVariants, defaultVariants })原子配方：全量生成、不支持响应式变体、可与组件共置
defineRecipe({...})配置配方：JIT 生成、支持响应式变体、须注册进 config
sva({ slots, base, variants }) / defineSlotRecipe插槽配方：多部件组件，返回各 slot 类名映射
cx(...classes)拼接 className（类似 clsx）
token('colors.red.400')按路径读 token；token.var() 给 var(--...)
styled('button', recipe?, options?)JSX 工厂：样式当 props；选项含 forwardProps/shouldForwardProp/defaultProps/dataAttr
splitCssProps(props)拆样式 props 与其余 props（自定义组件吃样式 props）
recipe.splitVariantProps(props)拆变体 props 与其余 props

三、条件 / 伪状态速查 ​

类别示例
交互态_hover _active _focus _focusVisible _disabled
子元素_first _last _odd _even
伪元素_before _after _placeholder
ARIA/data_expanded(aria-expanded) _checked _selected；任意 '&[data-state=closed]'
朝向/方向_horizontal _vertical _portrait _landscape _ltr _rtl
明暗_dark _light
组/兄弟_groupHover _groupFocus _peerHover（父/兄加 group/peer 类）
at-rule 键'@media (...)' '@container' '@supports' '@layer'

Panda 内置 80+ 条件；属性级条件用 { base, _hover, md, ... } 对象，base 为默认值，可嵌套。

四、配置字段速查（panda.config.ts） ​

字段作用
preflight启用 CSS reset（@layer reset）
include / exclude静态分析的扫描范围（漏配→样式不生成）
outdir生成目录，默认 styled-system
jsxFrameworkreact/preact/vue/qwik/solid，启用 JSX 组件运行时
strictTokens / strictPropertyValues只准 token 值 / 校验属性值；破例用 '[任意值]' 逃生舱
theme.tokens / theme.semanticTokens原始 token / 语义 token（花括号引用 {colors.red.500}、明暗 { base, _dark }）
theme.textStyles命名排版组合（textStyle 消费）
theme.recipes注册配置配方
staticCss强制全量生成未被静态命中的变体（组件库分发）
conditions / patterns / utilities / globalCss / hooks自定义条件 / 布局原语 / 工具属性 / 全局样式 / 构建钩子

五、tokens 类型速查 ​

colors、gradients、sizes、spacing、fonts、fontSizes、fontWeights、letterSpacings、lineHeights、radii、borders、borderWidths、shadows、easings、opacity、zIndex、assets、durations、animations、aspectRatios、cursors（共 20+ 种）。

  • 必须 value 包裹：{ value: '#0FEE0F' }；嵌套默认用 DEFAULT 键。
  • 落地：--colors-primary 等 CSS 变量，声明在 :where(:root, :host)（低特异性，便于局部换主题）。

六、静态分析约束（易踩坑） ​

坑结果正解
传运行时动态值给 css()（css({ color: fromApi() })）漏提用 token/CSS 变量，或有限取值做 recipe 变体
运行时重命名属性（circleSize→size）漏提prop 名直接对应样式属性，或走 recipe
以为「零运行时 = 无 JS」误解仍带拼类名的轻量运行时，只是不在浏览器产/注 CSS
配置配方变体没被静态用到却想分发CSS 里没有该变体用 staticCss 全量生成
cva 想传响应式变体 props不支持改用 defineRecipe（配置配方支持）
老浏览器不支持 @layer层失效@csstools/postcss-cascade-layers polyfill

七、选型对比：CSS-in-JS 组 ​

维度Panda CSSStyleXvanilla-extractCSS ModulesTailwind
出品Chakra 团队MetaSeek（开源社区）打包器生态Tailwind Labs
提取机制静态分析源码 → PostCSS构建期编译构建期执行 .css.ts打包器作用域类名扫描 class 生成
运行时极轻（不注入）极轻零零零
产物原子 CSS原子 CSS作用域 class作用域 class原子 CSS
设计系统层完整（token/recipe/pattern）少（偏原语）中（recipe/sprinkles）无中（theme+工具类）
类型安全强强强弱弱（靠插件）
RSC/SSR友好友好友好友好友好
一句话类型安全的完整样式引擎可预测的原子样式原语文件即样式契约局部作用域基线class 字符串原子化

八、权威链接 ​