深度定制ZenNotes：编写自定义CSS主题与覆盖设计令牌实战指南

【免费下载链接】zennotesKeyboard-first local Markdown notes with Vim motions, diagrams, and MCP integration.项目地址: https://gitcode.com/gh_mirrors/zenn/zennotes

ZenNotes 是一款键盘优先的本地 Markdown 笔记应用，除了 Vim 手势、图表与 MCP 集成，它还内置了一套接近 Obsidian 级别的自定义 CSS 主题系统。通过本指南，你可以用纯文本文件重写整个界面的配色、字体与圆角：编写一个theme.css覆盖全部--z-*设计令牌，叠加overrides文件微调任意组件，甚至不写代码就能用 Quick Tweaks 换色。所有改动都在~/.config/zennotes/下实时生效，随你的 dotfiles 同步。

ZenNotes 主题定制：三层架构速览

在动手之前，先理解 ZenNotes 的样式分层——主题（Themes）、覆盖（Overrides）、快速调整（Quick Tweaks），它们按固定顺序注入页面，后写的层赢级联：

1. 自定义主题：themes/<slug>/文件夹，只注入当前激活主题的 CSS，换主题互不串扰 🎨
2. 覆盖文件：overrides/*.css，叠加在任何主题之上，适合"换个主题也想保留的私货样式"
3. Quick Tweaks：设置面板里的色板与预设，注入在最顶层，优先级最高

下面这张 ZenNotes 暗色界面截图就是主题令牌作用后的效果——侧边栏、标签页、画布底色全部来自--z-*变量：

第一步：如何创建自定义主题文件夹

主题就是一个放进配置目录的文件夹，文件夹名即主题 ID：

~/.config/zennotes/ └── themes/ └── my-theme/ ├── manifest.json # 名称、作者、版本、描述、modes ├── theme.css # 主题样式（必需） └── my-font.woff2 # 可选：字体/图片资产

manifest.json最小可用示例：

{ "name": "My Theme", "author": "you", "version": "1.0.0", "description": "A short description.", "modes": "both" }

• modes取"light"/"dark"/"both"；preview色板仅用于设置页的色块展示
• 缺失 manifest 也能工作：主题会以文件夹名显示并假定支持双模式
• 更省事的方式：在Settings → Appearance → Custom themes点New theme，应用会自动生成中性浅色/暗色起始令牌，你只管改色

首次运行时，应用会自动种入一个完整示例主题Soft Paper（移植自 Nick Milo 的同名 Obsidian 主题）和一份 README 说明，照着改即可。加载逻辑见 apps/desktop/src/main/custom-themes.ts。

设计令牌 --z-* 完全速查表：theme.css 怎么写

ZenNotes 的颜色全部收敛在一组--z-*CSS 变量上（定义于 packages/app-core/src/styles/index.css）。注意令牌值是空格分隔的 RGB 三元组，方便 Tailwind 写透明度：

一个支持明暗双模式的最小主题骨架——暗色覆盖写在[data-theme-mode="dark"]下，永远不要硬编码主题名：

:root { --z-bg: 255 255 255; --z-fg-1: 29 29 31; --z-accent: 0 122 255; } :root[data-theme-mode="dark"] { --z-bg: 28 28 30; --z-fg-1: 255 255 255; --z-accent: 10 132 255; }

除了令牌，你还可以写任意 CSS：自定义字体（@font-face+--z-text-font）、背景纹理、组件级调整。下面这张截图里的语法着色与链接配色，正是--z-*令牌在编辑器中的真实呈现：

⚠️ 字体与图片资产必须与theme.css同目录，并通过zen-theme://my-theme/my-font.woff2引用；远程http(s)地址一律不会被加载，这是安全红线。

覆盖任意 UI 细节：overrides 文件编写步骤

只想改一处细节、又不想动整个主题？把.css文件丢进~/.config/zennotes/overrides/，然后在Settings → Appearance → Overrides里开启即可。启用中的覆盖文件按文件名顺序拼接后注入在主题之后，因此：

• 用:root[data-theme] {}作选择器，可同时压过内置主题与自定义主题
• 远程 URL 同样被禁止加载

应用自带的example.css是一本"配方手册"（默认全部注释，不影响外观），里面给了几个现成配方：

/* 所有主题上更冲的强调色 */ :root[data-theme] { --z-accent: 255 59 48; } /* 仅暗色模式：OLED 纯黑背景 */ :root[data-theme-mode="dark"] { --z-bg: 0 0 0; --z-bg-softer: 12 12 12; }

完整令牌清单与配方见 apps/desktop/src/main/overrides.ts。

不写代码也能换配色：Quick Tweaks 颜色与预设

不想碰 CSS？Settings → Appearance → Quick Tweaks提供一套经过可读性筛选的免代码控制：

• 色板：强调色 + 6 个语法/诊断色，点色块直接换
• Density 密度预设：Compact / Default / Comfortable，同步缩放编辑器标签条与侧边栏、笔记列表行高（紧凑模式下笔记行还会收起为一行摘要）
• Corners 圆角预设：Square / Default / Rounded，通过全局--z-radius-scale乘子一次性方化或柔化所有圆角

面板内置实时预览，改色即刻可见。选中的值以themeTweaks存入可携带配置，并注入为最顶层样式，确保"手动选的一定赢"。预设的度量来源见 packages/shared-domain/src/overrides.ts。

实时生效与开发者工具：改完立刻看见

• 主题与覆盖目录都被文件监听器盯着（200ms 防抖），编辑器里保存一下，界面立即刷新，无需重启 ⚡
• 设置页的Developer tools按钮可打开检查器：点选任意元素、找出它的类名与令牌，再回头写 CSS，调试闭环很短
• 三层样式的注入顺序（active-theme → overrides → tweaks）在渲染端由 packages/app-core/src/lib/custom-themes.ts 保证，切换明暗模式时无需重新注入

延伸阅读：源码与文档路径

从一个文件夹、一份theme.css起步，ZenNotes 的外观就完全由你定义——改配色是十分钟的事，改字体和圆角只需两行 CSS 🎨

【免费下载链接】zennotesKeyboard-first local Markdown notes with Vim motions, diagrams, and MCP integration.项目地址: https://gitcode.com/gh_mirrors/zenn/zennotes