OpenPencil 技术开发者深色风格指南(tech-developer-dark):基于 GitHub 暗色体系的 AI 落地页设计规范

原创2026-10-11 18:58:111,347 阅读

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:风格自包含,杜绝跨风格污染

文档开篇即声明两条硬性约束:

  1. 自包含原则:本指南的调色板、圆角尺度、间距、阴影与组件处理,仅当该指南被明确选中时才应用;不得把 food、social、dashboard、luxury、terminal 等其他指南的模式"借"进本风格。
  2. 结构帧默认透明:未命名的布局帧(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 规定选择规则:

  1. 用户显式命名风格(如 "brutalist"、"minimal"、"terminal")→ 按名称或主标签匹配;
  2. 否则从请求中推断 3-5 个标签(平台 / 视觉 / 行业三个维度,例如 "developer tool" → developer + monospace);
  3. 按标签重叠度选出最佳风格指南;
  4. 在规划输出中以 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_properties MCP 工具完成既有设计的重换肤;两端相同时不产出任何替换。
  • 摘要(chips):summary.rs 将钉住的风格压缩为"名称 + 最多 4 个色板(背景、表面、强调、主文本)",并按 id 记忆化——聊天面板每一帧都会绘制它,避免在每帧都重跑数十 KB 文档的值提取;若文件无法解析出色值,返回空色板而非猜测值。
  • 悬停卡片:card.rs 是摘要的放大版:展示 is_user(内置语料 or 用户导入)、最多 8 个色板(STYLE_CARD_SWATCH_CAP)、display/body 字体族与指南自述首句;缺失字段渲染为缺失行,绝不伪造默认值。

十、实践要点:将本指南落地到你的开发者落地页

汇总本指南的可执行要点(可直接用于对照自检):

  1. 配色:页面背景 #0D1117,卡片/交替区块 #161B22,浮层 #1C2128;主文本 #E6EDF3 / 次文本 #8B949E / 弱文本 #6E7681 / 占位 #484F58;强调统一 #58A6FF(悬停 #79C0FF,着色底 #58A6FF20);语义色 #3FB950(成功)/ #D29922(警告)/ #F85149(错误);边框 #30363D(默认)/ #21262D(微妙)/ #58A6FF(激活)。
  2. 字体: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 字距。
  3. 间距:区块间 64-80px 垂直留白;Hero 垂直内边距 [120, 0],区块 [80, 0];卡片内边距 24px(紧凑)/ 32px(标准);功能网格 3 列、间距 24px。
  4. 圆角:卡片 8px、按钮/输入框 6px、行内代码/小徽章 4px、大面板最多 12px、状态圆点 9999px。
  5. 组件纪律:导航固定顶部高 64px、背景 #0D1117、底部 #30363D 细边框;代码块是全宽语法高亮的一等元素;集成 Logo 条灰阶哑光处理;热门定价方案使用蓝色边框标记。
  6. 图标:Lucide outline 风格;主操作蓝色 #58A6FF、次级 #8B949E、禁用 #484F58;尺寸按 14/16/20/24-32px 阶梯使用。

结语

tech-developer-dark 是一份"规范即代码"的完整风格系统:它既为人类设计师提供了可直接对照的精确 Token 表,也为 OpenPencil 的 AI 生成管线提供了机器可解析的结构化数据。理解这份文档,等于同时掌握了 GitHub 暗色美学的设计语言与 OpenPencil 风格指南子系统的运作原理——从规划阶段的 styleGuideName 选择,到运行期的标签/名称匹配,再到生成阶段的值提取与换肤映射,全程有源码与测试佐证。若你的下一款开发者工具需要"让受众一眼认出这是开发者产品"的落地页,这份指南是最直接的起点。

登录后查看全文
openpencil