Kuma UI

零运行时 CSS-in-JS 库，通过编译时提取实现接近原生 HTML 的渲染性能，内置 Headless 组件系统。

技术简介说明

Kuma UI 是一个零运行时的 CSS-in-JS 框架，由日本开发者 poteboy 创建。它采用独特的"混合方案"（Hybrid Approach）——静态样式在构建时提取为原生 CSS（🐻 标记），动态样式在运行时通过 CSS 变量或 inline style 处理（🦄 标记），兼顾了零运行时的高性能和运行时 CSS-in-JS 的灵活性。

Kuma UI 的核心差异化在于其 Headless 组件系统——所有内置组件（Box、Flex、Text、Button 等）都是无样式的（unstyled），只提供语义化的 HTML 元素和行为逻辑。开发者通过 Utility Props 或 styled/css 函数添加样式，拥有完全的视觉设计控制权。这一设计使其特别适合构建自定义设计系统。

Kuma UI 的性能表现令人印象深刻——基准测试显示其组件渲染速度（0.0092ms）甚至快于原生 HTML 元素（0.0138ms），因为静态样式在构建时已被编译为纯标记。项目正在开发 v2 版本，计划引入 Rust 编写的编译工具 jaku，并将核心 API 迁移到 @kuma-ui/macro，目标是成为 Emotion/styled-components 的零运行时替代品。

基本信息

• 官网：https://www.kuma-ui.com/
• GitHub：https://github.com/kuma-ui/kuma-ui （⭐ ~1,900）
• License：MIT
• 最新版本：v1.6.4（@kuma-ui/core，2026 年 4 月）；@kuma-ui/next-plugin v1.4.2（2025-05-29）
• 主要维护者/公司：poteboy（创建者，Frontend Tech Lead at THECOO, Inc.，Tamagui 成员）；核心团队包括 Taishi Naritomi、Kotaro Sugawara、Yuku Kotani

快速上手

安装

Next.js 项目：

# 安装核心包和 Next.js 插件
npm install @kuma-ui/core
npm install --save-dev @kuma-ui/next-plugin

Vite 项目：

npm install @kuma-ui/core
npm install --save-dev @kuma-ui/vite

Webpack 项目：

npm install @kuma-ui/core
npm install --save-dev @kuma-ui/webpack-plugin

基础配置

Next.js 配置（next.config.js）：

const { withKumaUI } = require('@kuma-ui/next-plugin')
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
}
 
module.exports = withKumaUI(nextConfig, {
  // Kuma UI 选项
  // wasm: true, // 可选：启用 WASM 编译器，更快的构建速度
})

Vite 配置（vite.config.ts）：

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

Webpack 配置（webpack.config.js）：

const { KumaUIPlugin } = require('@kuma-ui/webpack-plugin')
 
module.exports = {
  plugins: [new KumaUIPlugin()],
}

主题配置（kuma.config.ts，可选）：

import { defineTheme } from '@kuma-ui/core'
 
export default defineTheme({
  tokens: {
    colors: {
      primary: '#007bff',
      secondary: '#6c757d',
      text: '#333333',
      background: '#ffffff',
    },
    fontSizes: {
      sm: '12px',
      md: '14px',
      lg: '18px',
      xl: '24px',
    },
    spacing: {
      sm: '4px',
      md: '8px',
      lg: '16px',
      xl: '24px',
    },
  },
})

最小示例

import { Box, Flex, Text, Button, styled } from '@kuma-ui/core'
 
function App() {
  return (
    <Box p="xl" bg="background">
      <Flex direction="column" gap="md">
        <Text fontSize="xl" fontWeight="bold" color="text">
          Hello Kuma UI
        </Text>
        <Button
          bg="primary"
          color="white"
          px="lg"
          py="md"
          borderRadius="4px"
          _hover={{ opacity: 0.9 }}
        >
          点击我
        </Button>
      </Flex>
    </Box>
  )
}
 
// 使用 styled API 创建自定义组件
const Card = styled('div', {
  padding: '16px',
  borderRadius: '8px',
  boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
  backgroundColor: 'white',
})

核心概念与架构

混合方案（Hybrid Approach）

Kuma UI 的核心创新在于其"混合方案"——将样式分为两类处理：

源码 (JSX + CSS-in-JS)
    │
    ▼
┌─────────────────────┐
│  Babel 插件          │  ← 默认转译方式
│  或                  │
│  WASM 编译器         │  ← 可选，更高性能
└────────┬────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│  静态分析                                │
│  🐻 静态样式 → 提取为 .css 文件           │
│  🦄 动态样式 → 保留为 CSS 变量/inline     │
└────────┬────────────────────────────────┘
         │
         ▼
    构建产物：原生 HTML + CSS + 最小运行时

🐻 静态样式：可以在构建时完全确定的样式（如 color: 'red'、padding: '16px'），被提取为原生 CSS 类

🦄 动态样式：依赖运行时值的样式（如 color={props.color}），通过 CSS 变量或 inline style 在运行时处理

编译时提取流程

1. Babel/WASM 编译：拦截 JSX 中的 Kuma UI 组件和样式函数
2. 静态分析：识别可构建时确定的样式属性
3. CSS 提取：静态样式生成 .css 文件
4. JSX 转换：原始组件替换为带有 className 的 HTML 元素
5. 动态处理：无法静态化的样式通过 CSS 变量注入

核心 API

核心特性

• 零运行时（Hybrid）：静态样式构建时提取为原生 CSS，动态样式通过 CSS 变量最小化运行时开销
• Headless 组件系统：内置无样式组件（Box、Flex、Grid、Text、Button 等），提供语义化 HTML 和行为，开发者完全控制视觉设计
• Utility-First Props：类似 Chakra UI 的 style props（color、bg、p、m、fontSize 等），支持 TypeScript 自动补全
• React Server Components 兼容：少数原生支持 RSC 的 CSS-in-JS 库之一，动态属性会迫使组件变为 Client Component
• 接近原生的渲染性能：基准测试显示组件渲染速度（0.0092ms）快于原生 HTML（0.0138ms）
• TypeScript 类型安全：完整的 TypeScript 支持，Utility Props 和 Theme Tokens 提供 IDE 智能提示
• WASM 编译器：可选的 WASM 编译模式，比 Babel 更快的构建速度
• Tree Shaking 友好：完全不用动态样式时，可 tree-shake 掉框架组件（节省约 30KB）
• 主题系统：通过 kuma.config.ts 定义设计令牌，支持颜色、字体、间距等 Token
• 不污染项目目录：不像 Panda CSS 生成 styled-system/ 目录，Kuma UI 在内部处理样式提取

生态图

框架集成

npm 包生态

设计灵感来源

社区生态

• 社区规模较小：npm 周下载量 ~897（@kuma-ui/core），社区资源有限
• Discord：discord.gg/QtsQ4EPp7G（小型社区）
• Twitter/X：@kuma__ui
• 2023 JS Rising Stars：Styling/CSS-in-JS 类别 #8

适用场景

• React 项目追求零运行时性能：Kuma UI 的混合方案在保持零运行时的同时提供了比 vanilla-extract 更好的动态样式灵活性
• 自定义设计系统：Headless 组件系统提供完全的视觉控制，适合构建不依赖预设样式的自定义设计系统
• RSC 优先项目：原生支持 React Server Components，动态属性处理得当
• Emotion/styled-components 迁移：v2 计划成为 Emotion 替代品，API 风格相似（styled、css），迁移成本较低
• Chakra UI 风格偏好：Utility Props 与 Chakra UI 高度相似，适合习惯 Chakra DX 的团队
• 性能敏感应用：基准测试显示渲染速度接近原生 HTML，适合高性能要求的场景
• 不想污染项目目录：不像 Panda CSS 生成 styled-system/ 目录，Kuma UI 在内部处理样式提取

开发与工程化

开发流程

1. 安装配置：安装核心包和对应的 bundler 插件
2. 主题配置：可选创建 kuma.config.ts 定义设计令牌
3. 编写组件：使用 Headless 组件 + Utility Props 或 styled/css 编写样式
4. 开发调试：通过 HMR 实时预览样式变化
5. 构建部署：编译器自动提取静态样式为 CSS 文件
6. SSR 配置：强烈推荐设置 SSR 以防止 FOUC

SSR 配置（Next.js）

// app/layout.tsx
import { KumaRegistry } from './kuma-registry'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-CN">
      <KumaRegistry>
        <body>{children}</body>
      </KumaRegistry>
    </html>
  )
}

// app/kuma-registry.tsx
'use client'
 
import React, { useState } from 'react'
import { useServerInsertedHTML } from 'next/navigation'
import { StyleRegistry, createStyleRegistry } from '@kuma-ui/core'
 
export function KumaRegistry({ children }: { children: React.ReactNode }) {
  const [registry] = useState(() => createStyleRegistry())
 
  useServerInsertedHTML(() => {
    return <>{registry.flushToComponent()}</>
  })
 
  return <StyleRegistry registry={registry}>{children}</StyleRegistry>
}

CI/CD 集成

• Kuma UI 与标准 CI/CD 流程兼容
• 构建时编译器自动提取样式
• 确保 CI 环境安装 Node.js 和必要的构建工具
• WASM 编译器模式（wasm: true）可能在某些 CI 环境中需要额外配置

代码组织建议

src/
├── kuma.config.ts        # 主题配置（可选）
├── components/
│   ├── Layout.tsx         # 使用 Headless 组件
│   ├── Button.tsx         # 使用 styled API
│   └── Card.tsx           # 使用 css 函数
├── styles/
│   └── global.ts          # 全局样式
└── app/
    ├── layout.tsx         # KumaRegistry
    └── page.tsx

性能与安全

性能特点

性能优化策略

1. 最大化静态样式——尽量使用可静态分析的样式值，让编译器提取为原生 CSS
2. 动态样式隔离——将动态属性放在组件树末端（tip of the component tree）
3. 启用 WASM 编译——wasm: true 比 Babel 更快
4. 启用 SSR——防止 FOUC，Next.js 中配置 KumaRegistry
5. 代码分割动态部分——使用 React.lazy + Suspense 隔离动态样式组件
6. 避免 Spread 运算符——会阻止静态分析，应显式传递 props
7. Tree Shaking——完全避免动态样式可节省约 30KB
8. 配置 outputDir——生成物理 CSS 文件而非虚拟模块注入

安全注意事项

• Kuma UI 编译时提取的 CSS 是静态的，不存在运行时注入风险
• 动态样式通过 CSS 变量传递，注意不要暴露用户输入到 CSS 变量中
• styled API 的模板字面量在构建时求值，不存在 XSS 风险

已知性能瓶颈

• 动态样式开销：大量动态样式会增加运行时 CSS 变量操作开销
• RSC 陷阱：单个动态属性会迫使整个元素变为 Client Component
• Babel 编译速度：大型项目 Babel 编译可能较慢（WASM 模式可缓解）
• HMR 延迟：Next.js 客户端组件中存在未文档化的临时 workaround

技术对比

关键对比结论

• vs styled-components/Emotion：Kuma UI 提供零运行时性能，API 风格相似，是潜在替代品（v2 目标）
• vs Panda CSS：Panda CSS 生态更完善、社区更大；Kuma UI 有 Headless 组件和不污染目录的优势
• vs vanilla-extract：vanilla-extract 更成熟、框架支持更广；Kuma UI 提供更好的动态样式灵活性
• vs Tailwind：Kuma UI 提供组件式开发体验（vs 工具类字符串），但社区规模远小

最佳实践

推荐模式

1. 最大化静态样式

   // ✅ 静态值 - 编译为原生 CSS
   <Box p="16px" color="primary" bg="background" />
    
   // ❌ 动态值 - 运行时处理
   <Box p={`${dynamicValue}px`} />

2. 动态样式隔离

   // ✅ 将动态属性放在组件树末端
   function StaticLayout() {
     return (
       <Box p="xl" bg="background">
         <DynamicContent /> {/* 动态部分隔离在此 */}
       </Box>
     )
   }
    
   function DynamicContent() {
     const color = useUserColor()
     return <Text color={color}>动态内容</Text>
   }

3. 使用 styled 创建可复用组件

   import { styled } from '@kuma-ui/core'
    
   const Card = styled('div', {
     padding: '16px',
     borderRadius: '8px',
     boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
   })
    
   // 使用 Utility Props 覆盖
   <Card bg="primary" p="xl">内容</Card>

4. 使用 Theme Tokens 统一设计

   // kuma.config.ts
   export default defineTheme({
     tokens: {
       colors: { primary: '#007bff', text: '#333' },
       spacing: { sm: '4px', md: '8px', lg: '16px' },
     },
   })
    
   // 组件中使用 Token
   <Box p="lg" color="text" bg="primary">Token 驱动</Box>

5. 启用 SSR——Next.js 中必须配置 KumaRegistry

常见陷阱

1. Spread 运算符——<Box {...props} /> 阻止静态分析，必须显式传递每个 prop
2. 忘记 SSR 配置——Next.js 中不配置 SSR 会导致 FOUC
3. 过度使用动态样式——大量动态属性会导致更多组件变为 Client Component
4. RSC 动态值陷阱——单个动态属性会迫使整个元素变为 Client Component
5. Windows + Next.js 编译失败——已知 Issue #423，注意平台兼容性
6. API 变化风险——v2 尚未发布，API 可能发生重大变化

技术局限与边界

已知限制

不适用场景

• 非 React 项目：Kuma UI 仅支持 React，不适用于 Vue、Svelte 等
• 需要稳定 API 的长期项目：v2 尚未发布，API 可能发生重大变化
• 高度动态样式：大量运行时值驱动的样式（如可视化编辑器）
• 需要完整设计系统：Headless 组件无默认样式，需自行构建完整 UI
• 大型团队协作：社区小，遇到问题时可参考资源有限
• CSS-in-JS 行业趋势下行：Tailwind CSS 占据更大市场份额

迁移注意事项

• 从 styled-components 迁移：API 风格相似（styled），但需注意零运行时限制
• 从 Chakra UI 迁移：Utility Props 相似，但 Headless 意味着需要自行定义所有样式
• 从 Emotion 迁移：v2 计划作为 Emotion 替代品，但目前 API 仍有差异
• 升级到 v2：核心 API 将迁移到 @kuma-ui/macro，React v19 成为最低要求

学习资源

• 官方文档：https://www.kuma-ui.com/docs
• GitHub 仓库：https://github.com/kuma-ui/kuma-ui
• GitHub Discussions：https://github.com/kuma-ui/kuma-ui/discussions （v2 RFC 等）
• Discord：discord.gg/QtsQ4EPp7G
• Twitter/X：@kuma__ui
• 团队页面：https://www.kuma-ui.com/team
• 性能基准：https://github.com/kuma-ui/kuma-bench
• 视频资源：
  • JSConf JP - poteboy 演讲
• 对比文章：
  • Kuma UI vs Panda CSS - First Impressions

2026 年现状

最新版本

发展趋势

• v2 开发中：v2 RFC 已发布（Discussion #409），核心变更包括：
  • 核心 API 迁移到 @kuma-ui/macro（需要编译器介入的 API 集中管理）
  • React v19 成为最低要求
  • Rust 编写的工具 jaku 正在开发中
  • 核心理念："编译器应只是优化工具，而非必需品"
• "Emotion 替代品"计划：相同语法 + 零运行时 + RSC 兼容
• 性能持续提升：近期版本约 60% 渲染性能提升
• RSC 动态值完全兼容：2025 年实现
• HMR 改进：更可靠的样式热更新检测

社区活跃度

评估：社区规模小，属于"技术上有趣但采用率低"的项目。遇到问题时可参考资源有限，生产使用需评估维护风险。

项目状态评估