KPanel 界面与视觉语言规范

August 19, 2026 · View on GitHub

  • 版本：2026-08-18
  • 状态：长期强制规范
  • 适用范围：KPanel Web 界面、桌面工作区、组件、图标、主题、动效、文案呈现和本地功能预览

本文件是 KPanel 的界面与视觉语言入口。它定义可读性、视觉层级和交互呈现的产品约束；具体业务文档可以 扩展本文件，但不得降低本文件的字号、对比度、键盘、缩放、状态反馈和响应式要求。业务规则、质量等级和 发布门禁仍以 PROJECT_RULES.md 和 docs/development-quality-standard.md 为准。

1. 产品视觉原则

KPanel 是直接管理真实 Linux 资源的运维工作台。界面应让管理员在低配置主机、网络抖动和长任务场景下仍能 快速识别状态、完成操作并恢复失败，不用“更小的字”和“更高的信息密度”掩盖复杂度。

  1. 清晰优先：操作名称、当前状态、影响范围和下一步恢复动作比装饰更重要。
  2. 克制而精致：使用稳定的绿色品牌色、清晰表面层级、适度圆角和轻阴影；不依赖微小文字、过度渐变、 低对比度或动画制造高级感。
  3. 真实反馈：加载、空、失败、部分成功、等待输入和需要人工处理必须有不同的可理解呈现，不能只换颜色。
  4. 渐进披露：首屏展示完成当前任务所需的最少信息，详细日志、低频设置和诊断信息按需展开，不能用缩小字号 塞进同一行。
  5. 一致且可恢复：同一种状态、确认、返回、取消和重试在不同页面使用相同语义；页面刷新、弹窗关闭和断线 不应让用户误以为真实后台任务消失。

2. 字体和可读性基线

2.1 结论：小字最小 12px

以下数值均指浏览器默认缩放 100% 时的计算后 CSS px，不是设计稿画布像素：

文字用途KPanel 基线规则
页面标题 / 主要结果18–28px通过层级和留白建立重点，不用超粗字堆叠
区块标题 / 主要操作16–18px操作按钮、表单标题和关键状态不得低于 14px
正文 / 表单 / 导航 / 错误与成功反馈14px这是默认可操作文字基线；长说明可用 15–16px
次要说明 / 帮助 / 时间 / 元数据13px仍需清晰可读，不能只靠颜色区分
紧凑标签 / 图表刻度 / 非核心摘要12px这是用户可见文字的绝对下限
12px 以下禁止不得用于有语义的文案、状态、按钮、输入提示、日志、表格、图表或错误信息

因此，KPanel 的明确规则是：可读文字最小 12px，正文和操作控件最小 14px，辅助信息不低于 13px。 现有代码中已发现 8–11px 的历史样式；它们属于迁移债务，不代表新规范允许继续新增同类样式。

以下内容不作为“文字”豁免：徽章、角标、状态点旁的短词、图表数字、AI 模型标签和终端提示只要承担信息含义， 仍须满足上述下限。纯装饰性图形应去除伪文字；代码/终端等专业内容也不低于 12px，并提供可复制、可滚动和 可放大的呈现方式。

2.2 层级不靠缩小字号实现

为了在放大字体后保持精致感，新增或修改界面应按以下顺序调整：

  1. 先删去不影响决策的装饰和重复文案；
  2. 再使用标题、正文、辅助文字三档层级，以及字重、颜色和间距建立重点；
  3. 再使用卡片分组、折叠、分页、工具提示或详情面板承载低频信息；
  4. 最后才调整容器尺寸和布局，不得把文字重新压回 12px 以下。

禁止用以下手段恢复“紧凑”外观：负向字距压缩中文正文、固定高度裁切文字、只显示省略号而没有完整查看路径、 让低对比度灰字承担关键状态、把可操作控件改成仅图标且没有可访问名称。

2.3 行高、字重和字距

  • 正文和中文说明的 line-height 建议为 1.5–1.7；紧凑摘要不低于 1.35；标题不低于 1.2。
  • 正文、状态和错误提示不得使用过细字重；默认至少使用 400，关键操作和状态使用 500–700。
  • 中文正文、表单和错误信息不得使用负字距；标题只可在真实浏览器复核后做轻微光学调整。
  • 文字增长、换行和长词必须优先保持内容完整，不能用 overflow:hidden、固定高度或强制单行破坏可读性。
  • 新增样式优先使用相对单位、语义 Token 或 clamp()；不得用固定 px 配合固定高度、裁切或不可换行布局阻止浏览器文本缩放。

2.4 对比度和缩放

  • 普通文字与背景的对比度目标不低于 WCAG 2.2 AA 的 4.5:1；大文字可按 3:1 评估。
  • 浅色、深色主题分别检查实际组合；muted 文字也不能因为“辅助信息”而失去可读性。
  • 页面必须支持浏览器缩放和文本放大到 200%，不裁切、不覆盖、不丢失操作；固定底栏、弹窗和桌面窗口必须随内容重新布局。
  • 功能预览和发布验收至少记录 100%、125% 和 200% 中受影响的级别；无法覆盖的级别必须写明原因和风险。

3. 视觉语言

3.1 颜色和表面

使用现有 CSS 语义变量，不在组件内随意新增同义颜色：

  • 品牌操作使用 --brand、--brand-strong、--brand-soft；品牌色表达行动和选中，不单独承担成功/失败语义。
  • 内容层使用 --surface、--surface-subtle、--surface-raised；边界使用 --border、--border-strong。
  • 文字使用 --text、--text-soft、--muted，并按浅色/深色主题分别复核对比度。
  • 成功、警告、危险和信息状态必须同时使用文字、图标、位置或结构表达，不能只用绿色、黄色或红色。
  • 背景、卡片和弹窗不叠加无意义的渐变、玻璃效果、发光或厚重阴影；视觉层级以一次主表面、一次抬升表面和 清晰边界为主。

3.2 圆角、间距和阴影

  • 默认间距以 4px 为基础节奏，常用组合为 8/12/16/24px；需要更大间隔时优先增加分组留白。
  • 现有语义圆角为 --radius-sm、--radius、--radius-lg，新组件不得为相同层级再创建另一套圆角。
  • 阴影只用于表达悬浮、弹窗和层级，不用阴影替代边界；浅色和深色主题的阴影强度分别复核。
  • 放大文字后优先让卡片增高、列换行或内容折叠；不得靠减小内边距、字号或点击区域保持原始像素密度。

3.3 图标和品牌

品牌图标、应用图标、透明背景、安全区和尺寸约束遵守 brand-icons.md 及 .codex-workflows/normalize-kpanel-app-icons.workflow.yaml。图标应保持识别度、视觉居中和小尺寸轮廓； 图标不能替代必要的文字标签，也不能因为放大字号而随意缩小到难以识别。

3.4 动效

  • 动效服务于状态变化、层级和方向，不用于延迟用户操作或掩盖后台任务状态。
  • 普通状态过渡保持短、轻、可打断；长任务必须显示可持续的进度和真实阶段。
  • 尊重 prefers-reduced-motion；减少动画时仍保留状态、焦点、成功和失败反馈。

4. 交互呈现契约

每个受影响控件至少定义以下状态：默认、悬停、键盘焦点、按下/执行中、禁用、加载、空、失败、部分成功和需要 人工处理。状态必须满足：

  • 键盘可以到达，焦点清晰可见，关闭弹窗后焦点回到合理来源；
  • 主要操作有文字或可访问名称，图标按钮不依赖用户猜图；
  • 破坏性操作说明影响范围，确认后仍由后端执行 Session、CSRF、输入和资源版本校验；
  • 错误信息说明真实原因、已经完成的步骤、是否留下部分结果和可执行的恢复方式；
  • 加载、空状态和失败状态不复用成功样式，不用短暂 Toast 作为唯一结果证据；
  • 点击目标遵守现有 WCAG 2.2 AA 目标：至少 24×24CSSpx24 \times 24 \text{CSS} \text{px}，触摸主操作优先 40–44px；
  • 状态不能只用颜色表达，必须有文本、图标、结构或可访问属性的等价信息。

5. 响应式和老人友好验收

5.1 最小验收矩阵

界面或视觉变更按影响范围选择矩阵，不要求无关页面机械重跑：

维度至少检查
视口390px 窄屏、768px 过渡宽度、1280px 桌面；桌面工作区另按其布局契约验收
缩放100%、125%、200% 文本/浏览器缩放；无裁切、重叠、横向阻断或不可达操作
主题浅色、深色；文字、边界、图标和状态语义保持可辨识
内容中文、英文、长名称、长错误、数字/路径、加载、空、失败和部分成功
操作鼠标/触摸、键盘 Tab/Enter/Escape、焦点可见、弹窗返回和取消
运行态受影响功能的控制台错误、真实加载反馈、后台任务连续性和恢复路径

5.2 保持精致感的具体方法

  • 以 14px 正文作为骨架，13px 辅助信息和 12px 紧凑摘要只在信息确实次要时使用；不让整页都变成同一字号。
  • 用颜色明度、字重、分组、留白和一致的图标尺寸建立信息层级；重要内容扩大，不重要内容折叠。
  • 把并列的低频字段改为两列、详情抽屉、可展开摘要或二级页面，避免所有字段挤在一张卡片里。
  • 长文本允许换行；在窄屏下先换布局，再考虑减少次要字段，最后才缩短文案，不能缩小可读字号。
  • 视觉复核同时看整体节奏和最小字号：截图好看但存在 8–11px 关键文字时，结论仍为不通过。

6. 实施和迁移规则

  1. 新功能和修改过的 UI 从本版本起不得新增 12px 以下的有语义文字；正文和操作控件不得低于 14px。
  2. 历史低于该基线的样式按受影响功能迁移，优先级为：P0 操作、错误、权限和状态；P1 帮助、表格、元数据和 AI 辅助文案； P2 图表刻度、低频摘要和装饰性标签。
  3. 不允许对全仓 CSS 做未经视觉验收的机械替换。迁移时同步调整容器高度、间距、换行、折叠和响应式布局，保留 原有业务行为和主题契约。
  4. 例外必须在任务验收记录中写出元素、计算字号、信息是否可替代、放大后的可用路径和退出期限；“为了精致”不是 例外理由。
  5. 组件级规范与业务设计文档冲突时，采用本文件更严格的可读性要求，并把业务文档改为引用本文件，而不是复制 另一套字号数字。

7. 验收记录格式

涉及界面或视觉的任务至少记录：

受影响页面/旅程：
最小计算字号及用途：
正文/操作控件字号：
视口与缩放：
浅色/深色主题：
键盘/焦点/触摸：
加载/空/失败/部分成功：
长文本与多语言：
对比度或可访问性证据：
预览等级、候选提交和证据目录：
历史小字号迁移债务与本次未处理范围：

“页面能打开”“截图看起来精致”“预览服务启动成功”不能单独证明可读性或交互验收通过。可见功能会话继续 使用 local-feature-preview-standard.md 的预览卡，并把本节字段中的未验证项 明确交给后续 L1–L3 验收。

8. 规范依据

WCAG 规定的是可访问结果，并没有为所有网页规定一个统一的 CSS 最小字号；12px/14px 是 KPanel 基于单管理员运维、 中文界面、低视力反馈和长期可读性制定的更严格产品基线。若实际用户反馈继续表明 12px 仍难以阅读，应优先提供字号/密度 偏好或继续提高辅助文字，而不是破坏整体层级。