argon-theme/.kiro/specs/global-ui-optimization/design.md

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 变量

: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)

.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)

.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. 设置面板设计

面板容器

#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)

.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. 分享按钮动画设计

容器样式

#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);
}

展开动画

#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; }

主按钮变换

#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. 评论展开动画设计

评论区容器

#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;
}

切换按钮图标动画

#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)

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)

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

设置存储结构

// 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. 在不同浏览器中验证兼容性