# Testing Tools — 视觉规范文档 > **版本**: 1.0.0 > **日期**: 2026-05-29 > **适用范围**: 所有新页面、新组件、UI 修改 > **设计系统**: 基于 [shadcn/ui](https://ui.shadcn.com/) + Tailwind CSS --- ## 目录 1. [设计原则](#1-设计原则) 2. [色彩系统](#2-色彩系统) 3. [排版规范](#3-排版规范) 4. [间距与布局](#4-间距与布局) 5. [圆角与阴影](#5-圆角与阴影) 6. [组件规范](#6-组件规范) 7. [交互与动效](#7-交互与动效) 8. [暗色模式](#8-暗色模式) 9. [工具色彩标识](#9-工具色彩标识) 10. [代码规范](#10-代码规范) 11. [反模式清单](#11-反模式清单) --- ## 1. 设计原则 ### 1.1 核心定位 Testing Tools 是一款**浏览器扩展开发者工具集**，视觉风格遵循： - **专业克制** — 低饱和度色彩，避免视觉噪音 - **信息密度优先** — 紧凑布局，在 400×600px 的 popup 空间内高效展示 - **开发者友好** — 等宽字体用于代码/数据，清晰的信息层级 - **一致性至上** — 所有页面、组件遵循同一套视觉语言 ### 1.2 设计关键词 ``` 简洁 · 现代 · 功能导向 · 低对比度 · 微圆角 · 微妙阴影 ``` ### 1.3 与 shadcn/ui 的关系 本项目以 shadcn/ui 为底座，所有基础组件（Button、Input、Select 等）均来自或对齐 shadcn/ui 的默认样式。业务组件在此基础上扩展，**不得破坏底层设计语言的统一性**。 --- ## 2. 色彩系统 ### 2.1 CSS 变量定义 所有色彩通过 CSS 自定义属性（HSL 格式）管理，定义于 `src/index.css`： #### 亮色模式 (`:root`) | 变量名 | HSL 值 | 用途 | 近似色 | | -------------------------- | ------------------- | ------------- | --------- | | `--background` | `0 0% 100%` | 页面背景 | `#ffffff` | | `--foreground` | `222.2 84% 4.9%` | 主文字 | `#020617` | | `--card` | `0 0% 100%` | 卡片背景 | `#ffffff` | | `--card-foreground` | `222.2 84% 4.9%` | 卡片文字 | `#020617` | | `--popover` | `0 0% 100%` | 浮层背景 | `#ffffff` | | `--popover-foreground` | `222.2 84% 4.9%` | 浮层文字 | `#020617` | | `--primary` | `222.2 47.4% 11.2%` | 主按钮/强调 | `#0f172a` | | `--primary-foreground` | `210 40% 98%` | 主按钮文字 | `#f8fafc` | | `--secondary` | `210 40% 96.1%` | 次级背景 | `#f1f5f9` | | `--secondary-foreground` | `222.2 47.4% 11.2%` | 次级文字 | `#0f172a` | | `--muted` | `210 40% 96.1%` | 静音/禁用背景 | `#f1f5f9` | | `--muted-foreground` | `215.4 16.3% 46.9%` | 次要文字 | `#64748b` | | `--accent` | `210 40% 96.1%` | 悬停高亮 | `#f1f5f9` | | `--accent-foreground` | `222.2 47.4% 11.2%` | 悬停文字 | `#0f172a` | | `--destructive` | `0 84.2% 60.2%` | 错误/删除 | `#ef4444` | | `--destructive-foreground` | `210 40% 98%` | 错误文字 | `#f8fafc` | | `--border` | `214.3 31.8% 91.4%` | 边框 | `#e2e8f0` | | `--input` | `214.3 31.8% 91.4%` | 输入框边框 | `#e2e8f0` | | `--ring` | `222.2 84% 4.9%` | 焦点环 | `#020617` | | `--radius` | `0.5rem` | 全局圆角 | `8px` | #### 暗色模式 (`.dark`) 暗色模式下所有变量自动反转，保持对比度关系： | 变量名 | HSL 值 | 近似色 | | ---------------------- | ------------------- | --------- | | `--background` | `222.2 84% 4.9%` | `#020617` | | `--foreground` | `210 40% 98%` | `#f8fafc` | | `--primary` | `210 40% 98%` | `#f8fafc` | | `--primary-foreground` | `222.2 47.4% 11.2%` | `#0f172a` | | `--secondary` | `217.2 32.6% 17.5%` | `#1e293b` | | `--muted` | `217.2 32.6% 17.5%` | `#1e293b` | | `--border` | `217.2 32.6% 17.5%` | `#1e293b` | ### 2.2 使用规范 ```tsx // ✅ 正确：使用 CSS 变量
// ✅ 正确：使用语义化色彩名 // 图标按钮 // 危险操作 ``` ### 6.2 Input 来源：`src/components/ui/input.tsx` ```tsx // 标准输入框 // 错误状态 ``` **规范要点**： - 高度统一为 `h-10`（40px） - 等宽字体用于数据输入 - 占位符使用 `text-muted-foreground/60` - 错误时边框变红并调整焦点环 ### 6.3 SwitchButtonGroup 来源：`src/components/ui/switch.tsx` ```tsx // 分段控制器 ``` **规范要点**： - 容器：`rounded-lg bg-muted p-1` - 选中项：`bg-background text-foreground shadow-sm font-semibold` - 未选中项：`hover:bg-background/50 hover:text-foreground/80` - 尺寸：`small`（32px）用于工具页，`medium`（36px）标准 ### 6.4 Card（工具卡片） 来源：`src/pages/Dashboard/ToolCard.tsx` ```tsx // 标准工具卡片结构
{/* 上半部分：图标 + 标题 + 箭头 */}
{/* 图标容器 */}
{/* 文字 */}

标题

描述

{/* 下半部分：预览区（可选） */}
{snapshot}
``` ### 6.5 TextInputArea 来源：`src/components/TextInputArea.tsx` ```tsx // 多行文本输入区 ``` **规范要点**： - 外容器：`rounded-md border border-input bg-background shadow-sm` - 焦点状态：`focus-within:ring-1 focus-within:ring-ring` - 错误状态：`border-destructive focus-within:ring-destructive` - 底部工具栏：`h-10 bg-muted/30 border-t border-border/50` - 字体：`font-mono text-sm` ### 6.6 Dialog 来源：`src/components/ui/dialog.tsx` ```tsx // 对话框内容 标题 描述文字 {/* 内容 */} ``` ### 6.7 Select 来源：`src/components/ui/select.tsx` ```tsx ``` ### 6.8 Checkbox 来源：`src/components/ui/checkbox.tsx` ```tsx // 标准复选框 // 小型复选框（工具栏内） ``` ### 6.9 Badge 来源：`src/components/ui/badge.tsx` | 变体 | 场景 | | ------------- | ------------------ | | `default` | 状态标签、分类 | | `secondary` | 次要标签 | | `destructive` | 错误标签 | | `outline` | 可点击标签、筛选器 | ### 6.10 CopyButton 来源：`src/components/CopyButton.tsx` ```tsx // 标准复制按钮 // 小型复制按钮 ``` **规范要点**： - 默认 `variant="ghost" size="icon"` - 复制成功后变为绿色背景 + 对勾图标 - 使用 `sonner` toast 提示复制结果 --- ## 7. 交互与动效 ### 7.1 过渡规范 | 属性 | 值 | 场景 | | ------------------- | ---------- | ----------------------------- | | `transition-colors` | 150ms ease | 色彩变化（悬停、焦点） | | `transition-all` | 150ms ease | 综合变化（SwitchButtonGroup） | | `duration-200` | 200ms | 复制按钮状态切换 | ### 7.2 焦点状态 所有可交互元素必须有可见的焦点指示器： ```tsx // 标准焦点环 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 // 紧凑焦点环（图标按钮） focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring // 输入框焦点 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 ``` ### 7.3 悬停状态 ```tsx // 按钮悬停 hover:bg-accent hover:text-accent-foreground // 卡片悬停 hover:bg-muted/30 hover:border-[rgba(var(--tool-color),0.45)] // 链接/文字悬停 hover:text-foreground hover:underline ``` ### 7.4 动画规范 使用 `tailwindcss-animate` 提供的动画： ```tsx // 淡入 animate-in fade-in duration-150 // 淡入 + 缩放（SwitchButtonGroup 选中项） animate-in fade-in-50 zoom-in-95 duration-150 // 从顶部滑入（下拉菜单） animate-in fade-in slide-in-from-top-2 duration-150 // 错误提示出现 animate-in fade-in slide-in-from-top-1 duration-150 // 骨架屏脉冲 animate-pulse ``` ### 7.5 禁用状态 ```tsx // 统一禁用样式 disabled:pointer-events-none disabled:opacity-50 ``` --- ## 8. 暗色模式 ### 8.1 实现方式 通过 `darkMode: 'class'`（Tailwind 配置）+ `.dark` 类切换： ```tsx // ThemeModeProvider 自动处理 document.documentElement.classList.toggle('dark', resolvedMode === 'dark'); ``` ### 8.2 暗色模式下的特殊处理 ```tsx // 彩色阴影增强（暗色模式下阴影需要更高透明度） shadow-[0_8px_24px_-8px_rgba(var(--tool-color),0.14)] dark:shadow-[0_8px_30px_-10px_rgba(var(--tool-color),0.25)] // 图标容器背景增强 bg-[rgba(var(--tool-color),0.08)] dark:bg-[rgba(var(--tool-color),0.12)] // 成功状态文字调整 text-emerald-600 dark:text-emerald-400 ``` ### 8.3 暗色模式色彩映射原则 | 亮色 | 暗色 | 说明 | | ---------------- | ---------------- | ------------------------------- | | 纯白背景 | 深蓝黑背景 | 避免纯黑 `#000`，使用 `#020617` | | 浅灰背景 | 深灰背景 | 保持层次关系 | | 深文字 | 浅文字 | 反转对比度 | | 彩色阴影低透明度 | 彩色阴影高透明度 | 暗色需要更强视觉反馈 | --- ## 9. 工具色彩标识 ### 9.1 色板定义 每个工具分配一个主题色，定义于 `src/config/features.tsx`： ```ts const PALETTE_COLORS: Record = { primary: '13, 148, 136', // teal (#0d9488) success: '22, 163, 74', // green (#16a34a) warning: '217, 119, 6', // amber (#d97706) error: '220, 38, 38', // red (#dc2626) secondary: '147, 51, 232', // purple (#9333e8) info: '37, 99, 235', // blue (#2563eb) }; ``` ### 9.2 工具色彩分配 | 工具 | 色彩键 | 色值 | | ----------- | ----------- | ------ | | 时间戳转换 | `primary` | Teal | | 存储清理 | `warning` | Amber | | 二维码工具 | `success` | Green | | 文本统计 | `secondary` | Purple | | JWT 解析 | `info` | Blue | | JSON 对比 | `primary` | Teal | | Base64 转换 | `info` | Blue | | 右键还原 | `success` | Green | ### 9.3 工具色彩使用规范 ```tsx // 1. 通过 style 注入 CSS 变量
// 2. 图标容器背景（低透明度） bg-[rgba(var(--tool-color),0.08)] dark:bg-[rgba(var(--tool-color),0.12)] // 3. 图标颜色 text-[rgb(var(--tool-color))] // 4. 悬停边框 hover:border-[rgba(var(--tool-color),0.45)] // 5. 悬停阴影 hover:shadow-[0_8px_24px_-8px_rgba(var(--tool-color),0.14)] // 6. 箭头悬停色 group-hover:text-[rgb(var(--tool-color))] ``` **注意**：工具色彩仅用于**标识和装饰**，不得用于功能性色彩（如成功/错误状态）。 --- ## 10. 代码规范 ### 10.1 Tailwind 类名组织顺序 使用 `cn()` 工具函数（`clsx` + `tailwind-merge`）组合类名，按以下顺序排列： ```tsx className={cn( // 1. 布局（display, position, flex, grid） 'flex items-center justify-between', // 2. 尺寸（width, height, padding, margin） 'w-full h-10 px-4', // 3. 外观（background, border, shadow, rounded） 'rounded-md border border-input bg-background shadow-sm', // 4. 文字（color, font, text-align） 'text-sm font-medium text-foreground', // 5. 交互（hover, focus, disabled, cursor） 'hover:bg-accent focus-visible:ring-2 disabled:opacity-50', // 6. 动画（transition, animate） 'transition-colors duration-150', // 7. 条件类 isActive && 'bg-primary text-primary-foreground', // 8. 外部传入 className, )} ``` ### 10.2 颜色使用检查清单 - [ ] 所有颜色使用 CSS 变量（`bg-background` 而非 `bg-white`） - [ ] 边框使用 `border-border` 及其透明度变体 - [ ] 文字层级使用 `foreground` → `muted-foreground` → `muted-foreground/60` - [ ] 错误状态使用 `destructive` 系列 - [ ] 工具色彩仅用于装饰性元素 ### 10.3 组件文件组织 ``` src/ ├── components/ui/ # shadcn 基础组件（只读，不修改） ├── components/ # 业务组件 │ ├── CopyButton.tsx │ ├── SwitchButtonGroup.tsx │ ├── TextInputArea.tsx │ └── ... ├── pages/ # 页面组件 │ ├── / │ │ ├── index.tsx # 页面入口 │ │ ├── use.ts # 业务逻辑 Hook │ │ └── components/ # 页面私有组件 │ └── ... └── providers/ # Context Providers ``` ### 10.4 新增页面模板 ```tsx // src/pages/NewTool/index.tsx import SwitchButtonGroup from '@/components/SwitchButtonGroup'; import { useI18n } from '@/utils/chromeI18n'; import { cn } from '@/lib/utils'; export default function Index() { const { t } = useI18n('newTool'); return (
{/* 页面内容 */}

{t('newTool:title')}

); } ``` --- ## 11. 反模式清单 以下模式**禁止**在项目中使用： ### 11.1 色彩反模式 ```tsx // ❌ 硬编码颜色
// ❌ 使用非语义化 Tailwind 颜色
// ✅ 使用 CSS 变量
``` ### 11.2 布局反模式 ```tsx // ❌ 固定高度导致内容截断
// ✅ 使用 min-height 或自适应
// ❌ 使用 margin 做组件间距
// ✅ 使用 gap
``` ### 11.3 组件反模式 ```tsx // ❌ 修改 shadcn/ui 基础组件样式 // 如需修改，通过 className 覆盖或创建包装组件 // ❌ 内联样式用于颜色（工具色彩除外）
// ❌ 混合使用不同圆角体系