OpenPencil 极简深色风格指南全解析:midnight-minimal-dark 设计系统落地指南
OpenPencil 极简深色风格指南全解析:midnight-minimal-dark 设计系统落地指南
本篇技术指南以 OpenPencil 开源仓库内置的视觉风格指南 crates/op-ai-skills/skills/style-guides/midnight-minimal-dark.md 为骨架,完整讲解其色彩、排版、间距、圆角与图标规范,并深入其背后的技能引擎实现——从 frontmatter 解析、风格注册表加载、结构化值提取到风格切换映射。读完本文,你将能够:直接读懂并复用这套极简深色 Web 应用设计系统;理解风格指南如何被 OpenPencil 的 AI 技能引擎(op-ai-skills crate)消费与选择;掌握编写同构风格指南所需的全部字段与约束。
风格定位:克制的深色工作空间
midnight-minimal-dark 是一套面向 webapp 平台的极简深色风格指南,其核心美学主张是"以克制换取宁静":深石板色(#0F172A)构成安静的海军蓝黑画布,天蓝色(#38BDF8)只出现在交互反馈场景——激活态、链接与关键指示器;全站仅使用 Inter 一种字体家族,通过字重(400–600)而非字体切换来建立层级。
指南用六个关键词概括自身气质(全部来自受控标签词表):
| 标签 | 含义维度 |
|---|---|
minimal、clean、austere |
视觉:极简、干净、朴素 |
dark-mode |
色调:深色模式 |
calm、quiet |
情绪:平静、安静 |
blue-accent |
强调色:蓝色系 |
Style Scope:风格隔离与结构性默认
该指南开篇即声明 Style Scope(风格适用范围):本指南是自包含(self-contained)的,只有在该指南被精确选中时才应用其调色板、圆角刻度、间距、阴影与组件处理方式;不得把 food、social、dashboard、luxury、terminal 等其他指南的模式借用进来。同时规定了两个结构性默认:
- 未命名的布局 frame 默认视为结构性容器:除非节点本身是卡片、输入框、按钮、徽章、图片遮罩、导航面等可见组件,否则不施加 fill、stroke、cornerRadius 或 shadow;
- 避免给组件套装饰性外壳,层级应当来自间距、排版以及本指南明确规定的表面(surface)。
这一约束并非仅仅写作习惯——style_guide/audit_tests.rs 中的审计测试断言每个风格指南都必须包含 ## Style Scope、"This guide is self-contained" 与 "Treat unnamed layout frames as structural by default" 三段契约文本,缺一则测试失败。也就是说,"风格隔离 + 结构默认"是 OpenPencil 全部风格语料的结构性不变量,而不是某一篇的偶然写法。
色彩系统:Slate 底色 + Sky 强调
色彩系统是这套风格的核心。总体原则:背景使用 Tailwind slate 色系(#0F172A、#1E293B)营造偏冷的蓝灰基调;#38BDF8(sky 400)只出现在需要交互反馈的地方。
核心背景色(Core Backgrounds)
| Token | 值 | 用途 |
|---|---|---|
| Page Background | #0F172A | 页面根背景(slate 900) |
| Card Surface | #1E293B | 卡片、面板、抬升容器(slate 800) |
| Sidebar Surface | #0F172A | 导航侧边栏背景 |
| Inset Surface | #162032 | 输入框、嵌套容器 |
| Hover Surface | #1E293B80 | 微妙 hover 高亮(50% 透明度) |
注意 Sidebar Surface 与 Page Background 同值——侧边栏并不额外加深,靠的是内容区卡片的 #1E293B 与之形成对比;Hover Surface 带 80 透明度后缀,是"隐形镀铬"哲学的直接体现。
文本色(Text Colors)
| Token | 值 | 用途 |
|---|---|---|
| Primary Text | #F1F5F9 | 标题、指标数值、主要内容(slate 100) |
| Secondary Text | #94A3B8 | 正文、描述、次级标签(slate 400) |
| Tertiary Text | #64748B | 时间戳、说明文字、非活跃元素(slate 500) |
| Muted Text | #475569 | 占位符、禁用态(slate 600) |
| Accent Text | #38BDF8 | 激活导航、链接、高亮(sky 400) |
边框色(Border Colors)
| Token | 值 | 用途 |
|---|---|---|
| Default Border | #1E293B | 卡片边框、分隔线(slate 800) |
| Subtle Border | #162032 | 区块分隔、细分隔线 |
| Active Border | #38BDF8 | 聚焦输入框、激活指示器 |
| Active Muted Border | #38BDF840 | 25% 透明度聚焦环 |
强调色(Accent Colors)
| Token | 值 | 用途 |
|---|---|---|
| Primary Accent | #38BDF8 | 激活态、链接、聚焦指示器(sky 400) |
| Accent Subtle | #38BDF820 | hover 背景、选区着色 |
| Accent Glow | #38BDF830 | 激活元素上的微妙光晕 |
| Success | #34D399 | 正向指标(emerald 400) |
| Error | #F87171 | 错误态(red 400) |
| Warning | #FBBF24 | 警告、提醒(amber 400) |
强调色体系呈现清晰的"阶梯式收敛":主强调色 #38BDF8 是唯一饱和色,强调色细分为 Subtle(20% 透明度)、Glow(30% 透明度)两级弱化版本,而 Success / Error / Warning 三个状态色各自独立承担语义。从 style_guide/parser.rs 的提取逻辑可以看到,这套表格的 ## Color System → ### Accent Colors → Primary Accent 结构正是引擎定位强调色的标准语法:extract_colors 优先在 "accent color" 子区块中按 "primary accent" 标签查找首个 #RRGGBB,从而保证每个指南提取出的 accent 语义一致。
排版系统:单一字体家族的层级艺术
字体家族
| Role | 家族 | 用途 |
|---|---|---|
| Everything | Inter | 全部文本——标题、正文、标签、数据、说明 |
字阶(Type Scale)
| 层级 | 字号 | 字体 | 字重 | 用途 |
|---|---|---|---|---|
| Display | 36px | Inter | 600 | 大指标数值、主计数器 |
| Title 1 | 24px | Inter | 600 | 章节标题 |
| Title 2 | 18px | Inter | 600 | 卡片标题、子章节标题 |
| Title 3 | 15px | Inter | 500 | 列表项标题、面板头 |
| Body | 14px | Inter | 400 | 描述、正文 |
| Body Large | 16px | Inter | 400 | 引导段、突出描述 |
| Label | 12px | Inter | 500 | 字段标签、导航项、列头 |
| Caption | 11px | Inter | 400 | 时间戳、元数据 |
| Micro | 10px | Inter | 500 | 状态徽章、辅助标签 |
字重(Font Weights)
| 字重 | 值 | 用途 |
|---|---|---|
| Regular | 400 | 正文、描述、说明文字 |
| Medium | 500 | 标签、列表标题、导航项 |
| Semibold | 600 | Display、标题、卡片标题——最大字重上限 |
Semibold(600)是该指南的字重天花板:即使是最重要的 Display 数值也只用 600,绝不引入 Bold 或 Black。这是"用大小和字重而非字体切换建立层级"的具体化。
字距(Letter Spacing)
- Display(36px):-0.5px(轻微收紧)
- 章节标题(24px):-0.3px
- 大写标签:+1px
- 正文:0px
行高(Line Height)
- Display(36px):1.1
- 标题(18–24px):1.2
- 正文(14–16px):1.5
- 说明文字(10–11px):1.4
引擎侧对排版的处理值得注意:parser.rs 的 extract_typography 会读取 ## Typography → ### Font Families 表格,按 role 关键词(display/heading/serif → display_font;body/functional/ui → body_font;data/mono → data_font)提取字体家族。midnight-minimal-dark 的 "Everything → Inter" 写法意味着三个通道都会解析为 Inter,这会让 build_style_mapping 在与其他多字体指南切换时生成完整的 from → to 字体替换。
间距系统:让内容呼吸的节奏
间距刻度(Gap Scale)
| 值 | 用途 |
|---|---|
| 4px | 行内图标+文本组合 |
| 8px | 状态指示器组、紧凑区块 |
| 12px | 列表项之间、按钮组 |
| 16px | 卡片内分区、导航项间距 |
| 20px | 表单字段组、面板分区 |
| 24px | 网格中的卡片间距 |
| 32px | 内容区主要章节 |
| 40px | 顶层页面区块分隔 |
内边距刻度(Padding Scale)
| 值 | 用途 |
|---|---|
| [12, 16] | 侧边栏导航项 |
| [10, 16] | 标准按钮 |
| [8, 16] | 输入框 |
| 20px | 卡片内边距(紧凑) |
| 24px | 标准卡片内边距 |
| [28, 32] | 内容区内边距 |
| [32, 40] | 内容区宽松间距 |
数组记法 [垂直, 水平] 对应设计工具的 padding 语义,这是该语料的标准写法。24–40px 的大间距是"冷静间距(Calm spacing)"原则的来源——章节间留白让内容自由呼吸,而不是靠边框划分区域。
布局模式(Layout Pattern)
- 屏幕宽度:1440px
- 侧边栏:240px 宽、垂直排布、
space_between分布、图标 + 文本导航 - 内容区:宽度
fill_container、高度fit_content、垂直排布、gap 32–40、padding [28, 32] - 分区间距:宽松留白让内容呼吸
- 侧边栏激活指示:激活项左侧 2px 天蓝边框 + 微妙强调背景
这份布局模式对引擎生成的结构化字段(fill_container / fit_content / space_between)与 schema.md 等生成期技能要求的节点属性语法保持了一致,便于 Agent 直接把指南翻译成画布节点。
圆角系统:8–12px 的温和表面
| 值 | 用途 | 设计理由 |
|---|---|---|
| 0px | 分隔线、全宽分隔条 | 扁平结构元素 |
| 6px | 徽章、输入框、小按钮 | 紧凑交互元素 |
| 8px | 按钮、下拉框、列表项 | 标准交互圆角 |
| 10px | 标准卡片、面板 | 主容器圆角 |
| 12px | 大卡片、弹窗、特色区块 | 最大圆角——柔和而平静 |
设计理由:8–12px 区间创造出柔和、亲切但不失现代感的观感,圆角圆润到"欢迎"的程度,却不会走向俏皮或圆润过度。中等圆角形成温和安静的表面,不争夺注意力——一切让位于内容。引擎的 extract_radius 会按行匹配关键词:含 "card/standard/container" 的行取作 card 半径(此处为 10px),含 "button/input/small" 的行取作 button 半径(此处为 8px),供后续风格切换与样式摘要使用。
图标规范:Lucide 描边体系
图标字体
- 家族:Lucide
- 风格:描边式(Outline),圆角连接与圆头端点
常用图标清单
layout-dashboard、bar-chart-2、users、settings、folder、file-text、search、bell、chevron-right、chevron-down、plus、x、check、trending-up、trending-down、calendar、clock、download、upload、filter、eye、lock、inbox、bookmark、archive
图标尺寸
| 尺寸 | 用途 |
|---|---|
| 14px | 行内指示器、微妙操作 |
| 18px | 侧边栏导航图标、列表项 |
| 20px | 卡片头图标、操作按钮 |
| 24px | 主导航图标、头部操作 |
图标颜色状态
| 状态 | 颜色 | 用途 |
|---|---|---|
| Active | #38BDF8 | 选中导航、激活态 |
| Default | #94A3B8 | 非激活导航、次要操作 |
| Muted | #475569 | 禁用图标、占位态 |
| On Surface | #F1F5F9 | 抬升表面上的图标 |
图标颜色状态与文本色表一一呼应:Active 用主强调色、Default 用次级文本色、Muted 用弱化文本色、On Surface 用主文本色——同一个 slate/sky 色板贯穿全部视觉通道,这就是"单色板体系"的完整闭环。
引擎视角:这份指南如何被 OpenPencil 消费
以上所有规范并非孤立文档,而是被 op-ai-skills crate 的完整管线所加载、解析与使用。理解这条链路,才能把"风格指南"真正用起来。
1. frontmatter 元数据解析
指南开头是 YAML 子集 frontmatter(name / tags / platform),由 frontmatter.rs 的 split_frontmatter / parse_array 解析。style_guide/types.rs 定义 StyleGuideMeta(name + tags + platform)与受控标签词表 STYLE_GUIDE_TAGS——midnight-minimal-dark 的 7 个标签全部落在词表内(minimal、dark-mode、calm、quiet、blue-accent、clean、austere)。Platform::Webapp 是默认平台,未知 platform 字符串也回退到 webapp(Platform::from_str 的 _ => Platform::Webapp)。
2. 注册表加载与选择
style_guide/loader.rs 在首次调用时把 style-guides/ 目录下全部 *.md 文件解析进 style_guide_registry()(编译期经 include_dir! 嵌入,无运行时文件 IO,可在 wasm32 上运行)。select_style_guide 的选型逻辑是:
- 显式提供
name时按名称精确匹配(可叠加 platform 约束); - 否则按 Jaccard 式标签得分排序:
match_score = 命中的请求标签数 / 请求标签总数,得分最高者胜出,平分时取注册表顺序靠前者。
因此当你请求 "minimal dark webapp" 时,引擎会提取出 minimal、dark-mode、webapp 等标签,与各指南做标签重叠打分,midnight-minimal-dark 即典型命中者之一。
3. 规划阶段的风格选择技能
style-guide-selector.md 是规划(planning)阶段的 Base 技能(trigger: null 即无条件启用,priority 3):它把可用风格清单注入给 Agent,要求按规则选型——用户显式命名风格则按名称/主标签匹配,否则从请求推断 3–5 个标签("dark" → dark-mode,"clean" → minimal 等)并按标签重叠度选最佳匹配,最终把 styleGuideName 写进 plan 输出。若没有合适匹配,则省略 styleGuideName,系统回退到 style-defaults.md 的默认浅色策略(其触发条件正是 flags: [noStyleGuideMatch])。
4. 结构化值提取与风格切换
style_guide/parser.rs 的 extract_style_guide_values 会把指南正文解析为结构化三通道:StyleColors(background/surface/accent/text_primary/text_secondary/text_muted/border)、StyleTypography(display_font/body_font/data_font)、StyleRadius(card/button)。对 midnight-minimal-dark 而言,可稳定提取出:
background: #0F172A surface: #1E293B accent: #38BDF8
text_primary: #F1F5F9 text_secondary: #94A3B8 border: #1E293B
card radius: 10px button radius: 8px fonts: Inter / Inter / Inter
基于此,style_guide/mapping.rs 的 build_style_mapping 对比两个指南的结构化值,产出 PropertyReplacement——一组 from → to 替换对,按 fill / text / stroke 颜色、字体家族、圆角分别归类,正是 replace_all_matching_properties MCP 工具重新换肤现有设计的输入。也就是说,从 midnight-minimal-dark 切换到另一个指南(或反向)时,引擎能自动算出需要替换的每个具体色值与圆角。
5. 摘要与悬浮卡片
style_guide/summary.rs 的 style_guide_summary 将固定(pin)的指南压缩为名称 + 最多 4 个色板 swatch(background、surface、accent、primary text),渲染在编辑器聊天面板的固定风格徽标行;style_guide/card.rs 的 style_guide_card 提供更详细的悬浮卡片(最多 8 个 swatch、字体、取自 ## Style Summary 段落的一句话自述——本篇指南的 Style Summary 首句即会被提取为卡片描述)。两者都以 id 为键做了 memoization,且文档中未声明的字段一律输出 None 而非猜测值。
6. 用户导入指南的兼容
除了内嵌语料,用户还能在运行时导入自己的 DESIGN.md 风格文件(style_guide/user_registry.rs,id 带 user: 前缀,桌面端持久化于 ~/.openpencil/styles/*.md);style_guide/token_table.rs 则是为社区 DESIGN.md 的 | Name | Value | Token | Role | 表格方言设计的"缺口填补器",仅在标准语法提取为空时按通道补齐。midnight-minimal-dark 这类按标准语法书写的语料始终以自身解析结果为准。
实战落地要点
- 何时选用:构建 Web 端工具型产品(数据面板、控制台、工作台)且用户明确要求"极简 / 深色 / 安静"时,midnight-minimal-dark 是最直接的候选;请求中出现
minimal、dark-mode、calm、blue-accent等标签都会提高其命中得分。 - 如何生成节点:遵循"未命名布局 frame 保持结构性默认"——普通容器不填色、不加边框、不设圆角与阴影;只有卡片(#1E293B / 10px)、输入框(Inset #162032 / 6–8px)、按钮(#38BDF8 激活 / [10,16] padding / 8px)等可见组件才使用显式表面。层级来自 24–40px 的大间距与字重对比。
- 如何保持正确:所有颜色只取自文档中的 Token 表;激活态唯一允许饱和色 #38BDF8;字重不超过 600;图标仅用 Lucide 描边家族且大小落在 14–24px 刻度内。
- 如何切换风格:风格切换由
build_style_mapping自动生成替换映射,无需手工记录每个色值;固定风格后在聊天面板可见 swatch 徽标,悬浮可查看来源(内嵌语料或user:导入)。
以上规范与机制共同构成 OpenPencil "Design-as-Code" 工作流的一环:风格指南既是给 AI Agent 的提示词语料(被逐字注入生成 prompt),又是可被结构化解析、差异对比与程序化换肤的数据源。想要完整复用这套极简深色风格,直接以 crates/op-ai-skills/skills/style-guides/midnight-minimal-dark.md 为模板、按本文整理的字段体系编写即可。