LinkPort/docs/ui-design.md

DBX 风格界面

功能重要性与状态配色（2026-09-24）

在紧凑布局上增加语义颜色层级：主要操作和当前选中项使用蓝色；核心入口（目标、网关）同时显示“核心”文字标记；配置类图标使用紫色，监控类使用青色，辅助功能保留低强调度。浅色背景调整为淡蓝灰，内容面板保持独立层次；深色主题保留石墨底色，以亮蓝、青色和紫色提供强调。

统计卡使用对应彩色顶部边框、浅色底和数字：代理总量蓝色、运行中绿色、活跃连接青色、只读配置紫色。启动操作绿色、停止操作橙色，运行/异常状态使用带文字的色块；异常网关区域仅在有异常时变红。错误和警告提示保留标题、正文及原有图标并增加彩色边线，删除操作沿用红色。颜色不代替文字，不将只读代理数或固定菜单分类误报为告警。

浅色、深色、海蓝及跟随系统均引用共享令牌，沿用已有主题存储键。手机隐藏核心入口的小标签但保留图标颜色、可访问名称和选中状态；按钮禁用、键盘焦点及原有确认流程保持有效。范围限展示，无 API、数据迁移或协议行为变化。本节取代下方历史的黑白主按钮描述；实际验证记录见本次变更原因。

本次生产构建及基于新嵌入程序的全部 124 项 Playwright 测试通过，覆盖主题、移动布局和原有交互；下方 spawn EPERM 为此前记录，不代表当前验证状态。隔离预览位于 bin/dev-build/ui-colors-20260924/light-desktop.png、dark-mobile.png。

linkport 的全部工作区页面采用参考本地 C:\work\github\dbx 的紧凑桌面工具风格。参考范围是视觉体系与通用控件，而不是把 DBX 的数据库编辑器、Tauri 运行时、连接状态或业务功能移植进来。linkport 继续使用 Vue 3、Element Plus 和原有管理 API。

2026-09-20 已进一步实现 清单 中 UI-001 至 UI-011 的代码：资源搜索、资源树、列设置、工作区标签、操作菜单、最近访问，以及独立 URL 参数、高级连接选项、连接标识与测试反馈。工作区操作及生命周期见 工作区交互，协议生效范围见 连接配置。代码实现与运行态验收分开记录，当前浏览器验证仍受环境限制。

设计来源与对应关系

DBX 参考位置	linkport 实现
apps/desktop/src/styles/tokens.css	web/src/theme.css：中性灰配色、深色石墨背景、文字层级、4px 控件圆角、6px 面板圆角
apps/desktop/src/components/layout/AppToolbar.vue、AppSidebar.vue	web/src/App.vue、style.css：紧凑工具栏、浅灰/深灰侧栏、小尺寸线性图标、选中标记
apps/desktop/src/components/ui/button/index.ts、input/Input.vue	web/src/controls.css：按钮、输入框、焦点状态、菜单、表格和浮层的统一外观

不增加 UI 框架或图标依赖，不复制 DBX 品牌标识。AppIcon.vue 提供 linkport 自有的线性 SVG 图标。字体优先使用本地 Geist，未安装时回退到系统中文字体和 Segoe UI；没有新增网络字体请求。

覆盖范围

• 代理管理、目标服务、运行概览、网关服务、连接与审计、命令审计、拖拽连线、监控运维、配置管理、多端同步和密码解密，共 11 个导航页面。代理页维护 Kubeconfig、SSH、SOCKS5 和 sing-box 网络配置，文件仅作为使用处的凭据。SQLite 文件菜单及功能已于 2026-09-25 移除。
• 登录页、菜单搜索、版本信息、主题选择、项目/环境筛选和账号状态。
• 表格、卡片、表单、标签、通知、工作区子页面，以及目标/网关连接编辑器。
• SQL 和命令输出、导入区域、集群配置和同步冲突面板使用相同的等宽字体及圆角令牌。

浅色主题采用白色内容区、浅灰侧栏及深色主按钮；深色主题使用分层石墨背景及浅色主按钮，文字、勾选标记和按钮文字同时适配。成功、警告和失败仍以语义颜色区分，不把所有状态改成灰色。

主题选择器位于工作区顶部工具栏中，不再悬浮遮挡页面信息。登录页保留独立选择器。原有 linkport-theme 存储键以及 light、dark、ocean、system 值不变；light 的显示名称从“浅色 · 森绿”改为“浅色 · 经典”，dark 改为“深色 · 石墨”。海蓝继续提供蓝色强调色，“跟随系统”继续响应系统深浅色变化。

布局与交互

• 桌面侧栏默认 224px，可调整为 192–420px，中等宽度为 192px；720px 及以下使用 52px 图标侧栏和独立资源树子页面。手机导航保留至少 44px 的按钮高度和完整可访问名称。
• 顶部工具栏采用约 44px 高度；工作区减少装饰性留白，保留标题、说明、筛选和主要操作。
• 目标/网关编辑器使用工作区子页面布局，保留固定标题/页签/页脚、页面独立滚动和原有键盘切换。外观使用紧凑标题和分段页签。
• 宽表格和拖拽画布仍在自身容器内滚动，窄屏保留网关卡片与表单换行。版本与主题工具不占据浮动覆盖层。
• 可见焦点样式覆盖导航、按钮、主题选择及输入控件；系统启用减少动态效果时，关闭不必要的界面动画。

视觉层本身不改变协议安全策略。后续功能扩展增加了有白名单和运行支持的目标参数、连接标识以及导航状态，沿用账号权限、凭据加密、启停和未保存确认；兼容与默认值详见连接配置文档。无表结构迁移，不需重置原主题偏好。

维护入口

项目品牌图标单独使用 web/public/linkport.svg，登录、侧栏和浏览器 favicon 共用；普通功能图标仍由 AppIcon.vue 提供。启动 ASCII 标识与资源嵌入说明见 项目标识。

main.ts 按 Element Plus 基础样式、深色变量、theme.css、style.css、controls.css、responsive.css 的顺序加载全局样式。颜色和尺寸定义放在 theme.css；布局放在 style.css；公共 Element Plus 外观放在 controls.css；断点规则放在 responsive.css。独立组件的局部样式应引用这些令牌，不再定义一套硬编码主题色。

ThemePicker.vue 复用原来的 theme.ts 状态，不创建第二套偏好存储。SidebarNavigation.vue 继续使用 App 提供的菜单、计数、搜索和导航事件。

2026-10-02：登录页和顶部工具栏的主题选择器增加太阳/月亮图标按钮，可直接在浅色与深色之间切换，悬停及可访问名称指示目标主题。浅色、深色、海蓝、跟随系统下拉选择保留，继续使用 linkport-theme 存储键。跟随系统时按钮读取实际深浅色状态，点击后保存明确的浅色或深色选择；无 API 或数据迁移。桌面和手机共用此控件，实际验证见变更记录。

验证与边界

• 新增 web/tests/dbx-ui.spec.ts，覆盖 13 个菜单在浅色、深色、海蓝和桌面/手机下的主题颜色、圆角、导航状态、页面宽度及工具栏布局；另覆盖四类编辑器、页签 Home/End 切换、登录主题持久化和系统主题跟随。用例包含截图输出，但本次没有执行成功或生成截图。
• 原 web/tests/responsive.spec.ts 的手机图标断言从字符字号调整为 SVG 可见性与实际宽度，仍保留原有尺寸、固定页脚、登录和退出检查。
• 当前锁定依赖已经可用，vue-tsc --noEmit 全量类型检查通过，7 项新增纯逻辑测试函数在单进程通过；全套 Playwright 测试发现成功，共 88 项。早期离线语法检查不是当前代码的生产构建证明。
• Go 1.25.0 全部后端测试及 go vet ./... 通过。协议新增验证使用本地 fixture；数据使用隔离测试目录，未接触真实目标或工作区 data。
• npm.cmd --prefix web run build 在启动 esbuild 时失败（spawn EPERM），Playwright worker 启动也被拒绝。尚无本轮新前端产物、嵌入程序或浏览器执行/截图；不能使用旧二进制和下方其他文档的历史截图代替验收。

依赖可用后，先运行前端构建，再编译 Go 程序；不要同时替换 web/dist 和构建嵌入资产。随后将 LINKPORT_E2E_BINARY 指向刚生成的可执行文件，使用隔离数据库和空闲端口运行完整 Playwright 套件。