Skip to content

DEV_LOG.md

Latest commit

 

History

History
169 lines (132 loc) · 9.49 KB

DEV_LOG.md

File metadata and controls

169 lines (132 loc) · 9.49 KB

开发指南与日志 (Developer Guide & Log)

🛠 开发指南 (Developer Guide)

目录结构

  • theme-src/: 主题源文件 (base + root)
  • website/: 文档/官网源码 (HTML/Assets)
  • dist/: 构建生成的主题文件 (发布产物)
  • bloom/: 主题包内资源 (仅主题所需，如字体)
  • scripts/: 构建与工具脚本

常用命令

  • npm run dev: 启动本地预览服务器 (支持热重载 CSS)
  • npm run build: 构建主题 (生成 dist/ 和 _pages/)
  • npm run package: 构建并打包 ZIP 发布文件
  • npm run release: 自动化发布流程 (打包 + 提交 + Tag + 推送)

发布流程

  1. 修改 VERSION.txt 版本号
  2. 执行 npm run release

📃 更新日志 (Changelog)

v1.3.4 (2026-03-09) 全量美学统合与深色模式深度优化

  • [Feat] 全量美学统合 (Unified Aesthetics)：
    • 统合 代码块 (Fences)、HTML 块 以及 YAML 配置头 (Frontmatter/Skill Headers) 的视觉语言。
    • 统一采用 18px 圆角卡片、Mac 风格“红黄绿”装饰点 以及 代码级背景色 (var(--code-bg))，彻底消除视觉碎裂感。
  • [Feat] GitHub 原生 Alerts 适配：全量支持 GitHub 原生 > [!NOTE]、> [!TIP]、> [!IMPORTANT] 等五种警示框语法，并注入 Bloom 特有的 Glassmorphism (磨砂玻璃) 质感。
  • [Fix] Mermaid 深色模式重构：修复了 Mermaid 流程图/时序图在暗色主题下线条不可见及文字对比度过低的问题，注入原生暗色变量。
  • [Fix] macOS 标题栏适配：修复了深色模式下窗口标题栏对比度低以及在“无缝模式”下出现的视觉割裂感。
  • [Fix] HTML 嵌入对比度修复：解决深色模式下嵌入 HTML 标签文字不可见以及悬停时背景意外变白的问题（强制注入 !important 覆盖）。
  • [Chore] 源码精修：全量重构 16 套主题的 root-*.css 格式，优化变量定义层级。

v1.3.3 (2026-01-29) 深度视觉修复

  • [Fix] Mermaid 暗色模式重构：弃用手动 SVG 覆盖，全面启用 Typora 原生 --mermaid-theme: night 变量，彻底解决时序图/流程图在暗色主题下的可见性与线条丢失问题。
  • [Fix] macOS 标题栏修复：解决浅色主题下文件名文字不可见 (低对比度) 及深色主题无缝模式下的“透白条”问题。
  • [Polish] Spring Dark (薰衣草紫·暗夜) 背景调优：将背景亮度从 18% 提升至 24% (#3B3640)，减轻视觉压抑感，阅读更从容。
  • [Chore] 清理 Demo 资源：移除冗余的调试文件，保持发布包纯净。

v1.3.2 (2026-01-28) 视觉优化与工程重构

  • [Fix] 修复 Mermaid 时序图在暗色主题下线条与文字可见性低的问题 (Issue #1)。
  • [Refactor] 工程结构重构：将官网源码（HTML/CSS/JS/Assets）收敛至 website/ 目录，根目录更清爽。
  • [Refactor] 主题配置 SSOT：通过 theme-list.js 单一数据源控制全局默认主题，一键切换。
  • [Feat] 官网预览页新增 Mermaid 图表实时渲染支持。
  • [Fix] 修复 README.md 中的资源文件引用路径。

2026-01-28 项目重构

  • 结构优化: 将官网文件移入 website/ 目录，根目录更清爽。
  • 修复: 修复 scripts/pages.js 部署脚本丢失 assets 问题。
  • 修复: 修复 GitHub Issue #1 (Mist Dark 下 Mermaid 时序图不可见) Issue Link。

2026-01-07 提示框 (Alert) 系统重构

1. 样式重构：从 GitHub 风格转向 Bloom 质感

  • 现状： 原有的 Warning/Caution/Important 使用 GitHub 风格的硬朗色块，且共用同一组黄色变量，导致视觉区分度低，且与 Bloom 主题的柔和风格不搭。
  • 重构：
    • 形态： 引入 12px 圆角 与 半透明背景 (color-mix)，营造磨砂玻璃质感。
    • 边框： 去除生硬的实线边框，改为半透明柔和边框。
    • 区分： 彻底拆分三种警告类型，分别赋予独立色相。

2. 语义化变量补完

  • 问题： 主题变量中缺少统一的“紫色/重要”语义色，导致 Important 样式无法根据主题自动适配。
  • 解决：
    • 编写脚本批量更新所有 16 个 root-*.css 文件。
    • 注入全局语义变量 --important：
      • 浅色系：oklch(65% 0.16 280) (柔和紫)
      • 深色系：oklch(75% 0.14 280) (明亮紫)
    • 确保了 Important 提示框在 Verdant、Amber、Petal 等不同色调主题下都能呈现协调的视觉效果。

3. 全局适配

  • 统一了 Note (Info), Tip (Success), Warning (Warning), Caution (Error), Important (Important) 五种提示框的实现逻辑。
  • 全部采用 var(--semantic-color) + color-mix 的动态生成策略，实现 16 种主题 的 100% 自动适配。

2026-01-05 配色方案优化

问题诊断

1. 致命的对比度隐患 (Accessibility Risk)

Mist & Stone 的 Accent 问题：

  • 现状：背景 L=96%，Accent L=65%
  • 问题：强调色用于文字链接时对比度太低，视力稍弱的用户看不清链接
  • 修复：Accent 亮度从 65% 降至 50%

Cyber 的"蓝光晕影"效应：

  • 现状：背景极黑 (12%)，Accent 是高饱和霓虹蓝 (Chroma 0.18, Hue 245)
  • 问题：Chromostereopsis（色立体视觉）导致文字边缘模糊、重影
  • 修复：降低 Chroma 0.18 → 0.14，Hue 从 245 调整到 230（偏青）

2. 深色模式的"层级缺失" (Hierarchy Issues)

  • 现状：深色系背景亮度统一设为 L=22%
  • 问题：L=22% 约等于 #303030，作为全局背景太亮，缺乏深邃感
  • 修复：全局背景从 22% 降至 14%

3. Spring 的单色问题 (Monochrome Flatness)

  • 现状：背景、文字、强调色全部锁定在 Hue=295
  • 问题：用户难以区分装饰、按钮、状态提示
  • 保留：暂不修改，保持单色风格设计意图

4. 色域映射风险 (Gamut Mapping)

  • Verdant & Forest 使用高饱和绿色，在 sRGB 覆盖率低的屏幕上可能失真
  • 保留：暂不修改，后续可增加 fallback 机制

修复数值

主题 变量 原值 新值
Dark --bg oklch(22% 0.02 260) oklch(14% 0.02 260)
Forest --bg oklch(22% 0.01 160) oklch(14% 0.01 160)
Spring --bg oklch(22% 0.02 295) oklch(14% 0.02 295)
Cyber --accent oklch(78% 0.18 245) oklch(75% 0.14 230)
Mist --accent oklch(65% 0.06 240) oklch(50% 0.08 240)
Stone --accent oklch(65% 0.04 40) oklch(50% 0.06 40)
Verdant --accent oklch(68% 0.05 160) oklch(50% 0.07 160)

层级变量更新

深色主题需要更新 --surface 以保持与 --bg 的层级差：

  • --bg = 14% → --surface = 22%

2026-01-07 薰衣草紫补完计划

1. 新增 Spring (浅色薰衣草紫)

  • 需求： 补全 5 浅 + 5 深的非对称缺口（原 Stone 浅 / Spring 深）。
  • 实现：
    • 重命名原 Spring 为 Spring Dark。
    • 新增 Spring (浅色) 主题，基于 Mist 浅色模板。
    • 色相统一为 H=295。
    • 背景 L=96%，强调色 L=60% C=0.14 (比深色版 L75% 更深以保证白底对比度)。

2. 新增 Stone Dark (暖石暗夜)

  • 需求： 达成 6 浅 + 6 深 (12 套) 的完美对称结构。
  • 实现：
    • 新增 Stone Dark 主题，基于 Mist Dark 模板。
    • 色相 H=40，背景 L=20%，强调色 L=75%。

3. 新增 Ripple (涟漪) 与 Ink (水墨)

  • 需求： 进一步扩展色彩空间，引入青色系与水墨单色系。
  • 实现：
    • Ripple (青碧)：H=195，填补了蓝绿之间的缺口，清冷高级。
    • Ink (水墨)：宣纸白/墨池黑底色 + 朱砂红 (H30) 强调色，东方美学极简风。
  • 成就： 最终达成 8 浅 + 8 深 (共 16 套) 的莫兰迪主题矩阵。

2026-01-05 全系莫兰迪化与更名

1. 经典主题更名与莫兰迪化

  • 变更： Light/Dark 更名为 Petal/Petal Dark。
  • 原因： 统一全系莫兰迪风格，原 Light/Dark 饱和度过高（0.24），现降至 0.08。
  • 视觉： 使用柔和的花瓣粉（H 354）作为强调色。

2. 深色莫兰迪补完

  • 变更： Forest 主题改造为 Verdant Dark。
  • 原因： 原 Forest 为高饱和荧光绿，不符合莫兰迪风格。现改造为低饱和度暗色豆沙绿，与浅色 Verdant 配套。

3. 主题架构调整

  • 统一所有主题为 4 浅 + 4 深的莫兰迪配色结构，并更新文档与展示页。
  • [2026-01-05] 新增 Amber (琥珀) 系列主题。
  • 优化： 根据用户反馈，将橙色调从沉闷的色相 (H 45) 调整为更具极客审美的琥珀橙 (H 65)，并全面重命名为 Amber。
  • 优化： 根据用户反馈，修复了 Petal (花瓣粉) 在深色模式优化后出现的色调偏移问题。通过微调色相 (H 350) 并显著提升强调色纯度 (Chroma 0.22)，找回了极受好评的“正统玫瑰粉”视觉美感。
  • 优化： 统一了全系蓝色调。将 Mist (雾蓝) 与 Cyber (青蓝) 统一至 H 240 色相轴，并新增 Mist Dark (雾蓝暗夜) 主题，实现莫兰迪蓝色系的深度对齐。
  • 精简： 移除了 Cyber 主题，简化主题库至 10 套精选方案（5 浅 + 5 深）。
  • 命名优化： 将"琥珀 (Amber)"细化为"琥珀橙 (Amber Orange)"，在 UI 显示中明确其橙色系身份，同时保持内部变量名简洁。
  • 清理： 删除了不再使用的旧主题源文件与生成的 css。
  • 优化： 重新组织 README，精简设计原则，明确 4+4 分类。