Communitygithub.com

MarketingOS 原子设计系统

构建或扩展一个基于品牌的原子设计系统,包含令牌、组件规范和一个 HTML 审查站点。适用于设计系统、UI 工具包、组件库、品牌到令牌的工作以及 Figma 令牌导出。可在活动的 MarketingOS 思维或独立的品牌文件上工作;保留现有系统和阶段审批。

MarketingOS 原子设计系统 是什么?

MarketingOS 原子设计系统是一个全面的框架,用于将品牌转变为可审查的设计系统。它采用分层方法:从发现阶段开始,建立令牌(tokens),然后逐步构建原子、分子、有机体、模板和页面,每个阶段之间都需要人工审批。该系统支持 v2 结构(最新的推荐布局)和遗留的 v1 系统,并包含明确的迁移路径。关键功能包括:自动品牌发现、设计灵感研究、强制令牌层级(品牌 → 别名 → 映射 → 响应式)、组件规范文件、静态 HTML 审查站点以及 Figma 变量导出。它适用于 MarketingOS 上下文(从活动的思维和项目记录中读取)或独立的品牌文件。该框架强调“先发现后设计”和“阶段间把关”,以防止错误在构建过程中传播。它使用 Bun 运行 TypeScript 脚本,提供验证脚本以确保一致性,并包含一个路由器,可根据项目状态决定适当的操作(例如,新系统、遗留系统或迁移)。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/the-vibe-marketing-lab/mos-design-skills/tree/HEAD/mos-atomic-design-system

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

MarketingOS 原子设计系统 是做什么的?

将品牌转变为一个可审查的设计系统:分层令牌、每个组件一个规范文件、以及一个静态 HTML 参考站点,每次只构建一个梯级,每级之间需要人工签字——所有内容都放在一个design-system/文件夹下,无论是人还是代理都可以通过一个单一的 README 进行导航。

MarketingOS 上下文和先决条件

从当前会话及其项目记录中解析活动的业务思维和网站目标。在请求信息之前,先读取思维的 BRAIN.md 或代理指令、CONTEXT.md、品牌、声音、受众、优惠和已保存的设计参考。保持每个业务的上下文独立。在设计简报中记录源思维和目标。当在没有 MarketingOS 的情况下使用时,则从提供的品牌文件入手,并识别真正的差距。

使用 Bun 来运行捆绑的 TypeScript 脚本。如果 Bun 缺失,引导用户访问官方安装说明 https://bun.com/docs/installation。将 $SKILL 解析为包含此加载的 SKILL.md 的真实目录;代理安装在不同的位置,因此不要假设特定的主路径。

如果用户选择了“品味技能”(Taste Skill),首先阅读其已安装的指令,并将其艺术指导和参考发现结果作为此框架的输入。保留此框架的品牌契约、令牌系统和阶段决策。品味技能是一个单独的可选依赖项,不与此包捆绑;当请求安装时,请查看其当前官方说明 https://github.com/leonxlnx/taste-skill。

一个初始提示可以驱动整个工作流程。将必要的决策和视觉阶段审批保持在同一个对话中,每次回复后恢复,无需再次复制粘贴提示。在用户请求的阶段停止;不要将一次调用视为跳过审批的许可。

核心理念

设计系统失败的方式有两种。要么是凭空创造的——模型挑选了一个漂亮的调色板,结果自信、连贯,但不是品牌。要么是一口气构建完成,因此底层的一个错误决定会悄无声息地传播到二十页,然后才有人看到。

本技能解决了这两个问题。先发现后设计: 找出已经决定的内容,并明确说明差距。梯级之间的关卡: 在基础层修改是五行代码的编辑;而在页面层同样修改则是二十页的工作。

路由器

确定用户所处的位置,然后采取行动。不要询问他们想要什么模式。

情况执行此操作
没有 STATE.json 且发现未找到现有的原子系统开始阶段 0 (v2 布局)
发现报告存在 existingAtomicSystem,但没有 STATE.json(手动构建的 HTML,例如现有项目的 public/atomic-framework/,或旧项目的 stage-*.html)遗留系统。 在其自己的文件和命名约定中扩展它:添加到其现有页面,保持其标记/类/ID 约定,并在其旁边的一个小 ATOMIC-NOTES.md 中记录新工作。其约定被保留,但质量底线不会降低:可见的 :focus-visible,44px 目标,对比度,以及一个包含“取用”和“留下”的灵感地图。如果它存在于一个兄弟仓库中,那就是第二个仓库——在写入之前询问(参见安全),并给出一个简短的 DESIGN-SYSTEM.md 指向它。除非用户要求迁移,否则不要搭建 v2。使用 verify-stage.ts --legacy <dir> 进行验证。详细信息:references/output-structure.md
design-system/STATE.json 包含 schemaVersion: 2v2 系统:报告状态,运行下一个未审批的阶段
STATE.json 不包含 schemaVersion: 2(在 docs/design-system/ 或 design-system/docs/ 下)v1 系统 由旧技能构建。在其 v1 布局和约定中扩展它(如果缺少 v1 脚手架文件,则使用 init-system.ts --schema 1)。除非用户要求,否则不要迁移
"迁移到 v2" / "移动到新结构"在分支上遵循 references/output-structure.md 中的迁移程序
"重做分子"(或请求中包含 --stage <n>)重建该阶段,标记下游为过时状态
"我们在哪里"(或 --status)打印阶梯,显示每个阶段的状态和版本,然后停止
"导出到 figma" / "figma 变量"运行 export-figma.ts —— 参见 references/figma-export.md。永远不是阶梯的一部分
用户明确放弃关卡("不要停下来等待审批";在评估或 CI 中使用 --non-interactive)不间断地运行阶梯,并在最后一起呈现所有关卡——参见下面的“放弃审批”
目标仓库不明确询问一次。不要在兄弟仓库之间猜测

首先解析目标仓库。其他所有内容都相对于它。

上面的 --stage、--status 和 --non-interactive 是用户向此技能提出请求的方式——是行为模式,而不是脚本标志。

设置

# 将 SKILL 设置为包含已加载 SKILL.md 的真实目录
bun $SKILL/scripts/discover-brand.ts --target <repo> [--siblings <dir>]   # 阶段 0
bun $SKILL/scripts/init-system.ts    --target <repo>               # 搭建 v2;仅对旧技能的 v1 系统使用 --schema 1
bun $SKILL/scripts/init-system.ts    --target <repo> --page <file> # 从 shell 阶段页面,填充 rail 和 aria-current
bun $SKILL/scripts/verify-stage.ts   --target <repo> --stage <n>   # 读取 schemaVersion;对手动构建的系统使用 --legacy <dir>
bun $SKILL/scripts/build-index.ts    --target <repo>               # 在每个审批阶段之后
bun $SKILL/scripts/export-tokens.ts  --target <repo>               # tokens.css → tokens.json + TOKENS.md (build-index 会运行它)
bun $SKILL/scripts/export-figma.ts   --target <repo>               # 可选

discover-brand.ts 默认搜索目标及其父目录。当活跃思维位于其他地方时,使用 --siblings <dir>。即使发现未找到匹配的兄弟,也要明确读取已解析的思维。每个脚本标志都在 references/output-structure.md 中有文档说明。

输出 (v2) —— 一个根目录,一个入口文件,每个组件一个规范文件:

design-system/
├── README.md          从此处开始——人和代理的入口点
├── STATE.json          schemaVersion 2, stages, approvals, inventory, version, themes
├── CHANGELOG.md        每个审批阶段/发布对应一条记录
├── brief/DESIGN-BRIEF.md
├── tokens/             tokens.css (规范) · tokens.json · TOKENS.md (生成) · figma/ (可选)
├── foundations/FOUNDATIONS.md
├── components/         INDEX.md (生成) · atoms/ molecules/ organisms/ templates/ <ID>-<slug>.md
├── rules/RULES.md
└── reference/          静态 HTML 审查站点 (noindex) · styles.css · pages/P-nn-<slug>.html

为什么这样组织、README 规范、v1 → v2 路径表以及迁移程序:references/output-structure.md。在搭建、编写 README 或进行迁移时阅读它。

阶梯

七个构建阶段。基础层放在原子之前,因为没有令牌就无法构建原子;规则放在最后,因为护栏是从实际决定的内容中编写的。路径相对于 design-system/。

#阶段产出
0发现brief/DESIGN-BRIEF.md, STATE.json, README.md 骨架, CHANGELOG.md, reference/index.html (00)
1基础层tokens/tokens.css (+ 生成的 json/md), foundations/FOUNDATIONS.md, reference/foundations.html (01)
2原子components/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A)
3分子components/molecules/M-nn-*.md, reference/molecules.html (03)
4有机体components/organisms/O-nn-*.md, reference/organisms.html (04)
5模板components/templates/T-nn-*.md, reference/templates.html (05)
6页面reference/pages.html (06), reference/pages/P-nn-*.html, reference/rules.html (07), rules/RULES.md, 最终 README.md, 版本 1.0.0

每个阶段的完整工件和验收标准:references/stage-specs.md。只阅读你当前所处阶段的章节,而不是整个文件。

阶段 0 — 发现

三个输入,然后综合。同时做前两个;它们不相互依赖。

1. 设计灵感。 首先重用来自活跃思维或品味技能传递的已保存参考;仅对缺少的原始 URL 进行询问——三到六个,最好是具体页面而非首页。使用可用的浏览器工具截取每个页面的快照,检查实际字体和布局。仅当 Interceptor 已安装且适合当前会话时使用它。提取计算出的调色板、字体堆栈、间距节奏和圆角——实际的渲染值,而非营销用的十六进制色值。

2. Mobbin MCP(可选)。 用于 URL 无法回答的模式问题:此类别的典型应用如何序列化引导流程、构建定价结构、处理空状态。MCP 可能已安装但未认证——如果只暴露了 mcp__mobbin__authenticate / complete_authentication,则运行 OAuth 流程并将 URL 交给用户。如果他们拒绝,则继续并在简报中记录此差距。永远不要暗示模式研究实际发生但实际并未发生。

3. 品牌发现。 运行 discover-brand.ts。它会探测目标及其兄弟仓库中的已知路径约定,合并配套文档,并在排名前按品牌家族进行分区——这样另一个品牌的精美文档就永远不会胜出。从中读取三件事:哪个文档、视觉契约是 full/partial/verbal-only,以及原子系统是否已经存在(如果存在,则扩展它而不是重新开始)。

在编译任何内容之前,向用户确认品牌来源。 这是一个错误,一旦发生,将使下游所有阶段无效。

然后编写 DESIGN-BRIEF.md。其灵感地图需要每一行的两半——我们“取用”的内容和我们有意“留下”的内容。“留下”列是判断所在之处;只包含“取用”的行是拼贴指令。其 §3 视觉契约命名了每种色调及每个给定十六进制色值所在的台阶、主题以及字体比例——阶段 1 编译的输入。

详细信息:references/brand-discovery.md 和 references/inspiration-research.md。

阶段 1–6 — 循环

每个阶段运行相同的五个节拍。

1. 构建。 遵循阶段规范。仅组合已审批的低层级组件。如果一个阶段需要一个基础层尚未提供的令牌,那意味着基础层不完整——返回并修改它,而不是定义局部值,否则系统会开始自相矛盾。阶段 1:首先阅读 references/token-architecture.md。阶段 2–4:首先阅读 references/component-anatomy.md,并从 assets/docs/COMPONENT-SPEC.md 为每个组件编写一个规范文件,连同其样本。阶段 1 还会运行 export-tokens.ts,以便在审查时 tokens.json 和 TOKENS.md 已经存在。使用 init-system.ts --page <file> 启动每个阶段页面,这样 rail 是生成的,而不是手动复制的。

2. 验证。 bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n>。在展示任何内容之前,修复它报告的问题。它检查 ID 连续性、tokens.css 之外的原始值、层级标记和层级引用、焦点处理、noindex、rail 连线、有机体配方和状态排序。

3. 展示。 在审查者之前查看渲染的页面,按此顺序:会话的可用浏览器工具在本地 HTTP 上渲染,并加载字体 → 另一个可用的可视化浏览器工具 → 仅进行 DOM 检查(计算的令牌、已加载的字体、在 375px 宽度下无水平滚动)。无头模式会遗漏 Web 字体和渲染问题,而这些正是判断的大部分内容。说明你使用了哪个层级以及未以视觉方式检查的内容。

4. 关卡。 展示工件,并使用可用的提问工具或简洁的消息询问:

  • 批准 → 推进 STATE.json,解锁下一阶段
  • 修改 → 记录意见,重建,验证,再次展示
  • 附带意见批准 → 推进,将意见记录为未决决策

只有在得到明确同意时才推进。关卡之所以存在,是因为审查者对品牌的了解有些地方没有记录下来——而且因为它是一个节流阀,可以让大型构建在原子阶段停止,并在下周继续。

放弃审批。 当用户明确表示不要停止时(或者评估或 CI 提示以非交互方式运行时),则不间断地运行阶梯:从请求和证据中回答阶段 0 的访谈,在简报的未决决策中将每个此类答案标记为临时,在 STATE.json 和 CHANGELOG.md 中将每个阶段记录为“未经审查批准(由用户放弃)”,并在最后一起呈现所有关卡。永远不要凭自己的判断放弃——一个沉默的用户并没有放弃任何东西。详细信息:references/stage-specs.md。

5. 索引。 批准后:将阶段的规范标记为 status: approved,运行 build-index.ts(重新生成 tokens.json、TOKENS.md、components/INDEX.md 和 README 文件索引),追加一个只列出更改的 CHANGELOG.md 条目,并更新 STATE.json 的 version——从基础层的 0.1.0 到模板层的 0.5.0;批准页面则发布 1.0.0。修改已审批的阶段是一个补丁版本(重新审批每个过时的下游阶段也是如此);完整规则见 references/output-structure.md。生成的文件带有“请勿手动编辑”的头部;编辑其源文件并重新运行。

当你展示一个阶段时,保持简短:构建了什么,每个级别的计数,任何你必须在没有证据的情况下做出的决定,以及最值得一看的一件事。而不是对每个样本的逐一介绍。

普遍适用的约定

完整细节见 references/html-conventions.md。关键约定:

  • 零填充连续 ID——A-01、M-17、O-04、T-05、P-02——在 UI 中通过 .card-label 显示,在 data-* 中镜像,并与规范文件名匹配。一旦批准即保持稳定;重新编号会破坏所有引用。
  • 四个令牌层级——品牌 → 别名 → 映射 → 响应式,每个层级由 tokens.css 中的一个 @tier 标记开始。原始字面量仅出现在品牌和响应式层级中。颜色、边框宽度和圆角从映射 → 别名 → 品牌,从不跳过;映射的 --space-*、--duration-*、--ease-*、--shadow-* 直接定义,因为他们本身就是别名。
  • 每个文件一个组件,以组件 ID 命名(例如 A-01-button.md)。
  • 每个组件必须有一个样本:一段用组件标记语言编写的、用 ```html 围起来的 HTML 片段,说明其所有状态和变体。一个只有规范而没有样本的组件是一个架构决策,而不是一个设计系统组件。
  • 静态 HTML 审查站点放置在 reference/styles.css 上自我样式,从通用原子页面样式(阶段 0 搭建时创建)开始,然后随着阶段进展填充实际令牌。使用 init-system.ts --page <file> 搭建新页面。
  • noindex,不是 nofollow。 整个 reference/ 目录对搜索引擎是 noindex 的。永远不要添加外部链接;审查站点是用于预览,而非发布。
  • 三个级别的列表适用于 Pages(页面级别)食谱。
  • 所有.RULES.md 条目必须以“DO”或“DO NOT”开头,后跟一个简短的解释。

关键参考文件

本技能附带了几个 Markdown 参考文件,必须按需阅读:

  • references/output-structure.md — 整体结构、README 规范、索引生成、版本控制和迁移路径。
  • references/stage-specs.md — 每个阶段的详细工件、验收标准和注意事项。
  • references/token-architecture.md — 四个层级的结构、命名和推导规则。
  • references/component-anatomy.md — 组件规范的结构和内容。
  • references/html-conventions.md — 所有设计系统中统一的 HTML 结构和 CSS 约定。
  • references/brand-discovery.md — 自动品牌发现过程的详细信息。
  • references/inspiration-research.md — 如何收集和记录设计灵感。
  • references/figma-export.md — 可选的 Figma 变量导出。
  • assets/docs/COMPONENT-SPEC.md — 可作为组件规范基础的模板。

始终读取与当前任务相关的参考部分,而不是一次性读取整个文件。

安全与引导

  • 对同时进行的更改保持安全。 两个代理可能会修改同一个设计系统;总是依赖对 STATE.json 的乐观锁和明确的阶段所有权。
  • 重叠上下文。 如果当前项目上下文与来自不同思维项目的另一个设计系统重叠,则发出警告。保持上下文分离。
  • 避免破坏性操作。 除了 --rebuild 标志外,此系统永远不会删除文件。始终保留已批准阶段的工作副本,并在安全的位置(如有必要,在分支上)记录任何雄心勃勃的清理操作。
  • 不要猜测。 如果目标仓库或程序不明确,请提问。避免基于不完整信息的假设。

使用

# 设置 SKILL 并运行发现
bun $SKILL/scripts/discover-brand.ts --target <target-repo-path>

# 搭建 v2 系统
bun $SKILL/scripts/init-system.ts --target <target-repo-path>

# 搭建一个特定页面
bun $SKILL/scripts/init-system.ts --target <target-repo-path> --page <page-filename>

# 验证一个阶段
bun $SKILL/scripts/verify-stage.ts --target <target-repo-path> --stage <stage-number>

# 重建索引(在每个审批阶段之后)
bun $SKILL/scripts/build-index.ts --target <target-repo-path>

# 导出令牌(由 build-index 自动运行)
bun $SKILL/scripts/export-tokens.ts --target <target-repo-path>

# 导出到 Figma(可选)
bun $SKILL/scripts/export-figma.ts --target <target-repo-path>

贡献

在 references/ 下为每个约定的方面添加或更新参考文件。标记关键行为以确保一致性。

许可

[在此处包含适当的许可信息]

相关技能