OpenPencil 风格指南解析:用 noir-elegant-dark 打造电影感暗色界面(深炭黑 × 鎏金 × Cormorant 衬线)
OpenPencil 风格指南解析:用 noir-elegant-dark 打造电影感暗色界面(深炭黑 × 鎏金 × Cormorant 衬线)
导读
noir-elegant-dark 是 OpenPencil 内置风格指南(style guide)语料库 op-ai-skills 中的一款面向 Web 应用(platform: webapp)的暗色设计规范,以黑色电影(film noir)美学与旧世界奢华感为基调:深炭黑 #121212 背景、克制点缀的鎏金 #D4AF37、Cormorant 古典衬线标题与 Lato 正文字体,以及 0–4px 的锐利圆角。本文将逐项拆解这份风格指南的颜色、字体、间距、圆角与图标规范,并结合 OpenPencil 仓库中 op-ai-skills 与 op-mcp 的源码,说明这份 Markdown 指南是如何被解析、检索、注入生成提示词(prompt),并驱动一次完整的 AI 设计生成的。读完本文,你将既能按规范手工复刻该风格,也能理解 OpenPencil 中“风格指南 → 结构化解构 → 风格切换”的底层工程链路。
这份文档在 OpenPencil 中扮演什么角色
noir-elegant-dark.md 位于 crates/op-ai-skills/skills/style-guides/ 目录下,与 ai-product-dark.md、terminal-minimal-dark.md 等六十余份风格指南共同构成随 crate 编译期嵌入(include_dir!)的“风格指南语料库”。它的核心机制与 TS 版 pen-ai-skills 对齐,整体流程见 lib.rs 顶部注释:
- 加载:
style_guide_registry()遍历嵌入的style-guides/目录,逐个解析 frontmatter,缓存为ParsedStyleGuide注册表(loader.rs); - 选择:根据请求的
name或tags做匹配打分,选出最合适的一份指南; - 注入:指南的完整 Markdown 内容被原样注入生成提示词(
content: raw.to_string()),因此文档中的每一条 token、每一个数值都会直接“教”给生成模型; - 结构化解构:
extract_style_guide_values()从## Color System、## Typography、## Corner Radius章节抽取颜色/字体/圆角三通道,用于风格切换(re-skin)与界面上悬浮卡片的色板展示(parser.rs)。
换句话说,本文解读的这份文档不是给人看的静态规范,而是会被 AI 生成管线逐字消费的“设计指令”。这也解释了为什么它的表述如此精确、表格如此密集——每个数值最终都可能变成画布上一个真实的 fill、cornerRadius 或 font family。
风格总览:黑色电影 × 黄金时代的克制奢华
文档开头的 ## Style Summary 给出了设计定位:一种受黑色电影美学与旧世界奢华启发的电影感暗色界面。深炭黑(#121212)表面作为背景,衬托克制的鎏金(#D4AF37)点缀——它让人联想到鎏金字体、黄铜构件与复古影院标题。Cormorant 标题带来古典衬线的粗细对比戏剧感,Lato 正文则提供干净现代的易读性,0–4px 的锐角强化了 Art Deco 与黄金时代的建筑精确感。
核心美学关键词(原文):
- Film noir 配色:深炭黑
#121212配暖金#D4AF37,唤起复古影院与黄铜细节; - 古典衬线展示:Cormorant 用于标题与指标数值——高对比、优雅的字形;
- 金色的克制:强调色仅在 100%、40%、20% 三档透明度下稀疏使用,制造层次而不刺眼;
- Art Deco 精确感:0–4px 圆角与细金色描边暗示建筑装饰与时代字体;
- 暖调中性色:文字色微微偏暖(
#F5F0E8、#B8B0A0)而非纯灰,与金色互补; - 装饰性分隔线:细金色规则线与 1px 描边在内容区间之间制造优雅分隔。
从源码侧印证“克制”这一约束:style_guide_registry 的审计测试强制每份指南必须声明“self-contained”(自包含)与“Treat unnamed layout frames as structural by default”(未命名布局框默认视为结构件),见 loader.rs 中的 every_style_guide_declares_its_scope_boundary 测试——这正是“金色克制、结构清晰”在工程上的强制手段。
Style Scope:自包含规则与防“串味”
文档的 ## Style Scope 是这类风格指南的通用纪律,原文规定:
- 本指南自包含;只有在明确选中本指南时才应用其配色、圆角、间距、阴影与组件处理方式;
- 不得把 food、social、dashboard、luxury、terminal 等其他指南的模式“借用”进另一种风格;
- 未命名布局帧默认按“结构件”处理:除非节点刻意是卡片、输入框、按钮、徽章、媒体遮罩、导航面或其它可见组件,否则不设置 fill、stroke、cornerRadius 或 shadow;
- 避免在组件外围套装饰性外壳,层级应来自间距、字体与指南明确的表面。
这条规则在测试中被强制校验:loader.rs 的审计测试断言每份语料指南都包含 This guide is self-contained 与 Treat unnamed layout frames as structural by default 文本,防止风格间的视觉泄漏(visual leakage)。
配色系统:六组 Token 全解析
文档的 ## Color System 是生成器最依赖的部分。以下完整继承并标注其语义。
核心背景(Core Backgrounds)
| Token | 值 | 用途 |
|---|---|---|
| Page Background | #121212 |
根页面背景 |
| Card Surface | #181818 |
卡片、面板、抬升容器 |
| Sidebar Surface | #121212 |
导航侧栏背景 |
| Inset Surface | #1E1E1E |
输入框、嵌套容器 |
| Overlay Surface | #0E0E0E |
弹窗背板、下拉背景 |
设计上,背景色阶在 #0E0E0E → #1E1E1E 之间拉开五个层级:最深的 Overlay 用于悬浮层,Card Surface 比页面背景亮一级以建立抬升感,而 Sidebar 与 Page 同色,保证导航区与页面浑然一体。
文字颜色(Text Colors)
| Token | 值 | 用途 |
|---|---|---|
| Primary Text | #F5F0E8 |
标题、指标数值、主要内容(暖白) |
| Secondary Text | #B8B0A0 |
正文、描述、次级标签(暖灰) |
| Tertiary Text | #7A7468 |
时间戳、说明文字、非活跃元素 |
| Muted Text | #4A4640 |
占位符、禁用状态 |
| Accent Text | #D4AF37 |
活跃导航、状态标签、链接、金色高亮 |
注意整条文字色阶都是“暖”的——即使最弱的 Muted 也是带棕调的 #4A4640 而非中性灰,这与金色点缀在色温上保持一致。
边框颜色(Border Colors)
| Token | 值 | 用途 |
|---|---|---|
| Default Border | #2A2620 |
卡片边框、分隔线(暖色调) |
| Subtle Border | #1E1C18 |
分区分隔、浅分隔线 |
| Accent Border | #D4AF37 |
活跃指示、聚焦输入框、装饰规则线 |
| Accent Muted Border | #D4AF3740 |
25% 透明度的装饰金描边 |
| Accent Light Border | #D4AF3720 |
轻微 hover 高亮 |
#D4AF3740 这类带 alpha 的写法表示金色以指定透明度使用——40% 对应 Accent Glow 的“40% 透明度”说明,25% 用于装饰描边,20% 用于 hover 底色。透明度体系(100/40/25/20%)正是“金色克制”原则的实现手段。
强调色(Accent Colors)
| Token | 值 | 用途 |
|---|---|---|
| Primary Accent | #D4AF37 |
活跃状态、金色高亮、主强调色 |
| Accent Glow | #D4AF3766 |
暖光效果(40% 透明度) |
| Accent Subtle | #D4AF3720 |
淡金背景、hover 状态 |
| Success | #7BAE6E |
正向指标(柔和绿,符合年代气质) |
| Error | #C4534A |
错误状态(柔和红,匹配暖色盘) |
| Warning | #D4AF37 |
警告沿用金色(自然的警示色) |
有趣的是,Success 的 #7BAE6E 与 Error 的 #C4534A 都是被刻意“压暗、去饱和”的复古色调,避免高饱和状态色破坏电影感氛围;而 Warning 直接复用金色,让警示不引入第三种强调色。
源码佐证:颜色如何被结构化提取
parser.rs 中的 extract_colors 用行级正则式标签匹配来提取 token:例如 Page Background 或 root … background 匹配背景通道,Card Surface / surface 匹配表面通道,Primary Accent / accent 匹配强调通道(且优先取 ### Accent Colors 子段落),Primary Text / Secondary Text / Muted Text 匹配文字通道。first_hex 对 7 位十六进制连串(如 #D4AF3740)会判定不合法而跳过——因为它本质是 RGBA 而非 6 位 RGB。提取出的结构化值随后被用于:
- 风格切换:
build_style_mapping把两份指南的from → to色值映射交给replace_all_matching_properties类工具做换肤(mapping.rs); - 界面色板:
style_guide_summary取 background / surface / accent / primary text 四个颜色渲染到聊天面板的“已固定风格”色带(summary.rs)。
字体排印:Cormorant × Lato 的双字体系统
文档的 ## Typography 定义了完整的字体角色、字号阶梯、字重、字距与行高。
字体家族
| 角色 | 家族 | 用途 |
|---|---|---|
| Display / 标题 | Cormorant | 主视觉数值、章节标题、特性标题 |
| Body / 功能 | Lato | 正文、描述、导航标签、按钮 |
Cormorant 是拥有高对比粗细笔画(thick/thin stroke)的古典衬线体,负责承载“电影标题”的戏剧感;Lato 则是几何感现代无衬线,负责信息密集区的可读性。双字体策略在源码中被结构化为 StyleTypography { display_font, body_font, data_font } 三个通道(types.rs),extract_typography 通过角色关键词(display / logo / heading / serif 匹配展示字体,body / functional / ui 匹配正文)解析 ### Font Families 表格,解析失败时按行位置回退(parser.rs)。
字号阶梯(Type Scale)
| 层级 | 字号 | 字体 | 字重 | 用途 |
|---|---|---|---|---|
| Display | 48px | Cormorant | 600 | 主视觉指标数值、电影感大标题 |
| Title 1 | 28px | Cormorant | 600 | 章节标题 |
| Title 2 | 20px | Cormorant | 600 | 卡片标题、子章节标题 |
| Title 3 | 16px | Lato | 600 | 列表项标题、面板标题 |
| Body | 14px | Lato | 400 | 描述、正文 |
| Body Large | 16px | Lato | 400 | 引言段落、突出描述 |
| Label | 12px | Lato | 500 | 字段标签、导航项、列标题 |
| Caption | 11px | Lato | 400 | 时间戳、元数据 |
| Micro | 10px | Lato | 600 | 状态徽章、辅助标签(大写) |
注意标题族全部使用 600 半粗,即使 48px 的 Display 也只用 600——Cormorant 的高对比字形本身已足够有分量,无需加粗到 700。
字重体系
| 字重 | 值 | 用途 |
|---|---|---|
| Regular | 400 | 正文、描述、说明 |
| Medium | 500 | 标签、导航项 |
| Semibold | 600 | 所有标题(Cormorant)、卡片标题 |
| Bold | 700 | 主要强调,极少使用 |
文档特别注明 700 是“rare — used sparingly”(罕见、克制使用),与全篇“克制”基调一致。
字距(Letter Spacing)
- Display(48px):
-1.5px(紧凑、戏剧化的衬线排印) - 章节标题(28px):
-1px - 大写标签:
+1.5px至+2px(Art Deco 模版字感觉) - 正文:
0px
行高(Line Height)
- Display(48px):
1.0 - 标题(20–28px):
1.15 - 正文(14–16px):
1.5 - 说明文字(10–11px):
1.4
间距系统:为 1440px 桌面布局服务的 Gap 与 Padding
文档 ## Spacing System 提供的是可直接落到画布布局属性上的数值,特别适合 space_between / gap 类弹性布局。
Gap 刻度
| 值 | 用途 |
|---|---|
| 4px | 行内图标 + 文本组合 |
| 8px | 状态指示器组、紧凑区块 |
| 12px | 列表项之间、按钮组 |
| 16px | 卡片内部区块、导航项间距 |
| 20px | 面板区块、表单字段组 |
| 24px | 网格中的卡片之间 |
| 28px | 内容区主要章节 |
| 32px | 页面顶级区块 |
| 48px | 大区块分隔、Hero 间距 |
Padding 刻度
| 值 | 用途 |
|---|---|
[12, 16] |
侧栏导航项(纵向 12,横向 16) |
[10, 20] |
标准按钮 |
[8, 16] |
输入框 |
24px |
标准卡片内边距 |
28px |
特性卡片内边距 |
[32, 48] |
内容区内边距 |
[48, 48] |
Hero 区内边距 |
布局模式(Layout Pattern)
- 画布宽度:
1440px - 侧栏:
260px宽,垂直排布,space_between,图标 + 文字导航 - 内容区:
width: fill_container,height: fit_content,垂直,gap28–48,padding[32, 48] - 装饰性金色规则线:
1px水平分隔线,#D4AF37,置于主要章节之间 - 侧栏指示器:活跃项左侧
3px金色边框
这套布局参数与 OpenPencil 画布的 DSL 词汇高度对应(fill_container、fit_content、space_between 都是生成指令中的原生概念),意味着模型可以直接把这份表格翻译成画布节点属性,无需二次推断。
圆角体系:0–4px 的 Art Deco 克制
| 值 | 用途 | 理由 |
|---|---|---|
| 0px | 分隔线、侧栏、装饰规则线 | 古典精确感 |
| 2px | 徽章、微型指示器 | 几不可察的柔化 |
| 4px | 卡片、按钮、输入框、面板 | 最大半径——Art Deco 克制 |
设计理由(原文):0–4px 范围保持了 Art Deco 与黑色电影美学的建筑精确感。锐角让人联想到蚀刻金属铭牌、鎏金相框与凸版活字块。近零圆角让 Cormorant 衬线字体与金色点缀承担全部装饰重量,结构元素保持严峻优雅。
在源码侧,extract_radius 通过 px_number 与行内关键词(card / standard / container 匹配卡片通道,button / input / small 匹配按钮通道)提取圆角值(parser.rs);风格切换时圆角作为标量 px 进入 RadiusReplacement { from, to } 替换列表(mapping.rs)。resolve_style.rs 中还内置了与这套克制审美一致的“sharp”圆角档位(<a href="https://link.gitcode.com/i/d75c57591d17e1106608dd3633ee94ba" target="_blank">0, 2, 4, 6, 8, 12, 16, full],[resolve_style.rs)。
图标体系:Lucide 与四种尺寸
图标字体
- 家族:Lucide
- 风格:Outline(线性描边),圆角连接与端帽
常用图标清单
layout-dashboard、bar-chart-2、users、settings、crown、award、star、gem、briefcase、calendar、clock、trending-up、trending-down、search、bell、chevron-right、chevron-down、plus、x、edit、eye、lock、heart、bookmark、filter、download
这份清单里 crown、award、star、gem 等“勋章/珍宝”类图标与金色点缀的奢华气质直接呼应,适合榜单、成就、会员等级等场景。
图标尺寸
| 尺寸 | 用途 |
|---|---|
| 14px | 行内指示器、表格行操作 |
| 18px | 侧栏导航图标、列表项 |
| 20px | 卡片头部图标、操作按钮 |
| 24px | 侧栏主图标、头部操作 |
图标颜色状态
| 状态 | 颜色 | 用途 |
|---|---|---|
| Active | #D4AF37 |
选中导航、金色高亮 |
| Default | #B8B0A0 |
非活跃导航、次级操作 |
| Muted | #4A4640 |
禁用图标、占位状态 |
| On Surface | #F5F0E8 |
抬升表面上的图标 |
工程落地:这份指南如何被选中并驱动生成
通过 tags 被检索:Jaccard 式打分
select_style_guide 支持两种选择路径(loader.rs):
- 按 name:精确匹配
name(可选加 platform 约束),用于用户显式固定某份指南; - 按 tags:对请求标签集合计算命中率
hits / request_tags.len()(Jaccard 式打分),分数最高者胜出;同分时保留注册表中靠前的候选(与 TS 版本行为一致)。
noir-elegant-dark 的 frontmatter 标签为 [elegant, dark-mode, serif, luxury, gold-accent, sophisticated, refined]——其中 elegant、dark-mode、serif、luxury、gold-accent、refined、sophisticated 全部在受控词表 STYLE_GUIDE_TAGS(types.rs)之中。因此当用户请求“优雅暗色 / 奢华风 / 衬线标题 / 金色点缀”时,这份指南会在标签打分中胜出。platform: webapp 意味着它在被限定为 webapp 的请求中才会参与竞争。
通过 MCP 工具被调用
op-mcp crate 提供了三个风格相关 MCP 工具(style_guide_tools.rs):
get_style_guide_tags:返回受控词表STYLE_GUIDE_TAGS及数量,供 Agent 了解可用的风格标签;get_style_guide:接受tags(JSON 数组或逗号分隔)、name、platform参数,调用select_style_guide选出一份指南并返回其name、tags、platform与完整 Markdown 内容(content),这份内容随后注入生成提示词;list_style_guides:列出语料库全部指南(及用户导入的DESIGN.md),支持按id、tag、platform过滤。
在规划阶段被引用:styleGuideName 契约
skills/phases/planning/decomposition.md 规定了生成规划阶段的硬性要求:"styleGuideName" 必须始终存在,且要从风格指南选择技能列出的可用指南中挑选,系统会自动加载完整风格规范。该文档同时定义了暗色触发的关键词集合:dark/cyber/terminal/neon/夜间/暗黑/deep/gaming/noir——即用户提到 noir(或其它暗色词)时,规划器会偏向暗色主题,而 noir-elegant-dark 正是这类意图的理想落点。design_prompt.rs 的 AESTHETIC QUALITY GUIDE 与 design_md_policy.rs 的暗色词表(dark, night, noir, cyber, neon, terminal, midnight, obsidian, onyx)同样将 noir 视为暗色主题信号。此外,规划模板要求根框架(rootFrame)的 fill 必须使用所选风格指南的背景色——对这份指南而言即 #121212。
一份可直接套用的生成诉求示例
结合上述契约,一个典型的用法是向生成管线下达如下诉求:
设计一个 1440px 宽的 Web 应用仪表盘,暗色主题,优雅、奢华、金色点缀、衬线标题。
规划阶段会解析出暗色意图并匹配到 noir-elegant-dark,随后:
- 通过
get_style_guide(tags 如["elegant","dark-mode","serif","luxury","gold-accent"])取回完整指南 Markdown; - 将指南内容注入生成提示词,模型据此落地:根画布 fill 取
#121212,卡片用#181818,标题走 Cormorant 600、正文走 Lato,圆角不超过 4px,侧栏活跃项使用 3px 金色左边框与#D4AF37图标; - 生成结束后,若用户想一键切换成另一风格,
build_style_mapping会基于两份指南的结构化值产出from → to替换包,交由属性替换工具完成换肤(mapping.rs)。
与同族暗色指南的差异化参考
在 style-guides/ 目录中,还有 elegant-luxury-dark.md、luxury-brand-dark.md、midnight-minimal-dark.md、dashboard-analytics-dark.md 等近似风格。noir-elegant-dark 的辨识度在于三点组合:暖金 #D4AF37 + Cormorant 衬线 + 0–4px 近零圆角——相比 midnight-minimal-dark(更冷、更极简)与 dashboard-analytics-dark(面向数据密度),它更强调电影感叙事与年代奢华,适合品牌展示页、会员体系、榜单成就、精品门户等需要“氛围与质感”的 Web 场景。选择时建议优先用 tags 驱动打分,让检索机制按语义替你做决策。
小结
noir-elegant-dark 是一份信息密度极高的“可执行设计规范”:从 #121212 的六级灰阶背景、#D4AF37 的 100/40/25/20% 透明度阶梯,到 Cormorant/Lato 双字体 48px→10px 的字号全谱、0–4px 圆角纪律与 Lucide 图标四尺寸体系,全部以表格化 Token 呈现。在 OpenPencil 的工程链路中,它既是可被 tags 打分检索的注册表条目,也是会被 MCP 工具整体注入提示词、被 extract_style_guide_values 结构化解构的“样式事实来源”。理解这份文档,等于同时理解了 OpenPencil“Design-as-Code”理念中最贴近视觉落地的一环:风格不是效果图,而是可解析、可替换、可重复生成的数据。