LingandRX
36b6bfd20d
* feat: 生成成功改为 toast 提示 * refactor: 数据预览改为显示示例数据，简化组件逻辑 * fix: 非必填字段预览显示 null * fix: 修复空值率与必填状态的逻辑 * fix: 切换为非必填时默认空值率 100% * feat: 字段编辑弹窗添加「完成」按钮 去除关闭按钮，添加取消按钮 * refactor: 删除未使用的 defaultNullRate 功能 * feat: 优化规则管理功能 * fix: 更新 features 测试断言以匹配新增的 testDataGenerator * refactor: 将 formatFileSize 重命名为 formatBytes 并移至通用工具模块 * refactor: 使用 Label 组件替换原生 label 元素，并在 DecodeResultPaper 中引入 Input 组件 * refactor: 规范化页面组件目录结构 * refactor(JsonTools): 规范化页面组件目录结构 * refactor(StorageCleaner): 规范化页面组件目录结构 * refactor(Timestamp): 规范化页面组件目录结构 * refactor(i18n): 移除 chrome.i18n 国际化，统一使用中文硬编码 * refactor(AppRoot): 移除 RouterProvider 组件，直接渲染子组件 * fix(RouterProvider): 将 goBack 重命名为 goHome，修复跨窗同步 merge 不一致 * fix(ThemeModeProvider): 修复主题快照同步与首屏闪烁问题 * refactor: 将 UI 文案改为中文并优化相关逻辑 * refactor: 清理代码注释并优化组件结构 * feat(Dashboard): 重构仪表板功能组件和逻辑 * refactor: 更新功能键名称并移除 README 文件 * refactor: 重构 TopBar 组件并更新项目结构 * feat(TopBar): 添加搜索功能组件并优化结构 * refactor: 统一使用 Button 组件替换原有 button 元素 * feat: 添加 EmptyPlaceholder 组件并更新相关页面 * feat(TextStatistics): 引入 StatCard 组件以优化统计信息展示 * feat(Timestamp): 重构时间戳转换功能，新增 ConverterForm 组件 * feat(Jwt): 重构 JWT 组件，新增常量和结果视图 * refactor(RightClickRestorer): 用状态配置表简化页面 UI 结构 * fix(business): 修复 skewedRandom 函数中的数学计算错误 * refactor(ImageUploader): 移除预览 URL 相关逻辑并简化粘贴事件处理 * feat(TestDataGenerator): 更新规则编辑提示和警告显示逻辑 * refactor(CopyButton.test): 移除冗余测试用例 * refactor(RouterProvider, chromeStorage, useContextMenuData): 更新存储获取逻辑以移除默认值参数 * refactor(代码重复): 抽取共享工具函数与 UI 组件，消除多处重复实现 * fix(RouterProvider): 修复初始加载状态逻辑，确保在加载前不覆盖 chrome.storage * feat(TopBar): 添加搜索框快捷键提示功能及相关测试 * refactor(StorageCleaner): 移动 isRestrictedUrl 函数到独立模块并更新相关引用 * fix(StorageCleaner): 修复 IndexedDB 清理竞态、部分成功计数与刷新后状态同步 * fix: 修复路由初始化竞态、存储状态静默覆盖与存储清理误删 * refactor: 统一中文文案并简化组件结构，提升代码可读性 * refactor: 更新 Worker 消息类型以支持生成任务 ID * fix: 修复 ruleStorage 写入失败处理与 CopyButton 成功态样式
869 lines
26 KiB
Markdown
869 lines
26 KiB
Markdown
# 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 变量
|
||
<div className="bg-background text-foreground border-border">
|
||
|
||
// ✅ 正确：使用语义化色彩名
|
||
<Button className="bg-primary text-primary-foreground">
|
||
<span className="text-muted-foreground">
|
||
|
||
// ❌ 错误：硬编码颜色值
|
||
<div className="bg-white text-black">
|
||
<div className="bg-[#f1f5f9]">
|
||
```
|
||
|
||
### 2.3 语义化色彩使用场景
|
||
|
||
| 色彩 | 场景 |
|
||
| -------------------------- | -------------------------------- |
|
||
| `background` | 页面根背景 |
|
||
| `foreground` | 主标题、正文 |
|
||
| `muted-foreground` | 描述文字、占位符、次级标签 |
|
||
| `border` | 卡片边框、分割线、输入框边框 |
|
||
| `card` + `card-foreground` | 卡片容器及其内容 |
|
||
| `primary` | 主按钮、选中状态、关键操作 |
|
||
| `secondary` | 次级按钮、工具栏背景、标签页背景 |
|
||
| `destructive` | 错误提示、删除操作、验证失败 |
|
||
| `accent` | 悬停背景、下拉选中项 |
|
||
|
||
---
|
||
|
||
## 3. 排版规范
|
||
|
||
### 3.1 字体栈
|
||
|
||
项目使用系统默认字体栈（Tailwind 默认），**不引入自定义字体**。
|
||
|
||
```css
|
||
/* Tailwind 默认 sans-serif */
|
||
font-family:
|
||
ui-sans-serif,
|
||
system-ui,
|
||
-apple-system,
|
||
BlinkMacSystemFont,
|
||
'Segoe UI',
|
||
Roboto,
|
||
'Helvetica Neue',
|
||
Arial,
|
||
sans-serif;
|
||
|
||
/* 等宽字体用于代码/数据 */
|
||
font-family:
|
||
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
|
||
```
|
||
|
||
### 3.2 字号层级
|
||
|
||
| 层级 | 类名 | 大小 | 字重 | 用途 |
|
||
| --------- | ------------------------------------------------ | ---- | ------- | ---------------------- |
|
||
| 页面标题 | `text-base font-bold` | 16px | 700 | 页面主标题（极少使用） |
|
||
| 卡片标题 | `text-sm font-bold tracking-tight` | 14px | 700 | 卡片/区块标题 |
|
||
| 正文 | `text-sm` | 14px | 400 | 普通正文 |
|
||
| 次级文字 | `text-xs` | 12px | 400/500 | 描述、标签 |
|
||
| 微标签 | `text-[10px] font-bold uppercase tracking-wider` | 10px | 700 | 区域标签、分类标题 |
|
||
| 数据/代码 | `font-mono text-sm` | 14px | 400 | 时间戳、JSON、代码 |
|
||
|
||
### 3.3 排版模式
|
||
|
||
```tsx
|
||
// 区域标签（Section Label）— 最常用
|
||
<span className="text-[10px] font-bold text-muted-foreground/90 uppercase tracking-wider">
|
||
输出结果
|
||
</span>
|
||
|
||
// 卡片标题
|
||
<h4 className="font-bold text-sm tracking-tight text-foreground leading-snug">
|
||
标题文字
|
||
</h4>
|
||
|
||
// 描述文字
|
||
<p className="text-[11px] font-medium text-muted-foreground/90 leading-normal">
|
||
描述内容
|
||
</p>
|
||
|
||
// 数据展示
|
||
<span className="font-mono font-bold text-foreground text-sm tracking-tight tabular-nums">
|
||
1716950400000
|
||
</span>
|
||
```
|
||
|
||
### 3.4 行高与字间距
|
||
|
||
| 属性 | 值 | 场景 |
|
||
| ----------------- | -------- | ------------------ |
|
||
| `leading-none` | 1 | 单行数据、紧凑布局 |
|
||
| `leading-snug` | 1.375 | 标题、短文本 |
|
||
| `leading-relaxed` | 1.625 | 长文本、代码块 |
|
||
| `tracking-tight` | -0.025em | 标题、数据 |
|
||
| `tracking-wider` | 0.05em | 大写标签 |
|
||
|
||
---
|
||
|
||
## 4. 间距与布局
|
||
|
||
### 4.1 容器尺寸
|
||
|
||
```tsx
|
||
// Popup 模式（默认）
|
||
<div className="w-[400px] max-w-[400px] min-w-[400px] h-[600px] min-h-[600px]">
|
||
|
||
// Tab 模式（全屏自适应）
|
||
<div className="sm:w-screen sm:max-w-none sm:min-w-0 sm:h-screen sm:min-h-0">
|
||
```
|
||
|
||
### 4.2 间距节奏
|
||
|
||
| Token | 值 | 使用场景 |
|
||
| --------------- | ----------- | ------------------ |
|
||
| `p-3` / `p-3.5` | 12px / 14px | 页面内边距（紧凑） |
|
||
| `p-4` | 16px | 标准页面内边距 |
|
||
| `p-5` | 20px | 卡片内部填充 |
|
||
| `gap-2` | 8px | 紧凑元素间距 |
|
||
| `gap-3` | 12px | 标准元素间距 |
|
||
| `gap-4` | 16px | 区块间距 |
|
||
| `gap-6` | 24px | 大区块间距 |
|
||
|
||
### 4.3 布局模式
|
||
|
||
#### 页面布局
|
||
|
||
```tsx
|
||
// 标准页面结构
|
||
<div className="p-4 w-full flex flex-col space-y-4 min-h-[500px] select-none">{/* 页面内容 */}</div>
|
||
```
|
||
|
||
#### 卡片布局
|
||
|
||
```tsx
|
||
// 标准卡片
|
||
<div className="p-5 rounded-xl border border-border bg-card text-card-foreground shadow-sm">
|
||
{/* 卡片内容 */}
|
||
</div>
|
||
|
||
// 可聚焦卡片（含焦点环）
|
||
<div className="border border-border rounded-xl bg-card ... focus-within:ring-1 focus-within:ring-ring focus-within:border-ring">
|
||
```
|
||
|
||
#### 双栏网格
|
||
|
||
```tsx
|
||
// 响应式双栏
|
||
<div className="grid grid-cols-1 md:grid-cols-2 gap-4 items-stretch">
|
||
```
|
||
|
||
#### 工具卡片网格（Dashboard）
|
||
|
||
```tsx
|
||
// Dashboard 紧凑网格
|
||
<div className="grid grid-cols-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6 gap-2">
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 圆角与阴影
|
||
|
||
### 5.1 圆角体系
|
||
|
||
| Token | 值 | 使用元素 |
|
||
| -------------- | ------ | ---------------------- |
|
||
| `rounded-sm` | 2px | Checkbox、小标签 |
|
||
| `rounded-md` | 6px | 按钮、输入框、Select |
|
||
| `rounded-lg` | 8px | 搜索框、小卡片 |
|
||
| `rounded-xl` | 12px | 大卡片、面板、图标容器 |
|
||
| `rounded-full` | 9999px | 标签、Avatar |
|
||
|
||
### 5.2 阴影体系
|
||
|
||
| 级别 | 类名 | 用途 |
|
||
| ---- | --------------------- | ---------------------- |
|
||
| 无 | — | 静态元素 |
|
||
| 低 | `shadow-sm` | 卡片、输入框、按钮 |
|
||
| 中 | `shadow-lg` | 下拉菜单、浮层、Dialog |
|
||
| 动态 | 自定义 `shadow-[...]` | 卡片悬停时的彩色阴影 |
|
||
|
||
### 5.3 彩色阴影规范（工具卡片专用）
|
||
|
||
```tsx
|
||
// 工具卡片悬停阴影 — 必须使用 rgba 格式配合 CSS 变量
|
||
className="hover:shadow-[0_8px_24px_-8px_rgba(var(--tool-color),0.14)]
|
||
dark:hover:shadow-[0_8px_30px_-10px_rgba(var(--tool-color),0.25)]"
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 组件规范
|
||
|
||
### 6.1 Button
|
||
|
||
来源：`src/components/ui/button.tsx`
|
||
|
||
#### 变体
|
||
|
||
| 变体 | 类名 | 场景 |
|
||
| ------------- | -------------------------------------------- | ------------------ |
|
||
| `default` | `bg-primary text-primary-foreground` | 主操作 |
|
||
| `destructive` | `bg-destructive text-destructive-foreground` | 删除、危险操作 |
|
||
| `outline` | `border border-input bg-background` | 次级操作、取消 |
|
||
| `secondary` | `bg-secondary text-secondary-foreground` | 次要操作 |
|
||
| `ghost` | 仅悬停背景 | 图标按钮、低优先级 |
|
||
| `link` | 下划线文字 | 跳转链接 |
|
||
|
||
#### 尺寸
|
||
|
||
| 尺寸 | 高度 | 内边距 | 场景 |
|
||
| --------- | ------- | ----------- | -------- |
|
||
| `default` | 40px | `px-4 py-2` | 标准按钮 |
|
||
| `sm` | 36px | `px-3` | 紧凑按钮 |
|
||
| `lg` | 44px | `px-8` | 突出按钮 |
|
||
| `icon` | 40×40px | — | 图标按钮 |
|
||
|
||
#### 使用示例
|
||
|
||
```tsx
|
||
// 主操作
|
||
<Button>确认</Button>
|
||
|
||
// 图标按钮
|
||
<Button variant="ghost" size="icon">
|
||
<Copy className="h-4 w-4" />
|
||
</Button>
|
||
|
||
// 危险操作
|
||
<Button variant="destructive" size="sm">删除</Button>
|
||
```
|
||
|
||
### 6.2 Input
|
||
|
||
来源：`src/components/ui/input.tsx`
|
||
|
||
```tsx
|
||
// 标准输入框
|
||
<Input
|
||
className="font-mono font-semibold h-10 shadow-sm placeholder:text-muted-foreground/60 focus:bg-background"
|
||
/>
|
||
|
||
// 错误状态
|
||
<Input
|
||
className="border-destructive focus-visible:ring-destructive"
|
||
/>
|
||
```
|
||
|
||
**规范要点**：
|
||
|
||
- 高度统一为 `h-10`（40px）
|
||
- 等宽字体用于数据输入
|
||
- 占位符使用 `text-muted-foreground/60`
|
||
- 错误时边框变红并调整焦点环
|
||
|
||
### 6.3 SwitchButtonGroup
|
||
|
||
来源：`src/components/ui/switch.tsx`
|
||
|
||
```tsx
|
||
// 分段控制器
|
||
<SwitchButtonGroup
|
||
value={mode}
|
||
options={[
|
||
{ value: 'ts2dt', label: '转日期' },
|
||
{ value: 'dt2ts', label: '转时间戳' },
|
||
]}
|
||
onChange={setMode}
|
||
size="small"
|
||
/>
|
||
```
|
||
|
||
**规范要点**：
|
||
|
||
- 容器：`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
|
||
// 标准工具卡片结构
|
||
<div className="group relative rounded-xl border border-border/70 bg-card p-4 h-auto flex flex-col gap-3 shadow-sm">
|
||
{/* 上半部分：图标 + 标题 + 箭头 */}
|
||
<div className="flex items-center justify-between">
|
||
<div className="flex gap-3 items-center">
|
||
{/* 图标容器 */}
|
||
<div className="flex items-center justify-center w-10 h-10 rounded-xl bg-[rgba(var(--tool-color),0.08)] text-[rgb(var(--tool-color))]">
|
||
<Icon className="h-5 w-5" />
|
||
</div>
|
||
{/* 文字 */}
|
||
<div>
|
||
<h4 className="font-bold text-sm">标题</h4>
|
||
<p className="text-[11px] text-muted-foreground/90">描述</p>
|
||
</div>
|
||
</div>
|
||
<ChevronRight className="h-4 w-4" />
|
||
</div>
|
||
{/* 下半部分：预览区（可选） */}
|
||
<div className="mt-1 pt-3 border-t border-dashed border-border/80">{snapshot}</div>
|
||
</div>
|
||
```
|
||
|
||
### 6.5 TextInputArea
|
||
|
||
来源：`src/components/TextInputArea.tsx`
|
||
|
||
```tsx
|
||
// 多行文本输入区
|
||
<TextInputArea
|
||
value={input}
|
||
onChange={setInput}
|
||
placeholder="输入内容..."
|
||
showCount={true}
|
||
showClear={true}
|
||
allowCopy={true}
|
||
minRows={6}
|
||
maxRows={12}
|
||
/>
|
||
```
|
||
|
||
**规范要点**：
|
||
|
||
- 外容器：`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
|
||
// 对话框内容
|
||
<DialogContent className="sm:rounded-lg">
|
||
<DialogHeader>
|
||
<DialogTitle>标题</DialogTitle>
|
||
<DialogDescription>描述文字</DialogDescription>
|
||
</DialogHeader>
|
||
{/* 内容 */}
|
||
<DialogFooter>
|
||
<Button variant="outline">取消</Button>
|
||
<Button>确认</Button>
|
||
</DialogFooter>
|
||
</DialogContent>
|
||
```
|
||
|
||
### 6.7 Select
|
||
|
||
来源：`src/components/ui/select.tsx`
|
||
|
||
```tsx
|
||
<Select>
|
||
<SelectTrigger className="h-9 shadow-sm bg-background">
|
||
<SelectValue />
|
||
</SelectTrigger>
|
||
<SelectContent className="max-h-64">
|
||
<SelectItem className="text-xs font-semibold focus:bg-accent cursor-pointer">选项</SelectItem>
|
||
</SelectContent>
|
||
</Select>
|
||
```
|
||
|
||
### 6.8 Checkbox
|
||
|
||
来源：`src/components/ui/checkbox.tsx`
|
||
|
||
```tsx
|
||
// 标准复选框
|
||
<Checkbox className="h-4 w-4 rounded-sm border-primary data-[state=checked]:bg-primary" />
|
||
|
||
// 小型复选框（工具栏内）
|
||
<Checkbox className="h-3.5 w-3.5 rounded border-input data-[state=checked]:bg-primary shadow-sm" />
|
||
```
|
||
|
||
### 6.9 Badge
|
||
|
||
来源：`src/components/ui/badge.tsx`
|
||
|
||
| 变体 | 场景 |
|
||
| ------------- | ------------------ |
|
||
| `default` | 状态标签、分类 |
|
||
| `secondary` | 次要标签 |
|
||
| `destructive` | 错误标签 |
|
||
| `outline` | 可点击标签、筛选器 |
|
||
|
||
### 6.10 CopyButton
|
||
|
||
来源：`src/components/CopyButton.tsx`
|
||
|
||
```tsx
|
||
// 标准复制按钮
|
||
<CopyButton text={content} />
|
||
|
||
// 小型复制按钮
|
||
<CopyButton text={content} size="sm" className="h-7 w-7 rounded-md border" />
|
||
```
|
||
|
||
**规范要点**：
|
||
|
||
- 默认 `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<PaletteColorKey, string> = {
|
||
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 变量
|
||
<div style={{ ['--tool-color' as string]: rgbValues }}>
|
||
|
||
// 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/ # 页面组件
|
||
│ ├── <ToolName>/
|
||
│ │ ├── index.tsx # 页面入口
|
||
│ │ ├── use<ToolName>.ts # 业务逻辑 Hook
|
||
│ │ └── components/ # 页面私有组件
|
||
│ └── ...
|
||
└── providers/ # Context Providers
|
||
```
|
||
|
||
### 10.4 新增页面模板
|
||
|
||
```tsx
|
||
// src/pages/NewTool/index.tsx
|
||
import SwitchButtonGroup from '@/components/SwitchButtonGroup';
|
||
import { cn } from '@/lib/utils';
|
||
|
||
export default function Index() {
|
||
return (
|
||
<div className="p-4 w-full flex flex-col space-y-4 select-none">
|
||
{/* 页面内容 */}
|
||
<div className="p-5 rounded-xl border border-border bg-card text-card-foreground shadow-sm">
|
||
<h4 className="font-bold text-sm tracking-tight">新工具</h4>
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 反模式清单
|
||
|
||
以下模式**禁止**在项目中使用：
|
||
|
||
### 11.1 色彩反模式
|
||
|
||
```tsx
|
||
// ❌ 硬编码颜色
|
||
<div className="bg-white text-black">
|
||
<div className="bg-gray-100">
|
||
<div className="text-gray-500">
|
||
|
||
// ❌ 使用非语义化 Tailwind 颜色
|
||
<div className="bg-slate-50">
|
||
<div className="text-zinc-400">
|
||
|
||
// ✅ 使用 CSS 变量
|
||
<div className="bg-background text-foreground">
|
||
<div className="bg-muted text-muted-foreground">
|
||
```
|
||
|
||
### 11.2 布局反模式
|
||
|
||
```tsx
|
||
// ❌ 固定高度导致内容截断
|
||
<div className="h-[200px]">
|
||
|
||
// ✅ 使用 min-height 或自适应
|
||
<div className="min-h-[200px]">
|
||
<div className="h-auto">
|
||
|
||
// ❌ 使用 margin 做组件间距
|
||
<div className="mb-4">
|
||
|
||
// ✅ 使用 gap
|
||
<div className="flex flex-col gap-4">
|
||
```
|
||
|
||
### 11.3 组件反模式
|
||
|
||
```tsx
|
||
// ❌ 修改 shadcn/ui 基础组件样式
|
||
// 如需修改，通过 className 覆盖或创建包装组件
|
||
|
||
// ❌ 内联样式用于颜色（工具色彩除外）
|
||
<div style={{ backgroundColor: '#f1f5f9' }}>
|
||
|
||
// ❌ 混合使用不同圆角体系
|
||
<Button className="rounded-lg"> // Button 应为 rounded-md
|
||
|
||
// ❌ 忽略焦点状态
|
||
<button className="..."> // 缺少 focus-visible 样式
|
||
```
|
||
|
||
### 11.4 暗色模式反模式
|
||
|
||
```tsx
|
||
// ❌ 仅适配部分元素
|
||
<div className="bg-white text-black dark:bg-gray-900 dark:text-white">
|
||
|
||
// ✅ 使用 CSS 变量自动适配
|
||
<div className="bg-background text-foreground">
|
||
|
||
// ❌ 暗色模式下使用不合适的透明度
|
||
<div className="bg-black/5 dark:bg-white/5"> // 对比度不足
|
||
|
||
// ✅ 使用语义化变量
|
||
<div className="bg-muted">
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 附录
|
||
|
||
### 12.1 常用类名速查
|
||
|
||
```
|
||
// 页面容器
|
||
p-4 w-full flex flex-col space-y-4 min-h-[500px] select-none
|
||
|
||
// 标准卡片
|
||
p-5 rounded-xl border border-border bg-card text-card-foreground shadow-sm
|
||
|
||
// 工具栏
|
||
flex h-10 items-center justify-between px-1.5 bg-secondary/40 rounded-xl border border-border/60
|
||
|
||
// 区域标签
|
||
text-[10px] font-bold text-muted-foreground/90 uppercase tracking-wider
|
||
|
||
// 数据展示
|
||
font-mono font-semibold text-foreground text-sm
|
||
|
||
// 错误提示
|
||
text-xs font-medium text-destructive
|
||
|
||
// 空状态
|
||
p-8 rounded-xl bg-muted/30 border border-dashed border-border/80 text-center
|
||
|
||
// 图标按钮容器
|
||
flex h-8 w-8 items-center justify-center rounded-md border border-input bg-background shadow-sm
|
||
|
||
// 焦点环
|
||
focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2
|
||
```
|
||
|
||
### 12.2 相关文件
|
||
|
||
| 文件 | 说明 |
|
||
| ------------------------------------- | ----------------------- |
|
||
| `src/index.css` | CSS 变量定义、全局样式 |
|
||
| `tailwind.config.js` | Tailwind 配置、色彩映射 |
|
||
| `src/lib/utils.ts` | `cn()` 工具函数 |
|
||
| `src/components/ui/*.tsx` | shadcn/ui 基础组件 |
|
||
| `src/config/features.tsx` | 工具配置、色彩分配 |
|
||
| `src/providers/ThemeModeProvider.tsx` | 主题模式管理 |
|
||
|
||
### 12.3 参考资源
|
||
|
||
- [shadcn/ui 文档](https://ui.shadcn.com/docs)
|
||
- [Tailwind CSS 文档](https://tailwindcss.com/docs)
|
||
- [Radix UI 文档](https://www.radix-ui.com/)
|
||
- [Lucide Icons](https://lucide.dev/)
|
||
|
||
---
|
||
|
||
_本文档随项目迭代更新。新增组件或修改视觉风格时，请同步更新此文档。_
|