企业官网建设流程全解析

Coze Studio 设计系统实战：@coze-arch/tailwind-config 配置包深度解析

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio

@coze-arch/tailwind-config 是 Coze Studio 前端 monorepo 中面向设计系统的 Tailwind CSS 统一配置包，它为 Agent 开发平台的所有前端应用提供一致的色彩、间距、排版与组件级语义样式，并内置明暗双主题切换与设计令牌转换能力。读完本文，你将掌握如何在tailwind.config中接入该包与 Coze 插件、理解其 CSS 变量主题体系与语义类（如coz-fg-primary、coz-bg-secondary）的生成原理，并能将设计令牌自动转换为 Tailwind 配置。

一、包定位与核心特性

该包位于 frontend/config/tailwind-config，包名为@coze-arch/tailwind-config（版本 0.0.1），是 Coze 架构（@coze-arch系列）中负责统一视觉基建的组成部分。其核心目标与特性包括：

• 完整设计系统：预置颜色、间距、排版与组件级样式，覆盖 brand（品牌色）、foreground（前景/文字）、background（背景）、stroke（描边）等完整语义；
• 暗黑模式支持：基于 CSS 变量的明/暗主题切换（darkMode: 'class'）；
• 语义化工具类：提供coz-fg-primary、coz-bg-secondary等可读性强的类名；
• 组件就绪：为按钮、输入框等预定义圆角、高度、阴影等样式；
• 丰富色板：包含 brand、red、yellow、green、emerald、orange、cyan、blue、purple、magenta 等功能色与语义色；
• 统一间距体系：从 1px 到 1080px 的标准化间距刻度；
• 设计令牌集成：支持将设计令牌（design tokens）转换为 Tailwind 配置。

从 package.json 可以看出，该包的运行时依赖包括tailwindcss@~3.3.3、@tailwindcss/forms@^0.5.7、@tailwindcss/nesting、postcss@^8.4.32、postcss-loader@^7.3.3、autoprefixer@^10.4.16以及 monorepo 工具@coze-arch/monorepo-kits，开发依赖则复用@coze-arch/eslint-config与@coze-arch/ts-config。

二、安装与接入

2.1 安装

在 monorepo 中，通过 workspace 协议安装该包，然后执行 Rush 更新依赖：

# 在你的 workspace 中安装该包 pnpm add @coze-arch/tailwind-config@workspace:* # 更新 Rush 依赖 rush update

2.2 基本用法

在应用的tailwind.config.js中，将默认导出配置展开作为基础，并补充自身的content与theme.extend：

const cozeConfig = require('@coze-arch/tailwind-config'); module.exports = { ...cozeConfig, content: [ './src/**/*.{js,ts,jsx,tsx}', // 你的内容路径 ], // 按需扩展或覆盖 theme: { extend: { ...cozeConfig.theme.extend, // 你的自定义扩展 }, }, };

默认导出定义在 src/index.js，它是一个完整的 Tailwind 配置对象：darkMode: 'class'、默认content指向./index.html与./src/**/*.{js,ts,jsx,tsx}，plugins默认为空数组（语义类由独立的 Coze 插件提供）。

2.3 使用 Coze 插件

要启用语义工具类与 CSS 变量，还需挂载插件入口@coze-arch/tailwind-config/coze：

const cozePlugin = require('@coze-arch/tailwind-config/coze'); module.exports = { // ... 你的配置 plugins: [ cozePlugin, // 其他插件 ], };

2.4 设计令牌集成

若你的团队以设计令牌驱动主题，可以通过design-token子路径把令牌自动转换成 Tailwind 配置：

import { designTokenToTailwindConfig, getPackagesContents } from '@coze-arch/tailwind-config/design-token'; const tokenConfig = designTokenToTailwindConfig(yourDesignTokens); module.exports = { content: [ './src/**/*.{js,ts,jsx,tsx}', ...getPackagesContents(), // 自动发现各包的内容路径 ], theme: { extend: tokenConfig, }, };

三、真实接入案例：coze-studio 应用

仓库中的实际消费者 frontend/apps/coze-studio/tailwind.config.ts 展示了生产级组合方式，它同时使用了本包的三个能力：

import type { Config } from 'tailwindcss'; import { designTokenToTailwindConfig, getTailwindContents, } from '@coze-arch/tailwind-config/design-token'; import json from '@coze-arch/semi-theme-hand01/raw.json'; import { SCREENS_TOKENS } from '@coze-arch/responsive-kit/constant'; const contents = getTailwindContents('@coze-studio/app'); console.log(`Got ${contents.length} contents for tailwind`); export default { content: contents, // Safelist content can allow dynamic tailwind className safelist: [ { pattern: /(gap-|grid-).+/, variants: ['sm', 'md', 'lg', 'xl', '2xl'], }, ], important: '', presets: [require('@coze-arch/tailwind-config')], theme: { screens: { mobile: { max: '1200px' }, }, extend: { screens: SCREENS_TOKENS, ...designTokenToTailwindConfig(json), }, }, corePlugins: { preflight: false, // 关闭 @tailwind base 默认样式，避免影响现有样式 }, plugins: [require('@coze-arch/tailwind-config/coze')], } satisfies Config;

该案例展示了几个关键实践：

1. presets 机制：通过 Tailwind 的presets字段引入基础配置，而非展开合并，配置更干净；
2. 令牌驱动：designTokenToTailwindConfig(json)将@coze-arch/semi-theme-hand01/raw.json中的设计令牌转换为theme.extend；
3. 禁用 preflight：corePlugins.preflight: false关闭 Tailwind 基础样式重置，避免与既有组件库样式冲突；
4. safelist 兜底：对动态生成的gap-*、grid-*类做安全名单处理，防止被 JIT 裁剪。

四、API 参考与配置详解

4.1 主配置：颜色体系

主配置在 src/index.js 中定义了完整的theme.extend.colors，每个色阶都映射到 CSS 变量（RGB 值 + 透明度变量）：

// 品牌色（Brand） 'text-brand-5' // 品牌主色，映射 rgba(var(--coze-brand-5), 1) 'bg-brand-1' // 品牌浅色背景 'border-brand-3' // 品牌描边 // 语义色（Semantic） 'text-foreground-3' // 一级文本 'text-foreground-2' // 二级文本 'bg-background-1' // 一级背景 'bg-background-0' // 二级背景 // 功能色（Functional） 'text-red-5' // 错误/危险 'text-yellow-5' // 警告 'text-green-5' // 成功

值得注意的细节：brand色系从 0～7 逐级加深（如--coze-brand-0到--coze-brand-7），并额外提供50、30等浅色档位（--coze-brand-50、--coze-brand-30）；foreground提供1～7七档文字明暗层级；除品牌色外，还内置 red、yellow、green、emerald、orange、cyan、blue、purple、magenta 九个功能色系，以及 black、white、stroke、mask、icon、fornax 等特殊色组，可满足图表、标签、头像、代码高亮等场景。

4.2 主配置：间距与尺寸

间距体系同时提供语义命名与精确像素值两种用法：

// 语义间距 'p-normal' // 32px padding（var(--coze-32)） 'm-small' // 20px margin（var(--coze-20)） 'gap-mini' // 16px gap（var(--coze-16)） // 精确间距 'w-320px' // 320px 宽度 'h-240px' // 240px 高度 'p-24px' // 24px padding

间距刻度语义名对应关系为：mini（16px）、small（20px）、normal（32px）、large（40px）、mm（48px）、md（64px）、xl（80px）、xxl（96px）。同时spacing中直接注册了从 1px 到 1080px 的全部像素键，使w-320px、h-240px这类写法开箱即用，width、height、minWidth、minHeight等维度也共享同一套刻度。

4.3 主配置：排版

字号通过fontSize提供语义与像素两种命名，底层引用 CSS 变量：

'text-mini' // 10px（var(--coze-10)） 'text-base' // 12px（var(--coze-12)） 'text-lg' // 14px（var(--coze-14)） 'text-xl' // 15px（var(--coze-15)） 'text-xxl' // 16px（var(--coze-16)） 'text-24px' // 24px（var(--coze-24)）

lineHeight同步提供了12px～36px的刻度，保证行高与字号刻度体系一致。

4.4 组件化尺寸令牌

除通用维度外，配置还针对组件细化了专用令牌（这些令牌正是coz-btn-*、coz-input-*语义类的取值来源）：

此外还预置了icon-down、icon-up两个旋转动画（0.2s ease-out），对应animate-icon-down/animate-icon-up工具类。

五、Coze 插件：语义类与 CSS 变量

Coze 插件的实现位于 src/coze.js，它基于tailwindcss/plugin的addBase与addUtilities两个钩子工作：

1. addBase：将明/暗主题变量分别注入:root与.dark选择器，实现暗黑模式切换；
2. addBase（第二批）：将各语义变量表（前景/中景/背景/描边/阴影/按钮/输入框）解析为--coz-*系列 CSS 变量；
3. addUtilities：为每个语义键生成对应的工具类，映射到color、background-color、border-color、box-shadow、border-radius、height等属性。

其中核心辅助函数generateSemanticVariables(semantics, theme, property)遍历语义表，借助 Tailwind 的theme()函数把colors.brand.5这类引用解析为最终 CSS 值（src/coze.js）。

5.1 语义前景类（Foreground）

// 语义前景类 'coz-fg-primary' // 一级文本颜色（foreground.3） 'coz-fg-secondary' // 二级文本颜色（foreground.2） 'coz-fg-hglt' // 高亮文本（brand.5） 'coz-fg-hglt-plus' // 更强高亮（foreground.5） 'coz-fg-dim' // 弱化文本（foreground.1） 'coz-fg-white' // 白色文本（foreground.7） 'coz-fg-hglt-ai' // AI 相关紫色高亮（purple.5）

除基础层级外，semanticForeground还定义了完整的功能色前景（coz-fg-hglt-red/yellow/green及各自-dim变体）、图表/标签色（coz-fg-color-cyan/blue/purple/magenta/...）、代码专用高亮色（coz-fg-hglt-orange/emerald/cyan/blue/purple/magenta）以及品牌/备选色（coz-fg-color-brand、coz-fg-color-alternative）。

5.2 语义中景与背景类（Middleground / Background）

// 语义背景类 'coz-bg-primary' // 一级背景（background.1） 'coz-bg-secondary' // 二级背景（background.0） 'coz-bg-plus' // 更上层背景（background.2） 'coz-bg-max' // 最高层背景（background.3） // 中景类（Middleground，覆盖 hover/pressed 等交互态） 'coz-mg-hglt-plus' // 品牌高亮填充（brand.5） 'coz-mg-hglt-plus-hovered' // 悬停态（brand.6） 'coz-mg-hglt-plus-pressed' // 按压态（brand.7） 'coz-mg-hglt-secondary' // 次级品牌填充（brand.0） 'coz-mg-primary' / 'coz-mg-secondary' // 常规背景层级 'coz-mg-card' / 'coz-mg-card-hovered' // 卡片背景 'coz-mg-mask' // 遮罩背景

semanticMiddleground是最大的语义表，覆盖了品牌交互态（hovered/pressed）、AI 紫色系交互态、功能色交互态（coz-mg-hglt-plus-red、-yellow、-green及其 pressed/hovered/dim）、卡片/标签/头像专用色（coz-mg-color-cyan/blue/purple/...三级）等近 80 个类。

5.3 组件语义类

// 组件专用类 'coz-btn-rounded-large' // 大按钮圆角（btnBorderRadius.large） 'coz-btn-rounded-normal' // 常规按钮圆角（btnBorderRadius.normal） 'coz-btn-rounded-small' // 小按钮圆角（btnBorderRadius.small） 'coz-btn-rounded-mini' // 迷你按钮圆角（btnBorderRadius.mini） 'coz-input-height-large' // 大输入框高度（inputHeight.large） 'coz-input-height-normal' // 常规输入框高度（inputHeight.normal） 'coz-input-height-small' // 小输入框高度（inputHeight.small） 'coz-input-rounded-normal' // 常规输入框圆角（inputBorderRadius.normal） 'coz-shadow-large' // 大阴影（boxShadow.large） 'coz-shadow' / 'coz-shadow-default' // 常规阴影 'coz-shadow-small' // 小阴影（boxShadow.small）

5.4 描边语义类

'coz-stroke-hglt' // 品牌高亮描边（brand.5） 'coz-stroke-primary' // 常规描边（stroke.5） 'coz-stroke-plus' // 强化描边（stroke.6） 'coz-stroke-max' // 最强描边（stroke.max，即 stroke.7） 'coz-stroke-opaque' // 不透明描边 'coz-stroke-hglt-red/yellow/green' // 功能色描边 'coz-stroke-color-cyan/blue/purple/...' // 图表/标签描边

六、主题系统：CSS 变量与明暗双主题

主题变量的定义文件为 src/light.js 与 src/dark.js。所有颜色都以RGB 三元组（而非 hex）存储，以支持透明度叠加：

:root { --coze-brand-5: 81, 71, 255; --coze-fg-3: 15, 21, 40; --coze-bg-1: 247, 247, 252; } .dark { --coze-brand-5: 166, 166, 255; --coze-fg-3: 255, 255, 255; --coze-bg-1: 24, 28, 43; }

颜色在使用时通过rgba()组合透明度变量（--coze-*-alpha）实现透明支持：

.text-brand-5 { color: rgba(var(--coze-brand-5), 1); } .bg-brand-1 { background-color: rgba(var(--coze-brand-1), var(--coze-brand-1-alpha)); }

这种“RGB 变量 + 独立 alpha 变量”的设计使得同一色板在不同透明度下（hover、pressed、disabled、蒙层）无需预生成大量色阶，也便于明暗两套主题只切换基色即可。

6.1 明暗主题的差异设计

对比 src/light.js 与 src/dark.js 可以观察到主题化的关键手法：

• 方向相反：亮色主题下coze-fg-3（一级文字）是深色15, 21, 40、coze-bg-1（一级背景）是浅色247, 247, 252；暗色主题则完全反转；
• 透明度层级不同：亮色主题的文字 alpha（如coze-fg-2-alpha: 0.62、coze-fg-3-alpha: 0.82）与暗色主题（0.39、0.79）有独立取值，保证两种模式下文字与背景的对比度都达到可读性要求；
• 特殊变量：coze-fg-revert（反色文字）、coze-fg-white、coze-bg-9（带 TODO 注释待移除）等为特定组件服务。

6.2 新增颜色的操作流程

若设计系统新增颜色，需要按以下步骤在四个文件中同步修改：

1. 在light.js与dark.js中添加对应的 RGB 值；
2. 添加透明度（alpha）值以支持透明场景；
3. 更新主配置 src/index.js 中的theme.extend.colors；
4. 若需要语义类，在 src/coze.js 的semanticForeground/semanticMiddleground/semanticBackground/semanticStroke表中补充映射。

七、设计令牌转换：design-token 子模块

design-token子路径对应的实现是 src/design-token.ts，提供两个核心函数。

7.1 designTokenToTailwindConfig(tokenJson)

将设计令牌 JSON 转换为{ colors, spacing, borderRadius }三个维度的 Tailwind 配置：

const tokenConfig = designTokenToTailwindConfig({ palette: { light: { 'primary-500': '#3b82f6' }, dark: { 'primary-500': '#60a5fa' } }, tokens: { color: { light: { 'primary-color': 'var(primary-500)' }, dark: { 'primary-color': 'var(primary-500)' } }, spacing: { 'spacing-sm': '8px', 'spacing-md': '16px' } } });

从源码看（src/design-token.ts），转换逻辑如下：

• tokens.color通过colorTransformer处理：颜色键中的-color-前缀会被剥离，并追加主题后缀（如primary-color+light→primary-light）；
• 颜色的取值若为var(xxx)形式，会通过genColorValueFormatter从palette对应主题中查找实际色值并替换（src/design-token.ts）；
• tokens.spacing会去除$spacing-前缀（如$spacing-sm→sm）；
• tokens.border-radius会去除--semi-border-radius-前缀（兼容 Semi 设计体系的令牌命名）。

7.2 getTailwindContents(projectRoot)

自动发现 monorepo 中各包的源码路径，用于拼接 Tailwind 的content数组。其实现位于 src/tailwind-contents.ts：

const contents = getTailwindContents(); // 返回示例： // [ // '/path/to/package1/src/**/*.{ts,tsx}', // '/path/to/package2/src/**/*.{ts,tsx}', // ... // ]

其工作方式为：先固定加入本包自身../src/**/*.{tsx,ts}，再通过@coze-arch/monorepo-kits的lookupSubPackages枚举子包，仅保留依赖声明中出现react的包（避免把纯工具包纳入扫描），拼接其src/**/*.{ts,tsx}，最后兼容性地加入@coze-arch/coze-design组件库的 JS 文件（src/tailwind-contents.ts）。注意：调用时需传入projectRoot参数（如'@coze-studio/app'），否则会抛出projectRoot is required。

7.3 可复用插件工厂：genTailwindPlugin

src/util.js 额外导出了genTailwindPlugin(defaultCls, darkCls)工厂函数，允许自定义主题变量的挂载选择器（默认为:root与.dark）。它与coze.js的插件主体逻辑一致，适合在特殊场景（如某个应用需要将主题变量挂载到自定义容器类而非全局根节点）下复用，可作为团队二次封装的起点。

八、开发、结构与工程化约定

8.1 目录结构

frontend/config/tailwind-config/ ├── src/ │ ├── index.js # 主 Tailwind 配置（默认导出） │ ├── coze.js # Coze 插件：语义工具类与 CSS 变量 │ ├── design-token.ts # 设计令牌转换工具 │ ├── tailwind-contents.ts # 自动发现各包 content 路径 │ ├── light.js # 亮色主题 CSS 变量 │ ├── dark.js # 暗色主题 CSS 变量 │ └── util.js # genTailwindPlugin 插件工厂 ├── config/rush-project.json # Rush 工程配置 ├── package.json ├── eslint.config.js └── tsconfig.json

package.json中通过exports字段声明了四个子路径入口：.（主配置）、./coze（插件）、./util（工具）、./design-token（令牌转换），这是各应用能按需引入不同能力的基础。

8.2 工程质量命令

# 运行 ESLint 检查 pnpm lint # 构建（该包为配置包，build 为 no-op） pnpm build

package.json中build、test脚本均为exit（no-op），符合“纯配置包无需构建与单测”的定位；lint通过eslint ./ --cache --quiet执行。Rush 侧配置位于 config/rush-project.json，定义了ts-check操作及其输出目录。

8.3 包导出与版本说明

该包依赖 Tailwind CSS~3.3.3（3.x 系列），配置语法基于 3.x 的 JavaScript 配置对象；由于design-token.ts以 TypeScript 源码直接导出，消费方需确保构建链路能处理 TS 文件。包遵循 Apache-2.0 许可（源码头部声明 Copyright 2025 coze-dev Authors），是 Coze 架构下开源共享的基础设施包。

九、总结：如何用好这套配置

综合本文内容，在 Coze Studio 相关前端应用中接入@coze-arch/tailwind-config的最佳实践可以归纳为四点：

1. 三层接入：用presets引入主配置获得色板与刻度体系，用plugins挂载coze插件获得语义类与 CSS 变量，用design-token子模块对接设计令牌自动生成扩展配置；
2. 关闭 preflight：在已有组件库的项目中通过corePlugins.preflight: false避免基础样式污染（参考 coze-studio 应用配置）；
3. 优先使用语义类：在业务代码中优先使用coz-fg-*、coz-bg-*、coz-mg-*、coz-stroke-*等语义类，主题切换时无需改动业务代码；
4. 按场景选用色系：前景/背景选择foreground/background语义层级，强调与交互使用brand及-hglt系列，图表/标签使用color-*系列，代码高亮使用code专用系列，保证视觉语言的统一与可维护。

【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio