Skip to content

[Feature]: 建立 WebUI 样式 token 与组件化主题体系 #272

Description

@xxynet

Short description

为 WebUI 建立语义化设计 token 与基础组件样式边界,逐步消除全局 CSS 覆盖、颜色硬编码和 !important 补丁,使主题能够统一维护与扩展。

Problem to solve

当前 WebUI 同时混用 Tailwind 工具类、src/assets/main.css 中的全局规则和组件内样式。样式规则已出现跨组件覆盖风险:

  • 全局 input、select、textarea 规则以 !important 强制背景、边框和焦点样式,组件难以安全地声明差异。
  • 全局规则直接重写 Tailwind 的 .text-gray-*、.bg-*、.border-* 工具类;同一个 Tailwind class 在浅色和深色下不再保持可预测的语义。
  • .bg-white.rounded-lg.shadow 这类组合选择器会将任意符合该组合的元素强制改为玻璃卡片,新增页面可能被意外影响。
  • 色值分散在页面、组件和全局样式中。静态审查发现约 310 处 hex/rgb/rgba 色值、59 处 !important,而 CSS 自定义属性 var(--...) 使用次数为 0。
  • PluginView.vue(2083 行)等大页面还同时承载多个弹窗与其样式,重复的 modal、按钮、表单视觉规则难以持续保持一致。

深浅色切换目前可用,但只是给根节点切换 .dark class。调整品牌色、边框、表单、对比度或新增主题时,需要跨多个文件修改裸色值,容易产生视觉回归。

Proposed solution

按不改变现有视觉设计的渐进方式治理:

  1. 定义语义化设计 token,例如 --color-surface、--color-surface-raised、--color-text-primary、--color-text-muted、--color-border、--color-accent、--shadow-card;在 :root 与 .dark 中分别赋值。
  2. 缩减 main.css 的职责至 token、reset 和真正的全局基础规则;移除对 Tailwind 通用工具类和宽泛 class 组合的全局覆盖。
  3. 将卡片、按钮、表单、弹窗等重复视觉能力沉淀为明确的基础组件或语义 class;组件内部样式应使用 token,避免全局选择器越界。
  4. 迁移 CustomSelect、CustomMultiSelect、TagInput 等共享控件的重复规则,并移除彼此的非 scoped 样式交叉。
  5. 逐步替换裸色值和 !important,保留仅在第三方组件兼容确有必要时的最小例外。
  6. 在不扩大本 Issue 范围的前提下,后续将大型页面中的独立弹窗/区域拆为子组件,降低样式与业务逻辑的耦合。

建议验收标准:

  • 主题基础颜色和阴影由 token 集中定义,浅色/深色切换不需要修改页面级裸色值。
  • 新增基础卡片、表单或 modal 不会被通用 Tailwind class 组合的全局规则意外改写。
  • 不再以全局 .dark .text-gray-* 等规则重写 Tailwind 工具类。
  • !important 仅保留在无法替代的第三方组件兼容场景,并有明确说明。
  • 现有浅色与深色界面的主要页面经人工回归后无明显视觉变化或可访问性回归。

Alternatives considered

继续在 main.css 追加深色模式覆盖或为每个组件单独补丁,短期改动较小,但会继续提高选择器优先级和主题维护成本,因此不建议。

Additional context

本 Issue 基于当前仓库的静态样式审查,不包含特定用户环境或运行时错误。建议拆成多个小 PR 逐步落地,先完成 token 与全局覆盖收口,再迁移基础组件和页面。

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions