argon-theme/.kiro/specs/loading-animation-cleanup/design.md

# 加载动画系统清理与文本效果修复 - 设计文档

## 1. 架构概述

本次优化分为两个独立模块：
1. **加载动画清理模块**：移除旧代码，统一使用 `PageLoader`
2. **文本效果修复模块**：为文本特效添加文章容器选择器支持

## 2. 加载动画清理设计

### 2.1 问题分析

**旧代码位置**：`argontheme.js` 第 4970-5040 行

**旧代码特征**：
- 使用 `article-loading-overlay` ID
- 手动创建 DOM 元素和骨架屏 HTML
- 使用 `setInterval` 模拟进度
- 监听 `window.load` 事件
- PJAX 事件处理中重复创建相同元素

**新系统特征**：
- 使用 `PageLoader` 模块（IIFE 封装）
- 统一的 `loading-*` 类名前缀
- SVG 圆环进度指示器
- 智能进度算法（缓动函数）
- 延迟显示和最小显示时间控制

### 2.2 清理策略

#### 2.2.1 页面初始加载
**旧代码**（需移除）：
```javascript
// 第 4970-4995 行
var bar = document.getElementById('page-loading-bar');
// ... 创建 article-loading-overlay ...
window.addEventListener('load', function() { ... });
```

**新方案**：
- 在 `DOMContentLoaded` 时调用 `PageLoader.show()`
- 在 `window.load` 时调用 `PageLoader.hide()`
- 已在现有代码中实现，无需修改

#### 2.2.2 PJAX 加载动画
**旧代码**（需移除）：
```javascript
// 第 4997-5033 行
function initPjaxAnimations() {
    jQuery(document).on('pjax:start', function() {
        // ... 创建 article-loading-overlay ...
    });
    jQuery(document).on('pjax:end', function() {
        // ... 移除 overlay ...
    });
}
```

**新方案**：
- `pjax:start` 时调用 `PageLoader.show()`
- `pjax:end` 时调用 `PageLoader.hide()`
- 需要新增此部分代码

### 2.3 实现步骤

1. **定位旧代码**：确认第 4970-5040 行的完整范围
2. **移除旧代码**：删除整个旧的加载动画实现
3. **添加 PJAX 支持**：在 `PageLoader` 模块后添加 PJAX 事件监听
4. **测试验证**：确保页面加载和 PJAX 导航都正常

### 2.4 新增 PJAX 集成代码

```javascript
// PJAX 加载动画集成
if (typeof jQuery !== 'undefined') {
	jQuery(document).on('pjax:start', function() {
		PageLoader.show();
	});
	
	jQuery(document).on('pjax:end', function() {
		PageLoader.hide();
		// 重新初始化页面动画
		setTimeout(function() {
			initImageLoadAnimation();
			initScrollAnimations();
			initSmoothScroll();
		}, 100);
	});
}
```

## 3. 文本效果修复设计

### 3.1 问题分析

**当前样式选择器**：
```css
.color-curtain { ... }
.text-blur { ... }
.huhua { ... }
```

**问题**：
- 缺少文章容器选择器（`article .entry-content`、`.article-content`）
- 在某些文章布局中可能不生效

### 3.2 修复策略

参考黑幕样式的修复方式，为每个文本效果添加文章容器选择器。

#### 3.2.1 彩色黑幕（color-curtain）

**当前样式**：
```css
.color-curtain, .color-curtain a, a .color-curtain, .color-curtain a.new {
    background-color: var(--curtain-bg, #252525) !important;
    color: var(--curtain-bg, #252525) !important;
    /* ... */
}
```

**修复方案**：
```css
/* 基础样式 */
.color-curtain,
article .entry-content .color-curtain,
.article-content .color-curtain {
    background-color: var(--curtain-bg, #252525) !important;
    color: var(--curtain-bg, #252525) !important;
    /* ... */
}

/* 链接样式 */
.color-curtain a,
article .entry-content .color-curtain a,
.article-content .color-curtain a {
    color: inherit !important;
    /* ... */
}

/* 悬停样式 */
.color-curtain:hover,
article .entry-content .color-curtain:hover,
.article-content .color-curtain:hover {
    color: var(--curtain-fg, #fff) !important;
}
```

**夜间模式优化**：
```css
html.darkmode .color-curtain,
html.darkmode article .entry-content .color-curtain,
html.darkmode .article-content .color-curtain {
    --curtain-bg: #1a1a1a;
    --curtain-fg: #e0e0e0;
}
```

#### 3.2.2 模糊文本（text-blur）

**当前样式**：
```css
.text-blur, .text-blur a, a .text-blur, .text-blur a.new {
    filter: blur(2px) !important;
    /* ... */
}
```

**修复方案**：
```css
.text-blur,
article .entry-content .text-blur,
.article-content .text-blur {
    filter: blur(2px) !important;
    transition: filter var(--text-blur-transition-time, .2s) ease;
    display: inline-block;
}

.text-blur:hover,
article .entry-content .text-blur:hover,
.article-content .text-blur:hover {
    filter: none !important;
}
```

#### 3.2.3 划掉文本（huhua）

**当前样式**：
```css
.huhua {
    color: #9ea3a9 !important;
    text-decoration: line-through !important;
    /* ... */
}
```

**修复方案**：
```css
.huhua,
article .entry-content .huhua,
.article-content .huhua {
    color: #9ea3a9 !important;
    text-decoration: line-through !important;
    text-shadow: none !important;
    transition: color .2s ease;
}

.huhua:hover,
article .entry-content .huhua:hover,
.article-content .huhua:hover {
    color: #7f858b !important;
}
```

**夜间模式优化**：
```css
html.darkmode .huhua,
html.darkmode article .entry-content .huhua,
html.darkmode .article-content .huhua {
    color: #6a7075 !important;
}

html.darkmode .huhua:hover,
html.darkmode article .entry-content .huhua:hover,
html.darkmode .article-content .huhua:hover {
    color: #555a5f !important;
}
```

### 3.3 代码组织

在 `style.css` 中重新组织文本效果样式：

```
/* ==========================================================================
   文章文本特效（Text Effects in Articles）
   ========================================================================== */

/* ---------- 彩色黑幕（Color Curtain） ---------- */
/* 基础样式 */
/* 链接样式 */
/* 悬停样式 */
/* 夜间模式 */

/* ---------- 模糊文本（Text Blur） ---------- */
/* 基础样式 */
/* 悬停样式 */

/* ---------- 划掉文本（Strikethrough） ---------- */
/* 基础样式 */
/* 悬停样式 */
/* 夜间模式 */
```

## 4. 正确性属性（Correctness Properties）

### 4.1 加载动画属性

**Property 1.1**: 页面加载时必须显示加载动画
- **验证方式**：刷新页面，观察是否出现 SVG 圆环进度指示器
- **预期行为**：`DOMContentLoaded` 后显示，`window.load` 后隐藏

**Property 1.2**: PJAX 导航时必须显示加载动画
- **验证方式**：点击文章链接，观察是否出现加载动画
- **预期行为**：`pjax:start` 后显示，`pjax:end` 后隐藏

**Property 1.3**: 不存在旧的 `article-loading-overlay` 元素
- **验证方式**：检查 DOM 树和控制台
- **预期行为**：只有 `loading-overlay` 元素，无 `article-loading-overlay`

### 4.2 文本效果属性

**Property 2.1**: 文本效果在文章中可见
- **验证方式**：在文章中添加 `<span class="color-curtain">测试</span>`
- **预期行为**：文本被彩色背景遮盖

**Property 2.2**: 悬停时文本效果正确响应
- **验证方式**：鼠标悬停在文本效果上
- **预期行为**：
  - `color-curtain`：显示文本内容
  - `text-blur`：取消模糊
  - `huhua`：颜色变深

**Property 2.3**: 夜间模式下颜色正确
- **验证方式**：切换到夜间模式，检查文本效果颜色
- **预期行为**：使用夜间模式专用颜色变量

## 5. 测试策略

### 5.1 单元测试（手动）

1. **页面初始加载**
   - 刷新页面
   - 观察加载动画是否正常显示和隐藏
   - 检查控制台是否有错误

2. **PJAX 导航**
   - 点击文章链接
   - 观察加载动画是否正常显示和隐藏
   - 检查页面内容是否正确更新

3. **文本效果显示**
   - 在文章编辑器中添加测试内容：
     ```html
     <span class="color-curtain">彩色黑幕测试</span>
     <span class="text-blur">模糊文本测试</span>
     <span class="huhua">划掉文本测试</span>
     ```
   - 发布文章并查看效果

4. **文本效果交互**
   - 鼠标悬停在每个文本效果上
   - 验证交互行为是否正确

5. **夜间模式**
   - 切换到夜间模式
   - 重复步骤 3 和 4

### 5.2 回归测试

- 验证其他页面功能未受影响
- 验证移动端响应式布局正常
- 验证浏览器兼容性（Chrome、Firefox、Safari、Edge）

## 6. 风险评估

### 6.1 高风险
- **PJAX 功能失效**：移除旧代码可能影响 PJAX 导航
  - **缓解措施**：仔细测试 PJAX 导航，确保新代码正确集成

### 6.2 中风险
- **样式冲突**：新增选择器可能与现有样式冲突
  - **缓解措施**：使用 `!important` 确保优先级，参考黑幕样式的成功经验

### 6.3 低风险
- **性能影响**：新增选择器可能轻微影响 CSS 性能
  - **缓解措施**：选择器数量有限，影响可忽略

## 7. 实施计划

### Phase 1: 清理旧加载动画代码
1. 备份 `argontheme.js`
2. 移除第 4970-5040 行旧代码
3. 添加 PJAX 集成代码
4. 测试页面加载和 PJAX 导航

### Phase 2: 修复文本效果样式
1. 备份 `style.css`
2. 重构 `color-curtain` 样式
3. 重构 `text-blur` 样式
4. 重构 `huhua` 样式
5. 添加夜间模式优化
6. 测试所有文本效果

### Phase 3: 验证和提交
1. 完整回归测试
2. 检查代码规范
3. 编写详细的 Git commit 信息
4. 提交代码

## 8. 成功标准

- ✅ 旧加载动画代码完全移除
- ✅ 页面加载和 PJAX 导航动画正常工作
- ✅ 所有文本效果在文章中正常显示和交互
- ✅ 夜间模式下颜色正确
- ✅ 无控制台错误或警告
- ✅ 代码遵循项目规范
- ✅ Git commit 信息详细清晰