OpenPencil 技术开发者深色风格指南(tech-developer-dark):基于 GitHub 暗色体系的 AI 落地页设计规范
OpenPencil 技术开发者深色风格指南(tech-developer-dark):基于 GitHub 暗色体系的 AI 落地页设计规范
本文档面向 OpenPencil(开源 AI 原生矢量设计工具)的 op-ai-skills 技能语料库,深度解析内置风格指南 tech-developer-dark(技术开发者深色)的完整设计规范。该风格面向 Web 应用(platform: webapp)落地页,其灵感直接取自 GitHub 暗色 UI 与现代代码编辑器:深墨色背景搭配 GitHub 蓝强调色,JetBrains Mono 等宽字体赋予页面"由开发者构建、为开发者服务"的代码原生身份。读完本文,你将掌握这套风格的全部 Design Token(色彩、字体、间距、圆角、图标),并理解它在 OpenPencil AI 设计生成管线中如何被加载、选择、解析与落地(如风格切换映射与聊天面板中的风格摘要/卡片),可直接复用于同类开发者工具的落地页设计。
一、这份文档在 OpenPencil 中的定位:不是设计稿,而是可编程的风格规范
tech-developer-dark.md 位于 crates/op-ai-skills/skills/style-guides/tech-developer-dark.md,是 op-ai-skills crate 内嵌的风格指南语料(style-guides/ 子树)中的一员。与普通的"视觉规范文档"不同,它是结构化的可执行数据:
- 文件头(frontmatter)声明了机器可读的元数据,由 frontmatter.rs 中的无依赖 YAML 子集解析器处理(仅支持
key: value、行内[a, b]数组与trigger:下一层嵌套,恰好覆盖语料所需切片); - 正文遵循固定章节契约(
## Color System、## Typography、## Corner Radius等),由 parser.rs 的extract_style_guide_values提取结构化值,供风格切换、摘要卡片等下游能力使用; - 语料通过
include_dir!宏在编译期内嵌进二进制(见 lib.rs 中的SKILLS静态目录),运行期零网络请求、同步完成加载,audit_tests.rs 明确断言注册表 ≥ 50 个风格指南且内容非空。
1.1 Frontmatter:如何声明一份风格指南
本文件的 frontmatter 为:
---
name: 'tech-developer-dark'
tags: [developer, dark-mode, monospace, tech, code-inspired, terminal, landing-page]
platform: webapp
---
三个字段的含义与约束如下:
| 字段 | 值 | 说明 |
|---|---|---|
name |
tech-developer-dark |
唯一标识;select_style_guide 按名称精确查找的键,也是规划阶段输出 styleGuideName 时使用的名字 |
tags |
developer, dark-mode, monospace, tech, code-inspired, terminal, landing-page |
受控词表(见 types.rs 的 STYLE_GUIDE_TAGS),用于按标签打分匹配;必须全部来自该词表且非空 |
platform |
webapp |
目标平台,见 types.rs 中 Platform 枚举(webapp / mobile / landing-page / slides / card);未知或缺失时默认回落为 webapp |
值得注意:platform: webapp 与 tags 中的 landing-page 并不冲突——platform 决定该指南可被哪些页面类型请求命中(平台过滤是硬性的),而 landing-page 只是用于标签匹配的语义标签。同目录下的 developer-terminal-dark.md(VS Code 风)与 terminal-minimal-dark.md(终端青色、platform: mobile)即是"易混淆但可区分"的相邻风格,依靠名称 + 平台双约束精确区分。
二、Style Scope:风格自包含,杜绝跨风格污染
文档开篇即声明两条硬性约束:
- 自包含原则:本指南的调色板、圆角尺度、间距、阴影与组件处理,仅当该指南被明确选中时才应用;不得把 food、social、dashboard、luxury、terminal 等其他指南的模式"借"进本风格。
- 结构帧默认透明:未命名的布局帧(layout frame)默认是纯结构节点——除非该节点有意是卡片、输入框、按钮、徽章、媒体蒙版、导航表面等可见组件,否则不赋予 fill、stroke、cornerRadius 或 shadow。避免在组件外面包裹装饰性外壳,层级应来自间距、排版与指南明确声明的表面。
这条契约被 loader.rs 的测试强制检查:每个注册的风格指南都必须包含 ## Style Scope、"This guide is self-contained"、"Treat unnamed layout frames as structural by default" 三段句式,任何缺失都会导致 CI 失败——防止语料在演进中悄悄丢失隔离纪律。
三、Style Summary:GitHub 暗色 × 代码原生
本风格定位为面向开发者受众的落地页:深墨色背景(#0D1117)搭配 GitHub 蓝(#58A6FF),为技术受众营造熟悉、可信的环境;JetBrains Mono 标题给页面一种代码原生身份,暗示"由开发者构建,为开发者服务";Inter 正文保证营销文案的可读性;代码块与终端风格 UI 元素强化技术可信度。
核心美学清单:
- GitHub 暗色调色板:
#0D1117背景 +#161B22卡片表面,开发者即刻产生熟悉感 - GitHub 蓝强调色:
#58A6FF用于链接、CTA 与高亮——"可点击代码引用的颜色" - 代码原生展示:JetBrains Mono 用于标题与功能高亮,赋予文本等宽节奏
- 紧凑圆角:8px 卡片、6px 按钮——功能性、工程思维的圆角
- 代码块一体化:语法高亮代码块作为一等内容元素
- 终端母题:圆点指示器、命令行提示符、等宽标签作为装饰模式
四、色彩系统(Color System)
4.1 核心背景(Core Backgrounds)
| Token | 值 | 用途 |
|---|---|---|
| Page Background | #0D1117 |
页面根背景(GitHub dark) |
| Section Alt | #161B22 |
交替区块背景 |
| Card Surface | #161B22 |
功能卡片、定价卡片 |
| Elevated Surface | #1C2128 |
下拉菜单、模态框、工具提示 |
| Code Block | #0D1117 |
代码片段背景 |
| Code Block Alt | #161B22 |
行内代码背景 |
设计上,"页面背景"与"代码块背景"同为 #0D1117,刻意让代码块融入页面底色,而非成为突兀的独立面板——这与 GitHub README 中代码块的处理一致。
4.2 文本颜色(Text Colors)
| Token | 值 | 用途 |
|---|---|---|
| Primary Text | #E6EDF3 |
标题、主要内容 |
| Secondary Text | #8B949E |
正文、描述 |
| Tertiary Text | #6E7681 |
说明文字、注释、元数据 |
| Muted Text | #484F58 |
占位符、禁用文本 |
| Blue Text | #58A6FF |
链接、激活态、高亮 |
| Green Text | #3FB950 |
成功态、代码字符串 |
| Orange Text | #D29922 |
警告态、代码关键字 |
| Red Text | #F85149 |
错误态、代码删除 |
这组文本色完整复刻了 GitHub 深色主题的语法着色语义(green = 字符串、orange = 关键字、red = 删除),因此"代码块"不仅是装饰,其内部语法高亮与页面语义色完全同源。
4.3 边框颜色(Border Colors)
| Token | 值 | 用途 |
|---|---|---|
| Default Border | #30363D |
卡片边框、分隔线 |
| Subtle Border | #21262D |
浅分隔线 |
| Active Border | #58A6FF |
聚焦输入框、激活指示 |
| Code Border | #30363D |
代码块边框 |
4.4 强调色(Accent Colors)
| Token | 值 | 用途 |
|---|---|---|
| Primary Accent | #58A6FF |
CTA 按钮、链接、激活态 |
| Accent Muted | #58A6FF20 |
着色背景、徽章填充(20% 透明度,即 8 位 HEX 后两位 20) |
| Accent Hover | #79C0FF |
按钮悬停态 |
| Success | #3FB950 |
正向指示、对勾 |
| Warning | #D29922 |
告警态 |
| Error | #F85149 |
错误态、破坏性操作 |
| On Accent | #FFFFFF |
蓝色背景上的文字 |
源码侧佐证:这些颜色如何被机器读取?parser.rs 的 extract_colors 通过行标签匹配(如 page background、card surface、primary accent、primary text)配合 first_hex(首个 #RRGGBB,第 7 位十六进制字符会使匹配失效)提取结构化颜色。这意味着表头标签必须与解析器期望的标签一致,否则该色值不会被识别为对应角色。例如本文件的 Primary Accent 与 Accent Muted(#58A6FF20 为 8 位 HEX)并存,解析器只取首个 6 位 HEX,因此 Accent Muted 不会被误读为强调色主值。
五、排版系统(Typography)
5.1 字体族(Font Families)
| 角色 | 字体族 | 用途 |
|---|---|---|
| Display / Code | JetBrains Mono | Hero 标题、功能标题、代码片段、终端元素 |
| Body / Functional | Inter | 正文、导航、按钮、描述 |
extract_typography 解析 ### Font Families 下的 | Role | Family | Usage | 表格:按角色关键字(display/heading/serif → display_font,body/functional/ui → body_font,data/mono → data_font)匹配,匹配失败时按行位置回退(第 1 行 → display、第 2 行 → body、第 3 行 → data)。因此本文件的 JetBrains Mono 会被识别为 display_font 与 data_font,Inter 被识别为 body_font。
5.2 字号阶(Type Scale)
| 级别 | 字号 | 字体 | 字重 | 用途 |
|---|---|---|---|---|
| Hero | 56px | JetBrains Mono | 700 | 首屏主标题 |
| Display | 44px | JetBrains Mono | 600 | 大型章节标题 |
| Title 1 | 32px | JetBrains Mono | 600 | 章节标题 |
| Title 2 | 24px | JetBrains Mono | 500 | 小节标题 |
| Title 3 | 18px | Inter | 600 | 卡片标题、功能名 |
| Body Large | 18px | Inter | 400 | Hero 副标题、导语段 |
| Body | 16px | Inter | 400 | 描述、营销文案 |
| Code | 14px | JetBrains Mono | 400 | 代码块、CLI 命令 |
| Label | 14px | Inter | 500 | 导航、按钮文字 |
| Caption | 12px | Inter / JetBrains Mono | 400-500 | 元数据、终端提示符、技术标签 |
| Micro | 11px | Inter | 500 | 徽章、overline(大写) |
5.3 字重(Font Weights)
| 字重 | 值 | 用途 |
|---|---|---|
| Regular | 400 | 正文、代码块 |
| Medium | 500 | 标签、导航、小节标题 |
| Semibold | 600 | 章节标题、展示文本 |
| Bold | 700 | Hero 标题 |
5.4 字间距(Letter Spacing)
- Hero(56px):
-2px(负字距压缩大标题,GitHub 特色) - Display(44px):
-1.5px - 章节标题(32px):
-1px - 大写标签:
+2px(上浮扩展,增强标签感) - Code / 等宽:
0px - 正文:
0px
5.5 行高(Line Height)
- Hero(56px):
1.05 - Display(44px):
1.1 - 标题(24-32px):
1.2 - 正文(16-18px):
1.6 - 代码(14px):
1.5 - 说明文字(11-12px):
1.4
排版上有一条可验证的工程约束:标题全用等宽 JetBrains Mono,正文全用 Inter,两族字体、两个世界观——展示层代码化、阅读层人本化。这与同仓库 style-defaults.md 中"标题应具区分性、正文字体应可读、最多 2 个字体族"的生成原则一致。
六、间距系统(Spacing System)
6.1 间距阶(Gap Scale)
| 值 | 用途 |
|---|---|
| 4px | 行内图标+文字组合、圆点分隔符 |
| 8px | 徽章组、紧凑簇 |
| 12px | 导航项、按钮组 |
| 16px | 卡片内容分区、代码块内边距 |
| 24px | 网格中卡片间距、功能列表项 |
| 32px | 区块内部内容 |
| 48px | 区块内内容块之间 |
| 64-80px | 页面区块之间 |
6.2 内边距阶(Padding Scale)
| 值 | 用途 |
|---|---|
| [8, 16] | 紧凑按钮、行内代码 |
| [10, 20] | 标准按钮 |
| [12, 24] | CTA 按钮 |
| 16px | 代码块内边距 |
| 24px | 卡片内边距(紧凑) |
| 32px | 卡片内边距(标准) |
| [80, 0] | 区块垂直内边距 |
| [120, 0] | Hero 区块垂直内边距 |
(方括号格式 <a href="https://link.gitcode.com/i/540961e6c95c20562d10bc13d9609152" target="_blank">水平, 垂直] 为 OpenPencil 的布局帧 padding 记法,与 [schema.md 中框架属性规范保持一致。)
6.3 布局模式(Layout Pattern)
- 页面宽度:最大
1280px - 内容容器:居中
1120px,内边距[0, 32] - Hero 区:居中文本 + 下方代码块或终端动画
- 功能网格:3 列,间距 24px,等宽字体标题卡片
- 代码展示:全宽代码块 + 语法高亮
- 集成 Logo:单行条,灰阶/哑光的开发者工具 Logo
- 定价:3 列,间距 24px,热门方案带蓝色边框(
#58A6FF) - 导航:固定顶部,
#0D1117背景,高 64px,底部细边框(#30363D) - 页脚:深色(
#0D1117)、极简、仓库风格的链接
七、圆角(Corner Radius)
| 值 | 用途 | 设计理由 |
|---|---|---|
| 4px | 行内代码、小徽章 | 最小化代码块的生硬感 |
| 6px | 按钮、输入框、下拉菜单 | GitHub 风格按钮圆角 |
| 8px | 功能卡片、定价卡片、代码块 | 主容器圆角 |
| 12px | 大卡片、Hero 面板 | 最大容器圆角 |
| 9999px | 状态圆点、头像框 | 全圆 |
设计依据:紧凑圆角(6-8px)镜像了开发者每日打交道的 GitHub 与 VS Code 设计系统,形成即时的视觉熟悉感——页面看起来、用起来都像受众已在使用的工具。回避过大的圆角,可防止设计滑向"消费导向 / 非技术感"。
圆角在源码层同样可被结构化读取:parser.rs 的 extract_radius 从 ## Corner Radius 中匹配首个 <数字>px,并通过行关键字(card/standard/container → 卡片圆角;button/input/small → 按钮圆角)拆分为两个角色。本文件对应的解析结果为 card=8、button=6。
八、图标(Icons)
8.1 图标字体
- 字体族:Lucide
- 风格:Outline 描边,圆角连接与端点
8.2 常用图标清单
terminal, code, git-branch, git-pull-request, github, zap, shield, lock, cloud, server, database, cpu, layers, package, download, arrow-right, chevron-right, chevron-down, menu, x, check, star, eye, copy, external-link, command, hash
这批图标高度契合技术主题:terminal/code/command 直接点题代码原生,git-branch/git-pull-request/github 呼应 GitHub 语境,server/database/cpu/cloud 支撑基础设施叙事,shield/lock 传递安全信任。
8.3 图标尺寸
| 尺寸 | 用途 |
|---|---|
| 14px | 与代码行内、元数据指示器 |
| 16px | 导航项、列表项目符号 |
| 20px | 卡片头部图标、按钮图标 |
| 24-32px | 功能区块图标、头部操作 |
8.4 图标颜色状态
| 状态 | 颜色 | 用途 |
|---|---|---|
| Blue | #58A6FF |
主操作、链接、选中 |
| Default | #8B949E |
标准图标、次级操作 |
| Muted | #484F58 |
禁用、占位图标 |
| Bright | #E6EDF3 |
深色表面上的图标 |
| Green | #3FB950 |
成功、勾选指示 |
| On Accent | #FFFFFF |
蓝色背景上的图标 |
九、从规范到生成:这套风格在 OpenPencil 管线中的完整生命周期
本指南不只是给人读的规范,它参与了 OpenPencil 的"提示词 → 画布 UI"生成闭环,共四个阶段:
9.1 规划阶段:风格选择(Planning)
规划技能 style-guide-selector.md 规定选择规则:
- 用户显式命名风格(如 "brutalist"、"minimal"、"terminal")→ 按名称或主标签匹配;
- 否则从请求中推断 3-5 个标签(平台 / 视觉 / 行业三个维度,例如 "developer tool" →
developer+monospace); - 按标签重叠度选出最佳风格指南;
- 在规划输出中以
styleGuideName字段携带所选风格名。
随后 decomposition.md 强制要求:styleGuideName 必须始终存在,且根帧 fill 必须使用所选指南的 bg: 色值。对本指南而言,根帧背景即 #0D1117。
9.2 运行时:注册表与选择器(Loader & Selector)
- 注册:style_guide/loader.rs 的
style_guide_registry()从编译期内嵌的style-guides/目录构建Vec<ParsedStyleGuide>(保留完整原始 Markdown,TS 对齐后逐字注入提示词);frontmatter.rs中的strip_comment会正确剥离tags数组中的#注释,parse_array负责拆分标签。 - 选择:
select_style_guide的优先级为名称优先(可选平台约束),其次按标签命中率(请求标签中被指南携带的比例,Jaccard 式评分)在平台过滤后的候选中取最高分,平分时取注册顺序更早者——这与 TS 版行为严格对齐(见 loader.rs 及其测试)。 - 稳定性契约:audit_tests.rs 遍历整个注册表验证"按自身名称精确查找必须返回同一指南",这正是
spawn_agents.styleguideName的子代理可复现性依赖:父代理记录下tech-developer-dark后,每个子代理调用get_style_guide都必须拿到同一份内容。
9.3 生成阶段:风格注入与值提取
- Agent 在生成循环中通过
get_style_guide_tags列出全部可用风格,并在需要时拉取完整风格指南(见 design-agent.md 的工具循环协议);无匹配内置风格时,保持所选风格指南的具体调色板/字体/圆角值,不做事后 token 置换。 - parser.rs 的
extract_style_guide_values按## Color System/## Typography/## Corner Radius三个章节提取结构化StyleGuideValues(颜色七通道、字体三通道、圆角双通道),并支持两种方言:语料语法优先,社区 token-table 语法(token_table.rs)按通道补齐空缺。
9.4 换肤与展示:风格映射、摘要、悬停卡片
- 风格切换映射:mapping.rs 的
build_style_mapping将两个风格指南的解析值做差,产出from → to替换包PropertyReplacement(fill / text / stroke 颜色、字体族、卡片与按钮圆角),直接喂给replace_all_matching_propertiesMCP 工具完成既有设计的重换肤;两端相同时不产出任何替换。 - 摘要(chips):summary.rs 将钉住的风格压缩为"名称 + 最多 4 个色板(背景、表面、强调、主文本)",并按 id 记忆化——聊天面板每一帧都会绘制它,避免在每帧都重跑数十 KB 文档的值提取;若文件无法解析出色值,返回空色板而非猜测值。
- 悬停卡片:card.rs 是摘要的放大版:展示
is_user(内置语料 or 用户导入)、最多 8 个色板(STYLE_CARD_SWATCH_CAP)、display/body 字体族与指南自述首句;缺失字段渲染为缺失行,绝不伪造默认值。
十、实践要点:将本指南落地到你的开发者落地页
汇总本指南的可执行要点(可直接用于对照自检):
- 配色:页面背景
#0D1117,卡片/交替区块#161B22,浮层#1C2128;主文本#E6EDF3/ 次文本#8B949E/ 弱文本#6E7681/ 占位#484F58;强调统一#58A6FF(悬停#79C0FF,着色底#58A6FF20);语义色#3FB950(成功)/#D29922(警告)/#F85149(错误);边框#30363D(默认)/#21262D(微妙)/#58A6FF(激活)。 - 字体:Hero 56px/700(JetBrains Mono,行高 1.05,字距 -2px);章节标题 32px/600(行高 1.2,字距 -1px);正文 16px/400(Inter,行高 1.6);代码 14px/400(JetBrains Mono,行高 1.5);大写标签 +2px 字距。
- 间距:区块间 64-80px 垂直留白;Hero 垂直内边距
[120, 0],区块[80, 0];卡片内边距 24px(紧凑)/ 32px(标准);功能网格 3 列、间距 24px。 - 圆角:卡片 8px、按钮/输入框 6px、行内代码/小徽章 4px、大面板最多 12px、状态圆点 9999px。
- 组件纪律:导航固定顶部高 64px、背景
#0D1117、底部#30363D细边框;代码块是全宽语法高亮的一等元素;集成 Logo 条灰阶哑光处理;热门定价方案使用蓝色边框标记。 - 图标:Lucide outline 风格;主操作蓝色
#58A6FF、次级#8B949E、禁用#484F58;尺寸按 14/16/20/24-32px 阶梯使用。
结语
tech-developer-dark 是一份"规范即代码"的完整风格系统:它既为人类设计师提供了可直接对照的精确 Token 表,也为 OpenPencil 的 AI 生成管线提供了机器可解析的结构化数据。理解这份文档,等于同时掌握了 GitHub 暗色美学的设计语言与 OpenPencil 风格指南子系统的运作原理——从规划阶段的 styleGuideName 选择,到运行期的标签/名称匹配,再到生成阶段的值提取与换肤映射,全程有源码与测试佐证。若你的下一款开发者工具需要"让受众一眼认出这是开发者产品"的落地页,这份指南是最直接的起点。