Panda CSS

类型安全、设计 Token 友好的零运行时样式系统，由 Chakra UI 团队打造。

技术简介说明

Panda CSS 是由 Chakra UI 作者 Segun Adebayo 创建的零运行时 CSS-in-JS 框架。它结合了 TypeScript 类型安全、设计 Token 系统和原子化 CSS 的优势，在构建时生成静态 CSS 文件，运行时不执行任何样式相关的 JavaScript 代码。Panda CSS 的核心目标是为开发者提供类似 Chakra UI 的直观开发体验（DX），同时保持零运行时的性能优势。

Panda CSS 的独特之处在于其三层设计 Token 架构（基础 Token → 语义 Token → 组件 Token），配合 W3C 设计令牌规范的支持，使其成为构建大型设计系统和多品牌应用的理想选择。它还是 Chakra UI v3 的底层样式引擎，经过生产验证。

2025 年 8 月，Panda CSS 发布了 v1.0 稳定版，标志着 API 正式进入稳定期。2026 年中，v2.0 Beta 引入了基于 Rust/Oxc 的编译引擎，构建性能提升了 17 倍，内存占用降低了 25 倍，展现出强劲的技术演进势头。

基本信息

• 官网：https://panda-css.com/
• GitHub：https://github.com/chakra-ui/panda （⭐ 6.1k+）
• License：MIT
• 最新版本：v1.11.1（稳定版，2026-05-08）；v2.0.0-beta.8（测试版，2026-07-01）
• 主要维护者/公司：Segun Adebayo（Chakra UI 作者）、astahmer（Alexandre Stahmer）；Chakra UI 组织

快速上手

安装

Next.js 项目（推荐方式）：

# 安装核心包
npm install -D @pandacss/dev
 
# 初始化配置
npx panda init

Vite 项目：

npm install -D @pandacss/dev @pandacss/vite

Remix / React Router 7：

npm install -D @pandacss/dev
# 通过 PostCSS 集成

通用 PostCSS（适用于任何支持 PostCSS 的构建工具）：

npm install -D @pandacss/dev @pandacss/postcss

基础配置

1. 生成 panda.config.ts（通过 npx panda init）：

import { defineConfig } from '@pandacss/dev'
 
export default defineConfig({
  // 启用 React JSX 支持
  jsxFramework: 'react',
  
  // 扫描文件范围
  include: ['./src/**/*.{js,jsx,ts,tsx}'],
  
  // 输出目录（生成的类型和样式）
  outdir: 'styled-system',
  
  // 主题配置
  theme: {
    extend: {
      tokens: {
        colors: {
          primary: { value: '#007bff' },
          secondary: { value: '#6c757d' },
        },
        spacing: {
          sm: { value: '4px' },
          md: { value: '8px' },
          lg: { value: '16px' },
        },
      },
      semanticTokens: {
        colors: {
          text: {
            value: {
              base: '#1a202c',
              _dark: '#f7fafc',
            },
          },
          background: {
            value: {
              base: '#ffffff',
              _dark: '#1a202c',
            },
          },
        },
      },
    },
  },
})

2. PostCSS 配置（postcss.config.js）：

module.exports = {
  plugins: {
    '@pandacss/postcss': {},
  },
}

3. Vite 配置（可选，替代 PostCSS）：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import panda from '@pandacss/vite'
 
export default defineConfig({
  plugins: [react(), panda()],
})

4. 在 package.json 中添加准备脚本：

{
  "scripts": {
    "prepare": "panda codegen",
    "dev": "next dev",
    "build": "next build"
  }
}

5. 在入口文件导入生成的样式：

// app/layout.tsx 或 main.tsx
import '../styled-system/styles.css'

最小示例

import { css, cx } from '../styled-system/css'
import { stack, hstack } from '../styled-system/patterns'
 
function App() {
  return (
    <div className={stack({ gap: '8', padding: '4' })}>
      <h1 className={css({ fontSize: '2xl', fontWeight: 'bold', color: 'primary' })}>
        Hello Panda CSS
      </h1>
      <div className={hstack({ gap: '4' })}>
        <button
          className={css({
            bg: 'primary',
            color: 'white',
            px: '4',
            py: '2',
            borderRadius: 'md',
            _hover: { opacity: 0.9 },
          })}
        >
          点击我
        </button>
      </div>
    </div>
  )
}

构建后，Panda CSS 会扫描所有文件，识别使用的样式，并生成对应的原子化 CSS 类到 styled-system/styles.css。

核心概念与架构

三阶段处理流程

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  1. Load Context │ →  │ 2. Generate Arts  │ →  │ 3. Extract CSS  │
│  解析配置+预设   │    │  生成类型+JS产物  │    │  扫描文件+写CSS │
└─────────────────┘    └──────────────────┘    └─────────────────┘

阶段 1 — Load Context：评估 panda.config.ts，合并预设（presets），创建解析器

阶段 2 — Generate Artifacts：写入 styled-system/ 目录，包括：

• css/ — css()、cx() 等函数
• tokens/ — Token 访问函数
• patterns/ — 布局模式（Stack、Grid 等）
• recipes/ — 配方函数
• types/ — TypeScript 类型定义

阶段 3 — Extract Styles：在每个文件上运行解析器，识别使用的样式，计算并写入 styles.css

静态分析引擎

v2 性能提升（~3,300 文件大型项目）

核心特性

• 零运行时（Zero-Runtime）：构建时生成静态 CSS，无浏览器端样式注入开销，极小运行时 JS 仅用于类名连接
• 完整 TypeScript 类型安全：从配置自动生成类型定义，IDE 智能提示、自动补全、编译时类型检查全覆盖
• 三层设计 Token 系统：基础 Token（原始值）→ 语义 Token（按用途命名 + 条件值）→ 组件 Token，遵循 W3C 设计令牌规范
• Recipe 配方系统：两种配方类型——Atomic Recipes（cva，与组件共置）和 Config Recipes（panda.config.ts 中定义，JIT 生成），支持多变体、复合变体
• Pattern 布局模式：预定义 Stack、HStack、VStack、Grid 等常用布局，可自定义扩展
• Conditions 条件系统：内置 hover、focus、dark mode、active 等条件，支持自定义条件（如 @media print）
• Presets 预设系统：可共享的配置包，支持 Token、Recipe、Pattern 的复用，适合设计系统分发
• 多品牌支持：通过预设和语义 Token 实现多品牌设计系统
• Text Styles：可复用的文本样式定义
• RSC 完全兼容：零运行时特性天然兼容 React Server Components
• Deprecation 机制：可标记废弃的 Token 和配方，平滑迁移

生态图

框架集成

生态项目

关键依赖

适用场景

• 设计系统构建：Panda CSS 的三层 Token 架构、Recipe 配方系统和 Presets 预设系统是构建大型设计系统的完整工具链，Chakra UI v3 本身就是基于 Panda 构建
• 企业级应用：TypeScript 类型安全确保跨团队协作的一致性，语义 Token 支持多品牌和多主题
• 类型安全优先项目：从配置到使用全程类型安全，IDE 智能提示覆盖 Token、Recipe、Pattern、条件等所有维度
• 多品牌/多主题应用：通过 Presets 和语义 Token 的条件值（_dark、自定义条件），实现灵活的品牌/主题切换
• 性能敏感项目：零运行时 + 原子化 CSS + Tree Shaking 确保最小的运行时开销和 Bundle 大小
• Chakra UI 迁移项目：Panda CSS 提供与 Chakra UI 相似的开发体验（style props），是 Chakra v2 → v3 迁移的自然路径
• 组件库开发：Config Recipes 可在 Presets 中共享，适合构建可分发的组件库

开发与工程化

开发流程

1. 初始化：npx panda init 生成 panda.config.ts 和 PostCSS 配置
2. 配置设计 Token：在 panda.config.ts 中定义 colors、spacing、fonts 等 Token
3. 定义 Recipe：为组件定义多变体样式配方
4. 编写组件：使用 css()、stack()、grid() 等函数编写样式
5. 开发调试：panda codegen 生成类型，开发时实时反映变化
6. 构建部署：Panda 自动扫描文件并提取使用的样式

文件组织建议

src/
├── recipes/              # Recipe 定义
│   ├── button.ts
│   └── card.ts
├── tokens/               # Token 扩展
│   ├── colors.ts
│   └── spacing.ts
├── patterns/             # 自定义 Pattern（可选）
│   └── custom-grid.ts
├── presets/              # 可共享预设（可选）
│   └── brand-a.ts
├── components/
│   ├── Button.tsx
│   └── Card.tsx
└── app/
    └── layout.tsx        # 导入 styled-system/styles.css

styled-system/            # 生成目录（加入 .gitignore）
├── css/
├── tokens/
├── patterns/
├── recipes/
├── types/
└── styles.css

CI/CD 集成

• 在 CI 中运行 panda codegen 确保类型生成
• 构建时 Panda 自动扫描文件并提取样式
• 建议在 CI 中添加 panda check（如果可用）验证配置正确性
• styled-system/ 目录不提交到 Git（加入 .gitignore）
• 升级到 v2 可获得显著的 CI 构建速度提升（17x）

Monorepo 支持

• v1 中跨包导入 JS 对象（Token、配方）需特殊配置
• v2 引入 designSystem: '@acme/ds' 配置简化 monorepo 场景
• 每个包可以有自己的 panda.config.ts，通过 Presets 共享配置

性能与安全

性能特点

CSS 输出优化

• 原子化 CSS：每个属性一个类，最大化复用
• Cascade Layers：使用 @layer 控制样式优先级
• :where 选择器：降低特异性，减少样式冲突
• CSS Variables：自动生成 CSS 变量，支持动态主题切换

性能优化建议

1. 使用 staticCss 预生成常用样式——避免运行时计算
2. 合理使用 Recipes——比内联 css() 更高效，JIT 仅生成使用的变体
3. 升级到 v2——获得 Rust/Oxc 引擎的 17x 构建性能提升
4. 避免过度使用 css() 内联——复杂样式优先使用 Recipe
5. 配置 include 精确范围——减少不必要的文件扫描

安全注意事项

• Panda CSS 生成的 CSS 类名是原子化的哈希值，不存在 XSS 注入风险
• Token 值是静态的，不存在运行时注入风险
• CSS 变量自动生成，注意不要在组件中暴露用户输入到 CSS 变量

已知性能瓶颈

• v1 构建时间：大项目（3,000+ 文件）编译可能需要 60+ 秒，内存占用 ~4GB
• TypeScript 类型生成：panda codegen 在大型配置中可能较慢
• 首次冷启动：开发服务器首次启动需要生成 styled-system/，有额外延迟

技术对比

关键对比结论

• vs Tailwind CSS v4：Tailwind 生态无敌（12M+ 项目），但缺乏 TypeScript 类型安全和设计 Token 系统；Panda CSS 适合需要严格类型管理的项目
• vs vanilla-extract：vanilla-extract 更成熟、框架支持更广；Panda CSS 开发体验更直观（style props），Chakra UI 生态更强
• vs Pigment CSS：Panda CSS 更成熟（v1 稳定 vs Alpha）、社区更大、框架限制更少
• vs Kuma UI：Panda CSS 生态更完善、维护更活跃；Kuma UI 有独特的 Headless 组件系统但社区规模小

最佳实践

设计 Token 管理

// panda.config.ts
export default defineConfig({
  theme: {
    extend: {
      tokens: {
        colors: {
          // 基础 Token：原始设计值
          blue: { 50: { value: '#eff6ff' }, 500: { value: '#3b82f6' }, 900: { value: '#1e3a8a' } },
          gray: { 50: { value: '#f9fafb' }, 500: { value: '#6b7280' }, 900: { value: '#111827' } },
        },
      },
      semanticTokens: {
        colors: {
          // 语义 Token：按用途命名 + 条件值
          text: {
            primary: { value: { base: '{colors.gray.900}', _dark: '{colors.gray.50}' } },
            secondary: { value: { base: '{colors.gray.500}', _dark: '{colors.gray.500}' } },
          },
          background: {
            surface: { value: { base: '#ffffff', _dark: '{colors.gray.900}' } },
            brand: { value: '{colors.blue.500}' },
          },
        },
      },
    },
  },
})

Recipe 选择指南

动态样式处理

// ✅ 方案1：CSS 变量（推荐）
function Component({ color }: { color: string }) {
  return (
    <div
      style={{ '--dynamic-color': color } as React.CSSProperties}
      className={css({ color: 'var(--dynamic-color)' })}
    />
  )
}
 
// ✅ 方案2：条件类名
const variants = {
  primary: css({ bg: 'primary', color: 'white' }),
  secondary: css({ bg: 'secondary', color: 'white' }),
}
function Button({ variant }: { variant: 'primary' | 'secondary' }) {
  return <button className={variants[variant]}>按钮</button>
}
 
// ❌ 避免：运行时直接传值
<div className={css({ color: props.color })} /> // 无法静态分析

常见陷阱

1. 运行时动态值——css({ color: props.color }) 无法被静态分析，需使用 CSS 变量或预定义变体
2. 忘记运行 panda codegen——新增 Token 或 Recipe 后需要重新生成类型
3. 提交 styled-system/——该目录是生成的，应加入 .gitignore
4. Keyframes 全局定义——动画必须在 panda.config.ts 中全局定义，无法在组件内局部定义
5. Monorepo 跨包引用——v1 中需要特殊配置，建议升级到 v2 使用 designSystem 配置
6. 过度使用内联 css()——复杂样式优先使用 Recipe，提高复用性和性能

技术局限与边界

已知限制

不适用场景

• 高度动态样式：如用户任意颜色选择器生成的样式（需 CSS 变量中转）
• 快速原型/MVP：学习曲线和配置成本高于 Tailwind
• 小型简单项目：配置开销可能超过收益
• 非 React 项目：虽然理论上支持其他框架，但生态和文档以 React 为中心
• 已深度使用 Tailwind 的团队：迁移成本高，收益不明确

迁移注意事项

• 从 Chakra UI v2 迁移：Panda CSS 提供相似的 DX，Chakra UI v3 底层即 Panda
• 从 styled-components/Emotion 迁移：需要将所有运行时样式重构为构建时可确定的静态样式
• 从 Tailwind 迁移：差异较大，从字符串类名转为函数调用风格
• v1 → v2 升级：API 基本兼容，主要变化在底层引擎（ts-morph → Oxc）

学习资源

• 官方文档：https://panda-css.com/docs/getting-started
• GitHub 仓库：https://github.com/chakra-ui/panda
• GitHub Discussions：https://github.com/chakra-ui/panda/discussions （活跃，仅 2 个 Open Issues）
• Discord：Chakra UI 官方 Discord（Panda CSS 频道活跃）
• Twitter/X：@panda__css — 官方公告、版本发布
• v1 路线图博客：https://www.adebayosegun.com/blog/panda-v1-roadmap
• 示例项目：
  • Panda CSS 官方示例
  • Park UI — 基于 Panda + Ark UI 的完整组件库示例
• 视频资源：
  • Segun Adebayo 关于 Panda CSS 的演讲

2026 年现状

最新版本

发展趋势

• v1 稳定：API 已稳定，生产可用，持续修复 bug 和 minor 改进
• v2 演进中：基于 Rust/Oxc 的编译引擎带来 17x 性能提升，2026 年下半年有望正式发布
• 社区增长：GitHub 6.1k+ Stars，Discord 活跃，Chakra UI v3 的背书带来持续关注
• 生态扩展：Panda MCP（AI 集成）、Figma 插件等工具不断丰富
• 团队扩张：Panda 正在招聘 Full Stack Developer（3+ 年经验），表明项目将持续投入
• 竞争定位：在"类型安全 + 零运行时 + 设计系统"领域，Panda CSS 是 2026 年增长最快的竞争者

社区活跃度

• GitHub 仅 2 个 Open Issues（代码质量高）
• GitHub Discussions 活跃（数百话题）
• Discord 核心团队成员在线
• 2,818 次发布记录（高频迭代）
• 3,498 次 Commits

版本选择建议