nanhaoluo
31d8fde308
- 基于Argon主题的WordPress博客主题 - 支持响应式设计和暗色模式 - 包含完整的文章管理和评论系统 - 集成友情链接管理功能 - 支持多种自定义设置选项 - 优化的用户界面和交互体验
439 lines
13 KiB
Markdown
439 lines
13 KiB
Markdown
# Design Document: Global UI Optimization
|
||
|
||
## Overview
|
||
|
||
本设计文档描述 Argon WordPress 主题的全局 UI 优化方案，参考 Apple Human Interface Guidelines 和 Material Design 3 设计规范。优化重点包括：按钮样式现代化、设置面板重构、分享按钮动画增强、评论展开动画优化，以及新增多种设计风格选项。
|
||
|
||
## Architecture
|
||
|
||
### 设计系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ CSS Variables Layer │
|
||
│ (动画时长、缓动函数、颜色、圆角、阴影等设计令牌) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Base Components Layer │
|
||
│ (按钮、卡片、输入框等基础组件样式) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Feature Components Layer │
|
||
│ (设置面板、分享按钮、评论切换等功能组件) │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ Theme Variants Layer │
|
||
│ (玻璃拟态、新拟态、Material 3 等主题变体) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 文件结构
|
||
|
||
```
|
||
style.css # 主样式文件（修改）
|
||
argontheme.js # 主脚本文件（修改）
|
||
template-parts/
|
||
└── post-actions.php # 文章操作按钮模板（修改）
|
||
```
|
||
|
||
## Components and Interfaces
|
||
|
||
### 1. 动画系统 CSS 变量
|
||
|
||
```css
|
||
:root {
|
||
/* 动画时长 */
|
||
--animation-fast: 150ms;
|
||
--animation-normal: 250ms;
|
||
--animation-slow: 400ms;
|
||
--animation-slower: 600ms;
|
||
|
||
/* 缓动函数 - Material 3 标准 */
|
||
--ease-standard: cubic-bezier(0.2, 0, 0, 1);
|
||
--ease-standard-decelerate: cubic-bezier(0, 0, 0, 1);
|
||
--ease-standard-accelerate: cubic-bezier(0.3, 0, 1, 1);
|
||
--ease-emphasized: cubic-bezier(0.2, 0, 0, 1);
|
||
--ease-emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1);
|
||
--ease-emphasized-accelerate: cubic-bezier(0.3, 0, 0.8, 0.15);
|
||
|
||
/* 弹性缓动 */
|
||
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
|
||
--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
|
||
|
||
/* 状态层透明度 - Material 3 */
|
||
--state-hover-opacity: 0.08;
|
||
--state-focus-opacity: 0.12;
|
||
--state-pressed-opacity: 0.12;
|
||
--state-dragged-opacity: 0.16;
|
||
}
|
||
```
|
||
|
||
### 2. 按钮组件设计
|
||
|
||
#### 主要按钮 (Filled Button)
|
||
```css
|
||
.btn-primary {
|
||
background-color: var(--themecolor);
|
||
border: none;
|
||
border-radius: var(--card-radius);
|
||
box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
|
||
transition:
|
||
background-color var(--animation-fast) var(--ease-standard),
|
||
box-shadow var(--animation-fast) var(--ease-standard),
|
||
transform var(--animation-fast) var(--ease-standard);
|
||
position: relative;
|
||
overflow: hidden;
|
||
}
|
||
|
||
.btn-primary:hover {
|
||
background-color: var(--themecolor-dark);
|
||
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.15);
|
||
}
|
||
|
||
.btn-primary:active {
|
||
background-color: var(--themecolor-dark2);
|
||
transform: scale(0.98);
|
||
}
|
||
```
|
||
|
||
#### 涟漪效果 (Ripple Effect)
|
||
```css
|
||
.btn-ripple {
|
||
position: relative;
|
||
overflow: hidden;
|
||
}
|
||
|
||
.btn-ripple::after {
|
||
content: '';
|
||
position: absolute;
|
||
width: 100%;
|
||
height: 100%;
|
||
top: 0;
|
||
left: 0;
|
||
pointer-events: none;
|
||
background-image: radial-gradient(circle, rgba(255,255,255,0.3) 10%, transparent 10.01%);
|
||
background-repeat: no-repeat;
|
||
background-position: 50%;
|
||
transform: scale(10, 10);
|
||
opacity: 0;
|
||
transition: transform var(--animation-slow), opacity var(--animation-normal);
|
||
}
|
||
|
||
.btn-ripple:active::after {
|
||
transform: scale(0, 0);
|
||
opacity: 1;
|
||
transition: 0s;
|
||
}
|
||
```
|
||
|
||
### 3. 设置面板设计
|
||
|
||
#### 面板容器
|
||
```css
|
||
#fabtn_blog_settings_popup {
|
||
background: var(--color-foreground);
|
||
border-radius: 16px;
|
||
box-shadow:
|
||
0 8px 32px rgba(0, 0, 0, 0.12),
|
||
0 2px 8px rgba(0, 0, 0, 0.08);
|
||
padding: 16px 20px;
|
||
backdrop-filter: blur(20px);
|
||
-webkit-backdrop-filter: blur(20px);
|
||
}
|
||
```
|
||
|
||
#### 分段控件 (Segmented Control)
|
||
```css
|
||
.segmented-control {
|
||
display: inline-flex;
|
||
background: var(--color-widgets-disabled);
|
||
border-radius: 10px;
|
||
padding: 3px;
|
||
gap: 2px;
|
||
}
|
||
|
||
.segmented-control-item {
|
||
padding: 6px 14px;
|
||
border-radius: 8px;
|
||
border: none;
|
||
background: transparent;
|
||
color: var(--color-text-deeper);
|
||
font-size: 13px;
|
||
font-weight: 500;
|
||
cursor: pointer;
|
||
transition: all var(--animation-fast) var(--ease-standard);
|
||
}
|
||
|
||
.segmented-control-item.active {
|
||
background: var(--themecolor);
|
||
color: #fff;
|
||
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.15);
|
||
}
|
||
```
|
||
|
||
### 4. 分享按钮动画设计
|
||
|
||
#### 容器样式
|
||
```css
|
||
#share_container {
|
||
position: relative;
|
||
display: inline-flex;
|
||
align-items: center;
|
||
}
|
||
|
||
#share {
|
||
display: flex;
|
||
gap: 6px;
|
||
position: absolute;
|
||
right: 0;
|
||
top: 50%;
|
||
transform: translateY(-50%);
|
||
opacity: 0;
|
||
pointer-events: none;
|
||
}
|
||
|
||
#share > a {
|
||
opacity: 0;
|
||
transform: scale(0.8) translateX(10px);
|
||
}
|
||
```
|
||
|
||
#### 展开动画
|
||
```css
|
||
#share_container.opened #share {
|
||
opacity: 1;
|
||
pointer-events: auto;
|
||
}
|
||
|
||
#share_container.opened #share > a {
|
||
opacity: 1;
|
||
transform: scale(1) translateX(0);
|
||
transition:
|
||
opacity var(--animation-normal) var(--ease-emphasized-decelerate),
|
||
transform var(--animation-normal) var(--ease-spring);
|
||
}
|
||
|
||
/* 错落动画延迟 */
|
||
#share_container.opened #share > a:nth-child(1) { transition-delay: 0ms; }
|
||
#share_container.opened #share > a:nth-child(2) { transition-delay: 30ms; }
|
||
#share_container.opened #share > a:nth-child(3) { transition-delay: 60ms; }
|
||
#share_container.opened #share > a:nth-child(4) { transition-delay: 90ms; }
|
||
#share_container.opened #share > a:nth-child(5) { transition-delay: 120ms; }
|
||
#share_container.opened #share > a:nth-child(6) { transition-delay: 150ms; }
|
||
#share_container.opened #share > a:nth-child(7) { transition-delay: 180ms; }
|
||
#share_container.opened #share > a:nth-child(8) { transition-delay: 210ms; }
|
||
```
|
||
|
||
#### 主按钮变换
|
||
```css
|
||
#share_show {
|
||
transition:
|
||
transform var(--animation-normal) var(--ease-standard),
|
||
opacity var(--animation-normal) var(--ease-standard);
|
||
}
|
||
|
||
#share_container.opened #share_show {
|
||
transform: rotate(45deg) scale(0.9);
|
||
opacity: 0.7;
|
||
}
|
||
```
|
||
|
||
### 5. 评论展开动画设计
|
||
|
||
#### 评论区容器
|
||
```css
|
||
#comments, #post_comment {
|
||
transition:
|
||
max-height var(--animation-slow) var(--ease-emphasized),
|
||
opacity var(--animation-normal) var(--ease-standard),
|
||
margin var(--animation-slow) var(--ease-standard),
|
||
padding var(--animation-slow) var(--ease-standard);
|
||
overflow: hidden;
|
||
will-change: max-height, opacity;
|
||
}
|
||
|
||
#comments.comments-collapsed,
|
||
#post_comment.comments-collapsed {
|
||
max-height: 0 !important;
|
||
opacity: 0;
|
||
margin-top: 0 !important;
|
||
margin-bottom: 0 !important;
|
||
padding-top: 0 !important;
|
||
padding-bottom: 0 !important;
|
||
border: none !important;
|
||
}
|
||
|
||
#comments:not(.comments-collapsed),
|
||
#post_comment:not(.comments-collapsed) {
|
||
max-height: 9999px;
|
||
opacity: 1;
|
||
}
|
||
```
|
||
|
||
#### 切换按钮图标动画
|
||
```css
|
||
#comments_toggle .btn-inner--icon i {
|
||
transition: transform var(--animation-normal) var(--ease-spring);
|
||
}
|
||
|
||
#comments_toggle.expanded .btn-inner--icon i {
|
||
transform: rotate(180deg);
|
||
}
|
||
```
|
||
|
||
### 6. 主题变体设计
|
||
|
||
#### 玻璃拟态 (Glassmorphism)
|
||
```css
|
||
html.style-glass .card,
|
||
html.style-glass #fabtn_blog_settings_popup {
|
||
background: rgba(255, 255, 255, 0.7);
|
||
backdrop-filter: blur(20px) saturate(180%);
|
||
-webkit-backdrop-filter: blur(20px) saturate(180%);
|
||
border: 1px solid rgba(255, 255, 255, 0.3);
|
||
}
|
||
|
||
html.darkmode.style-glass .card,
|
||
html.darkmode.style-glass #fabtn_blog_settings_popup {
|
||
background: rgba(66, 66, 66, 0.7);
|
||
border: 1px solid rgba(255, 255, 255, 0.1);
|
||
}
|
||
```
|
||
|
||
#### 新拟态 (Neumorphism)
|
||
```css
|
||
html.style-neumorphism .card {
|
||
background: var(--color-background);
|
||
box-shadow:
|
||
8px 8px 16px rgba(0, 0, 0, 0.1),
|
||
-8px -8px 16px rgba(255, 255, 255, 0.8);
|
||
border: none;
|
||
}
|
||
|
||
html.darkmode.style-neumorphism .card {
|
||
box-shadow:
|
||
8px 8px 16px rgba(0, 0, 0, 0.3),
|
||
-8px -8px 16px rgba(255, 255, 255, 0.05);
|
||
}
|
||
```
|
||
|
||
## Data Models
|
||
|
||
### 设置存储结构
|
||
|
||
```javascript
|
||
// localStorage 存储的设置项
|
||
{
|
||
'Argon_UI_Style': 'default' | 'glass' | 'neumorphism',
|
||
'Argon_Animation_Reduced': 'true' | 'false',
|
||
'Argon_Use_Serif': 'true' | 'false',
|
||
'Argon_Use_Big_Shadow': 'true' | 'false',
|
||
'Argon_Filter': 'off' | 'sunset' | 'darkness' | 'grayscale'
|
||
}
|
||
```
|
||
|
||
|
||
|
||
## Correctness Properties
|
||
|
||
*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
||
|
||
### Property 1: 按钮使用纯色背景
|
||
|
||
*For any* 主要按钮元素（.btn-primary, #share .btn, #comments_toggle），其 background 属性应该使用纯色（var(--themecolor) 或具体颜色值），而不包含 gradient 关键字。
|
||
|
||
**Validates: Requirements 1.1, 3.6**
|
||
|
||
### Property 2: 组件使用主题色 CSS 变量
|
||
|
||
*For any* 使用主题色的组件（按钮、选中状态、链接等），其颜色相关属性应该使用 var(--themecolor) 或其派生变量（--themecolor-dark, --themecolor-light 等），而非硬编码的颜色值。
|
||
|
||
**Validates: Requirements 1.4, 2.3**
|
||
|
||
### Property 3: 动画系统 CSS 变量定义
|
||
|
||
*For any* 动画相关的 CSS 变量，:root 选择器中应该定义 --animation-fast, --animation-normal, --animation-slow 时长变量，以及 --ease-standard, --ease-emphasized, --ease-spring 等缓动函数变量。
|
||
|
||
**Validates: Requirements 5.1, 5.2**
|
||
|
||
### Property 4: 分享按钮错落动画延迟
|
||
|
||
*For any* 分享按钮容器中的子元素（#share > a），每个元素应该有递增的 transition-delay 值，形成错落有致的动画效果。
|
||
|
||
**Validates: Requirements 3.2**
|
||
|
||
### Property 5: 评论区过渡动画属性
|
||
|
||
*For any* 评论区容器（#comments, #post_comment），其 transition 属性应该包含 max-height 和 opacity，并使用 CSS 变量定义的动画时长。
|
||
|
||
**Validates: Requirements 4.1, 4.2, 4.4**
|
||
|
||
### Property 6: GPU 加速动画属性
|
||
|
||
*For any* 交互动画（悬停、点击、展开/收起），应该主要使用 transform 和 opacity 属性进行动画，而非 width, height, top, left 等触发重排的属性。
|
||
|
||
**Validates: Requirements 5.3**
|
||
|
||
### Property 7: 样式切换过渡动画
|
||
|
||
*For any* 主要容器元素（.card, #fabtn_blog_settings_popup），应该定义 transition 属性覆盖 background-color 和 box-shadow 的变化，以支持样式切换时的平滑过渡。
|
||
|
||
**Validates: Requirements 6.4**
|
||
|
||
## Error Handling
|
||
|
||
### CSS 兼容性处理
|
||
|
||
1. **backdrop-filter 不支持时的降级**
|
||
- 使用 @supports 查询检测支持情况
|
||
- 降级为纯色背景加透明度
|
||
|
||
2. **CSS 变量不支持时的降级**
|
||
- 在变量值前提供硬编码的回退值
|
||
- 示例：`transition: all 250ms ease; transition: all var(--animation-normal) var(--ease-standard);`
|
||
|
||
3. **prefers-reduced-motion 处理**
|
||
- 检测用户偏好减少动画
|
||
- 将所有动画时长设为 0 或极短值
|
||
|
||
### JavaScript 错误处理
|
||
|
||
1. **localStorage 不可用**
|
||
- 使用 try-catch 包装存储操作
|
||
- 降级为内存存储或 cookie
|
||
|
||
2. **动画 API 不支持**
|
||
- 检测 Web Animations API 支持
|
||
- 降级为 CSS transition
|
||
|
||
## Testing Strategy
|
||
|
||
### 单元测试
|
||
|
||
1. **CSS 变量定义测试**
|
||
- 验证所有必需的 CSS 变量已定义
|
||
- 验证变量值格式正确
|
||
|
||
2. **样式类存在性测试**
|
||
- 验证 .style-glass, .style-neumorphism 等类已定义
|
||
- 验证 .segmented-control 组件样式已定义
|
||
|
||
3. **JavaScript 功能测试**
|
||
- 验证样式切换函数正确更新 localStorage
|
||
- 验证分享按钮展开/收起逻辑
|
||
|
||
### 属性测试
|
||
|
||
由于本功能主要涉及 CSS 样式和视觉效果，属性测试将通过以下方式进行：
|
||
|
||
1. **CSS 解析验证**
|
||
- 解析 style.css 文件
|
||
- 验证按钮背景不包含 gradient
|
||
- 验证动画属性使用 CSS 变量
|
||
|
||
2. **DOM 结构验证**
|
||
- 验证分享按钮子元素具有递增的 transition-delay
|
||
- 验证评论区容器具有正确的 transition 属性
|
||
|
||
### 视觉回归测试（可选）
|
||
|
||
1. 使用截图对比工具验证样式变更
|
||
2. 在不同浏览器中验证兼容性
|