design-system-library — 브랜드 디자인 시스템 SSOT
목적과 범위
글로벌 브랜드의 디자인 시스템(token 기반 분석 결과)을 단일 진실 원천(single source of truth)으로 보관하고, HTML 산출물에 적용 가능한 형태로 제공합니다.
두 가지 소비 경로:
- doc-html-report / HTML 문서 렌더 — 별도
moai-officer가 설치되고 해당 스킬을 사용할 수 있을 때design_system파라미터로 시스템 선택 → 토큰을 산출물 형식에 맞는 CSS와 HTML로 렌더 - Claude Design 핸드오프 —
design-system-prep가 본 라이브러리 시스템을 DESIGN.md 합성 소스로 사용 →design-handoff의 references/context에 지침 포함
핵심 원칙:
- 라이브러리는 데이터(token + 분석) SSOT — 렌더 로직은 소비자(doc-html-report)가 소유
- 아래
tailwind.config예시는 Tailwind v3 Play CDN 공식 문서의 JavaScript 설정 방식이다. 현재 v4 Play CDN의 CSS@theme방식과 섞지 않는다. 개발 미리보기용이며 최종 배포물에는 필요한 스타일을 정적 CSS로 포함하거나 프로젝트의 빌드 경로를 사용한다. - shadcn 컴포넌트는 React가 아닌 vanilla HTML/CSS로 재현 (단일 파일·React 불필요)
- 기존 doc-html-report 0의존 템플릿은 유지 — design_system 미지정 시 하위 호환
3개 기본 테마 (Default)
모든 HTML 산출물의 기본 선택지. 사용자가 명시하지 않아도 결과물 성격에 따라 자동 추천합니다.
| 테마 | 무드 | 캔버스 | 강조 | 폰트 | 적합 산출물 |
|---|---|---|---|---|---|
claude |
warm editorial (default) | cream #faf9f5 |
coral #cc785c |
Copernicus serif + StyreneB sans | 보고서·사업계획서·편집성 문서 |
clickhouse |
high-contrast engineering | near-black #0a0a0a |
electric yellow #faff69 |
Inter 700 | 기술 리포트·데이터 대시보드·개발자 문서 |
clay |
playful B2B | cream #fffaf0 |
6-color saturated cards (pink/teal/lavender/peach/ochre) | Plain Black/Inter | 랜딩·마케팅·제품 소개 |
상세 토큰: systems/anthropic-claude.md · systems/clickhouse.md · systems/clay.md
자동 추천 휴리스틱
| 산출물 | 추천 테마 |
|---|---|
| 주간 현황·경영 요약·사업계획서 | claude (warm editorial) |
| 인시던트 리포트·데이터 리포트·API 문서 | clickhouse (다크 엔지니어링) |
| 랜딩·제품 소개·마케팅 원고 | clay (playful saturated) |
| 재무제표·법률 문서 | claude (편집성·신뢰) |
전체 카탈로그
systems/registry.md 참조 — 분류(light/warm/dark) · 캔버스 · primary 색 · 폰트 · 무드 메타 포함.
전체 시스템의 파일 목록과 출처 수준은 registry.md와 BRAND-NOTICE.md에서 확인한다. 기본 3테마의 예시 config가 있으나, 현재 산출물의 렌더·대비 통과를 뜻하지 않는다. 경량 토큰의 출처·재사용 조건이 확인되지 않은 항목은 내부 참고로만 다룬다.
브랜드 분석 문서 상당수에는 원 브랜드의 공식 출처 URL이 기록돼 있지 않다. 이 토큰을 현재 공식 디자인 시스템과 동일하다고 주장하지 않고, 사용자 브랜드를 설계하는 참고값으로만 쓴다. 특정 브랜드를 그대로 재현해야 한다면 해당 브랜드의 현재 공식 자료와 사용권을 별도로 확인한다.
Tailwind v3 Play CDN 미리보기
mapping/tailwind.md 참조 — YAML design token → Tailwind CDN inline config 매핑 규칙 + shadcn vanilla 컴포넌트 변환표.
개발 미리보기 패턴 (네트워크 연결 필요, 최종 배포용 아님):
<!-- 1. Tailwind v3 Play CDN -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- 2. 브랜드 토큰 → tailwind.config 주입 -->
<script>
tailwind.config = {
theme: {
extend: {
colors: { primary: '#cc785c', canvas: '#faf9f5', /* ... */ },
fontFamily: { display: ['Copernicus', 'serif'], sans: ['StyreneB', 'Inter', 'sans-serif'] },
borderRadius: { md: '8px', lg: '12px', xl: '16px' },
spacing: { section: '96px', /* ... */ }
}
}
}
</script>
<!-- 3. shadcn vanilla 컴포넌트 (utility class로 직접 마크업) -->
<div class="bg-canvas rounded-lg border border-hairline p-8">
<h2 class="font-display text-3xl tracking-tight text-ink">...</h2>
</div>
shadcn vanilla 컴포넌트
components/ — shadcn UI 컴포넌트를 React 없이 vanilla HTML + Tailwind utility로 재현한 참조 마크업.
| 컴포넌트 | shadcn 원본 | vanilla 매핑 |
|---|---|---|
| Card | Card / CardHeader / CardContent |
div.rounded-lg.border.p-8 + token classes |
| Button | Button (variant: default/secondary/ghost) |
button.inline-flex.rounded-md.px-5.py-3 + variant class |
| Badge | Badge |
span.inline-flex.rounded-full.px-3.py-1.text-xs |
| Table | Table / TableHeader / TableRow |
semantic table.thead.tbody.tr + token borders |
| Tabs | Tabs / TabsList |
<details> 또는 vanilla JS tab + token classes |
| Alert | Alert |
div.rounded-lg.border.p-4 + semantic color |
각 컴포넌트의 풀 마크업(변형·접근성 메모 포함)은 개별 파일 — card.md · button.md · badge.md · table.md · tabs.md · alert.md. 토큰 매핑 규칙은 mapping/tailwind.md §1·§3.
소비자 연동
doc-html-report (별도 moai-officer 플러그인)
moai-officer:doc-html-report가 현재 앱에 설치·노출된 경우, design_system 입력은 다음 의도로 쓰인다. 설치되지 않았다면 디자인 토큰과 적용 지침을 제공하고 HTML 생성은 사용 가능한 도구 범위에서 별도로 수행한다. 실제 렌더 결과는 소비자 스킬에서 확인한다:
- 미지정 → 기존 0의존 템플릿 (Anthropic 영감 ivory/slate/clay, 하위 호환)
design_system: claude|clickhouse|clay|<카탈로그 항목>→ 이 라이브러리에서 토큰을 읽고 결과물 형식에 맞는 CSS와 HTML을 생성한다. 개발 미리보기에만 Play CDN을 쓴다.
체인 예시:
[텍스트 스킬] → ai-slop-reviewer → doc-html-report (design_system: clickhouse)
Claude Design 핸드오프 (moai-designer)
design-system-prep가 사용자가 지정한 시스템(또는 브랜드 무드 매칭)을 본 라이브러리에서 로드 → DESIGN.md 합성. design-handoff의 references.md / context.md에 design-system 지침으로 포함되어 claude.com Design 세션에 paste.
워크플로우
- 시스템 선택 — 사용자 명시 또는 산출물 성격 기반 자동 추천(위 휴리스틱)
- 토큰 로드 —
systems/<name>.md의 YAML frontmatter에서 실제로 있는 토큰을 읽는다. 일부 시스템에는typography·rounded·spacing·components가 없으므로 본문 분석에서 필요한 값을 확인한다. 본문에도 없는 값은 임의로 채우거나 원본 토큰이라고 표시하지 않는다. 대상 OS에 없거나 사용권이 없는 서체는 토큰과 본문의 대체 서체 안내를 확인한다. 사용권이 없는 서체명은 설치 여부와 무관하게 출력 CSS의 서체 목록에서 제거한 뒤 대체 순서로 렌더링한다. - 토큰 매핑 —
mapping/tailwind.md규칙을 참고하고, CTA·배지의 배경과 글자색 대비를 실제 계산 - shadcn vanilla 매핑 — 산출물 구조 카드/버튼/테이블을
components/참조 마크업으로 치환 - 단일 파일 렌더 — 대상 환경에 필요한 CSS와 마크업을 포함해 출력하고 브라우저에서 확인. 클릭 영역의 실제 가로·세로와 인접 요소 간격을 측정한 뒤에만 WCAG 2.5.8 AA 또는 2.5.5 AAA의 대상 크기 충족을 주장한다. Play CDN은 개발 미리보기일 때만 사용
디자인 시스템 파일을 수정해 DESIGN.md 형식을 점검할 때는 Node.js 18 이상과 npm이 실제로 있는 환경에서 npx --yes -p "@google/design.md@0.4.0" designmd lint DESIGN.md를 쓴다. 원저작자 안내는 Windows에서 점이 들어간 실행 이름이 마크다운 연결 프로그램으로 열릴 수 있어 designmd 별칭을 권한다. 이 명령은 macOS·Windows·Linux에서 같은 별칭을 사용한다. 앱에 실행 환경이 없으면 lint를 실행했다고 보고하지 않는다.
사용 예시
예시 1: ClickHouse 다크 테마 기술 리포트
결제 게이트웨이 502 장애를 ClickHouse 스타일 다크 테마로 인시던트 리포트 HTML로 만들어줘.
예시 2: Claude warm 테마 사업계획서
사업계획서를 Claude 디자인(warm cream + coral) HTML로 렌더해줘.
예시 3: Clay playful 테마 랜딩
신제품 랜딩 페이지를 Clay 스타일(컬러 카드)로 HTML로 만들어줘.
예시 4: Claude Design 핸드오프용 시스템 정리
Claude Design에 올릴 디자인 시스템 자료를 Linear 스타일 기반으로 정리해줘.
하지 않는 것
- 본 라이브러리는 렌더 로직을 소유하지 않습니다. 별도 설치된
moai-officer:doc-html-report·doc-html-slide가 현재 앱에 노출돼 있으면 해당 스킬에서 렌더합니다. - React / Vue / 빌드 단계를 도입하지 않습니다 — 단일 파일·CDN·vanilla 고수
- 외부 의존이 없는 단일 파일 출력(이메일 첨부·오프라인·인쇄)이 필요하고
moai-officer:doc-html-report가 설치돼 있으면 해당 기본 템플릿을 사용합니다. 설치되지 않았다면 토큰과 적용 지침을 제공하고, 현재 앱에서 HTML을 만들 수 있는지 별도로 확인합니다. - 브랜드 저작권 — 각 시스템은 분석·참고용 token이며, 저장소 Apache-2.0 라이선스의 적용 범위 밖입니다.
각 브랜드의 디자인·상표·서체 권리는 해당 소유자에게 있습니다. 상업적 산출물에 적용하기 전
반드시
BRAND-NOTICE.md의 사용 경계와 오픈 라이선스 대체 서체표를 확인하세요
참고 문서
systems/registry.md— 전체 카탈로그 인덱스systems/anthropic-claude.md·systems/clickhouse.md·systems/clay.md— 기본 3테마 상세 토큰 (claude.md는CLAUDE.md자동 로드 회피를 위해anthropic-claude.md로 명명)systems/keynote-editorial-dark.md— 프리미엄 에디토리얼 키노트 레시피(다크, no_box·거대숫자 3단·4모서리·단일 accent). 일반 다크 팔레트가 아닌 슬라이드 구성 계약references/korean-design-systems.md— 한국 기업 공개 디자인시스템 + 무료 한글 폰트 서베이 (당근 SEED·채널톡 Bezier·KRDS·Pretendard + 토스/브랜드 라이선스 함정 경고)mapping/tailwind.md— YAML 토큰 → Tailwind CDN config 매핑 규칙components/— shadcn vanilla 컴포넌트 참조 마크업