OpenPencil 风格指南解析:health-minimal-mobile-dark——健康追踪类深色移动端界面的完整设计规范与源码实现
OpenPencil 风格指南解析:health-minimal-mobile-dark——健康追踪类深色移动端界面的完整设计规范与源码实现
本指南围绕 OpenPencil AI 原生矢量设计工具内置的风格指南语料(style corpus)中的 health-minimal-mobile-dark 展开,逐项拆解这份面向健康追踪、健身监控与健康类应用的深色移动端设计规范:从深炭黑画布、鼠尾草绿强调色到 12–16px 克制圆角与集成式底部导航。读完本文,你将掌握该规范全部色彩 token、排版刻度、间距体系与移动端组合护栏的落地用法,并理解它在 OpenPencil 中如何被解析、按标签选择、结构化提取,以及用于风格切换(re-skin)的源码级机制。
一、风格指南在 OpenPencil 中的定位
OpenPencil 将视觉美学以 Markdown 风格指南的形式内置于技能库中。每个指南是一个带 frontmatter(YAML 子集)的 Markdown 文件,存放在 crates/op-ai-skills/skills/style-guides 目录下,health-minimal-mobile-dark.md 是其中之一。其 frontmatter 声明如下:
---
name: 'health-minimal-mobile-dark'
tags: [wellness, dark-mode, minimal, calm, sage-green, mobile, quiet]
platform: mobile
---
这三个字段在运行时都有实际语义(详见 crates/op-ai-skills/src/style_guide/types.rs):
name:指南的唯一标识,供精确引用(如子代理规格中的spawn_agents.styleguideName);tags:受控词表(STYLE_GUIDE_TAGS),wellness、dark-mode、minimal、calm、sage-green、mobile、quiet均在该词表中,用于按语义评分检索;platform:目标平台枚举之一,mobile对应Platform::Mobile,wire token 为"mobile";未知或缺失时默认回退为webapp。
Style Scope:自包含边界
该指南开篇的 ## Style Scope 明确了使用纪律:本指南自包含,只有在被精确选中时才能应用其调色板、圆角刻度、间距、阴影与组件处理,不得把食物、社交、仪表盘、奢华、终端等其他指南的模式混入本风格;未命名的布局帧默认视为结构性节点——不加填充、描边、圆角或阴影,除非该节点本意是卡片、输入框、按钮、徽章、媒体遮罩或导航表面;避免为组件套装饰性包裹壳,层级关系应来自间距、排版与本指南明确声明的表面。这条"结构性帧默认透明"的约定被审计测试强制检查(见后文"源码级机制")。
二、风格总览:安静、聚焦的深色健康画布
## Style Summary 对该风格的定性是:为健康追踪、健身监控与健康应用设计的平静、专注的深色移动界面。
- 安神的深色画布:深炭黑背景
#111111减少清晨或深夜健康打卡时的眼部疲劳; - 生命绿强调色:
#22C55E传达生长、健康与积极进展,规避了蓝色的临床冰冷感与红色的警报感; - 隐形字体:Inter 中等字重,可读性高到"隐形",让数据自己说话——用户在扫读心率、步数、睡眠指标时不会被字体抢戏;
- 克制圆角:12–16px 圆角干净实用,不过分圆润;
- 数据清晰度:指标周围留白充足,层级明确,支持一眼扫读;
- 集成式底部导航:全宽底部导航配绿色激活指示。
三、色彩系统全表
核心背景(Core Backgrounds)
| Token | Value | 用途 |
|---|---|---|
| Page Background | #111111 |
根屏幕背景(深炭黑) |
| Card Surface | #1A1A1A |
标准卡片、指标容器 |
| Elevated Surface | #222222 |
悬浮卡片、模态底衬 |
| Subtle Surface | #161616 |
内嵌区域、分组区块 |
| Tab Bar Surface | #1A1A1A |
集成式底部导航表面 |
文本颜色(Text Colors)
| Token | Value | 用途 |
|---|---|---|
| Primary Text | #F5F5F5 |
标题、指标数值、主标签 |
| Secondary Text | #A3A3A3 |
正文、描述 |
| Tertiary Text | #6B6B6B |
时间戳、说明文字、非激活标签 |
| Muted Text | #3B3B3B |
占位符、禁用文本 |
| Accent Text | #22C55E |
激活状态、正向数值、目标进度 |
边框颜色(Border Colors)
| Token | Value | 用途 |
|---|---|---|
| Default Border | #2A2A2A |
卡片边框、分隔线 |
| Subtle Border | #1E1E1E |
浅分隔线 |
| Active Border | #22C55E |
聚焦输入框、激活标签指示 |
强调色(Accent Colors)
| Token | Value | 用途 |
|---|---|---|
| Primary Accent | #22C55E |
激活状态、主按钮、进度条、标签指示 |
| Accent Light | #22C55E15 |
着色背景、选中行高亮 |
| Accent Muted | #22C55E20 |
徽章淡填充、进度轨道背景 |
| Accent On-Dark | #111111 |
绿色背景上的深色文字/图标 |
| Success | #22C55E |
目标达成、训练完成(与强调色相同) |
| Warning | #F59E0B |
静息过久、补水提醒 |
| Error | #EF4444 |
错过训练、异常读数 |
| Rest | #8B5CF6 |
睡眠追踪、恢复模式(柔和紫罗兰) |
设计上的刻意安排:Success 与 Primary Accent 同色(#22C55E),保证"积极进展"语义一致;Rest 用柔和的 #8B5CF6 而非蓝,区分"睡眠/恢复"与"呼吸/心率"类指标;#22C55E15、#22C55E20 是带 alpha 的绿色(15/20 透明度),用于不喧宾夺主的淡背景。
从源码看,## Color System 小节是结构化提取的目标区:解析器按 ### Accent Colors / ### Text Colors 子节顺序优先取值,逐行抓取首个 #RRGGBB(第 7 位十六进制数字会使该匹配失效),产出 background、surface、accent、text_primary、text_secondary、text_muted、border 七个颜色通道(见 crates/op-ai-skills/src/style_guide/parser.rs 的 extract_colors)。
四、排版系统
字体家族
| Role | Family | 用途 |
|---|---|---|
| Display / Heading | Inter | 屏幕标题、分区标题、指标标签 |
| Body / Functional | Inter | 正文、标签、按钮、导航 |
单一 Inter 家族贯穿全部角色,正是"隐形字体"策略的体现:不加衬线、不做双字体对比,最大程度让位给数据。
字阶(Type Scale)
| Level | Size | Font | Weight | 用途 |
|---|---|---|---|---|
| Display | 36px | Inter | 600 | 英雄指标值(步数、心率) |
| Title 1 | 22px | Inter | 600 | 屏幕标题 |
| Title 2 | 17px | Inter | 500 | 分区标题 |
| Title 3 | 15px | Inter | 500 | 卡片标题、指标分类 |
| Body | 14px | Inter | 400 | 描述、注释、训练详情 |
| Label | 13px | Inter | 500 | 字段标签、按钮文字 |
| Data | 14px | Inter | 600 | 指标值、统计、时长 |
| Caption | 12px | Inter | 400 | 时间戳、次要信息 |
| Small | 11px | Inter | 500 | 徽章、单位标签 |
| Micro | 10px | Inter | 500 | 标签栏文字(大写)、微型徽章 |
字重(Font Weights)
| Weight | Value | 用途 |
|---|---|---|
| Regular | 400 | 正文、描述、说明文字 |
| Medium | 500 | 标签、按钮、分区标题、卡片标题 |
| Semibold | 600 | 屏幕标题、英雄指标、数据值 |
字间距(Letter Spacing)
- Display(36px):
-0.5px - 分区标题(15–22px):
-0.3px - 大写标签栏文字:
+1px - 正文:
0px
行高(Line Height)
- Display(36px):
1.0 - 标题(15–22px):
1.2 - 正文(14px):
1.5 - 说明文字(10–12px):
1.4
排版区的 ### Font Families 表格同样被解析器结构化读取:按 Role 关键词(display/heading/logo/serif、body/functional/ui、data/mono)匹配 display_font、body_font、data_font,未命中时按行位置回退(见 parser.rs 的 extract_typography)。
五、间距与布局体系
间距刻度(Gap Scale)
| Value | 用途 |
|---|---|
| 2px | 紧凑行内配对 |
| 4px | 标签图标到文字、单位标签到数值 |
| 6px | 状态指示器到文字 |
| 8px | 紧凑指标组、进度环标签 |
| 12px | 列表项之间、网格内指标卡片 |
| 16px | 卡片内部区块 |
| 20px | 列表中卡片之间 |
| 24px | 内容内分区间隙 |
| 32px | 顶层屏幕分区断点 |
内边距刻度(Padding Scale)
| Value | 用途 |
|---|---|
| [0, 24] | 屏幕内容包裹层(仅水平) |
| [12, 21, 21, 21] | 标签栏分区外内边距 |
| 4px | 集成式标签栏内部内边距 |
| [8, 16] | 输入框、紧凑按钮 |
| [10, 20] | 标准按钮 |
| [12, 24] | 大按钮、CTA 按钮 |
| 16px | 紧凑卡片内边距、指标磁贴 |
| 20px | 标准卡片内边距 |
| 24px | 功能卡片内边距、英雄指标区 |
布局模式(Layout Pattern)
- 屏幕宽度:402px(移动端)
- 内容包裹层:padding
[0, 24],垂直排列,gap 24 - 状态栏:62px,标准 iOS
- 集成式标签栏:高度 62–72px,cornerRadius 0–12,padding 0–4,随页面流全宽铺开(非浮动胶囊)
- 标签项:fill_container、垂直、gap 4、居中对齐
- 指标网格:2 列网格、12px gap、等宽磁贴
- 进度环:卡片内居中,数值置于环内
移动端组合护栏(Mobile Composition Guardrails)
这是该指南(也是所有 platform: mobile 指南的强制要求)特有的构图纪律:
- 顶部节奏紧凑:状态栏、头部与首个内容块应保持连贯,除非设计刻意以图片主导,否则避免出现 80px+ 的空带;
- 搜索保持单行干净:一个中性输入框加可选筛选按钮;不要把输入框再包进第二层着色的圆角壳,分组帧保持结构性、透明;
- 横向轮播视口帧保持透明:不加白色圆角衬底、不加额外阴影;只有单独的卡片、图片或刻意设计的促销面板才获得填充、圆角或抬升;
- 图片卡上的收藏/点赞/书签/心形操作:仅用图标覆盖层或极淡的透明命中区;不要给心形加白色圆形气泡、边框或阴影;
- 底部导航集成进屏幕流:用安静的分隔线或激活指示区分,除非提示词明确要求浮动导航,否则避免浮动胶囊导航;
- 9999px 圆角仅用于真圆或微型胶囊:如头像、状态点、短徽章;绝不用于页面区块、搜索壳、轮播、卡片操作按钮或完整导航栏。
六、圆角规范(Corner Radius)
| Value | 用途 | 理由 |
|---|---|---|
| 8px | 小按钮、紧凑徽章、进度胶囊 | 最小功能化软化 |
| 12px | 标准卡片、指标容器、输入框 | 主容器圆角 |
| 14px | 大卡片、分组区块 | 数据容器的舒适圆角 |
| 16px | 英雄卡片、模态底衬、功能区块 | 最大标准圆角 |
| 9999px | 仅头像、状态点、短徽章 | 语义性微元素的真圆/胶囊;绝不用于导航、搜索、轮播或卡片操作按钮 |
设计理由(原文):克制的 12–16px 圆角反映了健康追踪应用"实事求是、不装点"的哲学——用户查看生命体征时需要的是清晰而非装饰;紧凑的圆角区间(12–16px,对比活泼风格常见的 12–24px)强化了"数据优先于装饰"的安静自信。源码中,圆角也是可结构化提取的通道之一:解析器在 ## Corner Radius 节内扫描 <数字>px,按行内关键词(card/standard/container、button/input/small)提取 card 与 button 两个圆角值(parser.rs 的 extract_radius)。
七、图标体系
图标字体
- 家族:Lucide
- 风格:Outline,圆角连接与圆头(干净、极简的描边)
常用图标清单
heart、activity、footprints、flame、droplet、moon、sun、dumbbell、timer、clock、target、trophy、apple、salad、bed、thermometer、wind、eye、scale、ruler、plus、minus、check、x、chevron-right、trending-up、trending-down、bar-chart-2
图标尺寸
| Size | 用途 |
|---|---|
| 14px | 行内指示器、小徽章 |
| 18px | 标签栏图标、列表项前置图标 |
| 20px | 卡片操作图标、指标分类图标 |
| 24px | 头部操作、通知铃铛、突出按钮 |
图标颜色状态
| State | Color | 用途 |
|---|---|---|
| Active | #22C55E |
选中标签、激活状态、绿色高亮 |
| Default | #6B6B6B |
非激活标签、次要操作 |
| Muted | #3B3B3B |
禁用状态、占位图标 |
| On Accent | #111111 |
绿色背景上的图标(深色) |
图标颜色状态与文本/边框 token 保持同一套语义层级:激活用绿、默认用三阶灰 #6B6B6B、禁用用更深的 #3B3B3B、绿底上用 #111111——与 Accent On-Dark 规则一致。
八、源码级机制:这份规范如何在 OpenPencil 中生效
1. 加载与解析(frontmatter)
风格指南由独立的 loader 解析(与技能注册表隔离,技能注册表明确跳过 style-guides/ 子树,见 crates/op-ai-skills/src/loader.rs)。crates/op-ai-skills/src/style_guide/loader.rs 中的 parse_style_guide_file 读取 name / tags / platform 三个字段,并把完整原始 Markdown 作为 content 保留——该 content 会被逐字注入生成提示词(TS 平价行为)。frontmatter 本身由 crates/op-ai-skills/src/frontmatter.rs 的 YAML 子集解析器处理(支持 key: value、跨行 [a, b] 数组、# 注释剥离),保证 crate 零额外依赖。
2. 选择机制:名称优先、标签评分兜底
select_style_guide(loader.rs)的决策逻辑:
- 传了
name时,直接按名称匹配(可选叠加platform约束),名称精确匹配优先于标签——这是子代理可复现性契约:父代理记录一个指南名后,所有子代理按名查询必须拿到同一个指南; - 未传名称时,先按 platform 过滤候选(
mobile请求只会看到platform: mobile的指南),再对请求标签集合计算 Jaccard-like 评分(命中标签数 ÷ 请求标签数),最高分胜出;同分时取注册表序更靠前者(与 TS 排序行为一致); - 没有任何匹配时返回
None,调用方回退到style-defaults.md。
也就是说,只要生成请求携带 wellness、dark-mode、minimal、calm、sage-green、mobile、quiet 等标签中的多个,本指南就很可能被命中;而 platform 约束确保移动端请求不会误选 Webapp 指南。
3. 结构化提取与风格切换(re-skin)
crates/op-ai-skills/src/style_guide/parser.rs 的 extract_style_guide_values 把指南的 ## Color System / ## Typography / ## Corner Radius 三节降维成 StyleGuideValues:7 个颜色通道、3 个字体通道、2 个圆角标量(card/button)。在此基础上,crates/op-ai-skills/src/style_guide/mapping.rs 的 build_style_mapping 对两份指南做差,产出 PropertyReplacement——一组 from → to 替换对,按 fill(背景/表面/强调)、text(主/次/弱文本)、stroke(边框)、font_family、corner_radius 分通道。这份映射正是 replace_all_matching_properties MCP 工具消费的输入:把一张已按 A 风格绘制的画布整体重绘成 B 风格。例如从暖色浅色风格切到本深色风格时,背景 #FFFFFF → #111111、主文本 #1F1F1F → #F5F5F5、卡片圆角按映射批量替换。
4. 对比度校验(可访问性兜底)
crates/op-ai-skills/src/color/contrast.rs 实现了 WCAG 相对亮度与对比度比计算(L = 0.2126R + 0.7152G + 0.0722B 线性化后 (L1+0.05)/(L2+0.05)),并对 primary/secondary/muted 前景与 primary/secondary/tertiary 表面、以及所有 on-surface.* / on-accent.* 组合按 4.5:1 目标扫描,产出 ContrastReport。on_color 则基于 OKLCh 明度与饱和度自动决定深/浅前景色——本指南"Accent On-Dark #111111"这类规则在代码里被一般化为:背景明度 < 0.5 用白、否则用深色 #0F172A。因此本指南 #111111 深底配 #F5F5F5 主文本的层级是有自动校验保障的。
5. 审计测试:规范结构的机器守卫
仓库用测试把这份指南的关键约定固化为不变量(见 crates/op-ai-skills/src/style_guide/loader.rs 与 crates/op-ai-skills/src/style_guide/audit_tests.rs):
- 每个指南必须声明
## Style Scope与 "This guide is self-contained"——防止跨指南视觉泄漏; - 每个指南必须包含 "Treat unnamed layout frames as structural by default"——防止布局帧被装饰化;
- 每个 mobile 指南必须包含
### Mobile Composition Guardrails、单行搜索、透明轮播视口、禁止心形白色气泡等约束; - 全部指南禁用 "Pill tab bar"、"bottom navigation pill"、"cornerRadius 100"、"100px" 等强制的胶囊导航措辞——与本文档"集成式底部导航而非浮动胶囊"的护栏一一对应;
- tag 词表卫生:
STYLE_GUIDE_TAGS只允许[a-z0-9-_]、无空格/冒号/引号/#、无重复; - 精确名称查找契约:对注册表内每个指南,
select_style_guide(name)必须原样返回该指南,保证子代理风格可复现。
6. 界面侧呈现:摘要色板与悬停卡片
在编辑器聊天面板中,被固定的风格指南会以"收据"形式展示:style_guide_summary(crates/op-ai-skills/src/style_guide/summary.rs)提取背景、表面、强调、主文本四枚色板并缓存;悬停时 StyleGuideCard(crates/op-ai-skills/src/style_guide/card.rs)展开到最多 8 个色板、display/body 字体与指南自述,并标注来源(内置语料 or 用户导入的 user:<slug>)。两份缓存都在导入指南变更时同步失效,确保"固定的是什么风格"永远可见、可核对。
九、在 OpenPencil 中应用该风格的要点
- 触发方式:生成请求带
mobile平台约束且标签命中wellness/dark-mode/minimal/calm/sage-green/quiet的组合时,本指南作为候选参与评分;名称直接指定health-minimal-mobile-dark则无条件命中(叠加 platform 校验)。 - 落地纪律:遵循 Style Scope——把未命名帧当结构、不为组件加包裹壳;遵循移动端护栏——搜索单行、轮播透明、心形不加白泡、底部导航集成进页面流而非浮动胶囊;9999px 只留给头像/状态点/短徽章。
- 验证方式:可在本仓库运行
op-ai-skills相关测试(如cargo test -p op-ai-skills),审计测试会断言语料中每个指南(含本文档)满足上述结构不变量;若测试失败即说明数据缺陷而非断言错误。 - 切换风格:通过
build_style_mapping生成的替换映射,可用replace_all_matching_properties把现有设计从其他风格一键重绘为本深色健康风格——色彩、字体、圆角按通道批量替换。
核心参考文件:health-minimal-mobile-dark.md(规范原文)、loader.rs(解析与选择)、parser.rs(结构化提取)、mapping.rs(风格切换映射)、contrast.rs(WCAG 对比度)、audit_tests.rs(语料守卫测试)。