OpenDesign PostHog 设计系统回填：evidence 驱动的 Token 契约与源码级设计资产还原

OpenDesign PostHog 设计系统回填evidence 驱动的 Token 契约与源码级设计资产还原【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-designPostHog 是开源产品分析领域的标志性品牌其官网以逃逸到野外的创业公司内部 wiki式视觉语言著称——暖鼠尾草底色、橄榄色文字、仅在 hover 时闪现的品牌橙色。OpenDesign 仓库通过 Design System 2.0 回填backfill流程把这一品牌拆解为一份可复用的结构化设计系统包并以evidence.md作为来源证据source evidence声明整个回填的边界。本文以 source/evidence.md 为核心骨架结合 DESIGN.md、tokens.css、token-contract.report.json 等仓库内资产完整还原该包的结构、Token 契约、逐行溯源机制与派生产物生成规则读者可据此理解 OpenDesign 如何将真实品牌资产工程化为可被 Agent 直接消费的设计系统。一、来源边界什么是 Design System 2.0 回填evidence.md开篇就划定了严格的来源范围Source ScopeThis Design System 2.0 backfill is derived from the curated OpenDesign bundled fixture. It does not claim a fresh crawl of the original upstream brand repository or website.这句话包含两层关键事实回填backfill而非抓取crawl该包并非对 PostHog 上游品牌仓库或官网的实时爬取产物而是基于 OpenDesign 仓库内预先策展curated的 bundled fixture 整理而来。这一点在 manifest.json 的source字段中再次得到印证——type: bundled、origin: OpenDesign curated bundled fixture。不声称上游证据包内所有取值均以 bundled fixture 为证据来源不虚构、不声称来自上游一手资料。这一克制声明是回填类资产的事实边界也是后文 Token 契约中每条绑定都带有no upstream recrawl was performed这一原因备注的原因。Included Fixture Files包含的 fixture 文件共有三个它们构成了整个设计系统包的主体文件相对路径角色设计规范design-systems/posthog/DESIGN.md视觉意图、色彩/字体/组件/布局规则、Dos Donts、Agent Prompt Guide令牌样式design-systems/posthog/tokens.css结构化 Token 绑定tokens.css是唯一事实源source of truth组件参考design-systems/posthog/components.html自包含组件 fixture首个style内嵌与tokens.css字节等价的:root块二、包结构与推荐阅读顺序manifest.jsonschema 版本od-design-system-project/v1声明了该包的完整资产拓扑{ schemaVersion: od-design-system-project/v1, id: posthog, category: Backend Data, description: Bundled OpenDesign package for PostHog, derived from curated DESIGN.md, tokens.css, and components.html fixtures., files: { design: DESIGN.md, tokens: tokens.css, designTokens: design-tokens.json, tailwind: tailwind-v4.css, components: components.html }, usage: USAGE.md, componentsManifest: components.manifest.json, importMode: normalized, preview: { dir: preview, pages: [ { path: preview/colors.html, role: colors }, { path: preview/typography.html, role: typography }, { path: preview/spacing.html, role: spacing } ] }, sourceFiles: { evidence: source/evidence.md, tokens: source/tokens.source.json, report: source/token-contract.report.json } }USAGE.md 给出了明确的阅读顺序Read Order对 Agent 与评审者同样适用先读 USAGE.md理解包契约再读DESIGN.md掌握视觉意图、约束与反模式将tokens.css的:root块原样粘贴到首个工件artifact的style中之后所有取值一律通过var(--*)解析需要精确选择器或状态时查阅components.html日常用components.manifest.json做组件清单速查需要视觉抽查时打开preview/下的colors.html、typography.html、spacing.html三个预览页。USAGE.md 同时给出了包级铁律Do/Avoid保留 schema token 名称以保证跨品牌切换可靠禁止在:root块之外使用裸十六进制色值禁止脱离tokens.css独立重定义 Tailwind 或 design-token 值禁止声称上游一手来源证据。三、设计系统本体PostHog 视觉语言的核心继承DESIGN.md是回填的视觉规范主体标题即点题Product analytics. Playful hedgehog branding, developer-friendly dark UI.其核心特征Key Characteristics必须完整继承暖鼠尾草/橄榄色系取代常见的 SaaS 蓝紫 earthy 且亲近IBM Plex Sans Variable 以 700/800 粗字重承担标题正文行高 1.50隐藏品牌橙#F54E00只出现在 hover 交互——惊喜式交互签名手绘刺猬插画与俏皮意象刻意反企业化anti-corporate鼠尾草调边框#bfc1b7与背景#eeefe9构成统一的暖绿系统近黑 CTA#1e1f23采用基于不透明度的 hover 状态内容密集型杂志式排版技术底座为 Tailwind CSS Radix UI shadcn/ui。3.1 色彩体系Color Palette RolesPrimaryOlive Ink#4d4f46正文橄榄墨、Deep Olive#23251d链接与高强调标题带绿调的近黑、PostHog Orange#F54E00隐藏品牌强调色仅 hover 出现。Secondary AccentAmber Gold#F7A501深色按钮二次 hover 强调、Gold Border#b17816特色 CTA 按钮边框、Focus Blue#3b82f6系统唯一蓝色保留给可访问性焦点环。Surface BackgroundWarm Parchment#fdfdf8页面主背景暖近白、Sage Cream#eeefe9输入框/次级表面、Light Sage#e5e7e0按钮/三级表面、Warm Tan#d4c9b8特色按钮、Hover White#f4f4f4通用 hover 背景。Neutrals TextOlive Ink#4d4f46、Muted Olive#65675e次级文字、Sage Placeholder#9ea096占位/禁用态、Sage Border#bfc1b7主边框、Light Border#b6b7af次级边框。Gradient System营销站无任何渐变——视觉语言刻意保持平坦而温暖深度靠分层表面与边框围合而非色彩过渡实现。3.2 字体与层级Typography Rules Hierarchy字体族IBM Plex Sans Variable显示与正文同源等宽为系统等宽栈ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, Courier New代码显示用Source Code Pro。层级表的代表性档位RoleSizeWeightLine HeightLetter SpacingDisplay Hero30px8001.20-0.75pxSection Heading36px7001.500pxFeature Heading24px7001.330pxCard Heading21.4px7001.40-0.54pxBody16px4001.500pxBody Relaxed15px4001.710pxNav / UI15px6001.500pxCode14px5001.430px原则提炼粗字重标题主导700–800正文行高 1.50–1.71 服务于长阅读21.4px、19.3px 等分数尺寸暗示 fluid/scaled 类型系统大写作为类目标签信号显示级选择性负字距30px 处 -0.75px而正文放松到 0。3.3 组件与交互Component Stylings按钮Dark Primary#1e1f23底 白字 6px 圆角 10px 12px内边距hover 为 opacity 0.7 Amber Gold 文字active 为 opacity 0.8 轻微缩放Sage Light#e5e7e0底 Olive Ink 字 4px 圆角Warm Tan Featured#d4c9b8底 黑字 无圆角Input-style#eeefe9底 Sage Placeholder 字 1px#b6b7af边框。所有按钮 hover 时闪现 PostHog Orange 或 Amber Gold 文字——这是品牌签名式交互惊喜。卡片Warm Parchment/白底 1px#bfc1b7边框 4–6px 圆角Sage Surface Card 用#eeefe9Shadow Card 仅0px 25px 50px -12px rgba(0,0,0,0.25)一个深阴影。表单#eeefe9底 #9ea096占位 1px#b6b7af边框 4px 圆角focus 为#3b82f650% 透明度 ring输入值文字#374151比主文字更深以保证可读性。导航顶栏暖背景、IBM Plex Sans 15px/600、链接 Deep Olive#23251dhover 下划线、右侧 Dark Primary CTA移动端折叠为汉堡菜单。图像处理手绘刺猬吉祥物、产品截图入设备框、企业 Logo 静音信任条Airbus、GOV.UK 等插画不规则、截图 16:9。3.4 布局、深度与响应式间距基单位 8px刻度含 2/4/6/8/10/12/16/18/24/32/34px 的 off-grid 值区块垂直留白 32–48px内容容器 1280pxtoken 固化值断点 13 个1px 至 1536px。圆角刻度2px 小内联元素、4px 主力按钮/输入/下拉、6px 次级容器、9999px 药丸。纵深体系仅有 4 级Level 0 平坦、Level 1 单边框、Level 2 复合边框、Level 3 唯一深阴影模态/下拉/巨型菜单专用——全系统只存在一个阴影定义其余深度全部靠#fdfdf8 → #eeefe9 → #e5e7e0的表面色阶递进传达。Dos保持橄榄/鼠尾草色族、hover 闪橙、标题用 IBM Plex Sans 700/800、正文行高 1.50–1.71、暖羊皮纸背景、4px 圆角主力、手绘插画、深色按钮用 opacity 型 hover。Donts禁用蓝紫科技色、禁止重阴影、禁止过度精致、禁止正文紧行高、禁止 12px 大圆角卡片、禁止去掉橙色 hover 闪光、禁止用库存摄影替代插画、禁止纯白#ffffff页面背景。3.5 Agent Prompt Guide可直接复用的提示词资产DESIGN.md第 9 节直接面向生成式 Agent 提供了可复制提示词例如Create a hero section on warm parchment background (#fdfdf8) with 30px IBM Plex Sans heading at weight 800, line-height 1.20, letter-spacing -0.75px, olive ink text (#4d4f46), and a dark CTA button (#1e1f23, 6px radius, white text, opacity 0.7 on hover)以及迭代检查清单Iteration Guide核对背景为#fdfdf8而非纯白全部文字走橄榄族而非纯黑/中性灰hover 必须闪#F54E00边框用#bfc1b7而非中性灰整体调性应是有趣的初创 wiki而非企业抛光感。四、Token 契约evidence.md 的核心机制evidence.md的Token Contract一节定义了本包最重要的工程机制source/token-contract.report.jsonmaps every TOKEN_SCHEMA binding back to the committedtokens.cssdeclaration line.即契约报告token-contract.report.json将共享 schemaTOKEN_SCHEMA中的每一个 Token 绑定逐条映射回已提交的tokens.css声明行。这意味着设计系统的每个取值都可审计、可溯源、可自动校验而不是散落的魔法数字。从 source/token-contract.report.json 可以看到这份契约的执行质量{ contract: TOKEN_SCHEMA, summary: { totalTokens: 56, declaredTokens: 56, sourceBackedTokens: 56, sourceBackedA1: 26, fallbackTokens: 26, aliasTokens: 0, layerCounts: { A1-identity: 8, B-slot: 4, A2: 26, A1-structure: 18 }, score: 100, grade: excellent, recommendRebuild: false } }56 个 Token 全部由tokens.css声明背书评分 100、评级 excellent、无需重建。每条绑定都带confidence: high与原因说明例如--bg的sources: [tokens.css:111]——精确到声明行号。4.1 TOKEN_SCHEMA 的分层模型从layerCounts可以看到共享 schema 的四层结构对应 design-systems/_schema/tokens.schema.ts 中的定义A1-identity8 个品牌身份层--bg、--fg、--muted、--border、--accent、--font-display、--font-body等是品牌不可妥协的核心绑定A1-structure18 个结构层类型字号--text-xs~--text-4xl、行高、字距、区块节奏、容器宽度等B-slot4 个槽位层--surface-warm、--fg-2、--meta、--border-soft品牌可独立绑定或通过var(...)别名到 A1 兄弟A226 个通用层--accent-on/hover/active、--success/warn/danger、间距、圆角、阴影、动效等schema 提供 fallback 默认值。26 个 fallback Token 的存在说明当品牌未发布某类取值时如 PostHog 未发布橙色按压态 hexschema 的 A2 默认值即兜底保证跨品牌一致性。五、tokens.css 逐条精读9 条品牌绑定决策tokens.css 头部注释以#Bind 1~#Bind 9的形式逐条记录了将 DESIGN.md 视觉规范编译进共享 schema 的决策理由这是本包最有价值的工程文档#Bind 1表面--bg绑定 Warm Parchment#fdfdf8永不使用纯白——DESIGN.md §7 明令禁止#ffffff--surface一级递进到 Sage Cream#eeefe9--surface-warm再递进到 Light Sage#e5e7e0三级表面用色阶替代阴影制造深度。#Bind 2前景--fg橄榄族而非中性灰——Olive Ink#4d4f46承载正文Deep Olive#23251d递进用于标题/高强调链接Muted Olive#65675e次级文字Sage Placeholder#9ea096禁用/元信息层。#Bind 3强调色--accent绑定 PostHog Orange#F54E00但几乎只作为 hover 时的文字色而非 CTA 填充——主要 CTA 按 §4 渲染为深色--fg-2领域hover/active 使用 schema 的color-mix默认black 8%/black 14%因为 DESIGN.md 未发布橙色按压态 hex。#Bind 4语义色--warn绑定 Amber Gold#F7A501DESIGN.md §2 的深色按钮 hover 强调、温暖信号--success/--danger留在 schema 默认值因为 DESIGN.md 未发布品牌绿/红。#Bind 5圆角刻意收紧——4px 是按钮/输入主力6px 是卡片层8px 封顶 lg12px 被 §7 Donts 明令禁止pill 保持 9999px 用于徽章与状态点。#Bind 6阴影--elev-raised是系统唯一被认可的阴影§6 only one shadow definition exists in the entire system仅限模态/下拉/巨型菜单等浮动元素卡片不得使用。#Bind 7焦点环--focus-ring绑定 Focus Blue#3b82f650% 透明度系统内唯一冷色作为仅限可访问性的键盘导航焦点色。#Bind 8字号天花板--text-2xl30px 为 display hero 上限、--text-3xl36px 为 section heading--text-4xl外推 44px 供 fixture 级 hero 文案-0.025em字距归一化 30px 处的 -0.75px。#Bind 9容器--container-max1280px§5 推断区间 1200–1280px 的上限gutter 按桌面/平板/手机递进为 24/16/12px匹配内容密集型编排节奏。Warm Tan#d4c9b8与 Hover White#f4f4f4两个品牌专属值不进入共享 token而是内联在需要的组件处——这是共享 schema 只收纳可复用层的克制设计。5.1 :root 块的关键声明速览:root { /* Surface3 级 */ --bg: #fdfdf8; --surface: #eeefe9; --surface-warm: #e5e7e0; /* Foreground ramp4 级 */ --fg: #4d4f46; --fg-2: #23251d; --muted: #65675e; --meta: #9ea096; /* Border2 级 */ --border: #bfc1b7; --border-soft: color-mix(in oklab, var(--border), var(--bg) 50%); /* Accent */ --accent: #F54E00; --accent-hover: color-mix(in oklab, var(--accent), black 8%); --accent-active: color-mix(in oklab, var(--accent), black 14%); /* Typography */ --font-display: IBM Plex Sans Variable, IBM Plex Sans, -apple-system, system-ui, Avenir Next, Avenir, Segoe UI, Helvetica Neue, Helvetica, Ubuntu, Roboto, Noto, Arial, sans-serif; --text-base: 16px; --text-2xl: 30px; --leading-body: 1.5; --tracking-display: -0.025em; /* Elevation Focus */ --elev-flat: none; --elev-raised: 0px 25px 50px -12px rgba(0, 0, 0, 0.25); --focus-ring: 0 0 0 3px rgba(59, 130, 246, 0.5); /* Motion */ --motion-fast: 150ms; --ease-standard: cubic-bezier(0.2, 0, 0, 1); /* Layout */ --container-max: 1280px; }注意--border-soft通过color-mix(in oklab, ...)向--bg混 50% 派生保证暖绿家族一致性而不引入新 hex动效部分因 DESIGN.md 为静态抽取范围未发布过渡规格回填绑定 schema 默认值150ms/200ms、标准缓动。六、派生产物design-tokens.json 与 tailwind-v4.cssevidence.md对派生产物给出了明确的编辑禁令design-tokens.jsonandtailwind-v4.cssare derived outputs and should be regenerated from the report and token stylesheet rather than edited by hand.即design-tokens.jsonschema 版本od-design-tokens/v1与tailwind-v4.css都是派生输出必须从契约报告 tokens.css重新生成禁止手工编辑——这保证了任何品牌的 token 变更都能通过单一事实源向下游可靠传播。tailwind-v4.css 头注释直接声明 Derived from tokens.css. Keep tokens.css as the source of truth.其实现方式是theme块内的逐项桥接例如import tailwindcss; import ./tokens.css; theme { --color-bg: var(--bg); --color-accent: var(--accent); --font-display: var(--font-display); --text-2xl: var(--text-2xl); --shadow-raised: var(--elev-raised); --spacing-section-desktop: var(--section-y-desktop); }由此 Tailwind v4 的bg-bg、text-fg、shadow-raised等工具类即可与品牌 token 一一对应。而design-tokens.json则在契约报告基础上增加了type字段color/typography/spacing 等与分层归属供其他消费端如设计 token 解析器使用。七、组件清单与独立 fixturecomponents.manifest.json 对components.html做了结构化盘点可作为无需打开 HTML 的组件速查表规模1 个style块、82 个选择器、42 个 class、32 个元素literals显示像素值 38 处、硬编码字体族 13 处、颜色表达式 0 处——印证所有可见值都来自 tokens.css的承诺。组件组groupsbuttons.btn/.btn-primary/.btn-secondary/.btn-ghost及 hover/active/focus-visible 状态、inputs.field下的 input/select/textarea/placeholder/focus-visible、cards.card/.card-warm/.panel、badges.pill/.pill-soft/.pill-status/.pill-warn、links、keyboardkbd、icons、typography、layout.container/.nav-*/.stack-*/.row-*。token 引用关系每组都列出其引用的 token 集合例如 cards 组引用--accent/--bg/--border/--elev-raised/--radius-md/--space-3~5等为组件与 token 之间的依赖分析提供机器可读数据。未用声明unusedDeclared--accent-active、--danger、--elev-flat、--radius-lg、--text-2xl等 11 个 token 在当前 fixture 中未被引用但仍保留在共享层供其他页面/组件按需消费。components.html本身是自包含 fixture——首个style内嵌与tokens.css字节等价规范化后的:root块任何浏览器打开即可独立渲染无需外部依赖。八、契约的机器校验guard 检查链路证据链并非一次性产物OpenDesign 通过 scripts/check-tokens-fixture-sync.ts 以 6 个 guard 检查函数持续守护 Token 契约并注册进pnpm guard见 scripts/guard.ts让失败精确定位到具体契约checkDesignSystemTokenFixtureSynccomponents.html的:root与tokens.css的:root规范化后字节等价checkDesignSystemA1RequiredTokens每个品牌必须声明 schema 的全部 A1-identity / A1-structure token缺失即失败checkDesignSystemA2RequiredTokens每个品牌必须声明全部 A2 tokencheckDesignSystemBSlotRequiredTokensB-slot token 必须出现在:root中可独立绑定或var(...)别名否则运行时空解析checkDesignSystemUnknownTokens品牌声明的每个 token 必须在共享 schema 中或属于BRAND_EXTENSIONS/BRAND_EXTENSION_PREFIXES白名单防止游离命名checkDesignSystemA2DefaultsParity_schema/defaults.css中每个 A2 声明与tokens.schema.ts对应条目的fallback字段一致。单独运行方式为pnpm exec tsx scripts/check-tokens-fixture-sync.ts。这条链路配合token-contract.report.json的逐行溯源构成了schema 定义 → 品牌绑定 → 派生产物 → 机器校验的闭环也解释了为何evidence.md可以自信地断言每个 TOKEN_SCHEMA 绑定都能映射回tokens.css的声明行。九、在 Agent 工作流中的实战用法综合 USAGE.md 与 DESIGN.md 的指引OpenDesign Agent 消费该包的标准流程是注入令牌将tokens.css的:root { … }块原样粘贴到首个工件style顶部之后所有取值一律var(--*)引用杜绝裸 hexUSAGE.md Avoid 第 1 条对照规范以DESIGN.md的 Dos/Donts 作为视觉约束清单特别守住四条红线——暖羊皮纸背景非纯白、橄榄文字族非中性灰、hover 橙色闪光不可移除、卡片不得使用 12px 圆角或重阴影复用组件从components.manifest.json的组件组中复用现有控件而不是发明新控件需要精确选择器/状态时查components.html抽查预览用preview/colors.html、preview/typography.html、preview/spacing.html做视觉 sanity check保持 schema 稳定保留 schema token 名称不变跨品牌切换如切换到同目录下其他品牌包时才可靠遵循生成提示词直接套用 DESIGN.md §9 的 Example Component Prompts 与 Iteration Guide将品牌约束编码进 prompt。十、结语PostHog 设计系统包是 OpenDesign Design System 2.0 回填管线的一个完整样本evidence.md负责声明来源边界与派生规则DESIGN.md承载全部视觉规范与 Agent 提示词tokens.css以 56 个分层 token 固化为唯一事实源token-contract.report.json提供逐行溯源design-tokens.json与tailwind-v4.css作为受控派生产物最后由 guard 检查链路闭环守护。理解这套证据 → 规范 → 令牌 → 契约 → 校验的工程化路径即可举一反三地解读或复现仓库中其他品牌airbnb、stripe、figma、github 等的设计系统资产。【免费下载链接】open-design Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. ️ Local-first desktop app. ️ Your coding agent becomes the design engine: prototypes, landing pages, dashboards, slides, images video — real files, HTML/PDF/PPTX/MP4 export. Claude Code / Codex / Cursor / DeepSeek Harness / OpenCode 20 CLIs via BYOK.项目地址: https://gitcode.com/gh_mirrors/opend/open-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考