
moai-designer
브랜드 디자인 시스템과 DESIGN.md, 디자인 토큰, 로고·비주얼, 모션 랜딩 제작을 돕는 스킬. Claude Design 핸드오프를 읽고 공식 Higgsfield 연결 또는 앱 이미지 도구로 브랜드 이미지 작업을 진행합니다.
- version
- 1.4.73
- GitHub stars
- 316
Install
/plugin install moai-designer@moai-coworkRun it inside Claude Code after adding the marketplace with /plugin marketplace add modu-ai/moai-cowork.
Contents
Discovered from sourceSkills 17
브랜드 디자인 시스템
사용자의 브랜드 색·서체·로고 사용 규칙과 화면 목적에서 재사용 가능한 시각 규칙을 만든다. 입력이 없다면 브랜드를 창작해 확정하지 않고 필요한 선택지와 확인 질문을 제시한다.
입력 확인
- 제공된 브랜드 가이드, 디자인 파일, 실제 화면, 카피와 대상 사용자를 확인한다. 접근할 수 없는 파일을 읽었다고 말하지 않는다.
- MoAI 프로젝트에서
.moai/project/brand/visual-identity.md가 있으면 이를 브랜드 기준으로 사용하고.moai/config/sections/design.yaml의 설정을 확인한다. 데스크톱 앱에 이 파일들이 없으면 사용자 제공 자료를 기준으로 작업한다. - 브랜드 자료끼리 충돌하면 해당 값과 출처를 나란히 보여주고 결정이 필요한 항목으로 남긴다. 한 자료를 임의로 우선시하지 않는다.
- Figma 파일은 실제 접근 가능한 연결 또는 사용자가 제공한 내보내기 파일로 읽는다. URL만 있다는 이유로 토큰 추출 완료를 주장하지 않는다.
산출물
요청 범위에 맞게 다음 중 필요한 항목을 작성한다.
- 색상: 브랜드 원색, 배경·표면, 텍스트, 상태색과 실제 사용 쌍
- 타이포그래피: 사용 가능한 서체, 크기·굵기·행간과 언어별 폴백
- 간격과 형태: 레이아웃 폭, 간격 척도, 반경·경계선·그림자
- 컴포넌트: 버튼·입력·카드·내비게이션 등의 상태, 사용 맥락, 키보드 포커스와 반응형 동작
- 토큰: 합의된 값만 JSON 또는 요청한 CSS 형식으로 표현하고 값의 출처를 붙임
히어로, 모바일 뷰포트, 그리드 칸 수, 프레임워크, 다크 모드, 성능 점수는 프로젝트 요구와 실제 검증 환경에 따라 정한다. 브랜드가 흰 배경이나 특정 색을 명시했다는 이유로 배제하지 않는다. 기존 디자인 시스템이 있으면 그 측정값과 명명법을 우선 확인한다.
접근성 검토
웹 콘텐츠라면 W3C WCAG 2.2에서 적용할 성공 기준과 수준을 확인한다. 실제 전경·배경 조합의 명도 대비를 계산하고 작은 텍스트, 큰 텍스트, UI 경계·상태를 해당 기준에 맞춰 평가한다. 토큰만으로 키보드 동작, 스크린리더 출력, 전체 페이지 준수나 Lighthouse 점수를 보장하지 않는다. 구현된 화면이 있으면 해당 환경에서 별도로 검사하고 결과를 기록한다.
브랜드 색 조합이 필요한 기준을 충족하지 못하면 사용 쌍·계산값·필요 기준과 조정안을 제시한다. 새 색은 브랜드 승인 전까지 제안값으로 둔다. 애니메이션은 사용자 설정과 prefers-reduced-motion을 고려한다.
후속 구현은 실제 프로젝트의 프레임워크와 토큰 구조에 맞춘다. 마감 결과에는 확인한 값, 제안값, 미검증 동작을 구분한다.
브랜드 비주얼
사용자의 이미지 용도와 브랜드 규칙을 실제 생성 도구에 전달할 수 있는 구체적인 제약으로 정리한다. 사용자가 이미 생성을 요청했고 세션에 도구가 있으면 프롬프트만 반환하고 끝내지 않는다.
브랜드 자료 확인
- 접근 가능한 디자인 시스템 핸드오프,
DESIGN.md, 토큰 파일, 브랜드 가이드, 마스코트 원본을 확인한다. 파일이 없으면 사용자가 제공한 색·서체·참조 이미지를 사용한다. - 팔레트, 형태, 여백, 분위기, 이미지 안 문구, 마스코트의 허용된 변형을 정리한다. 근거 없는 색·로고·제품 UI를 브랜드의 확정값처럼 만들지 않는다.
- 실제 사용 위치의 크기·비율·카피 공간을 확인한다. 히어로·OG·카드의 화면비를 일률적으로 고정하지 않는다.
- 기존 마스코트나 제품 이미지를 편집한다면 원본이 도구에 실제 첨부됐는지 확인하고 변경할 부분과 보존할 부분을 분리한다.
생성 경로
| 사용자 요청과 현재 호스트 | 실행 경로 |
|---|---|
| ChatGPT Work의 기본 이미지 생성·편집 | 현재 대화의 이미지 생성 도구를 사용한다. ChatGPT Images 공식 안내는 Images 2.5를 설명하지만, 도구가 내부 모델 ID를 노출하지 않으면 특정 API 모델을 사용했다고 단정하지 않는다. |
| Higgsfield 계정·모델·크레딧을 명시 | 이 플러그인에 연결된 공식 Higgsfield 도구를 확인한다. 사용 가능한 모델·파라미터와 크레딧 견적을 라이브 도구에서 조회한 뒤 생성한다. 별도 설치된 moai-media:media-higgsfield-image의 상세 절차도 사용할 수 있다. |
| Claude Cowork에서 Higgsfield 연결 사용 | 이 플러그인의 공식 Higgsfield 연결을 확인한다. 연결이 없으면 실제 생성 가능 여부를 밝히고 프롬프트를 제공한다. |
| 프롬프트만 요청 | 선택한 경로에 맞는 프롬프트와 브랜드 제약을 제공한다. |
일반 ChatGPT 이미지 요청을 Higgsfield로 자동 전환하지 않는다. 반대로 Higgsfield를 지정한 요청을 ChatGPT 기본 이미지 도구로 임의 전환하지 않는다. 앱 도구가 실제 API 모델 ID를 노출하지 않으면 결과에 특정 API 모델 ID를 붙이지 않는다. 여러 컷의 동일 인물·마스코트 참조가 필요하면 현재 연결이 참조 이미지와 일관성 기능을 지원하는지 확인한다. 생성 비용이 발생하면 실행 전에 견적과 사용자의 승인 조건을 확인한다. 별도 설치된 moai-media 스킬은 상세 작업에 활용할 수 있지만 필수 전제는 아니다.
결과 검수
생성된 이미지를 실제로 보고 색·형태·구도·로고·문구·인물 일관성을 확인한다. 이미지 속 텍스트는 오탈자를 점검한다. 배경 위에 웹 텍스트를 얹는다면 최종 화면에서 대비를 검사한다. 어긋난 항목은 관찰한 내용으로 기록하고 재생성이나 편집을 제안한다. 생성 도구 호출, 결과 확인, 파일 저장을 각각 별도 완료 상태로 보고한다. 실패가 모호하면 결과 상태를 먼저 확인하고 중복 생성하지 않는다.
출력에는 용도, 참조 자료, 적용 제약, 실제 사용한 생성 경로, 결과 이미지 또는 파일 경로, 검수 결과를 적는다. 결과가 없으면 생성 완료라고 말하지 않는다.
디자인 브리프
사용자의 요청을 디자인 도구나 담당자에게 전달할 수 있는 명확한 브리프로 정리한다. Claude Design 공식 안내에 따르면 디자인은 Claude 대화, Artifacts, Claude Code, claude.ai/design에서 시작할 수 있다. 브리프의 내용은 이 중 어느 경로에서도 사용할 수 있게 작성한다. ChatGPT Work에서도 같은 브리프를 읽고 현재 사용 가능한 디자인·이미지 도구에 맞게 활용할 수 있다.
작성 순서
- 사용자가 이미 준 목표, 대상 사용자, 필요한 화면·문서, 브랜드 자료, 참고 이미지·URL, 사용 환경과 제약을 추출한다. 없는 항목을 실제 사실처럼 채우지 않는다.
- 디자인 결정에 꼭 필요한 정보만 묻는다. 답을 기다리지 않아도 초안을 만들 수 있다면 미정·가정 항목을 표시하고 진행한다. 호스트 전용 질문 도구 이름을 절차의 필수 조건으로 두지 않는다.
- 참고 URL·이미지는 실제 제공되었거나 조회한 경우에만 넣는다. 특정 회사나 디자이너의 경력·소속을 프롬프트 속 가상 권위로 만들지 않는다.
- 브랜드 서체·색·레이아웃을 일괄 금지하거나 강제하지 않는다. 제공된 디자인 시스템과 사용 목적을 기준으로 정하고, 접근성·반응형·콘텐츠 길이 같은 확인할 제약을 명시한다.
- 원하는 산출물과 검토 기준을 적는다. Claude Design을 사용할 경우 실제 이용 가능한 앱 표면에서 브리프를 붙여 넣거나 대화에 전달한다. 디자인이 생성·내보내기·동기화됐다는 주장은 결과를 확인한 뒤에만 한다.
브리프 틀
# 디자인 브리프
## 목표
[사용자가 달성하려는 결과와 근거]
## 대상과 사용 맥락
[확인된 사용자·기기·상황 / 미정 사항]
## 필요한 화면·산출물
[각 화면의 목적과 핵심 콘텐츠]
## 브랜드와 참고 자료
[제공된 디자인 시스템·파일·URL / 출처]
## 제약과 검토 기준
[접근성·반응형·기술·문구·제외 범위]
## 결정 대기
[확인할 항목과 현재 가정]
사용자가 Claude Design용 복사 프롬프트를 원하면 이 브리프를 자연어 지시문으로 합쳐 제공한다. 디자인 시스템 준비는 moai-designer:design-system-prep, 특정 영역의 프롬프트는 moai-designer:design-prompt-builder, 생성된 결과 검수는 moai-designer:design-slop-check를 사용한다.
브랜드 카피 작성
브랜드 보이스, 대상 사용자, 화면 목적과 실제 제품 기능을 확인해 문구를 쓴다. MoAI 프로젝트에 .moai/project/brand/brand-voice.md가 있으면 읽고 그 용어와 문체를 따른다. 데스크톱 앱에서 그 파일이 없으면 사용자가 제공한 브랜드 자료를 사용한다. 자료가 없으면 임시 문체를 제안값으로 표시하고 브랜드 확정 카피라고 부르지 않는다.
진행 방법
- 필요한 화면과 각 문구의 역할을 정한다. 히어로·기능·가격·후기·푸터를 모든 페이지에 강제하지 않는다.
- 실제로 제공하는 기능, 적용 대상, 조건과 제약을 자료에서 확인한다. 수치, 무료 체험, 환불, SLA, 고객사 이름, 후기, 경쟁 우위를 만들어내지 않는다.
- 제목은 사용자가 얻는 결과나 해결할 작업을 구체적으로 쓰고, 버튼은 누른 뒤 일어나는 동작을 분명히 쓴다. 오류 메시지에는 문제와 사용자가 취할 수 있는 다음 행동을 담는다.
- 브랜드가 쓰는 언어와 호칭을 유지한다. 상투어와 근거 없는 최상급 표현을 점검하되, 실제 브랜드 서체·표현을 일괄 금지하지 않는다.
- 대안 문구는 비교가 유용할 때만 만든다. 변형을 만들었다는 이유로 A/B 테스트를 수행하거나 전환율이 높다고 주장하지 않는다.
- 최종 문구의 사실·숫자·링크·법적 문구를 원자료와 대조한다. 미확인 항목은 공개용 문구에 넣지 않고 확인 과제로 남긴다.
산출물
MoAI 코드 기반 디자인 파이프라인이 섹션 JSON을 기대하면 page_type, sections, metadata 구조로 출력하고 실제 필요한 섹션만 포함한다. 각 섹션의 primary는 기본 문구이며 variant_a는 실제 대안이 있을 때만 쓴다. 일반 데스크톱 요청은 표나 문서처럼 사용자가 편집하기 쉬운 형식으로 낸다. 자동 계산하지 않은 읽기 수준이나 성과 점수를 메타데이터에 채우지 않는다.
카피 길이는 실제 레이아웃과 언어에 맞춰 조정한다. 영어의 단어 수나 Flesch-Kincaid 점수를 한국어 카피에 적용하지 않는다. 디자인 토큰과 레이아웃을 함께 만드는 경우 moai-designer:design-brand-system에 문구 길이와 계층을 전달한다. 문체 검수에는 moai-coworker:ai-slop-reviewer 또는 moai-writer:korean-humanize를 사용할 수 있지만 사실·의미·숫자는 보존한다.
design-gui-guide — 10 GUI 요소 사용성 가이드라인 SSOT
목적과 근거
거의 모든 화면은 10개 표준 GUI 요소로 조립된다. 각 요소는 40년+ 다윈 필터를 통과한 관습이다 — Jakob's Law(사용자는 다른 사이트에서 보던 대로 너의 것도 작동하길 기대한다)가 익숙한 버전을 늘 더 낫게 만든다. 혁신 예산은 새 체크박스 종자를 만드는 데 쓰지 말고 콘텐츠와 서비스에 써라.
근거: UX Tigers, Jakob Nielsen, "10 GUI Design Elements Build Every User Interface" (2026-07-29) — 86개 증거 기반 가이드라인 + 보너스 2. 본 스킬은 이를 한국어 실용 지침으로 증류하고 shadcn 63종과 매핑한다. 원문 가이드라인(사용성 원칙·방법)을 재서술한 것이지 복사한 것이 아니다.
세 가지 상위 명제 (모든 86개 지침은 이 아래 있다):
- 기억시키지 말 것 — 인식(recognition) 우위 유지
- 추측시키지 말 것 — 시각 문법·관습을 훼손하지 말 것
- 기다리게 하지 말 것 — 반응·완결에 엄격한 예산
소비 지점
| 소비자 | 사용 방법 |
|---|---|
design-prompt-builder 패턴 3 | 디자인 시스템 생성 시 각 컴포넌트를 해당 요소 가이드라인에 맞춰 설계 |
design-prompt-builder 패턴 6 | 사용성 감사 시 Nielsen 10 휴리스틱 + 본 86개 지침(컴포넌트 단위)으로 평가 |
design-system-prep | DESIGN.md Component recipes 품질 기준 |
design-slop-check | 카피 중심 검수의 보완 — 컴포넌트 동작·레이아웃 품질은 본 스킬 |
1. Buttons — 누르면 무언가 일어난다
shadcn: Button · Button Group
버튼은 세계를 바꾸는 유일한 요소(링크·탭은 옮기고, 메뉴·다이얼로그는 대화를 재배열할 뿐). 그래서 라벨 규칙이 가장 엄격하다 — 잘못된 링크는 Back 한 번이지만, 잘못된 버튼은 고객 한 명을 잃는다.
- 누를 수 있게 보이게. 닫힌 형태 + 배경 대비 + 누름 시 상태 변화. 플랫 디자인으로 테두리/그림자를 걷어내면 "어떤 글자가 명령인지" 사용자가 추측하게 된다.
- 모든 버튼에 결과를 나타내는 동사 라벨. "Save Invoice"지 "OK"가 아니다. 효과가 2–4단어 안에 안 들어오면 라벨 문제가 아니라 더 깊은 문제.
- 화면마다 시각적으로 우세한 주 액션 정확히 1개. 주 액션이 2개 경쟁하면 주 액션이 없는 것.
- Fitts's law 준수. 자주 쓰는 액션은 크고 가깝게. 터치 타깃 최소 1×1cm.
- 모든 누름을 0.1초 안에 인지. 반응한 것처럼 느끼는 한계.
- 비활성 버튼은 주 색의 흐린 버전 + 왜 비활성인지/어떻게 켜는지 설명. 숨기지 말 것.
- 액션엔 버튼, 이동엔 링크. 두 시각 언어를 섞지 말 것.
- 버튼은 작업이 끝나는 자리에. 필드·콘텐츠 뒤, 읽기 흐름의 자연스러운 끝.
Split button: 주 액션(큰 영역, 1클릭) + 변형(작은 영역, 화살표/3점). 한 명령이 빈도로 압도적일 때만. 두 영역 사이 가시적 구분자 필수. 기본 하나가 안 정해지면 일반 메뉴 버튼을 써라.
2. Input Fields & Forms — 돈이 오가는 자리
shadcn: Input · Input Group · Input OTP · Textarea · Label · Field · Select · Native Select · Combobox · Date Picker · Checkbox · Radio Group · Switch · Toggle · Toggle Group · Slider
폼은 체크아웃·가입·리드 발생 — 사용성이 수익으로 직결된다(UX = profits). 가장 강한 지침은 뺄셈: 불필요한 필드 하나마다 완료율이 떨어진다. 선택 필드도 필드 세금(주의를 소모)을 매긴다 — DB에서 선택이어도 사용자 주의에선 선택이 아니다.
- 엄격히 필요 없는 필드는 삭제. 남길 필드 하나는 잃는 완료율/매출과 저울질해야 한다.
- 모든 필드에 필드 밖의 영구 라벨. placeholder는 힌트지 라벨이 아니다 — 타이핑 시작하면 사라진다.
- 유연한 입력 포맷 수용. 전화번호 하이픈 유무를 가리지 말고 코드에서 정제. 컴퓨터가 사람에게 떠넘긴 일을 되찾아라.
- 에러는 해당 필드 옆에, 사용자가 입력한 값은 보존. 에러로 입력을 날리는 폼은 두 번 쓰이지 않는다.
- 작업에 맞는 전용 컨트롤 사용. 날짜엔 Date Picker, 장바구니 제거엔 휴지통 아이콘(사용자 머릿속 "0으로 설정"이 아니라 "제거").
- 단일 컬럼 + 관련 필드 그룹화. 다중 컬럼은 읽기 순서를 모호하게 해 필드를 건너뛰게 한다.
- 제출 버튼은 결과 라벨. "Submit"이 아니라 "Place Order".
- 입력 도중 검증 금지. 키 입력 중 "잘못된 이메일"은 성급한 판단 — 필드를 벗어날 때 검증.
부담 인쇄 역설: "3문항, 40초"처럼 부담을 미리 말하면 두려움이 거래로 바뀐다. 단, 거짓말 금지 — 1분이라 했는데 5분이면 신뢰가 사라진다.
3. Menus — 정보 구조의 시각화
shadcn: Dropdown Menu · Navigation Menu · Menubar · Context Menu · Breadcrumb
메뉴는 공간 절약 + 인식 우위(가시 선택에서 고르기). 단, 완결성 주장이라는 함정 — 사용자는 메뉴를 "부엌이 만들 수 있는 전체 목록"으로 읽는다. 열리지 않을 라벨 아래 있는 것은 사용자에겐 없는 것이다.
- 카테고리는 사용자 어휘로 — card sorting·tree testing으로 검증. 조직도는 정보 구조가 아니다.
- hover보다 click-to-open. hover 필수면 짧은 지연 + 대각선 허용 경로 추가.
- 캐스케이드 2단계 한도. 더 깊으면 깊이 말고 카테고리를 재구성.
- 데스크톱에선 최상위 내비게이션 노출. 햄버거는 작은 화면 전용 — 보이지 않는 내비게이션은 안 쓰는 것이다.
- 현재 위치 표시. "you are here" 점 없는 지도.
- 중요도·작업 빈도순 정렬. 정확한 이름을 아는 경우에만 가나다/알파벳순.
- 가장 자주 쓰는 2–3 명령은 메뉴에서 빼고 가시 버튼으로 승격. 메뉴는 긴 꼬리용.
4. Links — 웹의 원자
shadcn: (Typography·Breadcrumb 맥락)
링크는 두 약속 — 클릭 가능하다는 시각 약속(색+밑줄)과, 반대편에 무엇이 있는지에 대한 약속(information scent). "Click here"/"Learn more"는 향이 0이다. 스캐닝 사용자는 링크 앞 11문자를 주로 읽는다.
- 링크는 링크답게. 본문 속 링크는 색+밑줄 — 색만은 색맹·저가 화면에서 실패.
- 링크 서식은 링크 전용. 다른 것에 밑줄을 주면 가구를 클리커블로 훈련시킨다.
- 정보를 담은 단어를 앞에. 앞 11문자가 대부분의 일을 한다.
- 목적지를 예측하게 + 맥락 없이도 의미 통하는 텍스트. 스크린리더는 링크 목록을 뽑아준다 — "click here" 14개는 무용.
- 방문·미방문 링크 구분 (링크 많은 디자인).
- 링크를 버튼으로, 버튼을 링크로 교차 복장 금지. 시각 문법이 의미를 운반한다.
- 기본 같은 탭에서 열기. 예외 시 링크에 표시(예: "(PDF)").
핵심 경계: 링크는 가고, 버튼은 한다. 두 언어를 흐리면 매 클릭마다 작은 세금이 붙는다.
5. Dialog Boxes — 중단은 그 값을 증명해야
shadcn: Dialog · Alert Dialog · Sheet · Drawer
Modal은 모든 작업을 차단하고 사용자의 작업 기억에 세금을 매긴다. 그래서 중단을 벌어야 한다 — 차단 결정, 되돌릴 수 없는 결과, 없으면 진행 못 하는 입력.
- 진짜 차단 결정에만 modal. 합리적으로 계속 작업할 수 있다면 중단은 정당화 안 된다.
- 버튼은 결과 라벨. "Delete 3 Files" / "Keep Files"가 질문에 답한다 — "OK"/"Cancel"은 모호.
- 안전한 선택을 기본으로, Esc는 항상 취소. 잘못된 Enter 한 번이 무언가를 파괴해선 안 된다.
- 다이얼로그당 1문제, 1–2문장. 상황·결과·선택 — 읽기 과제가 아니다.
- 되돌릴 수 있는 액션엔 확인 대신 undo. undo는 경고를 클릭하도록 훈련하지 않고 사용자를 보호.
- 작업 계속 가능하면 modeless. 찾기바꾸기가 1980년대에 푼 문제.
- 첫 방문자에게 오버레이로 인사 금지. 가치 전달 전 이메일을 요구하는 건 인사 전에 교제를 요구하는 것.
- 다이얼로그 위에 다이얼로그 금지. 중단 대기열은 상류 설계가 이미 실패한 것이다.
다크 패턴 경고: 오버레이는 3% 전환은 측정하지만 97%의 반감은 측정 안 된다 — "원한은 이벤트 핸들러가 없다". 강제 전환의 비용도 같이 측정하라.
6. Alerts · Notifications · Errors — 시스템의 대화 차례
shadcn: Alert · Toast · Message · Message Scroller
에러 메시지 가이드라인은 GUI 이전부터: 평언으로 무엇이 잘못됐는지, 정확히 어디서, 어떻게 복구하는지 — 사용자 탓 금지.
- 평언, 날것의 에러코드만 금지. "Error 0x80004005"는 개발자가 자기 위해 쓴 것이다.
- 무엇이·어디서 잘못됐는지 정확히. "문제가 발생했습니다"는 아무 도움 안 된다.
- 나아갈 길 제시. 좋은 에러 메시지는 1문장 복구 계획.
- 사용자 탓 금지. "illegal", "fatal", "invalid user" — 신뢰한 사람에게 죄를 떠넘기는 표현 금지.
- 심각도 ↔ 포맷 매칭. Toast는 FYI, 에러는 고쳐질 때까지 남는 인라인, modal은 재난 전용.
- 아이콘 + 색 + 글자로 신호(중복 코딩). 남성 약 1/12가 적녹 색약 — "빨간색 표시"만으로는 의미가 없다.
- 알림 배급. 기본 적게, 사용자가 볼륨 조절 — 매 중단은 한정된 신뢰 통장에서 인출.
Toast 함정: 자가 소멸이라 확인용("메시지 전송됨")엔 좋지만, 사용자가 조치해야 할 에러에 쓰면 4초 뒤 사라져 하드 웨이로 재발견된다.
7. Icons — 작은 그림, 큰 오해
shadcn: Lucide 아이콘 전반
아이콘의 만성 약점 — 사용자가 낯선 그림을 자주 잘못 추측. 보편 인식에 가까운 건 손에 꼽는다(돋보기·집·기어·휴지통). 나머지는 테스트 대기 중인 가설.
- 아이콘에 글자 라벨 짝지음. 공간이 진짜 안 되면 tooltip 제공 + 학습성을 픽셀과 맞바꿨음을 인정.
- 표준 은유가 있으면 그것 사용. 검색·설정의 새 기호는 사용자 주의를 써서 아무것도 사지 않는다.
- 은유를 믿기 전 인식 테스트. 5명에게 아이콘만 보여 의미를 물어라 — 망설임이 답이다.
- 일관된 스타일 + 구별되는 실루엣. 형제처럼 보이되 흘겨봐도 구별 가능하게.
- 학습된 아이콘을 유행으로 재디자인 금지. 친숙한 기호 재설계는 모든 기존 사용자에게 세금을 매긴다.
- 16×16에서 살아남는 favicon. 로고를 한 강한 형태 + 브랜드 색으로 단순화 — 정밀 디테일은 진흙이 된다.
- 아이콘 전용 버튼은 보편 소수만. 돋보기는 단독 가능, 네 "insights" 글리프는 안 된다.
텍스트 라벨은 살 수 있는 가장 싼 사용성 보험이다. 라벨링된 아이콘은 수업이고, 라벨 없는 아이콘은 시험이다.
8. Checkboxes · Radio Buttons · Toggles — 네모는 "아무거나", 동그라미는 "하나만"
shadcn: Checkbox · Radio Group · Switch · Toggle · Toggle Group
형태가 선택 모델을 가르친다 — 네모는 복수, 동그라미는 정확히 1개. 수십년 노출로 사용자가 배운 문법. 디자이너가 둘을 바꾸면 화면이 자기 규칙에 대해 거짓말한다.
- 독립 옵션엔 체크박스, 상호배타엔 라디오. 형태가 계약 — 지켜라.
- 옵션은 세로 배치. 가로는 어느 라벨이 어느 컨트롤인지 모호하게 만든다.
- 라벨 클릭 가능. 14px 동그라미는 잔인한 타깃 — 라벨이 면적을 공짜로 늘린다.
- 라디오 그룹엔 합리적 기본값 + (기권 유효하면) "None" 옵션. 한 번 누르면 취소 불가하다.
- 옵션은 긍정 어법. "뉴스레터 받기"가 "통신에서 제외하지 마세요"보다 낫다.
- 토글은 즉시 적용될 때만. 제출 단계가 뒤따르면 체크박스다 — Save 버튼 위 토글은 모순.
- 예/아니오는 라디오 2개가 아니라 체크박스 1개. 컨트롤 1, 결정 1, 읽기 절반.
- 2–4 옵션은 드롭다운 대신 가시 라디오. 한 번에 보는 게 클릭+기억 테스트보다 낫다.
9. Tabs — 한 행, 같은 타입, 같은 단계
shadcn: Tabs
물리적 비유가 규칙을 정한다 — 선택 탭은 패널에 붙어 보여야, 미선택은 클릭 가능하되 종속적으로. 라벨은 짧고 1행이 한도.
- 탭은 항상 1행. 안 들어맞으면 탭이 너무 많거나 라벨이 긴 것 — 탭 수/라벨을 고쳐라.
- 라벨은 평범한 1–2단어. 탭은 병렬 콘텐츠의 제목, 문장이 아니다.
- 선택 탭을 패널에 시각 연결 + 이웃과 구별. current/hover/unselected 세 가지 다른 외관.
- 같은 타입·같은 단계 콘텐츠에만 탭. 순차 프로세스엔 단계 표시자 있는 마법사.
- 대다수가 먼저 필요로 하는 탭을 기본. 탭 영역의 첫인상은 네가 열어둔 패널이다.
- 비교해야 할 콘텐츠를 탭에 걸치지 말 것. 앞뒤로 넘기는 건 기억 테스트 — 비교표가 답이다.
- 플랫폼이 허락하면 탭마다 URL. 사용자는 북마크·공유·Back — 링크 가능한 장소만 온전히 존재한다.
10. Search — 사용자가 자기 말로 목표를 말한다
shadcn: Command
검색은 살아남은 명령줄 — 가능성 공간이 메뉴를 넘어서면 글자가 이긴다. AI 프롬프트 입력란도 같은 화석의 환생. 검색 로그는 얻을 수 있는 가장 싼 사용자 리서치다.
- 콘텐츠 많은 사이트 매 페이지 상단에 오픈 검색창. 아이콘이 상자를 숨기면 클릭 한 번 + 가시성 마이너스.
- 상자 최소 27문자 폭. 전체 쿼리가 보여야 편집 가능 — 필드 안 스크롤은 비참하다.
- 제출은 돋보기 표시 + Enter 작동. 둘 다 사용자가 가져오는 관습.
- 오타·복수·동의어 관용. 엔진의 일은 사용자가 의미한 걸 찾는 것, 친 걸 채점하는 게 아니다.
- 결과 페이지에서 쿼리를 상자에 유지. 재구성이 검색 행동의 절반 — 편집을 재시작이 아니라 키 입력으로.
- 결과 페이지를 온전한 UI로 설계. 스캔 가능한 제목, 왜 매치했는지 드러내는 스니펫, 컬렉션 커지면 필터.
- 사용자가 사이트 일부로 여기는 모든 것 색인. 지원 섹션을 조용히 건너뛰면 거짓 "결과 없음"을 양산한다.
- 검색 로그 월 1회 마이닝. 대량·빈약 결과 쿼리는 사용자가 직접 접수한 사용성 버그다.
보너스 A. Windows & Scrolling — 상속받은 것, 새로 띄우지 말 것
shadcn: Sidebar · Scroll Area · Resizable (컨텍스트)
오늘날 디자이너는 윈도우(브라우저 탭)를 상속받지 디자인하지 않는다. 남은 설계 질문은 "언제 새 창을 띄울까" — 답: 드물게. 깜짝 창은 웹의 후진 기어(Back)를 부순다.
- 기본 같은 창/탭에서 열기. 새 탭을 원하는 사용자는 스스로 연다 — 대신 결정하지 말 것.
- 스크롤 속도·방향 하이재킹 금지. 스크롤은 근육 기억 — 덮어쓰면 페이지 전체가 빙의된 느낌.
- 스크롤 가능한 모든 영역에 스크롤바 가시 유지. 지도를 숨긴다고 영토가 짧아지진 않는다.
- 무한 스크롤은 아래에 사용자가 필요한 것이 없을 때만. 푸터가 중요하면 "Load More" 버튼.
- 콘텐츠를 중요도순 배치. 사용자는 스크롤하지만 주의는 매 화면마다 얇아진다 — 위가 프라임 부동산.
- Back 버튼 보호. 이것을 부수는 것(불필요한 새 창 포함)은 내비게이션의 주 undo를 부순다.
보너스 B. Pointers & Cursors — 화면 위의 손
shadcn: (커서/포커스 표시 — 간접)
포인터 형태는 클릭이 할 일을 알리는 기호 언어 — 화살표·손·잡기 손·I-beam. 디자이너가 커서를 직접 그리는 일은 드물지만 신호를 존중해야 한다.
- 플랫폼 표준 커서 사용, 재스타일링 금지. 커스텀 커서는 디자이너엔 참신, 사용자엔 거짓말 탐지기다.
- 진짜 클릭 가능 요소에만 손 모양, 편집 가능 텍스트에만 I-beam. 커서 변화는 약속 — 거짓은 진짜들을 갉아먹는다.
- 1초 이상 대기엔 busy 표시. 커서의 가장 오래된 일은 시스템이 들었는지 솔직해지는 것.
- 중요 정보·액션 경로를 hover 유일으로 만들지 말 것. 터치 기기엔 hover가 없다 — 키보드도.
- 키보드 사용자에게 가시 포커스 표시. 포커스 아웃라인은 키보드의 커서 — 미학상 제거하면 Tab으로 이동하는 모두를 고립시킨다.
자주 헷갈리는 경계 — 요약표
| 하려는 일 | 쓸 것 | 금지 |
|---|---|---|
| 페이지 이동 | Link | 버튼으로 복장 |
| 즉시 실행(상태 토글) | Switch / Toggle | Save 버튼 위 토글(모순) |
| 제출로 확정 | Checkbox + Button | 같은 것에 토글 |
| 복수 선택 | Checkbox | Radio |
| 정확히 1개 | Radio | Checkbox |
| 차단 결정 | Modal Dialog | 인라인 가능한 데 modal |
| FYI 확인 | Toast | 에러(사라지면 안 됨) |
| 정보가 많은 내비게이션 | Search / Command | 햄버거(데스크톱) |
출처
- Jakob Nielsen, UX Tigers, "10 GUI Design Elements Build Every User Interface" (2026-07-29) — 86개 증거 기반 가이드라인 + 보너스(윈도우·포인터). https://www.uxtigers.com/post/gui-widgets
- 본 스킬은 원문의 가이드라인(사용성 원칙·방법)을 한국어 실용 지침으로 증류·재서술한 것이지 원문을 복사한 것이 아니다. 인용 사례(Expedia $12M·Fitts's law·남성 1/12 색약·27문자 폭·앞 11문자·0.1초 반응 등)는 사실 관계에 기반한다.
- 이론 뿌리: Jakob's Law · 인식>재인(Nielsen heuristic 6) · Fitts's law(1954) · perceived affordance(Don Norman) · information scent(Pirolli & Card).
관련 스킬
| 스킬 | 사용 시점 |
|---|---|
moai-designer:design-prompt-builder | 패턴 3(생성)·6(감사)이 본 가이드라인을 컴포넌트별 체크리스트로 참조 |
moai-designer:design-system-prep | DESIGN.md Component recipes 품질 기준 |
moai-designer:design-slop-check | 카피 중심 검수의 보완 — 컴포넌트 동작·레이아웃 품질은 본 스킬 |
moai-designer:design-system-library | shadcn vanilla 컴포넌트 참조 마크업과 본 가이드라인의 짝 |
디자인 핸드오프 읽기
Claude Design 공식 안내는 디자인을 Claude Code로 넘기는 기능을 설명한다. 이 스킬은 사용자가 실제로 제공한 핸드오프 자료를 분석한다. 특정 ZIP 구조, README, tokens.json, components.json, chat-history.md가 공식적으로 항상 포함된다고 가정하지 않는다.
입력 확인
- 파일·폴더·링크가 실제 접근 가능한지 확인하고 목록을 기록한다. 접근되지 않는 링크를 읽었다고 말하지 않는다.
- README나 안내 문서가 있으면 의도와 파일 관계를 먼저 읽는다. 없으면 실제 디자인 파일, 코드, 자산의 역할을 확인한다.
- JSON·CSS·HTML·이미지 등 존재하는 자료에서 색·서체·간격·컴포넌트·레이아웃·상태·인터랙션을 추출한다. 이미지만 있으면 코드 구조나 동작을 추정으로 표시한다.
- 채팅 기록이나 결정 메모가 있으면 사용자가 명시한 결정과 이유를 출처와 함께 정리한다. 없으면 디자인 의도를 상상해 채우지 않는다.
- 기존 코드베이스와 매핑하려면 해당 프로젝트 파일을 실제로 읽는다. 보지 않은 컴포넌트와 일치한다고 말하지 않는다.
결과
# 디자인 핸드오프 분석
## 확인한 입력
- 접근한 파일·링크: [실제 목록]
- 열지 못한 자료: [이유]
## 구현에 필요한 결정
- 화면·상태·반응형·자산: [파일 근거]
- 브랜드 토큰과 컴포넌트: [원본 값과 위치]
## 미확인 사항
- 동작·콘텐츠·접근성·권한: [확인할 질문]
## 구현 지시 초안
[현재 프로젝트의 프레임워크·컴포넌트·브랜드 규칙을 반영한 짧은 지시]
구현 지시는 Claude Code나 ChatGPT Work에서 사용할 수 있는 중립적인 문장으로 쓴다. 특정 호스트 전용 명령은 사용자가 그 호스트를 선택했고 실제 기능을 확인한 경우에만 넣는다. 분석이 끝났다는 사실은 코드 구현·빌드·디자인 동기화 완료를 뜻하지 않는다. 원본 번들과 파일은 보존하고, 추출한 값과 추정값을 구분한다.
디자인 핸드오프 작성
사용자가 제공한 목표, 대상 사용자, 디자인 시스템, 화면 범위, 실제 참고 자료를 하나의 전달 가능한 지시로 정리한다. design-brief와 design-handoff-reader의 산출물이 실제로 있다면 읽고 연결한다. 읽지 않은 번들이나 연구 결과를 입력으로 채우지 않는다.
작성 절차
- 자료 확인: 제공된 브리프·화면·브랜드 보이스·토큰·참고 URL의 출처와 최신성을 확인한다. MoAI 프로젝트에서
.moai/project/brand/가 있으면 해당 브랜드 결정을 존중한다. 데스크톱 앱에 폴더가 없으면 사용자 자료를 사용한다. - 범위 정리: 만들 화면·상태·콘텐츠와 제외 범위 중 사용자가 실제로 정한 내용을 기록한다. 빠진 브랜드나 레퍼런스는 미정으로 표시하고 가상의 제품·URL·후기를 넣지 않는다.
- 붙여넣기 지시: 외부 디자인 세션용 문구에서 내부 SPEC ID·로컬 경로·에이전트 이름을 제거하고 목적, 대상, 참고 자료, 브랜드 규칙, 결과 형식과 검토 기준을 자연어로 적는다. 파일이 없는 경우에도 채팅에서 바로 사용할 수 있는 본문을 제공한다.
- 보조 파일: 사용자가 요청하거나 기존 MoAI Path A 파이프라인이 필요로 하면
prompt.md,context.md,references.md,acceptance.md,checklist.md로 분리한다. 파일을 만들었다면 실제 경로를 읽어 확인한다. 파일 분할은 Claude Design의 공식 내보내기 형식이라고 주장하지 않는다. - 검수: 브리프의 수치·디자인 값과 핸드오프가 일치하는지 대조한다. 구현 화면이 없는데 WCAG 준수·반응형 동작·디자인 완료를 PASS로 기록하지 않는다.
Claude Design 공식 안내에 따라 사용자는 Claude 대화, Artifacts 또는 claude.ai/design에서 디자인을 시작할 수 있다. ChatGPT Work 사용자에게는 동일한 브리프를 현재 사용할 수 있는 디자인 도구나 코드 작업에 전달할 수 있게 제공한다. 도구 간 자동 동기화나 붙여넣기가 실제로 일어나지 않았다면 완료라고 말하지 않는다.
참고 형식은 references/prompt-template.md와 references/supporting-files.md에 있다. 결과에는 생성한 문서의 위치, 실제 확인한 근거, 미결정 사항과 다음 작업을 짧게 적는다.
MoAI-ADK 프로젝트에서는
.moai/config/sections/design.yaml과 기존 스프린트 산출물을 읽는다. Claude Cowork·ChatGPT Work 데스크톱에서는 사용자가 제공한 브리프와 실제 시안으로 같은 평가 항목을 점검할 수 있다. 설정 파일이나 검사 도구가 없으면 그 항목을 미검증으로 기록하고 점수나 PASS를 만들어 내지 않는다.
design-iteration-loop
Implements the Builder-Evaluator GAN loop for iterative design quality improvement. Absorbed from the retired v2.x design constitution Section 11 and Section 12 (per the design constitution absorption policy). Integrates Sprint Contract Protocol, 4-dimension scoring, stagnation detection, and Evaluator Leniency Prevention.
In a MoAI-ADK project, read loop parameters from .moai/config/sections/design.yaml; the values below describe the current project configuration and are not portable defaults. In a desktop conversation without that file, agree on criteria with the user and report observations without inventing thresholds.
Quick Reference
Loop Parameters (from design.yaml)
design.gan_loop:
max_iterations: 5 # Maximum Builder-Evaluator cycles
pass_threshold: 0.75 # Score >= this value to exit loop
escalation_after: 3 # Escalate to user after N iterations without passing
improvement_threshold: 0.05 # Minimum score delta per iteration
strict_mode: false # If true, each must-pass criterion must pass individually
sprint_contract:
enabled: true
required_harness_levels: [thorough]
optional_harness_levels: [standard]
artifact_dir: ".moai/sprints"
max_negotiation_rounds: 2
4-Dimension Evaluation
| Dimension | Description |
|---|---|
| Design Quality | Visual consistency, supplied brand token compliance, measured contrast |
| Originality | Brand-specific expression against the supplied brief |
| Completeness | Requested BRIEF sections present, copy matches the agreed text |
| Functionality | Observed responsive behavior and tested interactions |
The current design.yaml does not define weights for these dimensions. Do not present 30/25/25/20 or any other split as configured. The ADK evaluator owns the overall score; cite its actual rubric and result. In a standalone desktop review, report each observed dimension and gaps without a synthetic overall score.
In the ADK loop, pass requires the evaluator's measured overall score to reach pass_threshold and every contracted must-pass criterion to pass. Strict mode adds the constitution's two-iteration minimum. A standalone desktop review without a configured evaluator does not issue this numeric PASS.
Implementation Guide
GAN Loop Execution Flow
Phase 1: Sprint Contract (when required by harness level)
Required when harness_level == thorough.
Optional when harness_level == standard and user opts in.
Skipped when harness_level == minimal.
Sprint Contract generation:
- Evaluator analyzes the BRIEF document and current iteration scope.
- Evaluator produces the Sprint Contract document:
acceptance_checklist: concrete, testable criteria for this iterationpriority_dimension: which of the 4 dimensions to focus ontest_scenarios: specific verification stepspass_conditions: minimum score per criterion
- Builder reviews the contract:
- Accept: proceed with implementation
- Request adjustment: propose alternatives (max
max_negotiation_roundsrounds)
- Contract is saved to
design.gan_loop.sprint_contract.artifact_dir/sprint-N.json
Constraint: Evaluator must not score on criteria outside the Sprint Contract. Builder must not claim criteria as met without evidence.
Phase 2: Builder Execution
Builder implements based on:
- Accepted Sprint Contract (if present)
- BRIEF document
- Copy JSON from
design-copywriting - Design tokens from
design-brand-systemordesign-workflow(Path A handler)
Builder outputs: code files, rendered previews (if Playwright available), implementation notes.
Phase 3: Evaluator Scoring
Evaluator scores against the 4 dimensions using the Evaluator Leniency Prevention mechanisms:
- Rubric Anchoring: Score each dimension against the rubric (0.25 increments) with explicit justification. Scores without rubric reference are invalid.
- Evidence-Only Verdicts: No PASS without concrete evidence (screenshot, test output, code reference).
- Anti-Pattern Cross-check: Check known anti-patterns before finalizing. Any detected anti-pattern caps the relevant dimension score at 0.50.
- Must-Pass Firewall: Copy integrity, mobile viewport, and WCAG AA are must-pass criteria. Failure in any must-pass = overall FAIL regardless of other scores.
Output: evaluation-report-N.json in sprint_contract.artifact_dir.
Phase 4: Loop Decision
if overall_score >= pass_threshold:
EXIT LOOP → proceed to next phase
elif iteration >= max_iterations:
ESCALATE → present failure report to user
elif stagnation_detected:
ESCALATE → present stagnation options
else:
ITERATE → pass feedback to Builder, increment N
Phase 5: Iteration Feedback
If looping back:
- Evaluator generates targeted feedback per failed criterion.
- Builder receives the feedback and previous Sprint Contract.
- Previously passed criteria carry forward (no regression allowed).
- New Sprint Contract is generated for failed criteria only.
Stagnation Detection
Stagnation is detected when the score improvement between consecutive iterations is below improvement_threshold for 2 or more iterations.
Tracking:
- After each iteration, record
{iteration: N, score: X}in the sprint artifact. - Calculate
delta = score[N] - score[N-1]. - If
delta < improvement_thresholdfor the last 2 iterations, flag stagnation.
When stagnation is detected, present the findings through the available user question channel with three options:
- Continue with current approach (Evaluator tries a different dimension focus)
- Adjust criteria (user provides guidance or relaxes constraints)
- Abort loop (accept current output as-is)
The escalation trigger at escalation_after iterations applies independently: if 3 iterations pass without a PASS score, escalate regardless of stagnation state.
Evaluator Leniency Prevention Mechanisms
The following 5 mechanisms prevent score inflation and must be applied on every evaluation:
Mechanism 1: Rubric Anchoring
Score descriptions for each dimension:
- 0.25: Major defects, fails most criteria
- 0.50: Partial compliance, notable issues remain
- 0.75: Solid compliance, minor issues only
- 1.00: Full compliance, no issues found
Always state which rubric level applies and why before assigning a numeric score.
Mechanism 2: Must-Pass Firewall
The following conditions cause immediate FAIL regardless of other scores:
- Copy text differs from the original
copy.jsonor BRIEF copy section - AI slop detected: purple gradient (#8B5CF6-#6D28D9) as primary visual element with generic white cards
- Mobile viewport broken at 375px width (content overflow, unreadable text)
- Any interactive element returns 404 or broken state
- An agreed accessibility criterion fails in a tool result; when Lighthouse is used and the brief sets a threshold, report its measured score
Mechanism 3: Anti-Pattern Penalty
Known anti-patterns that cap dimension score at 0.50:
- Generic icon set without brand customization (Originality capped)
- Hard-coded spacing values outside the design token scale (Design Quality capped)
- Missing
altattributes on non-decorative images (Functionality capped) - Section copy that does not match the contracted copy (Completeness capped)
Mechanism 4: Evidence Requirement
Each dimension score must cite specific evidence:
- Design Quality: Reference supplied tokens and a measured contrast ratio where available
- Originality: Describe what makes the design non-generic
- Completeness: List each BRIEF section and its implementation status
- Functionality: Reference actual test or browser observation; otherwise mark unverified
Mechanism 5: Regression Baseline
If a previous iteration passed a criterion, the current iteration must maintain that criterion. Regression from a previously passed criterion triggers an automatic score reduction in the relevant dimension.
Sprint Contract Structure
Sprint Contract document format (sprint-N.json):
{
"sprint_id": "sprint-N",
"iteration": N,
"priority_dimension": "Design Quality | Originality | Completeness | Functionality",
"acceptance_checklist": [
{
"id": "AC-01",
"criterion": "Hero headline contrast ratio >= 4.5:1",
"verification": "Check color pair with contrast calculator",
"status": "pending | passed | failed"
}
],
"test_scenarios": [
{
"id": "TS-01",
"description": "Mobile viewport renders without horizontal scroll",
"tool": "Playwright | visual inspection",
"command": "playwright test --viewport 375x667"
}
],
"pass_conditions": {
"Design Quality": 0.75,
"Originality": 0.70,
"Completeness": 0.80,
"Functionality": 0.75
},
"negotiation_history": [],
"created_at": "ISO-8601"
}
Advanced Patterns
Strict Mode
When strict_mode: true in design.yaml:
- Each contracted must-pass criterion must individually pass, as constitution §11 requires.
- An overall score cannot compensate for a failed must-pass criterion.
- Minimum 2 iterations required even if the first iteration achieves a passing weighted average.
- Strict mode is recommended for client-facing deliverables.
Independent Re-evaluation
Every 5th project triggers an independent re-evaluation:
- The same build is scored twice with independent prompts.
- If scores diverge by more than 0.10, a calibration warning is logged.
- Calibration results are stored in
sprint_contract.artifact_dir/calibration-log.json.
Playwright Integration
When a browser or Playwright is available, the Evaluator may run the relevant checks:
- Desktop screenshot (1280x720): full page
- Mobile screenshot (375x667): full page
- Interaction test: click all CTAs, verify no 404
- Accessibility scan: record the tool and its findings; an automated scan alone does not establish full WCAG conformance
When testing tools are unavailable, record code observations and mark browser behavior, accessibility and interaction criteria unverified. Do not score an unobserved criterion as passed.
Works Well With
design-brand-system: Provides design tokens that Evaluator validates in Design Quality dimensiondesign-copywriting: Copy JSON is the reference for Completeness dimension- 자체 Evaluator: GAN 루프는 매 스코어링 패스마다 본 스킬의 4-dimension scoring으로 평가합니다. MoAI harness(
moai)의sync-auditor가 함께 설치된 환경에서는 해당 agent로 평가를 보강할 수 있습니다. design-workflow: Extracted tokens (Path A) serve as the design reference baseline
Source: Absorbed from the retired v2.x design constitution per the design constitution absorption policy (Section 11 GAN Loop Contract, Section 12 Evaluator Leniency Prevention). REQ coverage: (internal provenance omitted) Version: 0.1.0
design-landing-motion — 다이나믹 랜딩 제작
moai-designer| 컨셉 → 효과 선택 → 필요한 에셋 → 구현 → 게이트
개요
밋밋한 랜딩과 기억에 남는 랜딩을 가르는 건 효과의 개수가 아니라 하나를 끝까지 완성했는지다. 이 스킬은 효과를 여러 개 뿌리는 것을 막고, 컨셉에 맞는 시그니처 효과 하나를 골라 초기 렌더·모바일·저감모션까지 완결시킨다.
두 번째 축은 비주얼이다. 사용자 자산과 브리프에 맞는 이미지를 먼저 고르고, 빈 곳에만 생성 이미지를 쓴다. 이미지 생성이 필요하지 않은 구성이라면 생성 단계를 생략한다.
하지 않는 것
- 호스팅·배포·도메인·DB·시크릿 관리 안 함 — 코드는 사용자 프로젝트 안에 만든다. 외부 호스팅 제품에 올리지 않는다.
- 이미지 생성 실행·모델 선택·크레딧 고지 — 실제 이미지 도구와 연결의 지원 범위·견적을 확인한다. 이 스킬은 필요한 자산과 사용처를 정한다.
- 디자인 토큰 정의 안 함 — 프로젝트의 디자인 시스템을 읽어 쓸 뿐 새로 만들지 않는다.
- 필요한 브리프 정보가 비면 사용 가능한 질문 채널로 확인하고, 답 없이 정할 수 없는 결정만 보류한다.
트리거 키워드
랜딩 페이지, 랜딩, 히어로, 스크롤 효과, 스크롤 스크럽, 패럴랙스, 시차, three.js, threejs, WebGL, R3F, GSAP, ScrollTrigger, 파티클, 마스크 리빌, 키네틱 타이포, 인터랙션, 다이나믹, 어워드, 모션 사이트
참조 파일
| 파일 | 언제 읽나 |
|---|---|
references/effects-catalog.md | 1단계 — 효과를 고를 때 (고르기 전에 반드시) |
references/asset-kit.md | 2단계 — 무엇을 생성할지 정할 때 |
references/motion-craft.md | 3단계 — DOM·CSS 모션을 짤 때 |
references/threejs-patterns.md | 3단계 — WebGL·3D가 들어갈 때 |
references/quality-gate.md | 4단계 — 끝내기 전 |
워크플로우
0단계 — 환경 판정과 브리프
환경 판정 (먼저). 프로젝트를 감지해 구현 문법을 정한다. 추측하지 않고 파일로 확인한다.
| 감지 | 스택 |
|---|---|
package.json에 react/next | React 경로 — 기존 의존성을 확인한 뒤 필요한 모션 도구를 선택 |
| Hugo·Astro·Eleventy·순수 HTML | 정적 경로 — 기존 CSS·JavaScript를 먼저 사용하고 필요한 경우에만 라이브러리 추가 |
| 파일을 볼 수 없는 채팅 요청 | 구현 환경을 확인하거나 플랫폼에 중립적인 제작 지시로 범위를 정함 |
컨셉 스파인. 이 사이트가 말하려는 한 가지를 한 문장으로 적는다("정밀함", "상승", "축적" 등). 효과 선택은 이 문장에 봉사해야 한다. 스파인 없이 효과부터 고르면 예쁘지만 겉도는 페이지가 나온다.
디자인 시스템 읽기. 팔레트·타이포·형태 언어·브랜드 금지 사항을 프로젝트에서 읽는다(design-brand-visual과 동일한 우선순위). 근거가 없으면 지어내지 말고 "근거 없음"으로 표시한다.
1단계 — 시그니처 효과 하나 선택
references/effects-catalog.md에서 하나만 고른다. 카탈로그 밖에서 즉흥적으로 고르지 않는다.
선택 규칙:
- 컨셉 스파인을 갚는 효과를 고르고, 왜 그 짝인지 한 문장을 브리프에 적는다.
- 같은 브랜드의 직전 빌드가 있다면 반복이 의도적인지 확인한다. 변화가 필요해도 브랜드 팔레트·CTA를 임의로 바꾸지 않는다.
- 모든 효과는 초기 렌더 완결과 저감모션 대체가 가능해야 한다. 둘 중 하나라도 불가능하면 그 효과는 탈락이다.
- 곁들이는 리빌 애니메이션은 허용하되, "이건 무엇을 전달하는가"에 답하지 못하면 뺀다.
2단계 — 필요한 에셋 준비
references/asset-kit.md에서 필요한 항목만 고른다. 확인된 브랜드 팔레트가 있으면 프롬프트에 반영한다. ChatGPT Work에서 모델을 지정하지 않은 이미지 요청은 현재 대화의 이미지 생성 도구를 사용한다. Images 2.5 요청은 앱이 모델 식별 정보를 노출하는지 확인하고, Flare·Sunburst API 모델 ID 지정 요청은 별도 API 경로의 사용 가능 여부를 확인한다. 사용자가 Higgsfield를 지정했거나 영상·3D 등 그 경로가 필요한 항목은 이 플러그인의 공식 Higgsfield 연결에서 지원 도구·모델·견적을 확인한다. 별도 설치된 moai-media:media-higgsfield-* 스킬의 상세 절차도 사용할 수 있다. Claude Cowork에서는 실제 연결된 도구를 확인한다. 생성 전에 비용·승인 조건을 따른다.
사용자 자산이 언제나 이긴다. 로고·제품 사진·팀 사진·폰트를 이미 갖고 있으면 그대로 쓴다. 생성은 빈 곳만 채운다.
이미지 도구가 없으면 사용 가능한 기존 자산으로 진행하고, 생성이 필요한 슬롯은 프롬프트와 함께 미완료로 표시한다. Higgsfield를 선택한 경우에만 그 웹 경로를 안내한다.
3단계 — 구현
판정된 스택의 문법으로 만든다. 모션 규범은 references/motion-craft.md, WebGL은 references/threejs-patterns.md.
순서가 중요하다: 정적 레이아웃을 먼저 완성하고 그 위에 모션을 얹는다. 모션부터 짜면 초기 렌더가 비어 있는 페이지가 나오고, 이건 게이트에서 걸린다.
4단계 — 게이트
references/quality-gate.md의 항목을 기계적으로 점검한다. 통과 못 하면 끝난 게 아니다.
하드 규칙
- 시그니처 효과는 페이지당 하나. 두 개 이상은 서로를 죽인다.
- 초기 렌더가 완결돼야 한다. JS가 돌기 전 스크린샷에 이미 완성된 히어로가 보여야 한다.
prefers-reduced-motion대체는 모든 애니메이션 요소에 필수. 저감모션에서는 핀 없이 최종 상태를 정적으로 보여준다.- 핫패스에서는
transform과opacity만 애니메이션한다. 레이아웃 속성(width·top·margin)을 움직이지 않는다. - 모바일 열화를 미리 선언한다. 커서 효과는 스크롤 대응으로, 긴 핀은 짧게. "데스크톱만 됨"은 열화가 아니라 방치다.
- 이미지 안에 본문 텍스트를 굽지 않는다. 타이포는 HTML로 얹는다.
- 가짜 제품·인물·후기로 빈 곳을 채우지 않는다. 생성이 불가하면 필요한 슬롯을 밝힌다. 브리프에 맞는 라이선스 자산이나 CSS 표현은 사용할 수 있다.
- 모션을 제대로 끝낼 수 없으면 정적으로 낸다. 반쯤 붙은 ScrollTrigger보다 깔끔한 정적 페이지가 낫다.
출력 형식
## 랜딩 제작 결과
- 컨셉 스파인: [한 문장]
- 판정 환경: [React | 정적] — 근거: [감지한 파일]
- 시그니처 효과: [카탈로그 id] — 스파인과의 연결: [한 문장]
- 참조한 디자인 시스템: [파일 경로] (없으면 "근거 없음")
- 생성 에셋: [항목별 목록과 실제 사용한 도구]
- 모바일 열화: [무엇이 어떻게 바뀌는지]
- 저감모션 대체: [정적 최종 상태 설명]
- 게이트: [통과 | 걸린 항목과 조치]
주의사항
- 효과를 고르기 전에 카탈로그를 읽는다. 즉흥 선택은 대체로 남들과 같은 결과를 낸다.
- 의존성을 추가하기 전에 프로젝트가 그걸 감당하는지 확인한다(번들 크기·빌드 설정·SSR 호환).
- WebGL은 실패할 수 있다(구형 기기·드라이버). 폴백을 반드시 둔다 —
references/threejs-patterns.md. - 접근성은 저감모션만이 아니다. 키보드 포커스·대비·스크린리더 흐름을 모션이 망가뜨리지 않는지 본다.
- 생성 비용은 에셋 수에 비례한다. 킷 구성을 확정하기 전에 사용자에게 알린다.
관련 스킬
| 스킬 | 시점 |
|---|---|
moai-designer:design-brand-visual | 대안: 이미지 한 장만 필요할 때 |
moai-designer:design-brand-system | 선행: 팔레트·타이포 기준 수립 |
moai-designer:design-tokens-transformer | 선행: 토큰을 CSS로 |
moai-designer:design-slop-check | 후속: 카피 AI 슬롭 점검 |
moai-media:media-codex-image | 선택: 별도 설치된 경우 ChatGPT 이미지 작업 상세 절차 |
moai-media:media-higgsfield-image | 선택: 별도 설치된 경우 Higgsfield 이미지 생성 절차 |
moai-media:media-higgsfield-video | 선택: 별도 설치된 경우 영상 생성 절차 |
moai-media:media-higgsfield-assets | 선택: 별도 설치된 경우 3D·업스케일·누끼 절차 |
moai-media:media-higgsfield-identity | 선택: 별도 설치된 경우 인물·마스코트 일관성 절차 |
출처
- Higgsfield Skills (공식 agent 문서) —
higgsfield-websitesv0.12.0 (MIT). 효과 카탈로그·모션 규범·에셋 킷 구성·안티슬롭 카피 규칙·게이트 항목의 착안점. - 원본은 Cloudflare Worker 호스팅 파이프라인과 결합돼 있고
higgsfield websiteCLI를 요구한다. 이 스킬은 디자인·모션·에셋 지식만 가져오고 호스팅 계층은 가져오지 않는다. 따라서 원본과 동작이 같지 않다. - 이미지 생성 실행·모델·비용: 현재 대화의 이미지 도구 또는 이 플러그인에 연결된 공식 Higgsfield 도구의 라이브 결과.
design-logo — 브랜드 정합 로고 생성
moai-designer| 브랜드 컨텍스트 → 로고 타입 → 제약 → 생성 → 정합 검증
개요
로고는 브랜드의 가장 작고 가장 오래 쓰이는 자산이다. 히어로 이미지와 달리 16px 파비콘에서 빌보드까지 모든 크기에서 읽혀야 하고, 컬러·흑백·단색으로 변형되어야 한다. 그래서 로고는 래스터 비주얼이 아니라 벡터/심볼로 접근한다.
이 스킬은 생성 전에 사용자가 제공한 브랜드 컨텍스트(토큰·보이스 포함)를 읽고 로고 타입을 선택한 뒤, 그 값을 프롬프트 제약으로 바꾸어 생성으로 넘긴다.
하지 않는 것
- 생성 모델·비용 고지 — 실제 연결에서 모델·견적·승인 조건을 확인한다. 모델 이름만 보고 벡터 출력을 보장하지 않는다.
- 디자인 토큰 정의 안 함 — 토큰의 진실원은 프로젝트의 디자인 시스템이다. 이 스킬은 읽어서 쓸 뿐 새로 만들지 않는다.
- 필수 브랜드 정보가 없으면 사용 가능한 질문 채널로 확인하고, 답이 없으면 확인 가능한 범위의 컨셉만 제시한다.
트리거 키워드
로고, 브랜드 마크, 워드마크, 레터마크, 모노그램, 심볼, 로고타입, 픽토그램, 앱 아이콘, 파비콘, 로고 컨셉, 로고 아이디어, 로고 리디자인, 엠블럼, 콤비네이션 마크, 애브스트랙트 마크
참조 파일
| 파일 | 언제 |
|---|---|
references/logo-types.md | 로고 타입 7종 분류와 "어떤 타입을 고를까" 선택 가이드 |
references/logo-craft.md | 로고 프롬프트 구성 · Recraft 사용 시 구조적 지침 · 텍스트 점검 |
references/logo-principles.md | 로고 5원칙 · 스케일러빌리티 · 변형 시스템 · 정합 검증 체크리스트 |
워크플로우
1단계 — 브랜드 컨텍스트 읽기
생성 프롬프트를 쓰기 전에 프로젝트의 진실원을 찾아 읽는다. 우선순위:
- 디자인 시스템 핸드오프 디렉터리(토큰 CSS·화면 설계 원본·브랜드 규칙 문서)
DESIGN.md또는 그에 준하는 브랜드 아이덴티티 문서- 토큰 파일(DTCG / CSS 변수 / shadcn 설정)
- 브랜드 보이스 문서(보이스·금지 사항·마스코트 사용 규칙)
데스크톱 채팅에서는 사용자가 메시지나 첨부로 준 브랜드 자료도 읽는다. 없으면 없는 대로 진행하되, 기존 브랜드 색인 것처럼 지어내지 않는다. 새 브랜드를 만드는 요청이라면 팔레트 후보를 제안하고 근거와 미확정 상태를 명시한다.
2단계 — 로고 타입 선택
사용자 요청과 브랜드 성격으로 로고 타입을 정한다 (references/logo-types.md의 선택 가이드 참조):
| 타입 | 어울릴 때 |
|---|---|
| 워드마크 | 이름이 짧·인지도가 있거나 이름 자체가 차별점 |
| 레터마크 | 이름이 길거나 두문어가 이미 익숙 |
| 심볼/픽토그램 | 보편적 형상이 브랜드와 연결될 때 |
| 애브스트랙트 | 구체 형상 없이 독자적 기하학적 마크 |
| 마스코트 | 캐릭터가 브랜드 인격 |
| 콤비네이션 | 심볼+워드마크 둘 다 필요 |
| 엠블럼 | 전통·공식·기관 이미지 |
사용자가 타입을 명시하지 않았고 브랜드 맥락만으로 정해지지 않으면 2~3개 후보와 선택 이유를 제시한다. 생성 개수와 지원 파라미터는 사용 가능한 경로에서 확인한다.
3단계 — 제약으로 변환
읽은 브랜드 컨텍스트를 생성 경로에 맞는 프롬프트 제약으로 바꾼다. 이 변환이 이 스킬의 핵심 산출이다.
| 브랜드 항목 | 프롬프트 제약 |
|---|---|
| 팔레트 | 정확한 색을 hex로 명시, 그 밖의 색조 금지 |
| 타이포 | 워드마크/레터마크면 폰트 성격(serif/sans/script/mono) |
| 형태 언어 | 각진/둥근, 기하학적/유기적 |
| 무드 | 차분한/대담한/따뜻한/장난기 |
| 금지 규칙 | 부정이 아니라 긍정 서술로 변환(→ 코어 R1) |
금지 규칙 변환 주의: "그라디언트 쓰지 마"를 그대로 넣으면 모델이 그라디언트에 주목한다. "flat solid fills only"처럼 원하는 것을 서술한다.
로고는 텍스트가 핵심인 경우가 많으니 R3(리터럴 텍스트는 따옴표 + 폰트 지정) 가 특히 중요하다 — 워드마크 "GLOW"는 "the word 'GLOW' in a geometric sans-serif" 처럼.
4단계 — 프롬프트 조립
선택한 로고 타입과 제약으로 프롬프트를 조립한다 (references/logo-craft.md). Recraft 모델을 실제로 선택할 수 있을 때는 그 모델의 구조적 프롬프트 지침을 적용한다.
- global-to-local 구조로 핵심 컨셉 → 형태 실루엣 → 레이아웃 → 컬러 → 무드 순으로 쌓는다.
- 디자이너 용어를 쓴다:
contained mark,horizontal lockup,lettermark,negative space cutout,monoline style,serif letterforms. 일상어("예쁜 로고")는 의도를 흐린다. - texture/material 언어를 피한다 — 벡터 로고는 "no texture, no gradients, consistent stroke"로 서술한다.
- 컬러는 프롬프트 + hex 병기 — "green and charcoal palette, deep green (#1b6e4a) with neutral charcoal (#2b2b2b)".
탐색 단계에서는 요청 범위·비용과 실제 지원 파라미터에 맞춰 후보 수를 정한다.
5단계 — 생성
ChatGPT Work의 컨셉 이미지는 현재 대화의 이미지 생성 도구를 기본으로 한다. 사용자가 Higgsfield를 지정했다면 이 플러그인의 공식 Higgsfield 연결에서 실제 모델·출력 형식·크레딧 견적을 확인한다. 생성 전에 비용과 승인 조건을 확인한다. 별도로 moai-media를 설치했다면 해당 이미지 스킬의 상세 절차를 사용할 수 있다. 벡터 마스터가 목적이라면 해당 경로에서 SVG가 실제로 제공되는지 확인하고, 제공되지 않으면 컨셉 이미지로만 표기한다.
이미지 도구가 없으면 프롬프트와 검토 기준을 제공하고 생성 상태를 미완료로 기록한다. Higgsfield 웹 안내는 사용자가 그 경로를 선택했을 때만 한다.
6단계 — 정합 검증
받은 로고를 로고 특유의 기준으로 점검한다 (references/logo-principles.md):
- 스케일러빌리티: 작게 축소해도(파비콘 16px) 형태가 살아있는가
- 단순성: 불필요한 디테일·텍스처가 없는가
- 변형 내성: 실루엣(단색)으로 변형해도 인식되는가
- 팔레트 정합: 브랜드 팔레트를 벗어나는가
- 텍스트: 워드마크/레터마크라면 철자·레터링이 정확한가
어긋나면 제약을 강화해 재생성한다. 어긋난 로고를 "대체로 맞다"고 넘기지 않는다 — 로고는 근사치를 허용하지 않는 종류의 기준이다.
출력 형식
## 로고 결과
- 로고 타입: [워드마크 | 심볼 | 콤비네이션 | ...] · 컨셉 수: [N]
- 참조한 브랜드 컨텍스트: [읽은 파일 경로] (없으면 "근거 없음" 명시)
- 적용 제약: [팔레트 hex / 타이포 / 형태 언어 / 무드]
- 생성 경로: [네이티브 이미지 | Higgsfield | 프롬프트만]
- 결과 형식: [실제 받은 파일 형식·위치 | 미완료]
- 정합 점검: [통과 | 어긋난 항목과 조치]
- 권장 변형 산출: [컬러 / 흑백 / 단색 실루엣 / 앱 아이콘]
주의사항
- 로고는 벡터/심볼로 접근한다 — texture, material, photographic, "realistic" 언어를 쓰지 않는다.
- 토큰 근거 없이 색·폰트를 지어내지 않는다. 근거가 없으면 없다고 적는다.
- 금지 사항은 긍정 서술로 바꿔 넣는다(R1).
- 워드마크/레터마크 텍스트는 따옴표로 감싸고 폰트를 함께 지정한다(R3).
- 로고 안에 슬로건·부가 텍스트를 과도하게 넣지 않는다 — 작아지면 깨진다.
- 생성 비용·모델은 추정하지 않는다 — 실제 도구의 모델·견적과 사전 고지 절차를 확인한다.
- 파일 형식을 확인한다. 실제 SVG 벡터 결과라면 경로·편집 가능성·텍스트 윤곽을 점검한다. PNG/JPG 결과는 컨셉 이미지이며 최종 벡터 마스터가 필요하면 별도 제작·벡터화가 필요하다.
관련 스킬
| 스킬 | 시점 |
|---|---|
moai-media:media-codex-image | 선택: 별도 설치된 경우 ChatGPT 이미지 작업 상세 절차 |
moai-media:media-higgsfield-core | 선택: 별도 설치된 경우 Higgsfield 비용·모델 확인 절차 |
moai-media:media-higgsfield-image | 선택: 별도 설치된 경우 Recraft 프롬프트 지침 |
moai-designer:design-brand-visual | 형제: 히어로·OG·목업 비주얼 |
moai-designer:design-brand-system | 선행: 브랜드 디자인 시스템 정의 |
moai-designer:design-slop-check | 후속: AI 슬롭 점검 |
출처
- Higgsfield MCP — 생성 실행 경로.
- Recraft — 벡터/로고/아이콘 프롬프트 크래프트(1차). global-to-local 구조, 디자이너 용어 사전.
- Higgsfield Skills (공식 agent 문서) (MIT) — 로고 용도 구분 참고.
- 생성 계약·비용·모델 선택: 현재 연결된 공식 Higgsfield 도구의 라이브 결과.
- 로고 타입 분류와 5원칙의 출처는
references/logo-types.md,references/logo-principles.md각 파일에 명시.
design-prompt-builder — UX 작업 프롬프트
사용자의 실제 목표, 대상 화면, 브랜드 자료와 제약을 먼저 확인한다. 직함이나 유명 회사 경력을 꾸며 전문가인 척하지 않는다. 패턴은 작업을 정리하는 참고 틀이며, 하나의 요청에 여러 관점이 필요하면 결합한다.
작업 유형
| 요청 | 프롬프트에 담을 핵심 |
|---|---|
| 정보 구조 | 콘텐츠 목록, 이용자의 주요 과업, 탐색 경로 |
| 리서치 | 확인할 가설, 대상자, 질문·관찰 방법 |
| 디자인 시스템 | 기존 브랜드 자산, 필요한 토큰·컴포넌트, 적용 환경 |
| 마이크로카피 | 화면 맥락, 사용자 행동, 브랜드 말투 |
| 온보딩 | 첫 과업, 현재 장애, 성공 판단 기준 |
| 사용성 감사 | 실제 화면·흐름, 관찰 가능한 문제, 개선 우선순위 |
| 대시보드 | 사용자의 결정, 지표 정의·출처, 데이터 상태 |
| 접근성 | 대상 플랫폼, 적용 기준, 검사 가능한 화면·상태 |
| 폼 | 필요한 정보, 오류·회복 흐름, 적용되는 개인정보 조건 |
| 프로토타입 테스트 | 검증할 흐름, 참가자, 과업과 관찰 기준 |
셰이더·3D·오디오·애니메이션 요청에는 해당 매체의 성능·기기·저감모션 제약을 추가한다. 프레임률이나 지연 시간은 근거 없이 보장하지 않고 실제 구현에서 측정한다.
진행
- 사용자가 준 요청과 첨부 자료에서 목표·대상·브랜드·제약·원하는 산출물을 추출한다.
- 빠진 정보가 결과를 바꾸면 사용 가능한 질문 채널로 짧게 확인한다. 없어도 진행 가능한 정보는
[확인 필요]로 남긴다. 매출, 전환율, 이탈률, 사용성 테스트 결과를 만들어 넣지 않는다. - 필요한 작업 유형을 고른다. 모든 디자인 시스템에 다크 모드나 전체 컴포넌트를 강제하지 않는다. 화면에 필요한 범위를 정한다.
- 다음 형식으로 바로 쓸 수 있는 프롬프트를 만든다.
목표: [사용자가 이루려는 일]
대상: [사용자와 화면·서비스]
자료: [제공된 브랜드 파일·화면·데이터·URL]
제약: [플랫폼·접근성 기준·기술·일정 중 실제로 확인한 것]
작업: [요청에 필요한 디자인·분석 단계]
산출물: [사용자가 요청한 결과 형식과 범위]
검증: [구현 후 또는 실제 사용자와 확인할 항목]
미확인: [결정에 필요한 질문]
- Claude Design을 지정한 사용자에게는 현재 사용 가능한 Claude Design 채팅이나 핸드오프 경로에서 이 프롬프트와 자료를 전달하도록 안내한다. ChatGPT Work에서 계속 작업할 때는 같은 프롬프트를 현재 대화에 적용한다. 외부 서비스에 이미 업로드·테스트·내보내기를 했다고 주장하지 않는다.
접근성 요청
적용 지역·제품·플랫폼과 요구 기준을 먼저 확인한다. 웹이라면 WCAG 2.2의 관련 성공 기준을 참고할 수 있다. 색 대비 계산, 키보드·스크린리더 점검, 실제 화면 테스트는 각각 수행한 경우에만 결과를 적는다. 프롬프트만 작성한 단계에서 준수나 인증을 선언하지 않는다.
카피와 사용자 데이터
실제 제품 문구, 가격, 성과, 후기와 법적 동의 내용은 사용자 자료에서 가져온다. 없는 값은 예시로 표시하거나 확인 요청으로 남긴다. 한국어 문구에 영어 단어 수 제한을 기계적으로 적용하지 않는다. 브랜드가 사용하는 폰트나 색을 근거 없이 금지하지 않는다.
출력
- 선택한 작업 유형과 선택 이유
- 복사해 사용할 프롬프트
- 미확인 정보와 적용 전 확인할 항목
관련 스킬: design-brief(브리프 정리), design-gui-guide(컴포넌트 사용성), design-slop-check(결과 카피 검토).
design-slop-check — 디자인 카피 검수
사용자가 제공한 카피를 원문 그대로 읽고, 화면 위치·독자·브랜드 말투·제품 사실을 확인한다. 자료가 없으면 판단 범위를 적는다. 패턴에 맞는 문구는 검토 후보이며, 한 표현만으로 AI 작성 여부를 확정하지 않는다.
검수 순서
-
실제 텍스트와 사용처를 수집한다. 파일·URL은 현재 세션에서 열 수 있을 때만 읽었다고 말한다. 추출하지 못한 PDF·이미지 속 문구는 미검토로 남긴다.
-
아래 신호를 문맥에 맞춰 살핀다.
신호 예시 확인할 점 추상적인 자기 평가 혁신적인, 차세대, world-class 무엇이 실제로 달라지는지 설명하는가 누구에게나 붙는 약속 손쉽게, seamlessly, effortlessly 어떤 과업이 어떻게 줄어드는지 근거가 있는가 의미 없는 나열 빠르게·쉽게·정확하게 각 단어가 구체적인 기능을 가리키는가 틀처럼 반복되는 구조 “A에서 B로”, “No more X. Just Y.” 브랜드가 의도적으로 쓰는 표현인가 확인되지 않은 사실 고객 수, 절약 시간, 무료 체험, 후기 사용자 자료나 공개 근거로 확인됐는가 -
수치·가격·성과·고객 사례는 출처와 적용 기간을 확인한다. 확인되지 않으면 지우거나
[확인 필요]로 남긴다. 더 구체적으로 보이게 하려고 숫자를 만들어 넣지 않는다. -
원문이 자연스럽고 정확하면 그대로 둔다. 불필요한 수정을 건수로 채우지 않는다. 문장이 어색하면 뜻과 조사·어순을 살려 1~2개 대안을 쓴다.
-
한국어 전반의 윤문이 필요하고 해당 스킬이 설치돼 있으면
moai-writer:korean-humanize로 후속 검토한다. 그 스킬이 없거나 실행하지 않았다면 후속 게이트가 통과했다고 말하지 않는다.
판정 경계
표현 검토: 상투적일 수 있으나 제품·브랜드 맥락이 필요하다.근거 확인: 사실 주장에 출처가 없다. 출처가 없다는 것은 거짓이라는 판정이 아니다.수정 권고: 문구가 실제 사용처에서 뜻을 흐리거나, 제공된 브랜드 말투와 충돌한다.유지: 문구가 목적에 맞고 바꿀 이유가 없다.미검토: 원문·화면·필요한 자료에 접근하지 못했다.
브랜드가 의도한 용어, 고유한 제목, 완결된 명사구를 자동으로 금지하지 않는다. 대시, 콜론, 짧은 문장, “A에서 B로” 같은 구조도 단독으로 AI 작성의 증거가 아니다.
출력
| 위치 | 원문 | 판정 | 근거 | 제안 |
|---|---|---|---|---|
| [화면·섹션] | [원문] | [위 판정] | [실제 문맥·출처] | [유지 또는 수정안] |
끝에 확인하지 못한 자료와 후속 검토가 필요한 주장만 적는다. 사용자가 수정 적용을 요청하면 승인된 문구를 해당 결과물에 반영하고 다시 읽어 의미가 유지됐는지 확인한다.
관련 스킬: design-copywriting(카피 초안), moai-writer:korean-humanize(한국어 윤문), moai-coworker:ai-slop-reviewer(일반 텍스트 검토).
design-sync-upload — 디자인 시스템 자료 전달
이 스킬은 사용자가 고른 디자인 시스템 자료를 정리하고 실제 전달 상태를 보고한다. 파일을 준비한 것과 Claude 계정에 업로드한 것, 디자인 시스템으로 분석한 것, 팀에 게시한 것은 서로 다른 단계다.
1. 자료와 권한 확인
- 사용자가 제공한 브랜드 가이드·코드베이스·완성 화면·토큰·로고 중 필요한 것만 목록으로 만든다.
DESIGN.md나 DTCG·CSS·shadcn 세 층은 있을 때만 포함한다. 없는 파일이나 로고 변형을 만들지 않는다. - 각 파일의 위치·크기·형식을 확인한다. 고객 자료·내부 수치·폰트 파일·저작권 자산은 업로드 범위와 사용권을 확인한다. 필요한 부분만 복사하거나 민감 정보를 가린 사본을 만들되 원본은 보존한다.
- 사용자에게 대상 Claude 계정·조직과 전달 파일 목록을 보여준다. 조직 공용 시스템 덮어쓰기·삭제·게시가 필요한 경우 실제 대상과 변경 내용을 확인하고 해당 동의를 받는다.
2. 현재 환경에 맞는 경로
| 현재 환경 | 진행 |
|---|---|
| Claude Cowork 또는 Claude 대화 | 사용자가 선택한 파일을 현재 대화에 첨부할 수 있으면 첨부하고, 디자인 시스템 생성·수정 요청을 전달한다. 앱이 제공하는 디자인 시스템 화면에서 실제 결과를 확인한다. |
| ChatGPT Work | 파일 묶음과 짧은 UPLOAD-GUIDE.md를 준비한다. 사용자가 Claude 앱의 디자인 시스템 화면에서 직접 첨부한다. ChatGPT 안에서 Claude 업로드가 끝난 것으로 보고하지 않는다. |
| Claude Code | 사용자가 해당 환경을 쓰는 경우 공식 /design-sync 경로를 안내한다. 이 명령을 데스크톱 앱의 일반 슬래시 명령처럼 안내하지 않는다. |
| DesignSync 도구가 현재 세션에 실제로 노출됨 | 도구의 현재 스키마·인증·대상 권한을 먼저 읽는다. 확인된 읽기 메서드로 대상과 기존 파일을 살핀 뒤 쓰기 계획을 만든다. 예전 finalize_plan·write_files·register_assets 계약을 확인 없이 호출하지 않는다. |
도구가 없거나 인증되지 않았으면 파일 준비와 UI 안내까지 진행한다. 인증 실패를 업로드 성공으로 바꾸지 않는다. 업로드 UI의 이름과 클릭 경로가 계정·제품 버전에 따라 다르면 현재 보이는 화면을 따른다.
3. 파일 묶음
사용자가 접근할 수 있는 프로젝트 안에 design-sync-staging/ 같은 상대경로 폴더를 만든다. 승인된 파일만 복사하고 다음 안내를 함께 둔다. 디렉터리를 만들 수 없는 대화에서는 파일 목록과 업로드 순서를 채팅에 적는다.
# 디자인 시스템 자료 전달 안내
- 대상 계정·조직: [확인된 값]
- 자료: [실제 준비한 파일과 용도]
- 제외한 자료: [민감 정보·사용권 미확인 등]
- 전달 경로: Claude Design의 현재 디자인 시스템 화면에서 파일 첨부
- 전달 후 확인: 추출된 색·서체·컴포넌트가 원본과 맞는지 실제 결과로 점검
- 팀에 게시: 조직 권한과 결과 검토 후 별도 결정
Claude의 디자인 시스템 설정 안내에 따르면 대화의 업로드 파일·연결 앱·Figma·코드베이스를 자료로 사용할 수 있고, 별도 Claude Design 화면에서는 조직 설정에서 자산을 올릴 수 있다. 완성된 화면이나 덱처럼 실제 사용 예를 함께 주면 추출 결과를 검토하기 쉽다. 파일을 업로드했다고 색·컴포넌트 추출이 정확해졌다고 단정하지 않는다.
4. 자동 쓰기 도구가 실제로 있을 때
- 기존 파일을 덮어쓰거나 삭제한다면 대상 프로젝트·경로·신규/덮어쓰기/삭제 목록·현재 내용을 잃을 수 있는 범위를 사용자에게 보여준다. 삭제는 쓰기와 따로 선택할 수 있게 한다.
- 현재 스키마가 제공하는 계획·승인 절차를 따른다. 파일 해시를 승인 직전과 호출 직전에 비교할 수 있으면 비교한다. 도구가 파일을 다시 읽는다면 그 사이 변경을 완전히 막았다고 보증하지 않는다.
- 쓰기 응답이 모호하면 원격 상태를 다시 읽어 어떤 파일이 기록됐는지 확인한다. 확인 없이 같은 쓰기를 재시도하지 않는다. 일부만 올라갔으면 부분 성공과 남은 파일을 구분한다.
- 게시나 조직 기본값 변경은 업로드와 별개로 다룬다. 화면 검토와 해당 권한·사용자 의사가 확인된 경우에만 실행한다.
5. 보고
대상: [계정·조직·디자인 시스템]
준비: [실제 파일 목록]
전달: [실제 업로드 성공 | 일부 성공 | UI 전달 대기 | 미실행]
추출 검토: [실제로 확인한 색·서체·컴포넌트 | 미검증]
게시: [실제 게시 확인 | 미게시 | 미검증]
남은 일: [사용자가 수행할 단계 또는 재검토 항목]
관련 스킬: design-system-prep(자료 정리), design-tokens-transformer(있는 토큰 변환), design-handoff-reader(Claude Design 결과 읽기).
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 컴포넌트 참조 마크업
디자인 시스템 자료 준비
사용자의 실제 브랜드 자산을 우선한다. 결과물은 사람이 검토할 수 있는 DESIGN.md와 전달 안내다. 문서를 만들었다고 Claude Design에 등록되거나 게시된 것은 아니다. 실제 등록 절차는 moai-designer:design-sync-upload를 따른다.
입력과 출처
- 사용자가 제공한 스타일 가이드, 디자인 파일, 토큰, UI 코드, 로고와 운영 화면을 확인한다. 파일과 URL은 실제로 열어 보고, 읽을 수 없으면 그 항목을 미확인으로 기록한다.
- 각 결정에 자산 경로 또는 URL과 관찰 위치를 남긴다. 스크린샷에서 눈으로 짐작한 색과 글꼴은 추정치로 표시하며, CSS나 디자인 파일의 원본 값과 구분한다.
- 서로 다른 자산이 충돌하면 현재 적용 중인 화면과 사용자 지정 기준을 확인한다. 우선순위를 추측하지 않는다. 브랜드 보이스와 금지 규칙도 실제 자료나 사용자의 명시적 결정에서만 가져온다.
- 사용자가 자산 없이 특정 브랜드의 분위기만 요청하면
design-system-library를 영감 자료로 열람할 수 있다. 이 라이브러리의 다수 문서는 현재 공식 출처 URL이 없으므로, 그 값을 해당 브랜드의 공식·현행 토큰이나 재사용 허가로 단정하지 않는다. 사용자 브랜드에 그대로 이식하기 전에 색 대비와 사용권을 별도로 확인한다. - 타사 사이트와 로고는 참고 자료로만 다룬다. 자사 자산인 것처럼 문서에 포함하거나 업로드하지 않는다.
필요한 정보가 없으면 확보 가능한 자료부터 정리하고 해당 항목을 미확정으로 둔다. 질문 채널이 있으면 결정에 필요한 내용만 묻는다. 채널이 없으면 확인이 필요한 결정을 보고한다.
산출물
사용자가 지정한 위치에 DESIGN.md를 작성한다. 지정하지 않았다면 작업 폴더의 design-system-prep/를 쓴다. 다음 항목 중 자료로 확인된 것만 담는다.
| 항목 | 기록할 내용 |
|---|---|
| 출처 목록 | 확인한 파일·URL, 관찰 위치, 확인 날짜, 추정 여부 |
| 브랜드 표현 | 문체·금지 표현·로고 사용 규칙의 실제 근거 |
| 색 | 원본 색상 값, 사용 맥락, 배경과 글자색 조합 |
| 글꼴 | 글꼴 이름·굵기·크기와 라이선스 확인 상태 |
| 간격·모서리·동작 | 자산에서 확인한 값과 적용 위치 |
| 구성요소 | 실제 UI나 코드에서 확인한 패턴 |
| 미확정 사항 | 충돌한 값, 부족한 자료, 사용자 결정이 필요한 항목 |
고정된 섹션 수나 토큰 계층을 강요하지 않는다. 없는 색 단계, 다크 모드, 그라디언트, 그림자, 마스코트, 로고 변형, 카피 규칙을 자동 생성하지 않는다. 새 디자인 제안이 필요하면 관찰한 브랜드 규칙과 분리해 제안이라고 표시한다. 토큰 변환이 실제로 필요할 때만 moai-designer:design-tokens-transformer를 사용한다.
색 대비는 최종 배경과 글자색 조합에서 계산한다. WCAG AA 일반 텍스트 기준 4.5:1, 큰 텍스트 3:1을 확인하고 측정 결과를 함께 적는다. 색 이름이나 단독 HEX 값만으로 접근성을 보증하지 않는다.
UPLOAD-GUIDE.md에는 전달할 파일 목록, 각 파일의 목적, 민감 정보와 사용권 확인 결과, 아직 미확정인 항목을 적는다. 실제 UI에서 허용하는 자료 형태와 현재 화면을 확인하고 순서를 안내한다. 특정 업로드 순서, 분석 시간, 게시 토글의 존재를 보편적인 절차로 가정하지 않는다. Claude Design에서 직접 가져오기가 가능한 소스는 그 UI를 우선 안내한다. ChatGPT Work에서는 검토 가능한 자료를 준비하고 사용자가 Claude Design에서 이어서 적용하도록 안내한다.
검증과 보고
- 작성한 파일을 다시 읽어 자산 경로, 색 값, 미확정 표시가 원본과 맞는지 확인한다.
- 링크가 열리지 않았거나 디자인 파일을 직접 파싱하지 못했다면 그 한계를 명시한다.
- 결과 상태를
자료 준비,Claude Design에 등록,결과 테스트,게시로 구분한다. 실제 관찰한 단계만 완료로 보고한다. - 원본 자산은 유지한다. 외부 업로드 전 고객 정보와 폰트·이미지 사용권을 확인한다.
관련 스킬
moai-designer:design-system-library: 자산이 없을 때의 영감 자료moai-designer:design-tokens-transformer: 확인된 토큰의 형식 변환moai-designer:design-sync-upload: Claude Design 전달과 적용
디자인 토큰 변환
사용자의 원본 토큰과 소비 프로젝트를 먼저 확인한다. 원본이 DTCG라면 그 파일을 기준으로 파생 결과를 만든다. CSS만 있으면 역추출할 수 있지만, 값만으로 브랜드 출처나 의도를 복원했다고 주장하지 않는다. 3계층 파일, Tailwind, shadcn, 다크 모드는 해당 프로젝트에서 실제 사용하는 경우에만 만든다.
입력 확인
- 원본 파일을 읽고 파일 경로·버전·토큰 이름·별칭·모드를 기록한다.
DESIGN.md의 설명만으로 색 값을 새로 만들지 않는다. - 대상 프로젝트의 CSS, Tailwind 버전, shadcn 사용 여부와 기존 변수 이름을 확인한다. 이미 있는 변수 체계를 보존한다.
$type과$value는 DTCG Format Module 2025.10에 맞춰 검증한다. 색은colorSpace·components를 가진 객체, dimension은 숫자와 단위의 객체, shadow는 그림자 객체 또는 그 배열, gradient는 색·위치를 가진 스톱 배열이다. CSS의#hex,linear-gradient(...),box-shadow문자열을 그대로 표준 DTCG 값이라고 표기하지 않는다.- 기존 파일이 다른 토큰 형식을 쓰면 그 형식을 명시하고 변환 가능한 값과 수동 결정이 필요한 값을 나눈다.
$description은 선택 사항이며, 값의 출처를 자동 증명하지 않는다. 실제 확인한 출처는 별도 기록한다.
변환
- 원본 경로 → 출력 변수 이름의 대응표를 먼저 작성한다. 이름 충돌, 별칭 순환, 미지원 타입은 출력 전에 보고한다.
- DTCG 값에서 CSS 값을 만들 때 색 공간 변환·단위·알파·그라디언트 종류처럼 표현이 달라지는 항목은 변환 기준과 오차를 적는다. CSS에서 역추출할 때 잃은 정보는
복원 불가로 표시한다. - 일반 CSS 소비처에는 필요한 custom property만 만든다. Tailwind v4의
@theme은 유틸리티가 필요한 변수에만 사용하고, 다른 CSS 변수 참조가 필요할 때는 공식 문서의@theme inline동작을 따른다. - shadcn을 쓰는 프로젝트에서는 공식 테마 문서의 현재 변수 계약과 프로젝트의
components.json을 대조한다. 보통--primary와--primary-foreground처럼 배경·전경 쌍을 만들며, Tailwind 매핑은--color-primary: var(--primary)형태다.--base-*나 상태색·차트 다섯 개를 임의의 필수 표준으로 만들지 않는다. - 다크 모드가 있으면 프로젝트의 실제 선택자와 토큰을 사용한다. 밝기만 기계적으로 올리거나 임의 색상을 생성하지 않는다. 원본에 없는 모드는 미확정 상태로 남긴다.
- 폰트 파일은 라이선스·배포 경로가 확인된 경우에만 넣는다. 파일이 있다는 이유로 셀프 호스팅 코드를 자동 생성하지 않는다.
검증
- JSON 파싱과 타입별 값 구조, 참조 대상과 순환 여부를 확인한다.
- 생성 CSS를 실제 대상 빌드로 검사한다. 대상 빌드를 실행할 수 없으면 정적 검사만 했다고 적는다.
- 대응표의 원본 토큰마다 출력 변수와 값을 대조한다. 역변환은 표현 가능한 하위 집합에만 왕복 검사를 하고, 손실 항목은 별도로 열거한다.
PASS는 실제 비교 결과가 있을 때만 쓴다. - 배경·전경 쌍을 실제 모드별로 계산해 대비를 확인한다. 주색 위 글자를 흰색으로 고정하지 않는다.
- 원본이 금지한 색·글꼴·표현이 있으면 변환 결과와 대조한다. 금지 규칙 자체를 창작하지 않는다.
보고
입력 경로와 확인한 형식, 생성한 파일, 변환한 토큰 수, 손실·충돌 목록, 실제 실행한 파서·빌드·대비 검사의 명령과 결과를 적는다. 확인하지 못한 플랫폼과 렌더 결과는 미검증으로 남긴다.
디자인 자료 연결
Claude Cowork와 ChatGPT Work 모두에서 사용할 수 있는 디자인 자료 정리 흐름이다. MoAI 프로젝트의 .moai/design/ 경로와 /moai design 설정은 해당 프로젝트에 실제 존재할 때만 적용한다. 현재 플러그인에 포함된 config/design.yaml과 rules/moai/design/constitution.md는 프로젝트에 복사된 설정·규칙의 존재를 대신 증명하지 않는다.
자료 선택
- 사용자가 제공한 화면, 디자인 파일, 토큰, 코드, 브랜드 가이드를 확인한다. 요청 목표와 사용 가능한 자료에 맞춰 경로를 고른다.
- Claude Design 결과가 있으면 실제 내보낸 파일의 구조와 사용권을 검사한다. 특정
manifest.json, ZIP 구조나 버전1.0이 공식 내보내기의 보편 형식이라고 가정하지 않는다. 현재 설치된 MoAI 수입기가 별도 형식을 요구하면 그 형식과 입력을 확인한 뒤에만 적용한다. - Figma 파일은 접근 가능한 공식 연결·권한·파일 구조를 확인한 뒤 추출한다. 동적 추출기 생성이나 인증 토큰을 기본 경로로 강제하지 않는다. 비밀 토큰 값은 문서와 산출물에 저장하지 않는다.
- 디자인 파일이 없어도 사용자의 브랜드 자산과 브리프로 시작할 수 있다.
design-system-prep,design-brand-system,design-copywriting등 필요한 스킬만 사용한다.
프로젝트 문맥
- 프로젝트에
.moai/project/brand/가 있고 실제 내용이 있으면 사용자의 현재 브랜드 기준으로 읽는다. 디자인 자료와 충돌하면 출처와 차이를 제시하고 사용자 결정을 받는다. - 프로젝트에
.moai/config/sections/design.yaml이 있으면 그 파일의design_docs설정을 읽는다. 없으면 자동 로드나 토큰 예산을 적용했다고 주장하지 않는다. .moai/design/spec.md,system.md,research.md가 실제로 있고 내용이 있을 때만 읽는다._TBD_로 된 틀은 근거로 쓰지 않는다. 길이를 줄여야 하면spec→system→research순서로 보존하되, 읽지 않은 부분을 분명히 표시한다.- 작업 대상 프로젝트가 MoAI 전용 예약 경로를 사용한다면 디자인 규칙의 현재 목록을 확인한다. 이 파일의 경로 표기가 실제 설치 구조와 다르면 사용자가 지정한 프로젝트 경로를 따른다. 사람 손으로 쓴 파일은 덮어쓰지 않는다.
가져오기와 안전성
받은 ZIP은 압축을 풀기 전에 엔트리 목록과 확장 후 크기를 확인한다. 절대 경로, 상위 경로 이동, 심볼릭 링크, 장치 파일, 실행 가능한 스크립트와 중첩 압축은 거부한다. 추출 대상 디렉터리 밖으로 쓰지 않는다. 이미지·SVG·폰트는 형식과 권리를 확인하고, SVG 안의 스크립트나 외부 참조를 무해하다고 가정하지 않는다. 형식이 불명확하면 원본을 보존하고 지원 가능한 자료만 별도로 다룬다.
토큰은 실제 파싱 결과를 design-tokens-transformer로 검증한다. 값이 빠지거나 이름이 충돌하면 임의의 브랜드 값을 생성하지 않는다. 구성요소와 카피도 제공된 자료에서 확인한 것만 추출한다.
산출과 검증
- 대상 프로젝트의 기존 구조를 확인하고 필요한 파일만 쓴다. 생성 경로와 원본 경로의 대응표를 남긴다.
- 원본 자산의 값과 변환된 토큰을 비교하고, 실제 실행한 파서·빌드·화면 검사만 통과로 보고한다.
- Claude Design에서 준비한 자료와 실제 업로드·적용·게시 상태를 구분한다. 업로드는
design-sync-upload의 현재 UI 절차를 따른다. - 데이터나 자산을 읽지 못한 경우, 형식 미지원과 미확인 사항을 다음 작업과 함께 보고한다.
관련 스킬
design-system-prep, design-brand-system, design-tokens-transformer, design-sync-upload, design-brief.
MCP servers 1
Sponsors
Details
- Marketplace
- modu-ai/moai-cowork
- Source
- plugins/moai-designer
- Category
- 디자인
More from modu-ai/moai-cowork
All 18- moai-lawyerv1.4.18
- moai-marketerv1.2.24
- moai-mediav3.3.16
- moai-officerv1.3.9
- moai-pmv1.7.0
- moai-recruiterv2.0.9
- moai-sellerv1.4.33
- moai-storyv1.2.5
- moai-threads-posterv2.0.7
- moai-tutorv1.3.5
- moai-writerv1.5.14
- moai-accountantv1.3.9
- moai-analystv1.3.7
- moai-careerv1.2.7
- moai-consultantv1.2.8
- moai-coworkerv1.2.28
- moai-csv1.2.9