darkings_Obsidian-MonokaiSyntax/TODO.md

Monokai Syntax 项目 TODO

来源：C:\Users\Jie\iCloudDrive\iCloud~md~obsidian\SecondBrain\project\Monokai Syntax\_RoadMap\原始开发规划.md 目标：构建并发布一个名为 Monokai Syntax 的 Obsidian 社区主题。主题参考 Monokai Pro 深色与浅色调色板，采用模块化 SCSS、Style Settings 配置扩展，并具备合规的发布流程。

已确认项目参数

• 作者名称：lat3ncy
• 初始版本号：1.0.0
• 包管理器：npm
• 测试 Obsidian Vault 路径：C:\Users\Jie\iCloudDrive\iCloud~md~obsidian\SecondBrain
• Vault 验证结果：路径存在，且包含 .obsidian 配置目录。

阶段 0：项目初始化

• 创建项目仓库结构。
  • 添加 package.json。
  • 添加 manifest.json。
  • 添加 versions.json。
  • 添加 .github/ 工作流目录。
  • 添加 src/scss/。
  • 添加 src/css/license.css。
  • 添加 src/css/style-settings/。
  • 添加 test/ 输出目录或 Vault 链接目录。
• 配置 npm 脚本。
  • 添加开发构建脚本。
  • 添加生产构建脚本。
  • 添加样式检查脚本。
  • 添加发布打包脚本。
• 配置 Vite 作为 CSS 构建引擎。
  • 将 src/scss/index.scss 编译为最终主题 CSS。
  • 注入静态许可证头部。
  • 将生成后的 Style Settings 元数据追加到最终 CSS。
• 配置 Stylelint。
  • 禁止在常规主题 CSS 中使用 ID 选择器。
  • 限制过深的选择器嵌套。
  • 统一空格与格式规则。
  • 标记不必要的 !important 用法。
• 确定本地开发工作流。
  • 将构建输出链接到测试 Obsidian Vault。
  • 安装或记录 Obsidian 主题热重载支持方式。

阶段 1：主题元数据

• 创建 manifest.json。
  • 将 name 设置为 Monokai Syntax。
  • 设置初始语义化版本号。
  • 将 minAppVersion 设置为 1.0.0。
  • 添加作者元数据。
  • 添加深色与浅色模式支持声明。
• 创建 versions.json。
  • 将初始主题版本映射到最低支持的 Obsidian 版本。
• 添加仓库文档。
  • 添加 README.md，包含安装、开发与截图说明。
  • 添加许可证信息。
  • 说明运行时 CSS 不得加载远程资源。

阶段 2：SCSS 架构

• 创建 src/scss/index.scss。
  • 首先导入变量文件。
  • 其次导入 mixin 文件。
  • 导入基础主题变量。
  • 导入组件模块。
  • 导入插件模块。
  • 导入 Style Settings 类名覆盖逻辑。
• 创建 src/scss/_variables.scss。
  • 定义深色调色板基础色。
  • 定义浅色调色板基础色。
  • 定义强调色、链接色、警告色、成功色、代码色、边框色与弱化色等语义别名。
  • 定义排版变量。
  • 定义间距与圆角变量。
• 创建 src/scss/_mixins.scss。
  • 按需添加主题模式辅助 mixin。
  • 添加焦点环辅助 mixin。
  • 添加紧凑密度辅助 mixin。
  • 添加减少动画辅助 mixin。
• 创建 src/scss/_base.scss。
  • 挂载全局 :root 变量。
  • 挂载 .theme-dark 变量。
  • 挂载 .theme-light 变量。
  • 设置基础字体与行高变量。
  • 设置 Obsidian 核心背景与文本变量。

阶段 3：深浅色调色板映射

• 实现深色模式基础颜色。
  • 将 #272822 映射到 --background-primary。
  • 将 #1e1f1c 映射到 --background-secondary。
  • 将 #f8f8f2 映射到 --text-normal。
  • 将低饱和灰色映射到弱化文本、图标、边框与悬停状态。
• 实现深色模式语义强调色。
  • 将洋红/红色映射到强调色与一级标题。
  • 将橙色映射到二级标题与元数据标签。
  • 将黄色映射到三级标题与文本高亮。
  • 将绿色映射到块引用边框与已完成复选框。
  • 将青色/蓝色映射到内部链接与外部链接。
  • 将紫色映射到列表标记与行内代码点缀。
• 实现浅色模式基础颜色。
  • 将 #fdf9f3 映射到 --background-primary。
  • 将 #f5f0e6 映射到 --background-secondary。
  • 将 #3d3d3d 映射到 --text-normal。
  • 确保非激活图标与弱化文本在浅色模式下仍清晰可见。
• 实现浅色模式语义强调色。
  • 将浅色洋红映射到强调色与一级标题。
  • 将浅色橙色映射到二级标题与元数据标签。
  • 将较深黄橙色映射到三级标题与文本高亮。
  • 将森林绿映射到块引用边框与已完成复选框。
  • 将较深青蓝色映射到链接。
  • 将浅紫色映射到列表标记与行内代码点缀。
• 检查核心对比度。
  • 验证两种模式下的正文文本对比度。
  • 验证两种模式下的链接对比度。
  • 验证浅色模式下的图标可见性。
  • 验证高亮文本可读性。

阶段 4：Markdown 与编辑器样式

• 创建 src/scss/components/_editor.scss。
• 设置标题样式。
  • 为 H1、H2、H3 应用不同颜色。
  • 保持编辑视图与阅读视图中的标题间距易读。
• 设置强调文本样式。
  • 让粗体文本颜色接近正文颜色。
  • 增加粗体字重，避免制造不必要的视觉噪音。
  • 设置斜体样式并保持可读性。
• 设置链接样式。
  • 应用青色/蓝色链接颜色。
  • 仅在确有价值时区分内部链接与外部链接。
  • 添加可访问的悬停与焦点状态。
• 设置块引用样式。
  • 使用绿色左边框。
  • 保持引用文本颜色可读。
  • 调整内边距与间距。
• 设置列表与任务列表样式。
  • 应用紫色列表标记。
  • 使用绿色表示已完成复选框。
  • 验证多级嵌套列表仍然清晰。
• 设置行内代码与代码块。
  • 使用类似编辑器的代码块背景。
  • 调整内边距、圆角与边框。
  • 应用等宽字体栈。
• 设置 Markdown 高亮。
  • 使用带模式区分透明度的黄色高亮。
  • 确保高亮文本仍然可读。
• 添加 CodeMirror 6 语法颜色。
  • 将字符串映射为黄色。
  • 将关键字映射为洋红色。
  • 将函数映射为绿色或青色。
  • 将常量与数字映射为紫色或橙色。
  • 将注释映射为弱化灰色。
  • 验证 Live Preview 与阅读视图的一致性。

阶段 5：Obsidian UI 组件

• 创建 src/scss/components/_ribbon.scss。
  • 让 Ribbon 背景与侧边栏背景保持一致。
  • 设置非激活图标样式。
  • 设置悬停图标样式。
  • 设置激活图标样式。
• 创建 src/scss/components/_tabs.scss。
  • 设置工作区标签页样式。
  • 设置激活标签页状态。
  • 设置标签页悬停状态。
  • 确保标题文本在两种模式下都可读。
• 创建 src/scss/components/_modals.scss。
  • 设置命令面板样式。
  • 设置建议列表激活项样式。
  • 设置弹窗背景与阴影。
  • 设置输入框焦点状态。
• 设置导航与文件浏览器样式。
  • 调整文件树悬停状态。
  • 调整已选中文件状态。
  • 设置折叠指示器与图标。
  • 验证侧边栏层级清晰。
• 设置元数据与属性样式。
  • 为元数据标签应用橙色。
  • 保持属性值可读。
  • 验证编辑控件可见。

阶段 6：核心插件样式

• 创建 src/scss/plugins/_graph.scss。
  • 设置关系图谱背景。
  • 设置图谱节点样式。
  • 设置图谱连线样式。
  • 设置悬停与聚焦图谱状态。
  • 避免密集图谱造成视觉拥堵。
• 创建 src/scss/plugins/_canvas.scss。
  • 将 Canvas 颜色预设 color-1 到 color-6 映射到 Monokai 调色板。
  • 验证卡片在深色模式下可读。
  • 验证卡片在浅色模式下可读。
  • 设置 Canvas 选中与边线状态。
• 检查常用核心插件界面。
  • 搜索。
  • 反向链接。
  • 出链。
  • 标签。
  • 书签。

阶段 7：Style Settings 集成

• 创建 src/scss/plugins/_style-settings.scss。
• 在 src/css/style-settings/ 下创建模块化 Style Settings 文件。
  • 添加总览或根设置模块。
  • 添加调色板滤镜设置模块。
  • 添加密度设置模块。
  • 添加图标设置模块。
  • 添加排版与行宽设置模块。
  • 添加强调色覆盖设置模块。
• 实现滤镜类名选择。
  • 添加 Classic 滤镜类。
  • 添加 Machine 滤镜类。
  • 添加 Octagon 滤镜类。
  • 添加 Ristretto 滤镜类。
  • 添加 Spectrum 滤镜类。
  • 确认每个滤镜只覆盖必要且风格一致的一组变量。
• 实现紧凑模式。
  • 减小文件树行高。
  • 减小 Ribbon 间距。
  • 减小代码块内边距。
  • 保留可用的点击目标尺寸。
• 实现单色图标模式。
  • 将文件树图标颜色转换为弱化灰阶。
  • 保持激活状态可辨识。
• 实现行宽控制。
  • 添加可读行宽变量滑块。
  • 支持从 40rem 到 75rem 的范围。
• 实现强调色覆盖。
  • 为强调色、链接色、成功色、警告色与代码色添加颜色变量控件。
  • 验证覆盖值同时影响编辑器与 UI 变量。
• 添加 Style Settings 元数据拼接构建步骤。
  • 定义确定性的文件顺序。
  • 将元数据追加到最终主题 CSS。
  • 验证生成后的 CSS 注释语法。

阶段 8：资产与合规检查

• 审计运行时 CSS 是否存在远程网络资源。
  • 移除外部 @import 引用。
  • 移除远程字体 URL。
  • 移除远程图片 URL。
• 确定字体策略。
  • 默认使用系统字体栈。
  • 如需打包字体，则本地化字体文件并记录许可证。
• 审计 !important 用法。
  • 移除可避免的声明。
  • 仅保留覆盖 Obsidian 或插件行为时确实必要的声明。
• 审计选择器特异性。
  • 优先使用 Obsidian 变量。
  • 仅在变量不足时使用定向选择器。
  • 尽量避免脆弱的深层 DOM 选择器。

阶段 9：测试与视觉 QA

• 创建测试 Obsidian Vault。
  • 添加包含标题、列表、任务列表、链接、标签、Callout、表格、图片、嵌入、代码块与高亮的笔记。
  • 添加长段落笔记，用于检查阅读舒适度。
  • 添加关系图谱与 Canvas 示例内容。
• 测试深色模式。
  • 验证编辑器视图。
  • 验证阅读视图。
  • 验证侧边栏。
  • 验证命令面板。
  • 验证设置弹窗。
  • 验证关系图谱。
  • 验证 Canvas。
• 测试浅色模式。
  • 验证编辑器视图。
  • 验证阅读视图。
  • 验证侧边栏。
  • 验证命令面板。
  • 验证设置弹窗。
  • 验证关系图谱。
  • 验证 Canvas。
• 测试 Style Settings 控件。
  • 验证每个滤镜类。
  • 验证紧凑模式。
  • 验证单色图标。
  • 验证行宽滑块。
  • 验证强调色覆盖。
• 测试基础可访问性。
  • 检查文本对比度。
  • 检查焦点可见性。
  • 检查悬停与激活状态。
  • 检查浅色模式图标可见性。
• 测试构建输出。
  • 运行 lint。
  • 运行开发构建。
  • 运行生产构建。
  • 确认生成的主题 CSS 可在 Obsidian 中加载。

阶段 9.5：PIP 优化实现顺序

• 实现 PIP 排版与高亮修复。
  • 在 src/scss/components/_editor.scss 中强化行内代码样式。
  • 修复 Live Preview 块引用 > 与左边框双线冲突。
  • 设置浅色模式 H1-H3 字重为 700。
  • 设置深色模式 H1-H3 字重为 600。
  • 加入高分屏文本边缘平滑策略。
  • 保持 Stylelint 规则，不使用 !important。
• 实现零插件图标系统。
  • 新增 scripts/generate-icon-theme.js。
  • 读取 icon-themes/Monokai Pro icon-theme.json 和 monokai-pro-icons.woff。
  • 提取 iconDefinitions、fileExtensions、fileNames 与文件夹图标映射。
  • 将 monokai-pro-icons.woff 转为 base64 字体数据。
  • 生成 src/scss/components/_file-icons.generated.scss。
  • 新增 src/scss/components/_file-icons.scss 并从组件入口导入。
  • 使用 [data-path$="..."] 选择器为文件树扩展名匹配图标。
  • 使用文件名选择器覆盖 package.json、README.md、TODO.md 等特殊文件。
  • 实现文件夹、展开文件夹、根文件夹图标。
  • 支持单色图标模式与彩色图标模式。
• 更新合规与构建检查。
  • 调整 audit:css，允许 data:font/woff;base64 本地内联字体。
  • 继续禁止远程 http://、https://、外部 @import 和 !important。
  • 将图标生成脚本接入构建或发布前流程。
  • 运行 npm run lint:css。
  • 运行 npm run check:contrast。
  • 运行 npm run build:vault。
  • 运行 npm run audit:css。
• 优化关系图谱交互响应。
  • 为图谱颜色、背景和高亮状态添加轻微过渡。
  • 为图谱控制按钮添加 hover 上移与点击复位动画。
  • 为图谱控制按钮添加点击时的轻微横向晃动反馈。
  • 为全局图谱与局部图谱面板添加聚焦反馈。
  • 移除关系图谱节点光晕，保持视觉 QA 前的干净底色。
  • 移除关系图谱容器空闲呼吸光晕。
  • 将关系图谱默认黑底调整为经典 Monokai Pro 深暖灰背景。
  • 将关系图谱底色对齐导航栏与标题栏背景。
  • 为关系图谱节点、连线、聚焦点、标签点与附件点应用经典 Monokai Pro 配色。
  • 支持 prefers-reduced-motion，减少动画偏好下关闭过渡与位移。
• 完成深浅色阅读视图视觉 QA 微调。
  • 降低 Callout 背景视觉权重。
  • 增强表格边框清晰度。
  • 提高已完成任务状态可见性。
  • 为阅读视图块引用添加克制背景与更舒适的左侧间距。

阶段 9.6：Active 视觉问题修复

来源：C:\Users\Jie\iCloudDrive\iCloud~md~obsidian\SecondBrain\project\Monokai Syntax\Active\主题视觉问题汇总_ThemeVisualIssues.md

• 修复导航栏文件夹折叠图标重复问题。
  • 移除导致双折叠箭头的额外文件夹图标。
  • 第一层保留 Obsidian 默认折叠图标。
  • 第二层使用修改后的 Monokai 折叠图标。
• 修复属性面板视觉不一致问题。
  • 调整笔记属性中属性值的底色。
  • 确保属性值背景与 Monokai Syntax 整体配色一致。
• 重构编辑模式 Callout 样式。
  • 拉开绿色长条框体与文本之间的距离。
  • 使用基于 #414339 的低透明度内容背景。
  • 保持 Callout 内容背景与主背景 #272822 有区分但不过度抢眼。
  • 将 note 与 info 映射到蓝青色 #66d9ef。
  • 将 warning 与 caution 映射到橙色 #fd971f 或黄色 #e6db74。
  • 将 error 与 danger 映射到洋红色 #f92672。
  • 将 success 与 check 映射到荧光绿 #a6e22e。
• 隐藏文档编辑区域最上方的冗余标题。
  • 确认编辑区域顶部不再重复显示当前文档标题。
  • 确认不影响标签页标题、文件列表标题与阅读视图标题。
• 校准 Dark Mode 核心配色。
  • 对齐正文区域与 VS Code Monokai Pro 的主背景观感。
  • 对齐标题栏与 VS Code Monokai Pro 的界面层级。
  • 对齐导航栏与 VS Code Monokai Pro 的界面层级。
• 优化 Terminal 插件面板样式。
  • 调整终端面板边距。
  • 让 Terminal 插件面板与主题整体间距系统一致。
• 复核行内代码样式。
  • 暗色主题使用比正文背景稍浅的行内代码背景。
  • 亮色主题使用比正文背景稍深的行内代码背景。
  • 行内代码文字颜色统一使用 Monokai Pro 绿色。
• 为特殊 Markdown 文件名添加专属图标。
  • AGENTS.md 显示专属图标。
  • 确认专属图标与普通 Markdown 文件图标可区分。

阶段 9.7：9.6 视觉返工项

• 调整行内代码样式。
  • 移除行内代码边框着色。
  • 保留行内代码与正文的背景区分。
  • 保留行内代码文字使用 Monokai Pro 绿色。
• 移除笔记属性值背景色。
  • 去掉属性值容器的额外背景色。
  • 保持属性值文字、输入态和焦点态清晰可读。
• 调整块引用样式。
  • 块引用左侧竖条改用 Monokai Pro 黄色。
  • 减小块引用左侧竖条粗细。
  • 加大块引用文字与左侧竖条之间的间距。
• 恢复 Callout 到最开始版本的蓝色背景方案。
  • 使用早期蓝色背景变量作为 Callout 面板背景。
  • 保留必要的内容间距优化。
  • 复核编辑视图与阅读视图中的 Callout 可读性。

阶段 9.8：视觉反馈二次返工

• 调整行内代码背景。
  • 行内代码背景色与当前明亮/黑暗模式下代码块背景色相同。
  • 保留行内代码文字使用 Monokai Pro 绿色。
• 调整块引用样式。
  • 块引用左侧竖条改回 Monokai Pro 绿色。
  • 继续保持较细竖条。
  • 进一步加大块引用文字与竖条之间的距离。
• 按截图调整 Callout 样式。
  • 使用 Monokai Pro 蓝青色作为标题、图标和边框语义色。
  • 使用同色低透明度背景形成浅蓝面板。
  • 保持边框、标题、正文在深色和浅色模式下都清晰。
• 调整复选框颜色。
  • 未选中状态使用 Monokai Pro 黄色。
  • 选中状态使用 Monokai Pro 绿色。
  • 所有颜色均来自 Monokai Pro 调色板。

阶段 9.9：Callout 与块引用间距微调

• 调整 Callout 内边距。
  • Callout 边框内的标题与正文都保留清晰 padding。
  • Callout 正文与标题之间保留舒适间距。
• 优化块引用文字间距。
  • 保留当前绿色背景与绿色细竖条方向。
  • 明显拉开块引用文字与左侧竖条距离。
  • 保持块引用正文可读，不让绿色背景过重。

阶段 10：CI 与发布自动化

• 创建 GitHub Actions 工作流。
  • 安装依赖。
  • 运行 Stylelint。
  • 运行生产构建。
  • 打包 theme.css、manifest.json 与所需发布资产。
• 添加由语义化版本标签触发的发布工作流。
  • 使用 v1.0.0 等标签触发。
  • 将构建后的 CSS 与 manifest 附加到 GitHub Release。
  • 构建产物缺失时让发布失败（fail_on_unmatched_files: true）。
• 添加发布前检查清单。
  • 确认各元数据文件中的版本号一致（release:pack 脚本已包含）。
  • 确认存在变更日志条目（CHANGELOG.md 已创建）。
  • 确认截图为最新版本。
  • 确认没有引用远程资源（audit:css 已包含）。

阶段 10.5：Callout 与块引用 Monokai Pro 重设计（进行中）

Callout 和块引用样式对齐 Monokai Pro 编辑器的装订线式彩色竖线风格。

• 块引用：暖金色竖线（#e6db74/#cc7a0a），无背景，阅读+编辑模式统一
• Callout：语义色左侧竖线（青/橙/洋红/绿），极微着色背景（暗 12%/浅 14%）
• Callout 图标：代码符号风格（#[i] <!> [×] {✓}），隐藏默认 Lucide SVG
• 间距优化：块引用左间距 1.25rem，Callout 内边距 1.25rem
• 修复编辑模式块引用 inline style 覆盖问题（:has(.cm-quote) + margin-left 方案）
• 修复 Callout 双竖条（.cm-callout 与 .callout 分离）
• CSS 规则收归 _active-visual-overrides.scss 单一源
• 最终视觉 QA 确认：编辑模式 Callout 图标显示、背景可见度、间距统一性

阶段 11：社区主题提交

• 创建官方要求的主题截图。
  • 使用 512 x 288 分辨率。
  • 使用 16:9 宽高比。
  • 展示深浅两种模式，或制作具有代表性的高质量预览。
• 准备官方提交元数据。
  • 主题名称：Monokai Syntax。
  • 作者名称或 ID。
  • 仓库 URL。
  • 支持模式：dark、light。
• Fork obsidianmd/obsidian-releases。
• 更新 community-css-themes.json。
• 提交主题收录 Pull Request。
• 根据审核反馈进行调整。
• 审核通过后发布第一个稳定版本。

里程碑顺序

• 里程碑 1：仓库脚手架可以构建空主题 CSS。
• 里程碑 2：深色与浅色基础调色板可在 Obsidian 中正常工作。
• 里程碑 3：Markdown 编辑器与阅读视图完成打磨。
• 里程碑 4：Obsidian UI 界面符合 Monokai Syntax 视觉语言。
• 里程碑 5：关系图谱、Canvas 与 Style Settings 可正常使用。
• 里程碑 6：Lint、构建与发布自动化通过。
• 里程碑 7：社区主题提交材料准备完成。