OpenPencil 风格指南解析:health-minimal-mobile-dark——健康追踪类深色移动端界面的完整设计规范与源码实现

原创2026-10-11 17:21:191,689 阅读

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 指南的强制要求)特有的构图纪律:

  1. 顶部节奏紧凑:状态栏、头部与首个内容块应保持连贯,除非设计刻意以图片主导,否则避免出现 80px+ 的空带;
  2. 搜索保持单行干净:一个中性输入框加可选筛选按钮;不要把输入框再包进第二层着色的圆角壳,分组帧保持结构性、透明;
  3. 横向轮播视口帧保持透明:不加白色圆角衬底、不加额外阴影;只有单独的卡片、图片或刻意设计的促销面板才获得填充、圆角或抬升;
  4. 图片卡上的收藏/点赞/书签/心形操作:仅用图标覆盖层或极淡的透明命中区;不要给心形加白色圆形气泡、边框或阴影;
  5. 底部导航集成进屏幕流:用安静的分隔线或激活指示区分,除非提示词明确要求浮动导航,否则避免浮动胶囊导航;
  6. 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(语料守卫测试)。

登录后查看全文
openpencil