devup-ui

devup-ui — 路由优先的零运行时 CSS-in-JS 采用方案

关键词：devup-ui · @devup-ui/react · zero runtime · build-time CSS extraction · devup.json

Devup UI 使用 Rust 驱动的预处理器，在构建时处理所有样式。 它没有运行时样式引擎：先选择匹配的打包器插件，再编写样式；插件是其他一切功能正常运行的关键。

Devup UI 通过在编译时提取样式，消除了传统 CSS-in-JS 在开发体验与性能之间的取舍：

• 零运行时 — 运行时不会执行任何用于样式处理的 JavaScript
• 零配置 / 零 FOUC — 无需客户端 Provider，不会出现样式闪烁
• 完整的语法覆盖 — 变量、条件语句、响应式数组、伪选择器
• 熟悉的 API — styled() 兼容 styled-components / Emotion 模式
• 最小化打包体积 — 使用 base-37 类名（a、b、…、aa、ab）；动态值会转换为 CSS 变量
• 支持 RSC — 可在 React Server Components 中使用

何时使用此技能

• 用户想要在项目中添加 Devup UI，并需要配置正确的打包器插件
• 用户正在选择 Next.js / Vite / Rsbuild / Webpack / Bun 集成方式
• 用户想用 Box/css 属性或 styled() API 编写样式，但不确定简写属性（bg、px、响应式数组、_hover）如何映射
• 用户想使用 devup.json 实现类型安全的主题（颜色、排版、通过 CSS 变量动态切换主题）
• 用户想从 styled-components / Emotion / Tailwind / Panda / vanilla-extract 迁移到零运行时方案
• 用户总是尝试使用运行时 CSS-in-JS Provider，需要了解在 Devup UI 中它并非必需（且会影响 RSC）

如果实际需求超出样式机制的范畴，请转至相应技能：设计令牌 / 视觉语言治理 → design-system；可复用组件 API / 结构 → design-system；布局 / 断点策略 → responsive-design；无障碍 → web-accessibility；样式之外的打包体积 / RSC / 重渲染性能 → react-best-practices。

说明

步骤 1 — 修改配置前先收集一份需求信息

一次性收集：

1. 打包器 — Next.js、Vite、Rsbuild、Webpack 或 Bun（这决定插件包）
2. React 模式 — App Router / RSC 或仅客户端模式（RSC 无需 Provider；不要添加）
3. 主题 — 项目是否需要 devup.json 令牌和动态（例如深色）主题？
4. 项目来源 — 全新项目，还是从 styled-components / Emotion / Tailwind / Panda / vanilla-extract 迁移？
5. 包管理器 — npm / pnpm / yarn / bun

步骤 2 — 安装核心包和匹配的打包器插件

npm install @devup-ui/react
# then exactly ONE bundler plugin:
npm install @devup-ui/next-plugin     # Next.js
npm install @devup-ui/vite-plugin     # Vite
npm install @devup-ui/rsbuild-plugin  # Rsbuild
npm install @devup-ui/webpack-plugin  # Webpack
npm install @devup-ui/bun-plugin      # Bun

也可以使用辅助工具；它会将此技能作为插件安装，并可在目标项目中搭建所选打包器的配置：

bash scripts/install.sh                                   # install the skill only
BUNDLER=next PROJECT=/path/to/app bash scripts/install.sh # + npm packages for Next.js
BUNDLER=vite PKG_MANAGER=pnpm PROJECT=. bash scripts/install.sh
GLOBAL=1 bash scripts/install.sh                          # install the skill globally

步骤 3 — 配置构建时插件（关键步骤）

// next.config.js  (Next.js)
import { DevupUI } from '@devup-ui/next-plugin'
export default DevupUI({})

// vite.config.ts  (Vite)
import { DevupUI } from '@devup-ui/vite-plugin'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
export default defineConfig({ plugins: [react(), DevupUI()] })

Rsbuild 使用 DevupUIRsbuildPlugin()，Webpack 使用 new DevupUIWebpackPlugin()，Bun 导入 @devup-ui/bun-plugin。完整代码示例： references/installation-and-plugins.md。

步骤 4 — 编写样式

import { Box, css, styled } from '@devup-ui/react'

// Prop-based styling with shorthands and responsive arrays
const view = (
  <Box bg="white" p={4} borderRadius="8px" _hover={{ bg: 'gray.100' }}>
    <Box fontSize={[14, 16, 20]} color="primary">Responsive text</Box>
  </Box>
)

// styled-components / Emotion compatible API
const Card = styled('div', {
  bg: 'white',
  p: 4,            // 4 * 4 = 16px spacing scale
  borderRadius: '8px',
  boxShadow: '0 4px 6px rgba(0,0,0,0.1)',
  _hover: { boxShadow: '0 10px 15px rgba(0,0,0,0.1)' },
})

数值型间距属性会乘以 4px。数组值会根据断点响应。_hover、_focus 等是伪选择器。动态值会编译为 CSS 变量（不会在运行时重新计算样式）。详情请见： references/styling-api.md。

步骤 5 — 使用 devup.json 设置主题（仅在需要时）

{
  "theme": {
    "colors": {
      "default": { "primary": "#0070f3", "text": "#000" },
      "dark":    { "primary": "#3291ff", "text": "#fff" }
    },
    "typography": {
      "heading": { "fontFamily": "Pretendard", "fontSize": "24px", "fontWeight": 700, "lineHeight": 1.3 }
    }
  }
}

主题令牌具有类型安全性，主题切换零开销（使用 CSS 变量）。RSC 无需 Provider 即可运行 — 不要为主题添加客户端 Provider。迁移方案和转向说明： references/theming-and-migration.md。

分流（不要过度承诺样式）

• 令牌治理、命名、视觉语言方向 → design-system
• 可复用组件 API／插槽结构／受控所有权 → design-system
• 页面外壳／断点／重排策略 → responsive-design
• 无障碍语义、焦点、标签、重排 → web-accessibility
• 瀑布流、包体积、RSC 边界、重复渲染问题 → react-best-practices

作为插件安装

npx skills add https://github.com/akillness/jeo-skills --skill devup-ui