设计原型说明

维刻 Vex · 写下想法，看见脉络。

仓库的 design 目录包含用于评审的 HTML、CSS、JavaScript 和品牌素材，本文件只维护说明。除明确写出仓库根路径外，下文的原型资源路径均相对于 design。Flutter 应用实现在 apps/vex；原型的版本与第三方许可由实际项目数据生成。安装流程页面仍为设计原型。

打开

在仓库根目录运行 node design/scripts/preview.cjs 后访问 http://127.0.0.1:4317/design/index.html。需要 Node.js 和 Python，预览服务会从 docs 自动生成内置文档；未安装第三方 Node / Python 包也可预览，无需访问外部字体或 CDN。

也可先执行 python scripts/sync_builtin_documents.py，再用现代浏览器直接打开 design/index.html。直接打开 HTML 时，改动文档后需重新执行生成命令；预览服务则在请求文档资源时自动更新。生成物被 Git 忽略，离线评审保留生成后的整个 design 目录及下述共享代码字体。

• index.html：桌面、手机、平板及六个平台安装流程的导航。
• Vex.html：桌面工作区，沿用 Vex 原型的布局和主要交互；手机、平板参数自动转到自适应原型。
• Vex-Adaptive.html：手机单页、平板分栏的触控布局。
• Appearance.html：八套配色和六套排版，使用同一篇文章连续比较。
• Vex-Installer-*.html：Windows、macOS、Linux、HarmonyOS、Android、iOS 的安装或获取流程。

Markdown 演示

桌面从视图菜单进入“演示模式”，或按 F5；自适应原型的视图菜单及手机更多菜单也提供入口。标题生成独立页面，--- 可显式分页；支持大纲直达、前后翻页、Home / End、字号调整与 Esc 退出。长页面可滚动，退出保留原工作区布局和编辑位置。演示不会修改源文。

演示栏提供“正文 / 导图”切换，两者共用当前页和大纲。导图翻页会聚焦对应节点；可平移、缩放或查看全图，点击节点定位章节，双击节点回到正文。演示中不提供节点重排或正文修改。

大图总览在低于 20% 且超过 300 个节点时省略无法辨认的节点文字；放大或聚焦章节恢复完整节点。原生实现此时直接绘制卡片，避免同时创建上千个文字与拖动控件。

程序使用相同的分页规则与四语言控制文案。桌面原生演示进入全屏，退出恢复进入前的窗口状态。浏览器支持时请求全屏，不支持时仍可在窗口内演示。assets/presentation.js 与 assets/presentation.css 为桌面、自适应原型共用实现。

品牌与外观

品牌主色统一称为“品牌墨青”，浅色主色值 #24766B。默认外观为纸白背景＋品牌墨青；深色模式使用更明亮的对应强调色。用户选择其他界面配色时，Logo 保持品牌色。

本轮原型统一引用 assets/vex-logo.svg：沿用原 V 形轮廓，改为品牌墨青底、白色 V。安装流程、导航和关于页面共用此素材。本轮不生成原生应用图标或真实安装包。

八套界面配色：品牌墨青、石墨、海蓝、沙金、蔷薇、鸢尾、橄榄、陶朱。每套均覆盖浅色与深色的背景、文字、边框、按钮及选中状态。旧方案中相近的蓝、青、紫色已合并，用中性灰、玫红和橄榄色补足差异。

原十八套排版合并为六套结构不同的阅读样式：

名称	用途	主要区别
简约	日常写作	清爽留白，正文色标题
文档	知识整理	分节细线，清晰层级
书卷	散文与长读	衬线字形、舒展行距、较窄行宽
技术	开发笔记	信息块标题，代码边框，较宽正文
专栏	观点文章	强标题、侧边标记、独立引用
刊物	发布阅读	窄栏、居中节标题、阅读节奏

紧凑间距是独立开关，不再作为一套排版重复计数。正文排版与界面配色独立设置，Markdown 内容不因外观切换改变。桌面、手机和平板共享配色及排版定义；HTML 导出带入所选排版。

工作区和交互

桌面保留 Vex 的文件与大纲、即时编辑与源码、阅读、导图、章节编排、导出、演示和引导。主工作区为单窗口；鸣谢和更新日志是独立文档窗口，不属于拆分工作区。

八种视图组合：即时编辑、源码、阅读、导图、源码＋渲染、源码＋导图、即时编辑＋导图、源码＋渲染＋导图。三视图上方为源码和渲染，下方为整宽导图。所有视图共用当前文档。

可评审即时编辑、源码联动、Markdown 格式插入、查找替换、撤销重做、文件切换、导图平移缩放与折叠、章节改名和正文编辑、新增与移动章节、升降级、删除、原文恢复和引导演练。Markdown / HTML 可下载为副本；高级导出与部分工具仅展示页面状态。浏览器不会自动写回导入的原文件。

导图首批提供单侧树形、双侧平衡、中心放射、向下树形、目录树和鱼骨图，不包含时间轴。桌面、手机和平板共用 D3 hierarchy 布局；切换保留选中与折叠状态，不改变 Markdown 内容或章节顺序，鱼骨图不推断因果关系。演示导图沿用当前选定布局。

七类菜单为文件、编辑、段落、格式、视图、工具、帮助。macOS 使用左侧交通灯、Vex 应用菜单和 Cmd 快捷键。手机保持写作 / 阅读 / 导图单视图，平板最多双栏；HarmonyOS 覆盖手机、平板和电脑原型。

代码块始终预留 32 px 页脚空间，语言输入框仅在编辑时可见，聚焦与失焦不改变块高度。修改正文或语言同步回 Markdown 围栏；Esc 取消本次块编辑。源码行号独立设置。

Mermaid 图表点击后展开上方源码与下方预览，修改后延迟更新；块内交互保持展开，点击外部收起。无效源码保留，并显示错误和过期预览。菜单、对话框、设置详情与图表展开共用短时缓动，并尊重系统减少动态效果和界面动效开关。

偏好与内置文档

偏好设置覆盖通用与文件、编辑器、Markdown、图片、外观、导出和 MCP 七类，普通页面按单项持久化。自动保存默认关闭，停止输入后 2 秒与恢复草稿分别配置。浏览器不写回原文件；启动行为、恢复、自动保存、图片落盘和高级导出等原生能力在本轮仅评审设置，不声称已实现。

外观设置包含文档水印文字、不透明度、正文显示与导出包含，两个开关默认关闭且互不影响。视图菜单可快速显隐正文水印，源码、导图和内置只读文档不加水印；水印不写入 Markdown。HTML 副本会按导出开关包含水印，PDF 为带独立开关的结果预览，不生成实际 PDF。新手引导使用贴近目标的短三角气泡，桌面和平板、手机共用边界避让逻辑。

手机的更多操作与正文排版使用底部面板，不使用桌面级联菜单。常用文档操作集中排列，帮助与关于在面板内单层切换；支持遮罩、关闭按钮、Escape 和标题区域下滑收起，并保留焦点与减少动态效果偏好。写作、阅读、导图、大纲仍通过底部导航切换，平板保留紧凑浮层。

桌面 MCP 原型包含服务、客户端和审计页签，可演练端口与令牌校验、启停、HTTP 配置、stdio 桥接配置、连接测试、读取、修改确认及审计。全部是本地状态模拟，不启动真实服务。mcpScenario=port-busy|unauthorized|timeout 可演练错误。手机和平板不运行常驻服务；内置文档子窗口也不运行 MCP。

偏好设置桌面宽度为 675px，MCP 控件与其他表单一样靠右排列，输入框统一 180px；令牌显隐和重新生成按钮内嵌在输入框右端。关于对话框桌面宽度从 560px 收到 420px，自适应版从 480px 收到 360px，手机仍受屏幕可用宽度约束。

docs/鸣谢.md 和 docs/更新日志.md 是内置文档的唯一正文源。运行 python scripts/sync_builtin_documents.py 生成 design/assets/generated/documents-data.js 与 apps/vex/assets/generated/documents/，不手动编辑或提交生成物。文档随应用安装，不复制到用户目录。桌面原生使用新进程打开，浏览器使用独立窗口模拟；手机和平板继续使用可滚动对话框。

字体策略与原生应用一致：界面／中文使用各平台系统字体及回退链，书卷使用系统宋体；只随应用携带约 0.92 MiB 的 Cascadia Code，原型通过 assets/fonts.css 共享 ../apps/vex/assets/fonts/ 中的两份文件。离线评审应保留这部分目录；没有共享字体时仍可回退到系统等宽字体。应用不额外内嵌 Inter 或完整宋体字库。

目录

路径	内容
assets/vex-logo.svg	原型与安装流程共用墨青 V Logo
assets/desktop/	Vex 桌面原型适配、单窗口工作区及品牌样式
assets/palettes.js / palettes.css	八套配色目录与明暗主题变量
assets/typography-catalog.js / typography.css	六套排版、正文规则及导出样式
assets/tokens.css	导航、移动端与安装流程的基础组件
assets/app.css / app.js	手机和平板布局、示例数据、交互
assets/editor.js / mindmap.js	移动端简化 Markdown 编辑及标题导图
assets/map-layout.js	桌面、移动端和演示共用的六种导图布局
assets/installer.css / installer.js	六个平台安装流程及状态演示

评审参数

应用支持 device=desktop|tablet|phone、platform=windows|macos|linux|harmonyos|android|ios、theme=light|dark|system、palette=weft|graphite|ocean|sand|rose|iris|olive|ember、typography=Simple|Basic|InkBlack|TechnologyBlue|Column|WeChatFormat。

桌面布局：layout=instant|source|read|map|source-render|source-map|instant-map|three；兼容旧的 source-read。手机、平板使用 source-read 表示源码＋阅读。scenario=draft|guide 打开预设评审场景。桌面语言使用 lang=zh-CN|zh-Hant|en-US|ja-JP，移动端 lang=en 仅切换主要导航。新增排版名称与部分交互文案尚未全部翻译。

preview=1 用于导航页内嵌预览，隔离浏览器持久偏好。普通应用页面只保存显示偏好，文档和撤销记录仍在内存中，刷新恢复示例；草稿恢复是预设场景。

安装流程支持 theme=dark、scenario=installed|error。异常场景首次失败，重试可完成。HarmonyOS 增加 device=phone|tablet|desktop；Android 增加 update=1；iOS 演练 GitHub Releases IPA、有效签名和设备授权，scenario=unsigned 展示不可安装状态。六个平台均具备可安装版本后统一通过 GitHub Releases 发布，本轮不发布真实包。

六平台自绘进度使用同一动画变量：百分比随进度移动并在两端避让，不显示复制路径、文件名或解包日志。scenario=installing&progress=46 可固定进度验收；实际点击安装仍会自动推进。macOS 保留拖入应用程序，Linux 保留软件包管理流程，iOS 保留签名与设备授权提示，不将 Windows 自定义安装选项套用到系统安装界面。

元素操作

桌面编辑区、源码和阅读区支持右键及 Shift+F10；分组箭头与标题栏菜单共用 Chevron 图标、尺寸和描边。级联菜单按视口翻转、限制高度，支持方向键、Escape 与点击外部关闭。手机和平板通过编辑区／阅读区标题右侧的更多按钮打开当前元素操作底部面板；文字长按仍交给系统选择菜单。面板固定标题和关闭按钮，只滚动操作列表。

表格在「段落 → 表格」和元素菜单提供行列插入、移动、删除、列对齐、复制、格式化源码及删除表格；表头与唯一列受保护，非表格位置禁用行列命令。不提供 Markdown 不支持的单元格合并。文字选区可剪切、复制 Markdown／HTML 代码／纯文本、粘贴、加粗、斜体、行内代码及删除；段落类型、标题级别、列表缩进和任务状态可转换。链接、图片提供地址复制、修改、取消链接或图片删除，图片支持预览与本地替换。代码块可编辑语言与正文，公式和 Mermaid 支持源码编辑、预览、复制、删除，Mermaid 保留原位展开源码与预览。

所有修改使用当前 Markdown 和现有撤销记录，不写回磁盘；阅读区和内置只读文档不提供修改操作。菜单捕获选区和元素位置，异步粘贴／文件选择前后验证文档是否变化，避免改错文档。剪贴板取决于浏览器授权，不可用时明确提示使用系统快捷键，不显示虚假的成功状态。复杂 Markdown 仍属于原型解析范围，正式编辑行为需在 Flutter 中另行实现和验证。

原型边界

所有安装、授权、替换、修复、移除、更新和商店获取都是状态演示，不修改系统。HarmonyOS 手机、平板和电脑页面是概念原型，正式系统界面与分发方式仍需结合设备和 SDK 验证。版本、包名、签名和获取状态不作为实际已发布信息。

浏览器原型用于评审视觉、布局和交互。应用使用 Flutter 原生渲染，单窗口、以本地文件为中心，代码位于 apps/vex；没有引入 SQLite、账户或云同步。复杂 Markdown、中文输入法、大文档与各平台文件访问、导出仍需持续工程验证，预览构建不代表各平台正式安装包已交付。

桌面设计来源：Vex，https://github.com/dotnet9/Vex 。运行代码已复制适配到本仓库，不依赖原仓库路径。

作者：沙漠尽头的狼 / CodeWF · https://codewf.com