활성화 계약
사용자가 평문으로 UI 디자인, 목업, 스크린, 랜딩 페이지, 시각적 방향을 요청하거나 design/ 아래의 아트보드를 반복 작업할 때 이 스킬을 기본적으로 사용하세요. 프로젝트의 실제 스택에서 프로덕션 코드를 구현하는 데는 사용하지 마세요.
/gentle:design 명령어는 선택적 단축키입니다. 모든 작업은 이 스킬과 gentle_design 도구(list, open, stop, implement, handoff)를 통해 일반 요청으로도 작동합니다.
엄격한 규칙
- 모든 아트보드는 하나의 독립적인 HTML 파일이어야 합니다: 인라인 CSS, JS, SVG; 시스템 폰트 스택만 사용하세요. 외부 URL, CDN, 원격 폰트, 이미지 또는 스크립트를 절대 참조하지 마세요.
- 대상 사용자에게 현실적인 콘텐츠를 사용하세요. lorem ipsum이나 플레이스홀더 이름은 사용하지 마세요.
- 접근성 마크업: 시맨틱 요소와 랜드마크, WCAG AA 대비, 보이는 포커스 스타일, 모든 모션에 대해
prefers-reduced-motion을 준수하세요. design/system.md가 존재하면 먼저 읽고 해당 토큰과 컴포넌트 규칙만 사용하세요. 아트보드를 마치기 전에 '디자인 시스템 동기화'의 자체 점검을 실행하세요.- 최대 한 번의 명확화 질문만 하며, 브리핑에 목표나 콘텐츠가 없는 경우에만 질문하세요.
- 반복 작업은 대상 아트보드만 수정합니다. 다른 아트보드는 절대 덮어쓰지 마세요.
결정 게이트
| 상황 | 조치 |
|---|---|
| 새 브리핑 | 새 design/<slug>/에 N개의 명확히 다른 방향성(기본 3개 또는 요청된 수)을 작성합니다 |
| 하나의 아트보드에 대한 피드백 | 해당 파일만 편집하고, 매니페스트 항목을 유지하며, tradeoff가 변경되면 업데이트합니다 |
| "저장하고 다른 접근법 시도" | 다음 NN으로 새 아트보드를 추가하고, 이전 아트보드는 유지하며 매니페스트에 추가합니다 |
| 사용자가 값(간격, 색상, 글꼴 스케일)을 조정하려 함 | 아트보드에 슬라이더나 컨트롤을 추가하고, 선택한 값을 프롬프트로 복사하는 "프롬프트로 복사" 버튼을 추가합니다 |
새 브리핑인데 design/<slug>/이 이미 존재함 | 새 슬러그를 선택하고, 다른 디자인을 절대 덮어쓰지 마세요 |
| 메시지에 디자인 댓글이 있거나 사용자가 적용을 요청함 | 아래 '캔버스 댓글'을 따릅니다 |
/gentle:design sync 또는 사용자가 프로젝트의 디자인 시스템 캡처를 요청함 | 아래 '디자인 시스템 동기화'를 따릅니다 |
| 사용자가 디자인 표시, 중지, 목록 또는 아트보드 구현을 요청함 | gentle_design 도구를 호출합니다(open, stop, list, 또는 implement with <slug>/<artboard>); implement가 반환하는 핸드오프 텍스트를 따르고, action "handoff"로 진행 상황을 보고합니다: 시작 시 status: "in_progress", 완료 시 status: "implemented", 실행 중인 앱이 있으면 previewUrl을 루프백 URL로 설정합니다 |
디자인 전
모든 새 브리핑 전에 이 게이트를 실행하세요: gentle_design 도구를 action: "list"로 호출한 후:
list 보고 내용 | 조치 |
|---|---|
system.exists false이고 designSources가 있음 | 먼저 '디자인 시스템 동기화'를 실행하고, 한 줄로 프로젝트 디자인 시스템을 동기화했음을 사용자에게 알린 후, 그 시스템으로 디자인합니다 |
designSources 없음 | 동기화를 건너뛰고 자유롭게 디자인합니다 |
system.staleSources가 있음 | 해당 소스의 이름을 말하고, design/system.md가 최신이 아닐 수 있음을 알린 후, 디자인 전에 다시 동기화할 것을 제안합니다; 사용자의 승인 없이 다시 동기화하지 말고, 낡은 토큰을 조용히 사용하지 마세요 |
실행 단계
- 브리핑을 파악합니다: 목표, 레이아웃, 콘텐츠, 대상 사용자.
gentle-ui-design을 로드합니다: 해당SKILL.md와 브리핑의 대상 사용자, 주요 작업, 성공 조건과 일치하는 참조만 읽습니다. 이 스킬은 전달을 담당하고, 해당 스킬은 UX 품질을 담당합니다.- 브리핑에서 kebab-case 슬러그를 선택합니다.
- 방향성은 색상뿐만 아니라 구조나 시각적 전략에서도 달라야 합니다. 각각에 절충점(tradeoff) 레이블을 붙입니다.
- 각 아트보드에 대해
design/<slug>/NN-<name>.html을 작성합니다(01-…,02-…; kebab-case 이름). design/<slug>/design.json을 작성합니다:
{
"title": "가격 페이지",
"brief": "학생 대상 노트 앱의 가격 페이지",
"feature": "odd/tasks/pricing-page.md",
"artboards": [
{ "file": "01-comparison-table.html", "title": "비교 테이블", "tradeoff": "밀도 높고 스캔하기 쉬움; 감성적 호소력 약함", "width": 1440, "height": 900 },
{ "file": "02-single-plan-hero.html", "title": "단일 플랜 히어로", "tradeoff": "강력한 집중; 플랜 차이 숨김", "width": 1440, "height": 900 }
]
}
width/height를 아트보드의 의도된 뷰포트(CSS 픽셀)로 설정하고, 매니페스트를 모든 변경 사항과 동기화 상태로 유지합니다. 필드:title,brief, 선택적feature, 그리고file,title,tradeoff,width,height가 있는artboards[].- ODD 링크: 디자인이 추적 중인 ODD 기능(현재 작업에 대한 기존
odd/tasks/<feature>.md)에서 비롯된 경우,feature를 해당 경로로 설정하고 해당 문서의## Log에design/<slug>/와 해당 아트보드를 명명하는 항목을 하나 추가합니다. 해당 디자인의 아트보드가 구현을 위해 핸드오프되면 Log 항목은 선택된 아트보드(list가 'Chosen'으로 보고)와 나머지가 대안임을 명시합니다. 소규모 추적되지 않은 작업의 경우feature를 생략하고 디자인을 독립적으로 유지합니다. 링크를 위해 기능 문서를 절대 새로 만들지 마세요. - UX 자체 점검: 완료한 모든 아트보드에 대해
gentle-ui-design의 구성 및 피드백(계층, 밀도, 피드백) 및 적응형 인터페이스(좁은 화면, 입력 접근, 상태) 지침과 대조하여 확인하고, 보고하기 전에 모든 차이를 수정합니다. - 아트보드를 작성하거나 변경한 후, 사용자가 하지 말라고 하지 않는 한
gentle_design도구를action: "open"과 슬러그로 호출합니다. 캔버스 탭이 이미 열려 있으면 새 탭을 여는 대신 해당 탭을 새로고침하므로, 모든 변경 후에 호출합니다. 반환된 URL을 보고합니다.
디자인 시스템 동기화
- 프로젝트 소스는 읽기 전용이며, 절대 편집하지 마세요. 소스: CSS 커스텀 프로퍼티(
:root,@theme,[data-theme]), Tailwind 구성 또는 v4@theme, 컴포넌트 라이브러리 폴더, 기존 토큰 파일, 그리고 선언된 폰트. design/system.md를 작성합니다: 색상(토큰 이름, 값, 용도), 타이포그래피, 간격, 모서리 반경, 그림자, 컴포넌트 규칙. 각 항목은 소스path를 명시합니다. 소스에서 찾은 값만 기록합니다.design/system.html을 작성합니다: 하나의 독립적인 아트보드, 1440px 너비, 해당 토큰(견본, 글꼴 스케일, 간격, 모서리 반경, 그림자)과 핵심 컴포넌트를 렌더링하며, 동일한 외부 URL 금지 규칙을 따릅니다. 캔버스는 이 보드를 모든 디자인의 첫 번째 보드로 표시합니다.- 디자인 소스가 없으면 그렇게 말하고, 사용자가 수락할 수 있는 최소한의 스타터 시스템을 제안합니다. 절대 발명된 값을 프로젝트 토큰으로 제시하지 마세요.
- 자체 점검:
design/system.md가 존재하는 동안 완료한 모든 아트보드에 대해, 아트보드가 사용하는 색상과 폰트 패밀리를 나열하고, 시스템 토큰과 비교하여 보고하기 전에 모든 차이를 수정합니다.
캔버스 댓글
캔버스의 댓글은 design/<slug>/comments.json에 저장됩니다. 세션은 또한 각 댓글 id를 명명하는 메시지로 이를 수신합니다.
gentle_design_comments도구(action: "list", 선택적slug및file)로 열린 댓글을 읽습니다. 도구가 없으면design/<slug>/comments.json을 읽고status가"open"인 항목을 사용합니다.- 각 댓글을
file의 아트보드만 수정하여 적용합니다.selector와excerpt를 사용하여 요소를 찾습니다. 댓글에screenshot이 있으면 먼저 확인합니다: 댓글 메시지에 첨부되어 도착하거나, 읽기 도구로design/<slug>/<screenshot>을 엽니다. 이는 사용자가 본 내용을 보여주며, 종종 정적 아트보드에는 표시되지 않는 일시적인 애니메이션이나 전환 상태입니다. - 적용된 각 댓글을 도구로 해결 상태로 표시합니다(
action: "resolve",slug,ids). 도구가 없으면status를"resolved"로 설정하고resolvedAt을 현재 ISO 시간으로 설정하며, 다른 모든 항목과 필드는 그대로 유지합니다. 적용하지 않은 댓글은 열린 상태로 두고 이유를 설명합니다.
파일 접근만 가능한 에이전트를 위한 파일 형식:
{
"version": 1,
"comments": [
{ "id": "k3x9p2ab", "file": "02-bold.html", "selector": "body > header > h1", "excerpt": "더 빠르게 배송", "comment": "제목을 더 짧게 만드세요.", "createdAt": "2026-10-26T10:00:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null },
{ "id": "m7q2w9cd", "file": "02-bold.html", "selector": "#cta", "excerpt": "시작", "comment": "호버 전환 중 버튼이 튀어요.", "screenshot": ".screenshots/m7q2w9cd.png", "createdAt": "2026-10-26T10:05:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null }
]
}
screenshot은 선택 사항입니다: 디자인 폴더 기준 상대 경로로, .screenshots/ 아래에 있으며, 사용자가 이미지를 첨부한 경우에만 존재합니다.
항목을 삭제하거나 순서를 변경하지 말고, 파일을 유효한 JSON으로 유지하십시오: 캔버스는 파싱할 수 없는 파일을 덮어쓰지 않습니다.
출력 계약
반환: 슬러그, 각 아트보드 파일(제목 및 tradeoff 포함), 이번 턴에 변경된 파일, 이번 턴에 해결된 댓글 id, 그리고 열려 있는 질문. 단계 10의 캔버스 URL을 제공하거나, 열지 않은 경우 /gentle:design open <slug>이 캔버스를 보여준다고 언급합니다. 동기화의 경우, 읽은 소스 경로, 그룹별 토큰 개수, 시스템이 제안된 스타터인지 여부를 반환합니다. '디자인 전'의 자동 동기화 후에는 실행되었다고 말하고 동일한 방식으로 보고합니다.
참조
- 프로젝트의
design/system.md(존재하는 경우) — 따라야 할 디자인 토큰. gentle-ui-design스킬 — 모든 아트보드와 함께 제공되는 UX 품질 지침.