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: 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>] # 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的未決決策部分中有對應的條目。沒有記錄的決策是無法審查的。