panel-project-deploy/references/panel-ui.md

# 炫酷科技面板风格 UI 规范

## 0. 主题根源统一（必须先做）

在添加任何玻璃效果之前，先让组件库自身输出完整暗色主题。

### Ant Design / Umi

必须通过官方 Token 配置暗色算法：

```ts
import { theme } from 'antd';

const darkTheme = {
  algorithm: theme.darkAlgorithm,
  token: {
    colorPrimary: '#22d3ee',
    colorTextBase: '#e6f7ff',
    colorBgBase: '#07142e',
    borderRadius: 14,
  },
  components: {
    Card: { colorBgContainer: 'rgba(7, 18, 39, 0.84)' },
    Table: { colorBgContainer: 'rgba(2, 8, 23, 0.2)' },
    Modal: { colorBgContainer: '#081428' },
    Drawer: { colorBgElevated: '#081428' },
  },
};
```

Umi 项目放入：

```ts
export default defineConfig({
  antd: {
    configProvider: {
      theme: darkTheme,
    },
  },
});
```

### 必须消除的问题

- 页面或 Layout 外层是黑色，Card/Table/Form 内部仍是默认白色。
- 组件库默认黑色文字落在白色小卡片里，而小卡片又嵌在黑色页面中。
- Modal、Drawer、Select、DatePicker 弹出后仍是浅色。
- 表格分页、Tabs、Empty、Descriptions 没继承暗色。
- 只通过 `color` 或 `background` 做零散补丁，没有统一 Token。

### 最低检查范围

每个含前端交互的项目至少逐页打开：登录页、首页/仪表盘、列表/表格页、表单页、详情/描述页、弹窗或抽屉、AI 页面、系统管理页。


## 1. 视觉方向

默认采用深色未来科技风：

- 深色或蓝黑色背景。
- 大面积低透明度玻璃面板。
- 青色、蓝色、紫色等霓虹渐变光效。
- 细微网格、点阵、光斑或扫描线。
- 面板边缘有高亮描边、角标或发光装饰。
- 卡片悬浮时轻微上浮并增强外发光。

如果项目明确要求浅色或商务风格，不强制深色；改用浅色玻璃拟态、浅蓝/紫渐变、柔和阴影和细发光边框。

## 2. 推荐设计 Token

### CSS 变量

```css
:root {
  --panel-bg: rgba(8, 18, 38, 0.68);
  --panel-bg-strong: rgba(10, 22, 48, 0.86);
  --panel-border: rgba(103, 232, 249, 0.24);
  --panel-border-strong: rgba(34, 211, 238, 0.72);
  --panel-radius: 18px;
  --panel-blur: 18px;
  --panel-shadow: 0 18px 50px rgba(2, 8, 23, 0.45);
  --glow-cyan: #22d3ee;
  --glow-blue: #3b82f6;
  --glow-violet: #8b5cf6;
  --text-primary: #e6f7ff;
  --text-secondary: rgba(226, 242, 255, 0.68);
  --grid-line: rgba(56, 189, 248, 0.08);
}
```

可根据项目主色调整，但必须保持统一，不应每个页面使用完全不同的发光色。

## 3. 全局背景

页面底层建议加入固定背景层：

```css
.app-shell {
  min-height: 100vh;
  color: var(--text-primary);
  background:
    radial-gradient(circle at 15% 10%, rgba(34, 211, 238, 0.22), transparent 32%),
    radial-gradient(circle at 85% 0%, rgba(139, 92, 246, 0.20), transparent 30%),
    linear-gradient(135deg, #020617, #081120 48%, #0f172a);
}

.app-shell::before {
  content: "";
  position: fixed;
  inset: 0;
  pointer-events: none;
  background-image:
    linear-gradient(var(--grid-line) 1px, transparent 1px),
    linear-gradient(90deg, var(--grid-line) 1px, transparent 1px);
  background-size: 36px 36px;
  mask-image: linear-gradient(to bottom, black, transparent 85%);
}
```

背景只做氛围，不允许降低正文对比度。

## 4. 通用玻璃面板

```css
.glass-panel {
  position: relative;
  padding: 20px;
  border: 1px solid var(--panel-border);
  border-radius: var(--panel-radius);
  background: linear-gradient(
    145deg,
    rgba(255, 255, 255, 0.08),
    var(--panel-bg) 38%,
    rgba(255, 255, 255, 0.03)
  );
  box-shadow: var(--panel-shadow), inset 0 1px 0 rgba(255, 255, 255, 0.08);
  backdrop-filter: blur(var(--panel-blur));
  transition: transform 0.25s ease, border-color 0.25s ease, box-shadow 0.25s ease;
  overflow: hidden;
}

.glass-panel:hover {
  transform: translateY(-3px);
  border-color: var(--panel-border-strong);
  box-shadow: 0 22px 60px rgba(2, 8, 23, 0.52), 0 0 28px rgba(34, 211, 238, 0.16);
}

.glass-panel::before {
  content: "";
  position: absolute;
  inset: 0;
  pointer-events: none;
  background: linear-gradient(120deg, rgba(34, 211, 238, 0.12), transparent 32%);
}
```

### 面板标题栏

```css
.panel-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  margin-bottom: 16px;
  padding-bottom: 12px;
  border-bottom: 1px solid rgba(125, 211, 252, 0.16);
}

.panel-title {
  display: flex;
  align-items: center;
  gap: 8px;
  margin: 0;
  font-size: 16px;
  letter-spacing: 0.04em;
}

.panel-title::before {
  content: "";
  width: 4px;
  height: 18px;
  border-radius: 999px;
  background: linear-gradient(180deg, var(--glow-cyan), var(--glow-violet));
  box-shadow: 0 0 12px rgba(34, 211, 238, 0.8);
}
```

### 角标装饰

可在关键面板四角加入科技角标：

```css
.glass-panel.is-featured::after {
  content: "";
  position: absolute;
  right: 14px;
  top: 14px;
  width: 22px;
  height: 22px;
  border-top: 1px solid var(--glow-cyan);
  border-right: 1px solid var(--glow-cyan);
  opacity: 0.8;
}
```

角标属于装饰元素，不应影响点击和内容阅读。

## 5. Tailwind 思路

若项目使用 Tailwind，可抽出可复用类：

```css
@layer components {
  .panel-card {
    @apply relative rounded-2xl border border-cyan-300/20 bg-slate-950/55 p-5 shadow-2xl backdrop-blur-xl transition duration-300;
  }

  .panel-card:hover {
    @apply -translate-y-1 border-cyan-300/70 shadow-cyan-400/10;
  }
}
```

不要为了视觉效果随意升级 Tailwind 大版本或重构整个构建链。

## 6. 页面与组件要求

### 导航栏

- 固定或吸顶时使用半透明深色玻璃背景。
- 当前菜单加发光下划线或胶囊背景。
- Logo 和系统名称放在左侧，操作区放在右侧。
- 移动端抽屉菜单也使用面板风格。
- 焦点状态清晰可见。

### 首页 / 仪表盘

至少包含：

- 欢迎信息或系统状态横幅。
- 3–5 个指标卡片。
- 图表、列表、表格或最近动态区域。
- 空状态和加载状态也要有面板骨架。

指标卡片结构：

```text
图标/状态点 + 指标名称
主要数值 / 状态
趋势描述 / 小型进度条
```

数值可以使用等宽或带轻微发光效果，但不能过度闪烁。

### 项目概述大屏（每个项目必做）

- 独立炫酷大屏页面（如 `/overview`），导航菜单顶部入口名为「概览」；深色科技基底 + 玻璃面板 + 霓虹光效。
- 必须接入后端真实聚合数据，禁止纯静态假数据：
  - 5 个左右核心指标卡：设备/摄像头总数、在线数与在线率、离线数、报警数（待处理/已处理）、规则数、用户数（按项目实体取数）；
  - 近 7 天趋势折线/面积图；状态结构环形图（带文字图例与数值）；最新事件滚动列表；实时时钟；数据约 10 秒自动刷新。
- 图表优先复用项目已有库，未引入可用 SVG/CSS 自绘，不为此强加重型依赖。
- 动态滚动可暂停，图表配色与整体统一，支持大屏分辨率与响应式降级。
- 页脚与概览页头部固定提供两个超链接：开源社区 `https://www.gitcc.com/`、GCC AI Coding `https://www.gitvv.com/`，hover 发光。

### 数据表格

- 表格外层使用面板包裹。
- 表头使用半透明高亮背景。
- 行 hover 时出现微弱青色背景。
- 操作按钮使用小型发光按钮或文字按钮。
- 分页器与面板风格一致。

### 表单与登录页

- 登录卡片居中，最大宽度约 420px。
- 输入框使用暗色半透明底、聚焦发光边框。
- 主按钮使用蓝青/蓝紫渐变和外发光。
- 可加入缓慢漂浮的光斑、粒子或圆环背景。
- 错误提示使用红橙色发光状态，不只依赖颜色表达错误。

### AI 对话页

- 左右或上下布局都可，但核心是独立面板式聊天窗口。
- 消息列表作为玻璃面板，用户消息和 AI 消息使用不同方向、颜色和透明度。
- 正在生成时显示呼吸光点或打字指示。
- API 设置使用右侧抽屉或弹窗，不离开当前页面。
- 流式输出时光标可用轻微闪烁效果。
- 服务商对接（用户指定时强制）：
  - 默认 Base URL 与默认模型必须预填为用户指定值；标准 Chat Completions网关地址以 `/v1` 结尾（例：`https://www.tokenfree.com/v1` + `kimi-k2.6`）。
  - 模型 ID 以服务商模型/定价页面实际字符串为准，禁止臆造。
  - 本地设置 key 必须带版本号；切换服务商时升级版本，旧配置只允许迁移用户自填 API Key。
- 设置抽屉内必须内置深色玻璃风格使用教程：官网链接 → 注册登录 → 控制台创建 API Key（`sk-` 开头）→ 粘贴 → 测试连接 → 保存；并展示 Base URL、默认模型及「Key 仅保存在本地」说明。
- 教程中的 `code`、列表、链接、注释文字统一使用深色面板配色（青色系文字 + 半透明深色底），禁止白底教程块嵌入深色抽屉。
- 未配置 Key 时页面顶部用玻璃风格 Alert 引导，不得阻塞页面浏览。

### 页脚

- 使用半透明面板或顶部分割发光线。
- 展示系统版本、状态、时间、开源社区链接等信息。
- 链接 hover 有发光反馈。
- 移动端分组堆叠，避免拥挤。

## 7. 动效规范

推荐：

- 面板 hover：`translateY(-2px ~ -4px)`。
- 面板进入：透明度 + 8px 内位移。
- 背景光斑：20–40 秒慢速移动。
- 加载点：1.2–1.8 秒呼吸动画。
- 焦点和状态变化：150–300ms。

避免：

- 大面积高频闪烁。
- 持续旋转、跳动的强动效。
- 多层重度模糊叠加导致 GPU 卡顿。
- 自动播放声音。

必须加入：

```css
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    scroll-behavior: auto !important;
    transition-duration: 0.01ms !important;
  }
}
```

## 8. 响应式要求

- 桌面端指标卡片常用 3–5 列网格。
- 平板端降为 2 列。
- 手机端变为 1 列，面板间距收敛。
- 表格支持横向滚动或在小屏转为卡片列表。
- AI 设置面板在手机端全屏或从底部滑出。
- 装饰光斑和角标在小屏可减弱或隐藏。

## 9. 无障碍要求

- 正文和背景对比度达到可读标准。
- 装饰元素设置 `aria-hidden="true"`。
- 按钮和链接必须有可理解文本或 `aria-label`。
- 输入框有关联 `label`。
- `focus-visible` 使用清晰发光轮廓。
- 错误、成功、警告不能只通过颜色区分，要配合图标或文字。
- 弹窗、抽屉打开后焦点管理合理，关闭后返回触发元素。

## 10. 验收清单

页面改造完成后逐项检查：

- [ ] 全局背景和面板变量已建立。
- [ ] 导航、首页/仪表盘、表单、表格、登录页、AI 页、页脚风格统一。
- [ ] 已通过组件库官方 Theme/ConfigProvider Token 启用暗色主题。
- [ ] Modal、Drawer、Select、DatePicker、Popover 等浮层没有白底黑字。
- [ ] Card、Table、Descriptions、Tabs、Pagination、Empty 没有外黑内白。
- [ ] 至少有玻璃模糊、发光边框、渐变光效和悬浮反馈中的三种效果。
- [ ] 主要信息没有被装饰元素遮挡。
- [ ] 深色文字、浅色文字对比度均满足阅读要求。
- [ ] 手机和平板布局正常。
- [ ] 键盘导航和焦点样式正常。
- [ ] `prefers-reduced-motion` 生效。
- [ ] 构建没有因新增样式失败。
- [ ] 原业务流程、接口请求和权限控制未被破坏。
## 11. 阻断式自动审计（必须通过）

面板风格改造完成后，必须运行技能内置脚本：

```bash
python scripts/panel_ui_audit.py \
  --base-url http://localhost:<端口> \
  --hash-routes \
  --username <账号> \
  --password <密码> \
  --submit-text <登录按钮文本> \
  --routes /campusState,/alarms,/ai-chat \
  --open-selector '.drawer-open-button' \
  --wait-until domcontentloaded
```

脚本必须检查：

- 普通正文：对比度至少 4.5:1。
- 大号文字或粗体：对比度至少 3:1。
- Card、Table、Descriptions、Tabs、Pagination、Empty、List 不允许出现深色外壳中的浅色孤立区域。
- Modal、Drawer、Select、DatePicker、Popover、Tooltip、Cascader 不允许白底黑字或低对比。
- Alert、Tag、Badge 文案、图标、关闭按钮和操作按钮必须使用暗色主题下可读的颜色。
- 地图、视频、画布只豁免媒体内容本身，不豁免其悬浮控件、标签、空状态和提示信息。

含轮询、WebSocket、SSE 的单页应用使用 `--wait-until domcontentloaded`。只有退出码为 0、报告中 `0 violations`，健康验证才算完成。禁止为了通过审计而临时降低阈值、删除选择器或跳过页面。