企业官网建设流程全解析

vibe-kanban 新设计系统（New Design System）样式指南：CSS 变量、Tailwind Token 与组件架构规范

【免费下载链接】vibe-kanbanGet 10X more out of Claude Code, Codex or any coding agent项目地址: https://gitcode.com/GitHub_Trending/vi/vibe-kanban

vibe-kanban 是一个让 Claude Code、Codex 等任意编码 Agent 效率倍增的开发工作台，其桌面端与云端 UI 共享一套被称为New Design System的新设计体系。本文以 packages/local-web/AGENTS.md 为骨架，结合 主题 Token 定义 与 Tailwind 配置 源码，完整讲解新设计系统的颜色、字号、间距、圆角、焦点态等 Token 用法，并深入解析其组件分层架构规则。读完本文，你将能按照项目规范为新界面编写风格统一、可直接合并进主分支的组件代码。

新设计系统：定位与组成

vibe-kanban 的前端代码分散在多个 package 中：packages/local-web（桌面/本地 Web 壳）、packages/web-core（跨端共享的核心 UI）、packages/remote-web（云端页面）与packages/ui（通用组件库）。新设计系统正是为了在这些包之间建立一套统一且紧凑的视觉语言而引入的。

根据 packages/local-web/AGENTS.md 的约定，新设计系统由两部分组成：

1. CSS 变量（Token）：定义在 packages/web-core/src/app/styles/new/index.css，作为所有颜色的唯一事实来源（single source of truth）；
2. Tailwind 配置：packages/local-web/tailwind.new.config.js 将上述 CSS 变量映射为text-*、bg-*、ring-*、p-*等实用类，供组件直接使用。

值得注意的是，这份样式通过@config指令被引用：index.css末尾的@config '../../../../../local-web/tailwind.new.config.js'显式指定了构建时使用的 Tailwind 配置，与项目默认的 Tailwind 配置相互独立。所有新设计样式约定作用域在.new-design类之下，从而保证新旧两套设计体系可以共存，新界面迁移过程中不会互相污染样式。

从目录结构看，新组件体系集中在packages/web-core/src/shared/components/ui-new/下，包含containers/子目录中的NavbarContainer.tsx、SharedAppLayout.tsx、SearchableDropdownContainer.tsx等容器组件，它们正是新设计系统的首批落地实现。

主题 Token：从 CSS 变量到明暗双主题

变量的组织方式

index.css 将 Token 划分为三个层级：

• 内部变量（--_xxx前缀）：仅用于内部派生，例如--_background、--_border、--_radius；
• 公共 Token（无下划线前缀）：面向组件的语义化变量，如--text-high、--bg-primary、--brand；
• VS Code 覆盖层：公共 Token 优先读取 VS Code 注入的 CSS 变量，失败时回退到内部默认值。

:root { color-scheme: light; --_radius: 0.125rem; --text-high: 0 0% 5%; --text-normal: 0 0% 20%; --text-low: 0 0% 39%; --bg-primary: var(--vscode-editor-background, var(--_bg-primary-default)); --brand: 25 82% 54%; }

所有颜色均以HSL 色值（h s% l%）存储，使用时通过hsl(var(--brand))包裹，这也正是 Tailwind 配置中brand: "hsl(var(--brand))"的由来。以hsl(var(--brand))形式存放的好处是：同一 Token 可以在任何需要透明度的地方使用/语法派生，例如hsl(var(--text-low) / 0.4)，背景纹理示例 中的diagonal-lines斜纹背景就是这么实现的。

明暗主题切换

暗色模式通过.dark类作用域切换，公共 Token 名不变、值整体替换（见 index.css 中.dark { ... }块）：

可以看到，品牌橙色--brand（hsl(25 82% 54%)）在明暗两种主题下保持一致，只有文字与背景色发生反转，这保证了品牌辨识度在深色界面中不受损失。此外暗色模式还会同步切换color-scheme: dark，让原生表单控件、滚动条等跟随系统外观。

与 VS Code 的深度融合

这是新设计系统最具特色的机制：公共 Token 的取值是var(--vscode-xxx, fallback)形式，例如：

--bg-primary: var(--vscode-editor-background, var(--_bg-primary-default)); --bg-secondary: var(--vscode-editorWidget-background, var(--_bg-secondary-default)); --bg-panel: var(--vscode-input-background, var(--_bg-panel-default)); --primary: var(--vscode-button-background, var(--_primary)); --ring: var(--vscode-focusBorder, var(--_ring)); --console-error: var(--vscode-terminal-ansiRed, var(--_console-error));

也就是说：当 UI 运行在 VS Code / Tauri 桌面容器中并被注入了 VS Code 主题变量时，界面会自动"穿上"用户当前编辑器主题的外衣；在纯浏览器环境（云端 Web、移动端 PWA）中则优雅回退到内置默认色。这解释了为何 Local Web 桌面端能与用户本机编辑器主题保持视觉一致。

除基础色外，index.css 还定义了完整的状态色（--success、--warning、--info、--neutral）、终端/控制台色（--console-background、--console-foreground、--console-success、--console-error）以及语法高亮 9 色（--syntax-keyword、--syntax-function、--syntax-constant、--syntax-string、--syntax-variable、--syntax-comment、--syntax-tag、--syntax-punctuation、--syntax-deleted），明暗模式各一套，供任务日志、代码 diff 等场景使用。

Tailwind Token：配置源码逐项解析

packages/local-web/tailwind.new.config.js 是设计系统的"接线层"。它的核心是一个getSize生成函数，基于固定的尺寸表按倍数计算 rem 值：

const sizes = { '2xs': 0.5, xs: 0.75, sm: 0.875, base: 1, lg: 1.125, xl: 1.25 }; const lineHeightMultiplier = 1.5; const radiusMultiplier = 0.25; const iconMultiplier = 1.25; const chatMaxWidth = '48rem'; function getSize(sizeLabel, multiplier = 1) { return sizes[sizeLabel] * multiplier + "rem"; }

颜色映射

配置将 CSS 变量逐一映射为 Tailwind 颜色，形成text-high、bg-secondary、ring-brand等实用类：

其中ringColor.DEFAULT被设为hsl(var(--brand))，因此写focus:ring-1（不带颜色）时默认就会呈现品牌橙色的焦点环。注意merged（PR 合并状态，紫色hsl(271 81% 46%)）在暗色下会提亮为hsl(271 81% 66%)，保证对比度。

字号与行高

字号采用"比 Tailwind 默认更小"的紧凑刻度，且每一项都携带计算好的行高（字号 × 1.5）：

需要说明的是，文档与配置注释中的像素值是面向紧凑界面的设计标注，实际落地以 rem 为准，最终渲染尺寸取决于html根字号（index.css 中移动端还支持--mobile-font-scale整体缩放根字号）。text-cta是专为按钮/行动号召文字设计的特殊刻度，行高乘数为 1（无额外行距）。

间距、圆角与图标尺寸

间距 Token 通过getSize('base', x)生成，与默认 Tailwind 的p-*体系完全解耦：

圆角以--radius: 0.125rem为基准、按 0.25 倍率递增：rounded-sm≈ 0.1875rem、rounded-md≈ 0.21875rem、rounded-lg≈ 0.28125rem，rounded（默认）即最小圆角，整体风格偏锐利、紧凑。配置还额外提供了border-width的border-base/border-half，以及按iconMultiplier = 1.25放大的图标尺寸族size-icon-2xs至size-icon-xl（如icon-xs= 0.9375rem）、聊天面板最大宽度width-chat=48rem等，并注册了pill、running-dot、border-flash、shake、accordion-down/up等关键帧动画供状态反馈使用。

组件样式速查：核心 Token 用法

以下内容直接继承自 packages/local-web/AGENTS.md 并补充了实现说明，是编写新设计组件时的"最小备忘单"。

颜色

文本色（替代所有text-gray-*）：

• text-high：主文本，最高对比度；
• text-normal：常规文本；
• text-low：弱化/次级文本、占位符。

背景色：

• bg-primary：主背景；
• bg-secondary：略深的次级背景，用于输入框、卡片、侧边栏；
• bg-panel：面板/浮起表面。

强调色：

• brand：品牌橙（hsl(25 82% 54%)）；
• error：错误状态；
• success：成功状态。

字号

紧凑字号刻度，text-base（1rem）为默认正文尺寸，text-xs至text-xl逐级递增，行高固定为字号的 1.5 倍。正文、输入框、按钮文字请优先使用text-base/text-sm，层级标题再向上取text-lg/text-xl。

间距

p-half/m-half（6px）、p-base/m-base（12px）、p-double/m-double（24px）三个主档位，以及p-plusfifty（18px）补充档位。组件内边距、元素间距统一从这些 Token 取值，避免随意写死像素。

圆角

默认圆角很小（--radius: 0.125rem）：rounded为默认小圆角，rounded-sm、rounded-md、rounded-lg逐级增大。输入框、按钮一般用rounded或rounded-sm即可。

焦点状态

焦点环使用ring-brand（品牌橙），且默认内嵌（inset）。基础层样式为所有可聚焦元素声明了*:focus { @apply ring-inset; }，因此组件中只需组合focus:outline-none focus:ring-1 focus:ring-brand即可获得统一的内嵌橙色焦点指示。

官方示例与真实组件对照

文档给出的三个基准示例（AGENTS.md）：

// 输入框 className="px-base bg-secondary rounded border text-base text-normal placeholder:text-low focus:outline-none focus:ring-1 focus:ring-brand" // 图标按钮 className="flex items-center justify-center bg-secondary rounded border text-low hover:text-normal" // 侧边栏容器 className="w-64 bg-secondary shrink-0 p-base"

这些模式在新组件中已经大量落地。例如 SharedAppLayout.tsx 中的侧边栏容器使用className="bg-secondary"，标题使用text-sm font-medium text-high truncate，菜单项使用flex items-center gap-2 px-4 py-3 text-sm text-normal hover:bg-secondary cursor-pointer；RemoteIssueLink.tsx 中的链接行使用flex items-center gap-half px-base text-sm text-low hover:text-normal hover:bg-secondary rounded-sm transition-colors。可见hover 时文字从text-low升为text-normal、背景切换为bg-secondary是贯穿全部组件的标准交互范式。

组件分层架构规则

packages/local-web/AGENTS.md 为编写新设计组件规定了清晰的架构边界：

• View 组件（位于views/）：无状态，所有数据通过 props 传入，只负责渲染与事件上报；
• Container 组件（位于containers/）：管理状态，负责数据获取、状态同步，并将数据以 props 形式下发给 View；
• UI 组件（位于ui-new/）：可复用原语，如Field、Label这类不承载业务逻辑的基础件；
• 文件命名：ui-new/下的文件名必须为PascalCase（例如Field.tsx、Label.tsx）。

从源码看，这条规范已在 packages/web-core/src/shared/components/ui-new/ 落地：containers/子目录中全部文件均为 PascalCase 命名（NavbarContainer.tsx、AppBarUserPopoverContainer.tsx、SearchableDropdownContainer.tsx、ColorPickerContainer.tsx、RemoteIssueLink.tsx、SharedAppLayout.tsx），并以*Container后缀直观标识其"管理状态"的职责。

这套"无状态 View + 有状态 Container + 原语 UI"的分层在工程上带来的收益是：View 可被任意容器复用且易于单测，Container 可独立替换数据来源而不影响渲染层。实际编写新组件时，应把业务逻辑尽量下沉到 Container，把展示逻辑收敛在无状态组件内，并优先从ui-new/现有原语组合界面。

高级特性：动效、终端配色与移动端适配

新设计系统不止于静态 Token，还内置了几组开箱即用的能力：

• 运行中状态动效：chat-box-running与create-issue-attention通过::before伪元素 +border-flash关键帧实现 1px 宽的品牌色流动边框，用于标注"任务正在执行"的聊天框与"待创建 Issue"的高亮入口（index.css）。同时遵循无障碍要求，prefers-reduced-motion: reduce下会关闭动画；
• ANSI 终端配色：.ansi-red、.ansi-green等 16 色类（含 bright 变体与ansi-bold/ansi-italic/ansi-underline）面向终端日志着色，明暗模式分别优化了对比度（浅色下用深一档色值，深色下提亮）；
• 表情符号回退：.color-emoji工具类按Apple Color Emoji → Segoe UI Emoji → Noto Color Emoji顺序回退，保证不同平台上表情一致；
• 移动端与 PWA：移动端禁用 overscroll 回弹（桌面 Tauri 窗口同样生效）、支持--mobile-font-scale根字号缩放、并为 PWA safe-area 提供明暗两套html/body背景色；
• 分栏控件适配：为 allotment 分栏面板提供--separator-border与--focus-border（品牌橙）变量，保证拖动分隔条与布局容器配色一致。

开发者接入指引

在本地 Web 包中开始使用新设计系统：

1. 样式入口：确认组件构建使用 tailwind.new.config.js 所配置的 Tailwind（该配置的content已覆盖packages/web-core/src、packages/remote-web/src、packages/ui/src等路径，详见配置中content数组）；
2. 主题变量：所有颜色、圆角等语义 Token 定义在 packages/web-core/src/app/styles/new/index.css，无需在组件内重复写死色值；
3. 组件落位：新组件放入packages/web-core/src/shared/components/ui-new/（原语）或其containers/（状态容器）子目录，文件名使用 PascalCase；
4. 编码规范：文本色一律使用text-high/normal/low，背景用bg-primary/secondary/panel，强调用brand，间距用p-half/base/double，焦点态统一focus:outline-none focus:ring-1 focus:ring-brand，并遵循"View 无状态、Container 管状态"的分层约定。

总结

vibe-kanban 的新设计系统是一套"以 CSS 变量为 Token 源头、以独立 Tailwind 配置为接线层、以分层组件规范为工程约束"的完整设计体系。它通过hsl()语义变量 + 明暗双主题 + VS Code 变量覆盖三层机制，在桌面端、云端与移动端之间实现了一致的紧凑视觉语言；同时借助text-high/normal/low、bg-primary/secondary/panel、brand强调色、rem 化字号/间距/圆角 Token 与ring-brand焦点态，为开发者提供了一份可直接照做的组件样式清单。配合 AGENTS.md 规定的views/（无状态）、containers/（管状态）、ui-new/（原语）分层与 PascalCase 命名约束，新界面组件既能保持风格统一，也具备清晰的职责边界，是项目持续推进 UI 现代化迁移的坚实基础。

【免费下载链接】vibe-kanbanGet 10X more out of Claude Code, Codex or any coding agent项目地址: https://gitcode.com/GitHub_Trending/vi/vibe-kanban