From f8c48a3047d2b906335f02352bf1ebc21c1bdef0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=A8=E9=9C=96=E9=93=83?= Date: Fri, 29 May 2026 19:51:44 +0800 Subject: [PATCH] docs: add comprehensive visual style guide Add VISUAL_STYLE_GUIDE.md to standardize UI development: - Design principles and keywords - Complete color system (CSS variables, semantic usage) - Typography hierarchy and patterns - Spacing, layout, and container specs - Border radius and shadow system - Component specs (Button, Input, Card, Dialog, etc.) - Interaction and animation guidelines - Dark mode implementation rules - Tool color palette and assignment - Code organization standards - Anti-patterns checklist - Quick reference appendix Update .gitignore to allow tracking the style guide. --- .gitignore | 1 + docs/VISUAL_STYLE_GUIDE.md | 871 +++++++++++++++++++++++++++++++++++++ 2 files changed, 872 insertions(+) create mode 100644 docs/VISUAL_STYLE_GUIDE.md diff --git a/.gitignore b/.gitignore index d22059f..c5eb473 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,4 @@ stats-*.json dev/* docs/* +!docs/VISUAL_STYLE_GUIDE.md diff --git a/docs/VISUAL_STYLE_GUIDE.md b/docs/VISUAL_STYLE_GUIDE.md new file mode 100644 index 0000000..ceb8169 --- /dev/null +++ b/docs/VISUAL_STYLE_GUIDE.md @@ -0,0 +1,871 @@ +# 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 覆盖或创建包装组件 + +// ❌ 内联样式用于颜色（工具色彩除外） +
+ +// ❌ 混合使用不同圆角体系 +