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-studiocoze-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-configworkspace:* # 更新 Rush 依赖 rush update2.2 基本用法在应用的tailwind.config.js中将默认导出配置展开作为基础并补充自身的content与theme.extendconst 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/cozeconst 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;该案例展示了几个关键实践presets 机制通过 Tailwind 的presets字段引入基础配置而非展开合并配置更干净令牌驱动designTokenToTailwindConfig(json)将coze-arch/semi-theme-hand01/raw.json中的设计令牌转换为theme.extend禁用 preflightcorePlugins.preflight: false关闭 Tailwind 基础样式重置避免与既有组件库样式冲突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色系从 07 逐级加深如--coze-brand-0到--coze-brand-7并额外提供50、30等浅色档位--coze-brand-50、--coze-brand-30foreground提供17七档文字明暗层级除品牌色外还内置 red、yellow、green、emerald、orange、cyan、blue、purple、magenta 九个功能色系以及 black、white、stroke、mask、icon、fornax 等特殊色组可满足图表、标签、头像、代码高亮等场景。4.2 主配置间距与尺寸间距体系同时提供语义命名与精确像素值两种用法// 语义间距 p-normal // 32px paddingvar(--coze-32) m-small // 20px marginvar(--coze-20) gap-mini // 16px gapvar(--coze-16) // 精确间距 w-320px // 320px 宽度 h-240px // 240px 高度 p-24px // 24px padding间距刻度语义名对应关系为mini16px、small20px、normal32px、large40px、mm48px、md64px、xl80px、xxl96px。同时spacing中直接注册了从 1px 到 1080px 的全部像素键使w-320px、h-240px这类写法开箱即用width、height、minWidth、minHeight等维度也共享同一套刻度。4.3 主配置排版字号通过fontSize提供语义与像素两种命名底层引用 CSS 变量text-mini // 10pxvar(--coze-10) text-base // 12pxvar(--coze-12) text-lg // 14pxvar(--coze-14) text-xl // 15pxvar(--coze-15) text-xxl // 16pxvar(--coze-16) text-24px // 24pxvar(--coze-24)lineHeight同步提供了12px36px的刻度保证行高与字号刻度体系一致。4.4 组件化尺寸令牌除通用维度外配置还针对组件细化了专用令牌这些令牌正是coz-btn-*、coz-input-*语义类的取值来源令牌组键说明btnBorderRadiuslarge/normal/small/mini按钮圆角10/8/5/4pxinputBorderRadiuslarge/normal/small输入框圆角10/8/6pxinputHeightlarge/normal/small输入框高度40/32/24pxboxShadowsmall/normal/large/DEFAULT三级阴影基于--coze-shadow-0的 rgba 叠加borderWidthDEFAULT/normal/half边框宽度1px / 0.5pxborderRadiustinyultra通用圆角240px此外还预置了icon-down、icon-up两个旋转动画0.2s ease-out对应animate-icon-down/animate-icon-up工具类。五、Coze 插件语义类与 CSS 变量Coze 插件的实现位于 src/coze.js它基于tailwindcss/plugin的addBase与addUtilities两个钩子工作addBase将明/暗主题变量分别注入:root与.dark选择器实现暗黑模式切换addBase第二批将各语义变量表前景/中景/背景/描边/阴影/按钮/输入框解析为--coz-*系列 CSS 变量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.small5.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 新增颜色的操作流程若设计系统新增颜色需要按以下步骤在四个文件中同步修改在light.js与dark.js中添加对应的 RGB 值添加透明度alpha值以支持透明场景更新主配置 src/index.js 中的theme.extend.colors若需要语义类在 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-colorlight→primary-light颜色的取值若为var(xxx)形式会通过genColorValueFormatter从palette对应主题中查找实际色值并替换src/design-token.tstokens.spacing会去除$spacing-前缀如$spacing-sm→smtokens.border-radius会去除--semi-border-radius-前缀兼容 Semi 设计体系的令牌命名。7.2 getTailwindContents(projectRoot)自动发现 monorepo 中各包的源码路径用于拼接 Tailwind 的content数组。其实现位于 src/tailwind-contents.tsconst 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 可复用插件工厂genTailwindPluginsrc/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.jsonpackage.json中通过exports字段声明了四个子路径入口.主配置、./coze插件、./util工具、./design-token令牌转换这是各应用能按需引入不同能力的基础。8.2 工程质量命令# 运行 ESLint 检查 pnpm lint # 构建该包为配置包build 为 no-op pnpm buildpackage.json中build、test脚本均为exitno-op符合“纯配置包无需构建与单测”的定位lint通过eslint ./ --cache --quiet执行。Rush 侧配置位于 config/rush-project.json定义了ts-check操作及其输出目录。8.3 包导出与版本说明该包依赖 Tailwind CSS~3.3.33.x 系列配置语法基于 3.x 的 JavaScript 配置对象由于design-token.ts以 TypeScript 源码直接导出消费方需确保构建链路能处理 TS 文件。包遵循 Apache-2.0 许可源码头部声明 Copyright 2025 coze-dev Authors是 Coze 架构下开源共享的基础设施包。九、总结如何用好这套配置综合本文内容在 Coze Studio 相关前端应用中接入coze-arch/tailwind-config的最佳实践可以归纳为四点三层接入用presets引入主配置获得色板与刻度体系用plugins挂载coze插件获得语义类与 CSS 变量用design-token子模块对接设计令牌自动生成扩展配置关闭 preflight在已有组件库的项目中通过corePlugins.preflight: false避免基础样式污染参考 coze-studio 应用配置优先使用语义类在业务代码中优先使用coz-fg-*、coz-bg-*、coz-mg-*、coz-stroke-*等语义类主题切换时无需改动业务代码按场景选用色系前景/背景选择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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考