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: 2 | v2 系统:报告状态,运行下一个未审批的阶段 |
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/ 下为每个约定的方面添加或更新参考文件。标记关键行为以确保一致性。
许可
[在此处包含适当的许可信息]