MarketingOS Atomic Design System
브랜드를 검토 가능한 디자인 시스템으로 전환합니다: 계층적 토큰, 컴포넌트별 명세 파일, 정적 HTML 참조 사이트로 구성되며, 한 단계씩 구축하고 각 단계마다 인간의 승인을 받습니다. 모든 결과물은 사람이나 에이전트가 단일 README에서 탐색할 수 있는 design-system/ 폴더 아래에 저장됩니다.
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에서 현재 공식 지침을 확인하십시오.
한 번의 초기 프롬프트로 전체 워크플로를 실행할 수 있습니다. 필수 결정과 시각적 단계 승인을 동일한 대화에서 유지하고, 각 응답 후 별도의 복사-붙여넣기 프롬프트 없이 계속 진행합니다. 사용자가 요청한 단계에서 멈추고, 한 번의 호출이 승인을 건너뛸 권한으로 간주되지 않도록 합니다.
아이디어
디자인 시스템은 두 가지 방식 중 하나로 실패합니다. 첫째, 발명됩니다. 모델이 멋진 팔레트를 선택하고 결과는 확신에 차고 일관되지만 브랜드와는 다릅니다. 둘째, 한 번에 모두 구축됩니다. 그래서 하단의 잘못된 결정이 아무도 보지 못하는 사이에 20페이지를 통해 조용히 전파됩니다.
이 스킬은 두 가지 문제를 모두 해결합니다. 디자인 전 발견: 이미 결정된 사항을 찾고 격차를 명시적으로 식별합니다. 단계 간 게이트: 기초에서의 재작업은 5줄 편집이면 되지만, 페이지에서의 동일한 재작업은 20페이지 분량입니다.
라우터
사용자의 현재 상태를 파악한 후 행동합니다. 사용자가 원하는 모드를 묻지 마십시오.
| 상황 | 실행할 작업 |
|---|---|
STATE.json이 없고 발견 결과 기존 원자 시스템이 없음 | 0단계 시작 (v2 레이아웃) |
발견 결과 existingAtomicSystem이 있지만 STATE.json이 없음 (수동 구축 HTML, 예: 기존 프로젝트의 public/atomic-framework/, 레거시 프로젝트의 stage-*.html) | 레거시 시스템. 자체 파일 및 명명 규칙 내에서 확장합니다. 기존 페이지에 추가하고, 마크업/클래스/ID 규칙을 유지하며, 새 작업은 그 옆에 작은 ATOMIC-NOTES.md에 기록합니다. 해당 규칙은 유지하되 품질 기준을 낮추지 않습니다: 가시적인 :focus-visible, 44px 대상, 대비, 그리고 취할 것(take)과 남길 것(leave)이 모두 채워진 Inspiration Map. 형제 리포지토리에 있는 경우, 두 번째 리포지토리이므로 쓰기 전에 질문하고(Safety 참조) 대상을 가리키는 짧은 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 스캐폴드; --schema 1은 이전 스킬 v1 시스템 전용
bun $SKILL/scripts/init-system.ts --target <repo> --page <file> # 셸에서 페이지 단계 실행, 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. 디자인 영감. 활성 두뇌의 저장된 참조 또는 Taste Skill 패스를 먼저 재사용합니다. 누락된 원시 URL에 대해서만 요청합니다. 가능하면 홈페이지보다는 특정 페이지 3~6개를 요청합니다. 사용 가능한 브라우저 도구로 각 페이지를 스냅샷하여 실제 글꼴과 레이아웃을 확인합니다. Interceptor는 설치되어 있고 세션에 적합한 경우에만 사용합니다. 계산된 팔레트, 글꼴 스택, 간격 리듬 및 반경을 추출합니다. 마케팅용 16진수가 아닌 실제 렌더링된 값입니다.
2. Mobbin MCP (선택 사항). URL로 답할 수 없는 패턴 질문(예: 이 카테고리가 온보딩을 시퀀싱하는 방법, 가격을 구성하는 방법, 빈 상태를 처리하는 방법)에 사용합니다. MCP가 설치되었지만 인증되지 않았을 수 있습니다. mcp__mobbin__authenticate/complete_authentication만 노출된 경우 OAuth 플로우를 실행하고 사용자에게 URL을 건넵니다. 사용자가 거부하면 계속 진행하고 브리프에 격차를 기록합니다. 패턴 조사가 이루어지지 않았음을 암시하지 마십시오.
3. 브랜드 발견. discover-brand.ts를 실행합니다. 대상 및 형제 리포지토리의 알려진 경로 규칙을 조사하고, 동반 문서를 병합하며, 브랜드 제품군별로 분할한 후 순위를 매깁니다. 따라서 다른 브랜드의 완성된 문서가 승리할 수 없습니다. 세 가지 정보를 읽습니다: 어떤 문서인지, 시각적 계약이 full/partial/verbal-only인지, 원자 시스템이 이미 존재하는지(존재한다면 처음부터 시작하는 대신 확장합니다).
무엇을 컴파일하기 전에 사용자와 브랜드 소스를 확인하십시오. 이 오류 하나가 다운스트림의 모든 단계를 무효화합니다.
그런 다음 DESIGN-BRIEF.md를 작성합니다. Inspiration Map에는 모든 행의 두 절반이 모두 필요합니다. 즉, 무엇을 취할 것인지(take) 그리고 무엇을 의도적으로 남길 것인지(leave)입니다. leave 열은 판단이 있는 곳입니다. "take"만 있는 행은 콜라주 지시사항입니다. §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단계는 또한 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에서 가로 스크롤 없음). 헤드리스 모드는 웹 글꼴 및 렌더링 문제를 놓치는데, 이는 평가되는 내용의 대부분입니다. 사용한 계층과 시각적으로 확인되지 않은 내용을 명시합니다.
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**에 있습니다. 핵심 규칙은 다음과 같습니다:
- 0으로 채워진 연속 ID —
A-01,M-17,O-04,T-05,P-02—.card-label을 통해 UI에 표시되고,data-*에 반영되며, 명세 파일 이름과 일치합니다. 승인되면 안정적입니다. 번호를 다시 매기면 모든 참조가 깨집니다. - 4계층 토큰 — brand → alias → mapped → responsive, 각 계층은
tokens.css에서@tier마커로 열립니다. 원시 리터럴은 Brand 및 Responsive에서만 사용됩니다. 색상, 테두리 너비 및 반경은 Mapped → Alias → Brand로 이동하며 건너뛰지 않습니다. 매핑된--space-*,--duration-*,--ease-*,--shadow-*등은 Alias 또는 Brand에서 파생되어야 하며 Responsive 또는 다른 곳에서 직접 값을 가져오지 않습니다.
계층 규칙을 위반하는 경우
verify-stage.ts가 잡아냅니다. 테스트를 실행하기 전에는 항상 실행하십시오.
- 두 개의 화면 크기로 시작: 375px(모바일) 및 1280px(데스크톱). 더 많은 중단점은 필요할 때만 추가하고
tokens.css의 Responsive 계층에 추가합니다. - 모든 참조 페이지는
<meta name="robots" content="noindex">를 포함하여 검색 엔진이 이를 인덱싱하지 않도록 합니다.verify-stage.ts가 이 규칙을 확인합니다. rail을 통해 페이지 연결: 각 단계 페이지는 현재 단계와 이웃 단계를 포함하는 탐색 막대를 가져야 합니다.init-system.ts --page가 이를 생성합니다.
안전 수칙
이 스킬은 파일을 생성하고 수정합니다. 다음 안전 수칙을 따르십시오:
- 대상 리포지토리를 확인하십시오. 추측하지 마십시오. 모호한 경우 한 번만 질문하십시오.
- 기존 시스템을 덮어쓰지 마십시오.
STATE.json이 발견되면 마이그레이션하거나 확장하십시오. 처음부터 다시 구축하지 마십시오. - 승인 없이 다운스트림을 진행하지 마십시오. 각 게이트는 명시적인 승인이 필요합니다(포기된 경우 제외).
- 스크립트가 아닌 사람이 읽기 위한 파일을 편집할 때는 주의하십시오. 생성된 파일(예:
tokens.json)에는 수정하지 말라는 헤더가 있습니다. 소스(tokens.css)를 편집하고 스크립트를 재실행하십시오. - 형제 리포지토리에서 쓰기 전에 질문하십시오. 대상이 아닌 리포지토리에서 파일을 생성/수정해야 하는 경우 사용자에게 알리고 허가를 구하십시오.
문제 해결
| 증상 | 원인 및 해결책 |
|---|---|
discover-brand.ts가 "대상 경로를 찾을 수 없음"을 보고함 | --target이 올바른 리포지토리 루트를 가리키는지 확인하십시오. 리포지토리가 존재하는지 확인하십시오. |
verify-stage.ts가 "계층 위반"을 보고함 | tokens.css에서 잘못된 위치에 원시 값을 사용하고 있습니다. 값을 올바른 계층으로 이동하거나 alias를 사용하십시오. |
build-index.ts가 design-system/components/INDEX.md를 찾을 수 없음 | init-system.ts를 먼저 실행하여 구조를 스캐폴딩했는지 확인하십시오. |
| 참조 페이지에 스타일이 없음 | design-system/reference/styles.css가 존재하는지 확인하십시오. build-index.ts가 이를 생성합니다. |
| "Mobbin MCP가 인증되지 않음" | 사용자에게 OAuth URL을 제공하고 인증을 요청하십시오. 거부하면 계속 진행하고 브리프에 기록하십시오. |
피드백 및 기여
이 스킬에 대한 문제나 제안 사항은 GitHub(https://github.com/marketing-os/mos-atomic-design-system/issues)에 제출해 주십시오. 풀 리퀘스트를 환영합니다. 주요 변경 사항에 대해서는 먼저 이슈를 열어 논의해 주십시오.