Kumo主题生成器完全指南：一份配置文件如何自动生成语义化CSS Token与FedRAMP主题

Kumo主题生成器完全指南一份配置文件如何自动生成语义化CSS Token与FedRAMP主题【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumoKumo 主题生成器Theme Generator是 Kumo 组件库的换肤中枢你只需编辑一份 config.ts 配置文件运行一条命令就能自动生成基础主题theme-kumo.css与 FedRAMP 合规主题theme-fedramp.css所有语义化 CSS Token 均从此单一数据源派生彻底告别手动维护多套主题样式。为什么需要主题生成器传统做法里换主题往往意味着复制粘贴大量 CSS、手动翻转几十处颜色值还容易漏改导致深浅色模式不一致。Kumo 的思路是把语义和颜色值分开概念说明示例语义 Token描述用途而非颜色kumo-canvas画布背景、kumo-brand品牌色主题值每个 Token 在各主题下的实际颜色浅色oklch(98.75% 0 0)/ 深色oklch(10% 0 0)生成器把上两表合并输出 CSS 变量--color-kumo-canvas: light-dark(...)组件代码只引用语义 Token如bg-kumo-canvas永远不写死颜色值——这就是换肤只需改配置、不用碰组件代码的原因。30秒上手一条命令生成全部主题在 Kumo 包内执行pnpm codegen:themes该命令定义在 package.json 中实际调用 index.ts 这个 CLI 入口输出到 src/styles/ 目录生成两个文件theme-kumo.css —— 基础主题包含全部Tokentheme-fedramp.css —— FedRAMP 主题只包含差异覆盖CLI 还支持几个实用参数参数作用--list列出所有 Token 及其新旧名称、所属主题--dry-run预览生成的 CSS不写入文件--use-new-names按新 Token 命名生成迁移场景--rename-map输出新旧名称映射 JSON供批量改码使用深读配置文件三类语义 Token 怎么组织config.ts 是唯一的单一数据源Single Source of Truth每个 Token 都是一个TokenDefinition类型定义见 types.ts核心结构是newName未来迁移名theme每个主题的浅色/深色值。配置按三类组织text文本 Token—— 生成--text-color-*变量配text-*工具类使用。例如kumo-default浅色取neutral-900、深色取neutral-100天然完成深浅色翻转。color颜色 Token—— 生成--color-*变量。Tailwind v4 中bg-*、border-*、ring-*、fill-*、stroke-*等所有带颜色的工具族都解析这同一套变量一条声明同时覆盖背景、边框甚至 SVG 图标着色见 types.ts 的注释。typography排版 Token—— 字号与行高xs/sm/base/lg不参与明暗切换但可按主题整体调整。文件末尾的AVAILABLE_THEMES [kumo, fedramp]声明了所有可用主题——未来新增主题只需在这里加一行并在各 Token 下补充对应色值即可。生成原理light-dark() 如何实现一套 CSS 双模式打开生成的 theme-kumo.css可以看到每个 Token 都被包装成--text-color-kumo-default: light-dark( var(--color-neutral-900), /* 浅色模式值 */ var(--color-neutral-100) /* 深色模式值 */ );这是 CSS 原生的light-dark()函数浏览器根据当前明暗模式自动取对应值无需 JS 切换、无需dark:前缀重复声明。生成逻辑在 generate-css.ts 的generateKumoThemeCSS()中除了theme块里的 Token 声明生成器还会追加一组按[data-theme]/[data-mode]作用域划分的运行时变量避免某些浏览器在 DOM 变更时出现短暂的light-dark()未解析值。FedRAMP 主题如何被自动覆盖生成FedRAMP 是美国联邦政府的云安全合规框架Kumo 为这类高安全场景提供了专属视觉主题。它的生成策略非常巧妙见 generate-css.ts 的generateThemeOverrideCSS()只输出差异遍历配置时凡某 Token 定义了fedramp分支就生成一条覆盖没有定义的就沿用基础主题。作用域限定覆盖规则包在[data-themefedramp]选择器里与基础主题互不干扰。配置里能清楚看到这种按需覆盖例如kumo-canvas与kumo-base在 FedRAMP 下统一为固定灰蓝#5b697cconfig.ts而kumo-hairline则覆盖为#c8d4e5。绝大多数 Token 无需改动FedRAMP 主题因此只有一份很小的 CSS 文件。迁移助手改名、预览与批量映射Token 命名会随项目演进而调整。生成器为此内置了完整的迁移链路每个 Token 可声明newName--use-new-names时按新名生成 CSS--rename-map导出旧名 → 新名映射 JSON可直接驱动批量改码codemod--dry-run让你在落盘前完整预览差异独立的 migrate.ts 迁移脚本负责把代码中的旧类名替换完毕最后提示Ready for codegen:themes to regenerate CSS。生成逻辑本身也有测试守护generate-css.test.ts 验证了生成的 CSS 结构与预期一致防止生成器静默漂移。总结改哪里、别改哪里✅要改颜色 / 加主题只编辑 config.ts然后pnpm codegen:themes✅预览结果加--dry-run零风险❌别手改theme-kumo.css 和 theme-fedramp.css——文件头部已标注AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY。一份配置、一条命令、两个主题文件深浅双模式自动就绪合规主题只维护差异——这就是 Kumo 主题生成器带来的配置即主题体验。【免费下载链接】kumoCloudflares component library for building modern web applications.项目地址: https://gitcode.com/gh_mirrors/kumo5/kumo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考