## Context

当前 `TimePeriodTabs` 组件使用了自定义的透明背景和半透明灰色样式,与 pencli 设计文件 (`.pans/v2.pen`, 节点 NDWwE) 中定义的视觉规范不一致。设计稿采用了更清晰的视觉层次:浅灰色背景容器包裹着三个标签,激活态使用白色背景突出显示。此外,当前实现缺乏暗色主题的适配。

**技术栈:**
- Vue 3 Composition API (`<script setup>`)
- SCSS 样式 (基于 CSS 变量的主题系统)
- 主题系统: `Web/src/assets/theme.css`

**设计规范来源:**
- `.pans/v2.pen` 节点 NDWwE (TabsWrapper)
  - 容器: padding `[8, 24]`, 垂直布局
  - SegmentedControl (节点 4iQfn): 
    - 背景 `#F4F4F5`, 圆角 `8px`, padding `4px`, gap `4px`, height `40px`
  - 激活态标签 (节点 LN1iU): 
    - 背景 `#FFFFFF`, 圆角 `6px`, 文字颜色 `#1A1A1A`, 字重 `600`
  - 非激活态标签 (节点 7LCL4, 7VSH1): 
    - 背景透明, 圆角 `6px`, 文字颜色 `#6B7280`, 字重 `500`

## Goals / Non-Goals

**Goals:**
- 完全符合 pencli 设计规范的视觉样式
- 支持亮色和暗色两种主题,保持良好的对比度和可读性
- 保持组件 API 不变,不影响现有使用方式
- 激活态具有明确的视觉反馈

**Non-Goals:**
- 不修改组件的交互逻辑或事件处理
- 不改变组件的 props 或 emits 接口
- 不添加新功能(如动画效果或手势支持)

## Decisions

### 决策 1: 直接使用 CSS 变量而非硬编码颜色

**选择:** 在 `theme.css` 中定义新的语义化 CSS 变量 `--segmented-bg` 和 `--segmented-active-bg`

**理由:**
- 项目已有成熟的 CSS 变量主题系统 (`Web/src/assets/theme.css`)
- 使用变量可以自动适配暗色主题,无需在组件中使用 `v-if` 判断
- 便于后续统一调整分段控制器样式
- 符合项目现有的样式管理模式

**备选方案 (未采用):**
- ~~硬编码颜色值~~ - 无法适配暗色主题
- ~~使用 computed 动态计算颜色~~ - 增加不必要的 JS 逻辑

### 决策 2: 暗色主题映射策略

**选择:** 暗色主题使用以下映射:
- 容器背景: `#27272a` (对应浅色的 `#F4F4F5`)
- 激活态背景: `#3f3f46` (对应浅色的 `#FFFFFF`)
- 激活态文字: `#f4f4f5` (对应浅色的 `#1A1A1A`)
- 非激活态文字: `#a1a1aa` (对应浅色的 `#6B7280`)

**理由:**
- 保持与现有深色主题色板 (`--bg-tertiary`, `--border-color`) 的一致性
- 确保 WCAG AA 级别的对比度标准(激活态文字对比度 > 4.5:1)
- 视觉层次清晰,激活态明显突出

**备选方案 (未采用):**
- ~~完全反转亮色主题颜色~~ - 对比度不足,可读性差
- ~~使用蓝色或其他强调色~~ - 与设计稿的中性灰色调不符

### 决策 3: 保留现有的 hover 和过渡效果

**选择:** 保留 `transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1)` 和 hover 状态

**理由:**
- 提升交互体验,符合现代 UI 设计规范
- 设计稿未明确禁止过渡效果
- 与应用其他组件的交互风格保持一致

## Risks / Trade-offs

### 风险 1: 新增 CSS 变量可能与未来设计稿冲突

**风险:** 如果后续设计稿为分段控制器定义了不同的颜色变量,可能需要重新调整

**缓解措施:**
- 使用语义化命名 (`--segmented-*`),明确变量用途
- 在 `theme.css` 中添加注释标注变量来源 (`/* From .pans/v2.pen NDWwE */`)

### 风险 2: 暗色主题对比度可能不够理想

**风险:** 在某些设备或环境光下,暗色主题的激活态可能不够明显

**缓解措施:**
- 使用 Chrome DevTools 的对比度检查工具验证
- 添加微妙的阴影效果增强视觉分离 (`box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3)`)

### 权衡: 放弃完全像素级还原设计稿字体

**权衡:** 设计稿使用 `DM Sans` 字体,但项目中可能未全局加载该字体

**决策:** 依赖 `--font-primary` 变量,由主题系统统一管理字体回退

**影响:** 在未加载 `DM Sans` 的环境下,会回退到系统字体,视觉效果略有差异,但可接受

## Migration Plan

**部署步骤:**
1. 更新 `theme.css`,添加新的 CSS 变量
2. 更新 `TimePeriodTabs.vue` 组件样式
3. 验证浏览器兼容性 (Chrome, Safari, Firefox)
4. 在亮色和暗色主题下分别测试视觉效果

**回滚策略:**
- 如发现严重视觉问题,可通过 Git 回滚单个文件
- CSS 变量的添加不会破坏现有样式,可以安全回滚

**影响范围:**
- 仅影响统计 v2 页面的时间段选择器组件
- 无 API 变更,无需后端配合

## Open Questions

无待解决问题。设计规范已明确,实现路径清晰。