ckm:design-system

개요

ckm:design-system이란?

ckm:design-system은 디자인 토큰 아키텍처, 컴포넌트 사양, 프레젠테이션 슬라이드 생성 기능을 하나의 재사용 가능한 워크플로로 통합한 디자인 시스템 스킬입니다.

이 스킬은 3계층 토큰 모델(primitive → semantic → component)을 중심으로 설계되어 있으며, 다음 항목에 대한 레퍼런스와 스크립트를 제공합니다.

• CSS variable 시스템
• Spacing 및 타이포그래피 스케일
• 컴포넌트 상태와 변형(variants)
• Tailwind 테마 설정
• 체계적인 슬라이드 및 피치덱 레이아웃

슬라이드 배경, 컬러 로직, 카피 공식을 비롯해 레이아웃, 내러티브 전략을 담은 의견 기반(opinionated) 데이터 테이블과 템플릿이 함께 제공되며, 토큰과 슬라이드 구조를 생성·검증하는 스크립트도 포함되어 있습니다.

이 스킬은 누구를 위한 것인가요?

ckm:design-system은 다음과 같은 분들을 대상으로 합니다.

• 명확한 토큰 아키텍처와 컴포넌트 스펙 레퍼런스를 원하는 디자인 시스템 리드 및 UI/UX 디자이너
• 견고한 토큰 파이프라인(CSS variables, validator, Tailwind 연계 힌트)이 필요한 프론트엔드 및 React/Tailwind 개발자
• 피치덱을 자주 만들며, 매번 처음부터 만드는 대신 재사용 가능한 브랜드 일관 슬라이드 프레임워크가 필요한 창업자, PM, 마케터

Figma 스타일의 디자인 사고를 실제 구현 가능한 토큰과 재사용 가능한 슬라이드 시스템으로 연결하고 싶다면 이 스킬이 잘 맞습니다.

어떤 문제를 해결하나요?

ckm:design-system은 다음을 도와줍니다.

• 디자인 토큰 표준화: primitive → semantic → component 레이어링을 문서화하여 정리합니다.
• CSS 토큰 생성: JSON으로부터 CSS 토큰을 생성하고, 코드베이스에서의 사용을 검증합니다.
• Tailwind 테마 설계: 동일한 토큰 아키텍처를 활용해 Tailwind 테마를 계획합니다.
• 컴포넌트 스펙 정의: 상태와 variants까지 포함해 화면 전반에서 UI 일관성을 유지합니다.
• 브랜드 일관 프레젠테이션 설계: 미리 정의된 슬라이드 레이아웃, 차트 추천, 컬러·감정 로직, 카피 공식을 활용해 슬라이드를 구성합니다.

UI와 슬라이드를 각각의 일회성 산출물이 아니라, 하나의 시스템으로 사고할 수 있는 구조를 제공합니다.

언제 ckm:design-system을 쓰면 좋을까요?

다음과 같은 상황에서 이 스킬 사용을 추천합니다.

• 디자인 시스템을 새로 도입하거나 리팩터링하면서 토큰 레이어를 명확히 정의하고 싶을 때
• 토큰 아키텍처와 연결된 CSS variable 및 Tailwind 가이던스가 필요할 때
• 디자인 토큰을 수동으로 관리하는 대신 자동 생성·검증하고 싶을 때
• 피치덱, 세일즈 프레젠테이션, 제품 데모를 자주 만들며, 반복 가능한 슬라이드 구조가 필요할 때

반면 하나의 정적인 UI 목업만 필요하다거나, 토큰·CSS variables를 아예 사용하지 않는 경우에는 과할 수 있습니다.

사용 방법

설치 및 기본 설정

1. ckm:design-system 스킬 설치

Agent/skills 환경에 스킬을 설치합니다.

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

위 명령은 nextlevelbuilder/ui-ux-pro-max-skill 저장소에서 design-system 스킬을 받아 로컬 skills 디렉터리에 추가합니다.

2. 핵심 파일 살펴보기

설치 후 스킬 폴더를 열고 다음 파일부터 확인하세요.

• SKILL.md – 스킬 개요, 사용 시나리오, 토큰 아키텍처, 빠른 시작용 명령어
• references/ – 토큰, 컴포넌트, variants, Tailwind 연계에 대한 개념 문서
• data/ – 슬라이드 배경, 컬러 로직, 카피 공식, 레이아웃, 타이포그래피, 전략이 담긴 CSV 파일
• scripts/ – 토큰 생성·삽입·검증 및 슬라이드 검색용 유틸리티 스크립트
• templates/design-tokens-starter.json – 자체 토큰 세트를 정의할 수 있는 스타터 JSON 템플릿

이 구조를 통해 토큰만, 슬라이드만, 혹은 전체 시스템을 사용할지 빠르게 결정할 수 있습니다.

토큰 아키텍처 설계하기

3. 3계층 토큰 모델 이해하기

SKILL.md와 references/token-architecture.md에서는 다음과 같은 3단계 구조를 설명합니다.

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

레퍼런스 파일을 참고해 각 레이어를 설계하세요.

• references/primitive-tokens.md – 기본 색상, spacing, radius, 타이포그래피 primitive
• references/semantic-tokens.md – --color-primary, --surface-elevated, --text-muted와 같은 목적 기반 토큰
• references/component-tokens.md – --button-bg, --card-border, --badge-pill-radius와 같은 컴포넌트 단위 변수

이렇게 분리하면 다음과 같은 이점이 있습니다.

• 테마를 교체할 때 컴포넌트를 다시 작성하지 않아도 됩니다.
• 구현 세부 사항(CSS variables, Tailwind config)을 디자인 언어와 정렬된 상태로 유지할 수 있습니다.

4. 토큰 JSON 생성 또는 커스터마이즈

templates/design-tokens-starter.json을 기반으로 자체 토큰 파일을 만드세요.

일반적인 워크플로는 다음과 같습니다.

1. templates/design-tokens-starter.json을 프로젝트로 복사해 tokens.json으로 저장합니다.
2. 색상, spacing, 폰트 크기 등 primitive 값을 먼저 채웁니다.
3. primitive를 semantic 역할(Primary, Secondary, Surface, Border 등)에 매핑합니다.
4. semantic 토큰을 각 주요 UI 요소의 component 토큰으로 매핑합니다.

다음 문서를 함께 참고하세요.

• references/component-specs.md – 컴포넌트가 토큰을 어떻게 소비하는지 사고하는 데 도움
• references/states-and-variants.md – hover, focus, disabled, error 등 상태와 변형 설계

토큰 생성 및 검증

5. 토큰으로부터 CSS variables 생성

SKILL.md에 설명된 토큰 생성 스크립트를 사용합니다.

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

• --config는 토큰 JSON 파일(예: tokens.json) 경로입니다.
• -o는 출력 CSS 파일(예: tokens.css) 이름입니다.

이렇게 생성된 CSS 파일은 토큰 세트를 --custom-properties 형태로 정의하며, 프론트엔드에 바로 import해 사용할 수 있습니다.

6. 코드베이스에서 토큰 사용 검증

코드가 승인된 토큰만 사용하고 있는지 확인하려면 토큰 validator를 실행합니다.

node scripts/validate-tokens.cjs --dir src/

지정한 디렉터리(예: src/)를 스캔하여 토큰 사용 패턴을 점검하며, 다음을 도와줍니다.

• 토큰이어야 할 하드코딩 값 탐지
• 더 이상 사용되지 않거나 정의되지 않은 토큰 식별

추가로 scripts/에는 다음과 같은 validator가 포함되어 있습니다.

• html-token-validator.py – HTML 내 토큰 사용 패턴 스캔
• slide-token-validator.py – 슬라이드 관련 맥락에서 토큰 사용 검증

이들을 활용해 UI와 슬라이드를 모두 디자인 시스템과 일관되게 유지할 수 있습니다.

7. 필요한 곳에 토큰 임베드하기

문서나 HTML에 토큰을 직접 삽입해야 하는 환경이라면 다음 스크립트를 사용할 수 있습니다.

• scripts/embed-tokens.cjs – 토큰을 대상 파일에 임베드

스크립트 내부 주석과 SKILL.md를 참고해 환경에 맞는 사용 방법을 확인하세요.

Tailwind 및 구현 시 고려사항

8. Tailwind 연계 계획하기

스킬에는 Tailwind 전용 레퍼런스가 포함되어 있습니다.

• references/tailwind-integration.md – 토큰 이름과 스케일을 Tailwind theme configuration에 매핑하는 방법

이를 활용해 다음을 수행하세요.

• primitive/semantic 토큰을 Tailwind colors, spacing, fontSize 스케일에 매핑
• primitive에서 파생된 primary 팔레트처럼 Tailwind utility class를 토큰 설계와 정렬

당장 Tailwind를 쓰지 않더라도, 토큰 시스템을 나중에 utility-first CSS로 확장하는 관점에서 유용한 참고 자료입니다.

시스템화된 슬라이드 덱 만들기

이 스킬의 주요 카테고리는 디자인 시스템이지만, ckm:design-system은 구조화된 프레젠테이션 디자인도 함께 지원합니다.

9. 슬라이드 데이터 테이블로 레이아웃과 비주얼 설계

data/ 디렉터리에는 베스트 프랙티스 기반 슬라이드 패턴이 담긴 CSV가 포함되어 있습니다.

• data/slide-backgrounds.csv – 슬라이드 타입(히어로, 비전, 팀, 추천사, CTA, 문제, 해결책 등)별 권장 배경 이미지 타입, 오버레이, 배치
• data/slide-color-logic.csv – 감정(좌절, 희망, 두려움, 안도, 신뢰, 긴급함, 호기심 등)을 배경 스타일, 텍스트 색, 강조 사용에 매핑
• data/slide-typography.csv – 슬라이드 타입별 타이포그래피 가이드(위계, 강조 등)
• data/slide-layout-logic.csv – 내러티브 목표와 감정(후킹, 문제, 해결, 증거, 성장, CTA, 타임라인, 기능 등)에 따른 레이아웃 패턴
• data/slide-layouts.csv – grid, split layout, hero 구조, 애니메이션 제안 등 CSS 구조 힌트가 포함된 구체적인 레이아웃 패턴

이 테이블들을 스크립트, 스프레드시트, 자체 덱 생성 파이프라인 등에서 불러와, 임의의 디자인이 아닌 내러티브와 감정에 의해 구동되는 일관된 슬라이드를 만들 수 있습니다.

10. 검증된 공식으로 슬라이드 카피 구조 잡기

data/slide-copy.csv에는 슬라이드 타입별 카피라이팅 공식이 포함되어 있습니다.

• AIDA (Attention → Interest → Desire → Action)
• PAS (Problem → Agitate → Solution)
• 4Ps (Promise → Picture → Proof → Push)
• Before-After-Bridge
• QUEST
• Star-Story-Solution

각 행에는 다음 정보가 들어 있습니다.

• formula_name 및 keywords
• 구조화된 components
• use_case 및 example_template
• emotion_trigger 및 slide_type

이를 활용해 다음과 같이 사용할 수 있습니다.

• 특정 공식을 따르는 슬라이드 카피를 에이전트에 프롬프트할 때 기준으로 사용
• 피치덱 및 세일즈 프레젠테이션 전반의 카피를 표준화

11. 전체 덱 전략 선택하기

data/slide-strategies.csv에는 다음과 같은 전체 덱 패턴이 정의되어 있습니다.

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

각 전략은 다음 항목을 포함합니다.

• 권장 슬라이드 개수
• 슬라이드 순서(타이틀, 문제, 해결, 성과, 시장 등)
• 목표, 타깃 audience, tone
• 내러티브 및 감정 흐름

이를 통해 다음을 할 수 있습니다.

• 선택한 전략에 맞춰 전체 슬라이드 아웃라인 생성
• 디자인 시스템과 내러티브 구조를 함께 정렬

12. 슬라이드 관련 스크립트 활용하기

scripts/ 디렉터리에는 슬라이드 워크플로와 관련된 유틸리티가 포함되어 있습니다.

• scripts/generate-slide.py – 핵심 슬라이드 생성 로직(직접 덱 생성기나 파이프라인에 맞게 수정 가능)
• scripts/search-slides.py, scripts/slide_search_core.py – 키워드와 컨텍스트를 기반으로 적절한 슬라이드 패턴·전략을 찾는 검색 유틸리티
• scripts/fetch-background.py – data/slide-backgrounds.csv 가이드를 바탕으로 Pexels/Unsplash 등에서 배경 이미지를 가져오는 데 도움

이 스크립트들은 기본 빌딩 블록으로, 환경과 자동화 요구사항에 맞게 실행하거나 커스터마이즈해서 사용하면 됩니다.

레퍼런스와 문서 활용하기

13. 구현 체크리스트로 레퍼런스 활용

references/ 폴더는 단순한 문서가 아니라, 디자인 시스템을 구축하는 동안 사용할 수 있는 체크리스트 역할도 합니다.

• references/token-architecture.md – primitive/semantic/component 레이어링이 탄탄한지 점검
• references/primitive-tokens.md – 기본 토큰 세트가 충분히 정의되었는지 확인
• references/semantic-tokens.md – 각 semantic 토큰에 명확한 목적이 있는지 확인
• references/component-tokens.md – 토큰을 실제 컴포넌트에 매핑
• references/component-specs.md – 상태, variants, 인터랙션, 접근성 고려사항 정리
• references/states-and-variants.md – hover, focus, active, disabled, error, success 상태 누락 방지

디자인 리뷰와 핸드오프 과정에서 이 파일들을 활용해 디자이너와 개발자의 이해를 맞춰 주세요.

스택에 맞게 스킬 적용하기

14. 점진적으로 통합하기

처음부터 전체 스킬을 도입할 필요는 없습니다. 다음과 같은 단계적 접근이 일반적입니다.

• 토큰만 먼저 도입 – templates/design-tokens-starter.json, generate-tokens.cjs, validate-tokens.cjs로 토큰 파이프라인부터 구축
• 슬라이드만 먼저 도입 – data/ CSV와 scripts/generate-slide.py로 기존 디자인 시스템은 유지하면서 프레젠테이션만 표준화
• 풀 시스템 도입 – 토큰, 컴포넌트, 슬라이드 구조를 모두 통합해 제품 UI와 피치덱 전반에 걸친 통합 브랜드 시스템 구축

가장 시급한 문제를 해결하는 부분부터 시작하고, 이후 점차 범위를 넓혀 가는 것을 권장합니다.

FAQ

ckm:design-system은 UI 키트인가요, 디자인 토큰 엔진인가요?

이 스킬은 구조화된 슬라이드 시스템을 함께 제공하는 디자인 시스템 및 토큰 아키텍처 스킬입니다. Figma UI 키트 형태로 제공되지는 않지만, 다음을 제공합니다.

• 3계층 토큰 아키텍처
• 토큰 생성 및 검증용 스크립트
• 컴포넌트 스펙과 상태에 대한 레퍼런스

제공된 토큰과 컴포넌트 구조를 Figma를 포함한 어떤 디자인 툴에도 손쉽게 반영할 수 있습니다.

Tailwind나 React 없이도 ckm:design-system을 사용할 수 있나요?

네, 가능합니다. Tailwind 연계는 references/tailwind-integration.md에 문서화되어 있지만 선택 사항입니다. 토큰은 표준 CSS variables 형태로 생성되므로, 어떤 스택에서도 사용할 수 있습니다.

• Vanilla CSS 또는 CSS Modules
• styled-components 및 기타 CSS-in-JS 솔루션
• Web Components 및 기타 프레임워크용 디자인 토큰

ckm:design-system은 프레젠테이션에 어떻게 도움이 되나요?

이 스킬은 슬라이드 덱을 하나의 디자인 시스템 문제로 다룹니다.

• data/slide-layouts.csv, data/slide-layout-logic.csv – 레이아웃 패턴과 CSS 구조 정의
• data/slide-backgrounds.csv, data/slide-color-logic.csv – 슬라이드 타입과 감정을 비주얼에 매핑
• data/slide-copy.csv, data/slide-strategies.csv – 카피 공식과 덱 구조 제공
• generate-slide.py, search-slides.py 등의 스크립트 – 슬라이드 생성과 검색 자동화

이를 통해 매번 새로 만드는 수작업 슬라이드 대신, 반복 가능하고 브랜드 일관성이 유지되는 덱을 구축할 수 있습니다.

제공된 CSV 데이터를 그대로 써야 하나요?

그럴 필요는 없습니다. CSV들은 **의견 기반 기본값(opinionated defaults)**입니다. 다음과 같이 활용할 수 있습니다.

• 빠른 피치덱 생성을 위해 그대로 사용
• 브랜드 보이스와 비주얼 스타일에 맞게 포크 후 수정
• 동일한 스크립트 패턴은 유지하면서 내용을 전부 자체 데이터로 교체

디자인 토큰만 필요하다면 어디서 시작해야 하나요?

포커스가 토큰과 UI 구현에만 있다면 다음 순서를 추천합니다.

1. SKILL.md에서 "When to Use"와 "Token Architecture" 섹션을 읽습니다.

2. references/token-architecture.md와 primitive/semantic/component 토큰 레퍼런스를 확인합니다.

3. templates/design-tokens-starter.json을 복사해 tokens.json을 만듭니다.

4. 아래 명령을 실행합니다.

   node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
   node scripts/validate-tokens.cjs --dir src/
   

슬라이드 시스템을 건드리지 않고도, 이 단계만으로 동작하는 토큰 파이프라인을 구축할 수 있습니다.

작은 프로젝트에도 ckm:design-system이 적합한가요?

상황에 따라 다릅니다. 특히 다음과 같은 프로젝트에서 강점을 발휘합니다.

• 여러 사람이 UI나 덱 제작에 참여할 때
• 일관성과 확장성이 중요한 경우
• 브랜드나 제품이 시간이 지나며 계속 진화할 것으로 예상될 때

단일 랜딩 페이지나 한 번 쓰고 끝나는 내부 프레젠테이션 정도라면, 전체 시스템은 다소 과할 수 있습니다. 그럴 땐 토큰 아키텍처나 슬라이드 공식만 가볍게 가져다 써도 충분한 가이던스를 얻을 수 있습니다.

스킬에 포함된 내용을 한눈에 보려면 어떻게 하나요?

skills 브라우저 또는 파일 탐색기에서 design-system 스킬의 전체 트리를 확인하세요. 특히 다음 디렉터리와 파일을 살펴보면 좋습니다.

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

이 구조를 보면 어떤 레퍼런스와 헬퍼 스크립트가 포함되어 있는지 한눈에 파악할 수 있고, 그중 어떤 부분을 자신의 워크플로에 통합할지 결정할 수 있습니다.