OpenPencil 极简深色风格指南全解析:midnight-minimal-dark 设计系统落地指南

原创2026-10-11 19:30:191,604 阅读

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 为模板、按本文整理的字段体系编写即可。

登录后查看全文
openpencil