feat: ai

2025-11-21 11:51:31 +08:00
parent 7ea114d876
commit 4b9decaa2a
37 changed files with 6401 additions and 30 deletions
--- a/.qoder/quests/blog-style-optimization.md
+++ b/.qoder/quests/blog-style-optimization.md
@@ -0,0 +1,510 @@
+# 博客样式优化设计
+
+## 目标
+
+优化博客的整体视觉呈现，确保风格统一、样式美观，并增强 Markdown 内容渲染和代码块高亮显示能力。
+
+## 背景
+
+当前博客基于 Astro + SolidJS 技术栈，已具备基础样式系统（包括 base.css、typography.css、enhancements.css），并支持暗色模式切换。项目使用 TypeScript 和 PNPM 包管理器，运行于 Node.js 22.21.1 环境。
+
+现有样式系统已建立 CSS 变量体系，覆盖颜色主题、圆角、阴影、过渡动画等设计规范，但在 Markdown 渲染和代码高亮方面存在提升空间。
+
+## 核心需求
+
+### 风格统一性
+
+确保整个站点在视觉呈现上保持一致的设计语言：
+
+- **色彩体系统一**：所有组件遵循统一的 CSS 变量定义，包括亮色和暗色两套主题配色
+- **间距规范一致**：页面布局、组件内边距、外边距采用统一的间距标准
+- **字体层级清晰**：建立明确的字体大小、行高、字重等级体系
+- **交互反馈统一**：hover、focus、active 等状态的视觉反馈保持一致性
+
+### Markdown 渲染优化
+
+提升 Markdown 内容的可读性和视觉表现：
+
+- **标题层级视觉区分**：h1-h6 各级标题具有明显的视觉差异，便于内容层级识别
+- **段落排版优化**：合理的行高、段落间距，提升长文阅读体验
+- **列表样式美化**：有序列表和无序列表具有清晰的视觉标识
+- **引用块样式增强**：blockquote 具有独特的视觉设计，突出引用内容
+- **链接交互优化**：链接具有醒目但不突兀的视觉效果和悬停动画
+- **图片展示优化**：图片具有适当的边框、圆角、阴影效果，支持放大效果
+- **分隔线美化**：hr 标签具有渐变或装饰性样式
+- **表格样式优化**：表格具有清晰的边框、斑马纹或悬停高亮效果
+
+### 代码块高亮
+
+实现专业的代码展示能力：
+
+- **语法高亮引擎选型**：选择合适的语法高亮方案（Shiki 或 Prism），支持多种编程语言
+- **主题适配**：代码高亮主题需适配亮色和暗色两种模式，确保视觉和谐
+- **代码块装饰**：代码块具有语言标识、行号显示、复制按钮等增强功能
+- **行内代码区分**：行内 `code` 标签与代码块在视觉上有明确区分
+- **代码块容器样式**：代码块具有边框、圆角、阴影、背景色等装饰效果
+- **横向滚动优化**：长代码行支持横向滚动，滚动条样式与整体风格匹配
+
+## 设计方案
+
+### 样式系统强化
+
+#### CSS 变量体系扩展
+
+在现有 CSS 变量基础上，补充完善以下变量定义：
+
+**代码相关变量**
+- 行内代码背景色、文字色、边框色
+- 代码块背景色（需区分亮色和暗色模式）
+- 代码块边框色
+- 代码行号颜色
+- 代码高亮行背景色
+
+**Markdown 元素专用变量**
+- 引用块左侧装饰色
+- 引用块背景色
+- 表格边框色
+- 表格斑马纹背景色
+- 链接装饰线颜色
+
+**间距规范变量**
+- 文章内容最大宽度
+- 标题上下边距
+- 段落间距
+- 列表项间距
+
+#### 排版增强策略
+
+**中英文混排优化**
+- 设置适合中文的行高（1.8-2.0）
+- 字体栈优先选择系统优化字体
+- 字符间距微调，提升可读性
+
+**响应式排版**
+- 大屏设备：标准字号（17px）
+- 平板设备：适中字号（16px）
+- 移动设备：缩小字号（15px），调整行高和间距
+
+### Markdown 渲染方案
+
+#### Astro Markdown 配置
+
+利用 Astro 内置的 Markdown 处理能力，通过配置优化渲染输出：
+
+**配置项规划**
+- 启用 GitHub Flavored Markdown（GFM）扩展，支持表格、任务列表等
+- 配置自动链接识别
+- 启用智能标点符号转换
+- 配置标题自动生成 ID，便于锚点跳转
+
+**插件集成考量**
+- 评估是否需要引入 remark 或 rehype 插件增强处理能力
+- 考虑添加目录生成插件
+- 评估是否需要图片懒加载或优化插件
+
+#### 自定义样式映射
+
+针对 Markdown 渲染后的 HTML 结构，编写精准的 CSS 选择器：
+
+**文章容器作用域**
+- 所有 Markdown 样式限定在 `article` 或 `.post-content` 作用域内
+- 避免全局样式污染
+
+**元素样式定义清单**
+- 标题：h1-h6 的字号、字重、颜色、间距、装饰效果
+- 段落：行高、间距、文字颜色
+- 链接：颜色、下划线样式、悬停效果、过渡动画
+- 列表：标记样式、缩进、间距
+- 引用块：边框、背景、左侧装饰、引号装饰
+- 图片：边框、圆角、阴影、悬停效果
+- 表格：边框、表头样式、斑马纹、悬停高亮
+- 分隔线：渐变效果或装饰性样式
+- 行内代码：背景、边框、颜色、字体
+
+### 代码高亮方案
+
+#### Shiki 语法高亮集成
+
+选择 Shiki 作为代码高亮引擎，原因如下：
+- Astro 官方推荐，集成简单
+- 基于 VS Code 主题引擎，主题丰富且美观
+- 支持服务端渲染，无需客户端 JavaScript
+- 支持多语言和自定义主题
+
+#### 主题配置策略
+
+**亮色模式主题**
+- 选择柔和、对比度适中的主题（如 GitHub Light、One Light）
+- 背景色需与整体页面风格协调
+
+**暗色模式主题**
+- 选择护眼、对比度适中的暗色主题（如 One Dark Pro、Night Owl）
+- 背景色需与暗色模式整体风格匹配
+
+**主题切换机制**
+- 通过 CSS 变量或 data-theme 属性实现主题动态切换
+- 确保切换过程平滑，无闪烁
+
+#### 代码块增强功能
+
+**语言标识显示**
+- 在代码块顶部或角落显示语言标签
+- 标签样式需与整体风格一致
+
+**复制功能**
+- 在代码块区域提供复制按钮
+- 点击后复制代码内容到剪贴板
+- 提供复制成功的视觉反馈
+
+**行号显示（可选）**
+- 评估是否需要显示行号
+- 行号样式不干扰代码阅读
+
+**代码块容器装饰**
+- 边框样式：细边框或无边框，颜色与主题协调
+- 圆角效果：使用统一的圆角变量（如 var(--radius-lg)）
+- 阴影效果：适度阴影增强层次感（如 var(--shadow-md)）
+- 左侧装饰线：渐变色装饰线增强视觉效果
+
+### 样式文件组织
+
+#### 文件结构规划
+
+当前样式文件结构保持不变，在现有基础上增强：
+
+**base.css**
+- 补充代码高亮相关 CSS 变量
+- 补充 Markdown 渲染相关变量
+
+**typography.css**
+- 优化现有文章排版样式
+- 补充缺失的 Markdown 元素样式
+- 确保所有样式作用域限定在 article 内
+
+**enhancements.css**
+- 添加代码块复制按钮样式
+- 添加语言标识样式
+- 优化表格、引用块等增强效果
+
+**代码高亮主题（新增）**
+- 考虑是否需要单独的代码主题样式文件
+- 如果使用 Shiki，可能无需额外 CSS 文件
+
+#### 样式优先级与覆盖策略
+
+**导入顺序**
+- reset.css → typography.css → enhancements.css
+- 确保增强样式可以覆盖基础样式
+
+**选择器特异性控制**
+- 避免使用过高权重的选择器
+- 优先使用类选择器和属性选择器
+- 必要时使用作用域限定
+
+### 响应式设计
+
+#### 断点规划
+
+遵循移动优先原则，定义以下断点：
+
+- 小屏移动设备：<= 480px
+- 大屏移动设备：481px - 768px
+- 平板设备：769px - 1024px
+- 桌面设备：>= 1025px
+
+#### 各断点样式调整策略
+
+**移动设备（<= 768px）**
+- 减小标题字号
+- 增加段落行高，便于触摸阅读
+- 代码块字号适当缩小
+- 表格横向滚动处理
+- 图片宽度 100%
+
+**平板设备（769px - 1024px）**
+- 标题字号适中
+- 代码块保持可读性
+- 表格可正常展示或滚动
+
+**桌面设备（>= 1025px）**
+- 最佳阅读体验
+- 充分利用屏幕空间
+- 图片可展示大尺寸
+
+### 暗色模式适配
+
+#### 主题切换机制
+
+依托现有的 `data-theme="dark"` 属性实现主题切换：
+
+**颜色变量切换**
+- 所有颜色变量在暗色模式下重新定义
+- 代码块背景色、文字色适配暗色主题
+- 边框、阴影适配暗色环境
+
+**代码高亮主题切换**
+- 根据 `data-theme` 属性切换 Shiki 主题
+- 确保暗色模式下代码可读性和对比度
+
+**过渡动画**
+- 主题切换过程平滑过渡
+- 避免颜色突变导致的视觉不适
+
+#### 暗色模式特殊处理
+
+**图片亮度调整**
+- 暗色模式下图片亮度略微降低（opacity: 0.9）
+- 悬停时恢复正常亮度
+
+**代码块对比度优化**
+- 暗色模式代码块背景色需与页面背景有一定区分
+- 语法高亮颜色对比度适中，避免刺眼
+
+## 技术实现要点
+
+### Astro 配置调整
+
+在 `astro.config.mjs` 中配置 Markdown 处理选项：
+
+**Markdown 配置项**
+- syntaxHighlight：设置为 'shiki'
+- shikiConfig：配置 Shiki 主题和选项
+- remarkPlugins：可选引入 remark 插件
+- rehypePlugins：可选引入 rehype 插件
+
+**配置示例结构**
+```
+markdown: {
+  syntaxHighlight: 'shiki',
+  shikiConfig: {
+    theme: 亮色主题,
+    themes: { light: 亮色主题, dark: 暗色主题 },
+    wrap: 是否换行,
+    langs: 支持的语言列表
+  },
+  remarkPlugins: [...],
+  rehypePlugins: [...]
+}
+```
+
+### CSS 变量定义规范
+
+**命名约定**
+- 使用 kebab-case 命名法
+- 前缀分类：--bg（背景）、--text（文字）、--code（代码）、--border（边框）等
+- 语义化命名，便于理解和维护
+
+**亮色与暗色变量对应关系**
+- 每个亮色变量在 `[data-theme="dark"]` 中都有对应定义
+- 变量名保持一致，仅值不同
+
+### 组件样式隔离
+
+**PostLayout 组件**
+- 确保文章内容区域使用 `.post-content` 类包裹
+- 所有 Markdown 样式限定在此作用域内
+
+**全局样式与组件样式协同**
+- 全局样式定义基础规范
+- 组件样式处理特定场景
+
+### 性能优化考量
+
+**CSS 体积控制**
+- 避免冗余样式定义
+- 使用 CSS 变量减少重复代码
+- 生产环境压缩 CSS
+
+**代码高亮性能**
+- Shiki 在构建时高亮，无运行时性能损耗
+- 避免客户端高亮库增加包体积
+
+**字体加载优化**
+- 使用系统字体栈，避免额外字体加载
+- 如需自定义字体，采用字体子集化和预加载
+
+## 验收标准
+
+### 风格统一性检查
+
+- 所有页面组件遵循统一的色彩体系
+- 间距、圆角、阴影等设计元素保持一致
+- 亮色和暗色模式切换流畅，无样式错乱
+- 响应式布局在各断点表现正常
+
+### Markdown 渲染质量
+
+- 标题层级清晰，视觉区分明显
+- 段落排版舒适，行高和间距合理
+- 列表、引用块、表格样式美观
+- 链接具有明确的视觉提示和交互反馈
+- 图片展示效果良好，支持悬停效果
+- 分隔线、行内代码等细节元素样式完善
+
+### 代码高亮效果
+
+- 支持常见编程语言的语法高亮（JavaScript、TypeScript、Python、Go、CSS、HTML 等）
+- 代码配色与整体主题协调
+- 亮色和暗色模式下代码可读性良好
+- 代码块具有清晰的边界和装饰效果
+- 行内代码与代码块视觉区分明显
+- 复制功能正常工作（如实现）
+
+### 可访问性
+
+- 颜色对比度符合 WCAG AA 标准
+- 键盘导航支持良好
+- 屏幕阅读器友好
+- 减少动画模式（prefers-reduced-motion）生效
+
+### 性能指标
+
+- 页面首次渲染时间无明显增加
+- CSS 文件体积控制在合理范围
+- 无不必要的客户端 JavaScript 加载
+- 代码高亮渲染速度快
+
+## 潜在风险与应对
+
+### 主题切换闪烁
+
+**风险描述**
+暗色模式切换时可能出现短暂的白屏或颜色闪烁。
+
+**应对策略**
+- 在 HTML 加载初期通过内联脚本读取主题偏好
+- 在 CSS 加载前应用主题属性
+- 使用 localStorage 持久化主题选择
+
+### 代码高亮主题适配问题
+
+**风险描述**
+选择的 Shiki 主题可能与整体风格不匹配。
+
+**应对策略**
+- 预先测试多个主题，选择最协调的方案
+- 必要时自定义 Shiki 主题配色
+- 通过 CSS 变量覆盖部分颜色
+
+### 移动端代码块可读性
+
+**风险描述**
+移动设备屏幕小，代码块显示可能不佳。
+
+**应对策略**
+- 设置合适的最小字号
+- 启用横向滚动，避免代码换行
+- 优化移动端代码块内边距
+
+### 长文章性能问题
+
+**风险描述**
+包含大量代码块的长文章可能导致渲染性能下降。
+
+**应对策略**
+- Shiki 在构建时处理，不影响运行时性能
+- 优化 CSS 选择器性能
+- 避免过度使用复杂动画
+
+## 后续优化方向
+
+### 交互增强
+
+- 代码块行高亮功能
+- 代码差异对比展示
+- 图片点击放大查看（Lightbox）
+- 文章目录自动生成和锚点跳转
+
+### 内容增强
+
+- 代码注释高亮
+- 公式渲染支持（KaTeX 或 MathJax）
+- 图表渲染支持（Mermaid）
+- 视频嵌入样式优化
+
+### 个性化定制
+
+- 用户可选代码高亮主题
+- 字号调节功能
+- 阅读进度指示器
+- 打印样式优化
+
+### 性能优化
+
+- 关键 CSS 内联
+- 非关键样式延迟加载
+- 图片懒加载和响应式图片
+- 字体加载策略优化
+
+## 潜在风险与应对
+
+### 主题切换闪烁
+
+**风险描述**
+暗色模式切换时可能出现短暂的白屏或颜色闪烁。
+
+**应对策略**
+- 在 HTML 加载初期通过内联脚本读取主题偏好
+- 在 CSS 加载前应用主题属性
+- 使用 localStorage 持久化主题选择
+
+### 代码高亮主题适配问题
+
+**风险描述**
+选择的 Shiki 主题可能与整体风格不匹配。
+
+**应对策略**
+- 预先测试多个主题，选择最协调的方案
+- 必要时自定义 Shiki 主题配色
+- 通过 CSS 变量覆盖部分颜色
+
+### 移动端代码块可读性
+
+**风险描述**
+移动设备屏幕小，代码块显示可能不佳。
+
+**应对策略**
+- 设置合适的最小字号
+- 启用横向滚动，避免代码换行
+- 优化移动端代码块内边距
+
+### 长文章性能问题
+
+**风险描述**
+包含大量代码块的长文章可能导致渲染性能下降。
+
+**应对策略**
+- Shiki 在构建时处理，不影响运行时性能
+- 优化 CSS 选择器性能
+- 避免过度使用复杂动画
+
+## 后续优化方向
+
+### 交互增强
+
+- 代码块行高亮功能
+- 代码差异对比展示
+- 图片点击放大查看（Lightbox）
+- 文章目录自动生成和锚点跳转
+
+### 内容增强
+
+- 代码注释高亮
+- 公式渲染支持（KaTeX 或 MathJax）
+- 图表渲染支持（Mermaid）
+- 视频嵌入样式优化
+
+### 个性化定制
+
+- 用户可选代码高亮主题
+- 字号调节功能
+- 阅读进度指示器
+- 打印样式优化
+
+### 性能优化
+
+- 关键 CSS 内联
+- 非关键样式延迟加载
+- 图片懒加载和响应式图片
+- 字体加载策略优化
+- 代码高亮渲染速度快