Communitygithub.com

MarketingOS 原子設計系統

基於品牌建立或擴充可審查的原子設計系統,包含層級化令牌、元件規格檔案與靜態 HTML 參考網站。適用於設計系統、UI 套件、元件庫、品牌到令牌的轉換與 Figma 令牌匯出。可在 MarketingOS 環境或獨立品牌檔案中運作;保留既有系統與階段審核結果。

MarketingOS 原子設計系統 是什麼?

MarketingOS 原子設計系統是一個結構化的工作流程,能將品牌資產轉變為完整、可審查的原子設計系統。它解決了設計系統常見的兩大痛點:發明式設計(模型自創漂亮色板,結果雖連貫卻非品牌本色)與一次性建構(底層錯誤默默傳播數十頁,直到最後才被發現)。此技能採用七階段「階梯式」建構方式,從探索(Stage 0)開始,依次經過基礎元素(Stage 1)、原子(Stage 2)、分子(Stage 3)、有機體(Stage 4)、模板(Stage 5)到頁面(Stage 6),每個階段之間都設有人工審核關卡(Gate),確保每個決策都經過確認後才繼續往下,避免錯誤擴散。它支援在 MarketingOS Brain 環境或獨立品牌檔案下運作,並能處理 v1(舊版)與 v2(目前版本)系統,也可擴充既有手動建立的系統。技能產出包含層級化 CSS 自訂屬性令牌(品牌→別名→映射→響應式)、每個元件的獨立規格檔案(COMPONENT-SPEC.md),以及一個靜態 HTML 參考網站,所有檔案均集中在 `design-system/` 目錄下,方便人類或代理程式從單一 README 導航。工作流程採用 Bun 作為 TypeScript 腳本執行環境,並提供多個輔助腳本(如 `discover-brand.ts`、`init-system.ts`、`verify-stage.ts`、`build-index.ts` 等)來自動化建構與驗證。

相容平台✓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 環境與先決條件

從當前工作階段及其專案記錄中解析出活躍的商業大腦(business brain)與網站目標。在詢問資訊前,先讀取大腦的 BRAIN.md 或代理程式指令、CONTEXT.md、品牌、語調、受眾、提案以及已儲存的設計參考資料。保持每個商業的環境獨立。在設計簡報中記錄來源大腦與目標。當未使用 MarketingOS 時,則根據提供的品牌檔案工作,並識別真正的缺口。

使用 Bun 來執行捆綁的 TypeScript 腳本。如果缺少 Bun,引導使用者前往官方安裝說明頁面 https://bun.com/docs/installation。解析 $SKILL 為載入此 SKILL.md 的真實目錄;代理程式安裝位置各異,請勿假設特定路徑。

如果使用者已選用 Taste Skill,請先讀取其安裝說明,並將其藝術方向與參考發現作為此框架的輸入。保留此框架的品牌合約、令牌系統與階段決策。Taste Skill 是獨立的選用依賴項,未隨此套件捆綁;當要求安裝時,請查閱其當前官方說明文件 https://github.com/leonxlnx/taste-skill。

一個初始提示即可驅動完整工作流程。在同一個對話中保留必要的決策與視覺階段審核,每次回覆後繼續進行,無需再次複製貼上提示。在使用者要求的階段停止;不要將一次調用視為跳過審核的許可。

理念

設計系統的失敗通常有兩種方式。一種是發明式——模型挑選了一個漂亮的色板,結果雖然自信、連貫,但並非品牌本色。另一種是一次性建構,導致底層的錯誤決策在任何人發現之前,就已默默地傳播到二十頁。

此技能同時解決了這兩個問題。探索先於設計: 先找出已經決定的部分,並明確指出缺口。階梯之間的關卡: 在基礎元素階段的修改只是五行編輯;同樣的修改到了頁面階段則是二十頁的大工程。

路由器

判斷使用者當前所處情境,然後採取行動。不要詢問他們想要哪種模式。

情境執行此操作
沒有 STATE.json,且探索未發現現有的原子系統開始 Stage 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>]   # Stage 0
bun $SKILL/scripts/init-system.ts    --target <repo>               # 建立 v2 支架;僅對舊技能的 v1 系統使用 --schema 1
bun $SKILL/scripts/init-system.ts    --target <repo> --page <file> # 從 shell 建立階段頁面,帶有導覽列與 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、階段、審核、庫存、版本、主題
├── 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 或進行遷移時請閱讀此文件。

階梯

七個建構階段。基礎元素(Foundations)排在原子(Atoms)之前,因為沒有令牌就無法建構原子;規則(Rules)排在最後,因為護欄是根據實際決策內容來撰寫的。路徑相對於 design-system/。

#階段產出
0探索(Discover)brief/DESIGN-BRIEF.md、STATE.json、README.md 骨架、CHANGELOG.md、reference/index.html (00)
1基礎元素(Foundations)tokens/tokens.css(+ 產生的 json/md)、foundations/FOUNDATIONS.md、reference/foundations.html (01)
2原子(Atoms)components/atoms/A-nn-*.md、reference/atoms.html (02)、reference/icons.html (02A)
3分子(Molecules)components/molecules/M-nn-*.md、reference/molecules.html (03)
4有機體(Organisms)components/organisms/O-nn-*.md、reference/organisms.html (04)
5模板(Templates)components/templates/T-nn-*.md、reference/templates.html (05)
6頁面(Pages)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。只閱讀你當前所處階段的章節,而非整個文件。

Stage 0 — 探索(Discover)

三個輸入,然後進行綜合。前兩個可以並行處理;它們彼此沒有依賴關係。

1. 設計靈感。 首先重複使用來自活躍大腦或 Taste Skill 傳遞的已儲存參考資料;僅要求提供缺失的原始 URL——三到六個,盡可能是特定頁面而非首頁。使用可用的瀏覽器工具對每個 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 節「視覺合約」應命名每種色調、每個給定十六進位色碼所處的階梯、主題以及字型比例——這些是 Stage 1 編譯的輸入。

詳細資訊:references/brand-discovery.md 和 references/inspiration-research.md。

Stage 1–6 — 迴圈

每個階段都執行相同的五個步驟。

1. 建構。 遵循階段規格。僅組合已審核通過的下層元件。如果一個階段需要一個基礎元素階段沒有的令牌,這意味著基礎元素階段不完整——應返回並修改它,而不是定義一個局部值,否則系統會開始自相矛盾。Stage 1:先閱讀 references/token-architecture.md。Stage 2–4:先閱讀 references/component-anatomy.md,並根據 assets/docs/COMPONENT-SPEC.md 為每個元件撰寫一個規格檔案,連同其樣本一起。Stage 1 還會執行 export-tokens.ts,以便在審查時 tokens.json 和 TOKENS.md 已存在。使用 init-system.ts --page <file> 開始每個階段頁面,以便導覽列是自動產生的,而非手動複製的。

2. 驗證。 執行 bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n>。在展示任何內容之前,先修復它報告的問題。它會檢查 ID 連續性、tokens.css 外部的原始值、層級標記與層級引用、焦點處理、noindex、導覽列連接、有機體配方以及狀態順序。

3. 展示。 在審查者之前檢視渲染後的頁面,順序如下:會話中可用的瀏覽器工具透過本地 HTTP 檢視,並載入字型 → 另一個可用的視覺瀏覽器工具 → 僅進行 DOM 檢查(計算後的令牌、已載入的字型、在 375px 寬度下無橫向滾動)。無頭模式會遺漏網頁字型與渲染問題,而這些正是評判的重點。說明你使用了哪個層級,以及未在視覺上檢查的內容。

4. 關卡。 呈現產出物,並使用可用的提問工具或簡潔的訊息進行詢問:

  • 批准(Approve) → 更新 STATE.json,解鎖下一個階段
  • 修訂(Revise) → 記錄意見,重建,驗證,再次展示
  • 附帶意見批准(Approve with notes) → 繼續前進,將意見記錄為未決決策

只有在獲得明確同意時才繼續前進。關卡之所以存在,是因為審查者對這個品牌有一些沒有寫在任何地方的理解——也因為它是一個調節閥,允許大型建構在原子階段後暫停,並在下週繼續。

放棄審核。 當使用者明確表示不要停止(或評估/CI 提示以非互動模式執行)時,無需暫停即可執行階梯:從請求與證據中回答 Stage 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——透過 .card-label 在 UI 中顯示,反映在 data-* 屬性中,並與規格檔案名稱匹配。一旦批准即保持穩定;重新編號會破壞所有引用。
  • 四個令牌層級——品牌(Brand)→別名(Alias)→映射(Mapped)→響應式(Responsive),每個層級由 tokens.css 中的一個 @tier 標記開啟。原始字面值僅允許出現在品牌層級和響應式層級。顏色、邊框寬度和邊框半徑必須按照映射→別名→品牌的順序進行,不可跳過;映射層級的 --space-*、--duration-*、--ease-*、--shadow-* 則是例外。
  • 每個元件一個規格檔案,結構依據 assets/docs/COMPONENT-SPEC.md。每個規格都包含一個實作範例(在 reference/ 中渲染)以及一個用於 data-* 和快照測試的複製就緒的選擇器。
  • 階段頁面會自我介紹。 每個 reference/stage-N.html 都包含一個 .stage-header,說明該階段建構了什麼、使用了哪些令牌層級,以及一個指向 references/ 中完整規格的連結。頁面本身也是動態的:.specimen 區塊支援 .variant 修飾符(.dark、.hover 等)以及標籤化的 .state-{default|loading|error|empty|disabled|focus} 切換功能。

安全事項

  • 永遠不要寫入第二個儲存庫,除非使用者明確要求。 如果目標不明確,請詢問一次。請勿猜測。
  • 僅使用 $SKILL/scripts/ 中的腳本進行寫入。 請勿直接編輯 design-system/ 中的檔案,除非你已透過 init-system.ts 或 verify-stage.ts 建立它們。
  • 備份。 在對 STATE.json 進行任何寫入操作之前,先將其複製到 STATE.json.bak。如果腳本失敗,則還原備份。
  • 在分支上進行測試。 在開始之前,建立一個具有描述性名稱的功能分支(例如 design-system/v2-atoms)。請勿直接提交到主分支。
  • 記錄決策。 你做出的每一個設計選擇,無論多小,都必須在 DESIGN-BRIEF.md 的未決決策部分中有對應的條目。沒有記錄的決策是無法審查的。

相關技能