MarketingOS アトミックデザインシステム
ブランドをレビュー可能なデザインシステムに変換します。階層化されたトークン、コンポーネントごとの1つのスペックファイル、そして静的なHTMLリファレンスサイトを、人間による承認を間に挟みながら一段ずつ構築します。すべては1つの design-system/ フォルダに格納され、人間またはエージェントが単一のREADMEからナビゲートできます。
MarketingOS のコンテキストと前提条件
現在のセッションとそのプロジェクト記録から、アクティブなビジネスブレインとウェブサイトターゲットを解決します。情報を求める前に、ブレインのBRAIN.mdまたはエージェント指示、CONTEXT.md、ブランド、ボイス、オーディエンス、オファー、保存されたデザインリファレンスを読み込んでください。各ビジネスのコンテキストは分離して保持します。ソースブレインとターゲットをデザインブリーフに記録します。MarketingOSを使用しない場合は、提供されたブランドファイルから作業し、実際のギャップを特定します。
バンドルされたTypeScriptスクリプトにはBunを使用します。Bunがない場合は、公式インストール手順(https://bun.com/docs/installation)にユーザーを誘導してください。`$SKILL` を、この読み込まれたSKILL.mdを含む実際のディレクトリに解決します。エージェントは別の場所にインストールされるため、特定のホームパスを想定しないでください。
ユーザーがTaste Skillを選択している場合、まずそのインストール済みの指示を読み、そのアートディレクションとリファレンス調査結果をこのフレームワークへの入力として使用します。このフレームワークのブランド契約、トークンシステム、ステージ決定を保持してください。Taste Skillは別のオプション依存関係であり、このパックにバンドルされていません。インストールが要求された場合は、https://github.com/leonxlnx/taste-skill にある現在の公式指示を検査してください。
1つの初期プロンプトで完全なワークフローを駆動できます。必要な決定とビジュアルステージの承認は同じ会話内で行い、毎回コピー&ペーストのプロンプトを必要とせずに、各返信後に再開します。ユーザーが要求したステージで停止してください。1回の呼び出しが承認をスキップする許可と見なされることはありません。
アイデア
デザインシステムは2つの方法のいずれかで失敗します。1つは「発明」される場合 — モデルが適切なパレットを選択し、結果は自信に満ち、一貫性はあるが、ブランドではありません。もう1つは「一度にすべて構築される」場合 — 下層の誤った決定が、誰も気付かないうちに20ページに静かに伝播します。
このスキルは両方に対処します。設計の前に発見: すでに決定されたことを見つけ出し、ギャップを明示します。各段階間のゲート: 基礎でのやり直しは5行の編集ですが、ページでの同じやり直しは20ページになります。
ルーター
ユーザーがどこにいるかを把握し、それに応じて行動します。どのモードが必要かを尋ねないでください。
| 状況 | 実行すること |
|---|---|
STATE.json がなく、発見で既存のアトミックシステムが見つからない | ステージ0(v2レイアウト)を開始 |
発見が existingAtomicSystem を報告するが、STATE.json がない場合(手書きのHTML、例:既存プロジェクトの public/atomic-framework/、レガシープロジェクトの stage-*.html など) | レガシーシステム。 そのファイルと命名規則で拡張:既存ページに追加し、マークアップ/クラス/IDの規則を維持し、新しい作業をその横の小さな ATOMIC-NOTES.md に記録します。その規則は保持されますが、品質基準は下げません。表示可能な :focus-visible、44pxのターゲット、コントラスト、そして「採用」と「意図的に採用しない」の両方が入力されたインスピレーションマップが必要です。それが兄弟リポジトリにある場合、それは2つ目のリポジトリです — そこに書き込む前に質問し(安全に関する注意事項を参照)、DESIGN-SYSTEM.md へのショートカットをターゲットに与えます。ユーザーが移行を要求しない限り、v2をスキャフォールディングしないでください。verify-stage.ts --legacy <dir> で検証します。詳細: references/output-structure.md |
design-system/STATE.json に schemaVersion: 2 がある | v2システム:ステータスを報告し、次の未承認ステージを実行 |
schemaVersion: 2 がない STATE.json(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> # シェルからステージページを作成、レールと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)— 1つのルート、1つのエントリファイル、コンポーネントごとに1つのスペック:
design-system/
├── README.md ここから開始 — 人間とエージェントのためのエントリポイント
├── STATE.json schemaVersion 2、ステージ、承認、インベントリ、バージョン、テーマ
├── CHANGELOG.md 承認されたステージ/公開ごとに1エントリ
├── 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の作成、または移行時に読んでください。
ラダー
7つのビルドステージ。基礎が原子より先にあるのは、トークンなしでは原子を構築できないからです。ルールが最後に来るのは、ガードレールは実際に決定されたことから書かれるからです。パスは 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 — 発見
3つの入力、そして統合。最初の2つは同時に行います。これらは互いに依存しません。
1. デザインインスピレーション。 アクティブなブレインまたはTaste Skillパスからの保存されたリファレンスを最初に再利用します。不足している生のURLのみを尋ねます — 3〜6個、可能であればホームページではなく特定のページ。利用可能なブラウザツールで各ページをスナップショットし、実際のフォントとレイアウトを確認します。Interceptorは、インストールされており、セッションに適切な場合のみ使用します。計算されたパレット、タイプスタック、スペーシングリズム、ラジウスを抽出します — マーケティング用の16進数コードではなく、実際のレンダリング値です。
2. Mobbin MCP(オプション)。 URLが答えられないパターンに関する質問に対して:このカテゴリがオンボーディングをどのようにシーケンスするか、価格設定を構造化する方法、空の状態を処理する方法。MCPはインストールされているが認証されていない場合があります — mcp__mobbin__authenticate / complete_authentication のみが公開されている場合は、OAuthフローを実行し、ユーザーにURLを渡します。ユーザーが辞退した場合は続行し、ギャップをブリーフに記録します。パターンリサーチが行われたと決して暗示しないでください。
3. ブランド発見。 discover-brand.ts を実行します。これは、ターゲットとその兄弟リポジトリ全体の既知のパス規則を調査し、コンパニオンドキュメントをマージし、ランク付けする前にブランドファミリーで分割します — そのため、別のブランドの洗練されたドキュメントが決して勝つことはありません。それから3つのことを読み取ります:どのドキュメントか、ビジュアル契約が full/partial/verbal-only のどれか、アトミックシステムがすでに存在するかどうか(存在する場合は、最初からやり直すのではなく拡張します)。
何かをコンパイルする前に、ブランドソースをユーザーに確認してください。 これは、下流のすべてのステージを無効にする唯一のエラーです。
次に DESIGN-BRIEF.md を書きます。その インスピレーションマップ には、すべての行の両方の半分(採用するもの と 意図的に採用しないもの)が必要です。採用しない列に判断が宿ります。「採用」のみの行はコラージュの指示です。その§3のビジュアル契約は、各色相と、指定された各16進数が位置するステップ、テーマ、タイプスケール比率を名前付けます — ステージ1がコンパイルする入力です。
詳細: references/brand-discovery.md および references/inspiration-research.md。
ステージ1〜6 — ループ
すべてのステージは同じ5つのビートを実行します。
1. 構築。 ステージスペックに従います。承認された下位レベルのピースのみを構成します。基礎にないトークンを必要とするステージは、基礎が不完全であることを意味します — ローカル値を定義するのではなく、戻って修正します。そうしないと、システムが自己矛盾を起こし始めます。ステージ1: 最初に references/token-architecture.md を読んでください。ステージ2〜4: 最初に references/component-anatomy.md を読んで、assets/docs/COMPONENT-SPEC.md から各コンポーネントに対して1つのスペックファイルを標本とともに書きます。ステージ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での横スクロールなし)。ヘッドレスモードは、判断の多くを占める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 にあります。生成されたファイルには手動編集禁止ヘッダーが付いています。ソースを編集して再実行してください。
ステージを提示するときは、簡潔に保ちます:何が構築されたか、レベルごとの数、証拠なしで決定しなければならなかったこと、そして最も見る価値がある1つのこと。すべての標本のツアーではありません。
すべてに適用される規則
完全な詳細は references/html-conventions.md にあります。重要なもの:
- ゼロ埋め連続ID —
A-01、M-17、O-04、T-05、P-02—.card-labelを介してUIに表示され、data-*にミラーリングされ、スペックファイル名と一致します。一度承認されると安定します。番号を振り直すと、すべての参照が壊れます。 - 4つのトークン階層 — ブランド → エイリアス → マップ → レスポンシブ。それぞれは
tokens.cssの@tierマーカーで開始されます。生のリテラルはブランドとレスポンシブにのみ存在します。色、境界線の太さ、半径はマップ → エイリアス → ブランドと進み、スキップはしません。マップされた--space-*、--duration-*、--ease-*、--shadow-*は直接エイリアスからブランドにマップできます。