컴포넌트 및 UI 디자인 스킬 (component-design)
웹 및 애플리케이션 컴포넌트, 섹션, 페이지를 설계하기 위한 구조화된 UX/UI 발견 및 사양 워크플로우입니다. stitch-design과 같은 시각적 프로토타이핑 도구와 코드 구현 워크플로우에서 사용할 수 있는 프로덕션 준비 디자인 사양(design-spec.md)을 생성합니다.
가드레일 및 핵심 원칙
[!IMPORTANT] 1. 코딩 금지 가드레일 (순수 디자인 범위): 이 스킬은 UX, UI, 레이아웃 아키텍처, 타이포그래피, 시각적 토큰에만 엄격하게 관련됩니다. React 컴포넌트, Next.js 지시문, TypeScript 프롭 인터페이스 또는 패키지 설치 명령(shadcn/Radix CLI 명령 없음)을 절대 출력하지 마십시오. 코드 구현은 다운스트림 개발 워크플로우에서 처리됩니다.
[!CAUTION] 2. 디자인 토큰 전제 조건 게이트 (토큰 우선 규칙):
docs/project.json에 검증된 표준 디자인 토큰 없이는 어떤 컴포넌트도 설계할 수 없습니다. 누락된 토큰은 컴포넌트 설계를 초안하기 전에 반드시 질문하고 저장해야 합니다. token-verification-matrix.md를 참조하세요.
[!TIP] 3. 토큰 보존 규칙 (스킬 내 직접 이미지 생성 금지): 절대 직접
generate_image를 호출하지 마십시오. 사용자가 이미지를 생성하여 프로젝트 디렉토리에 배치할 수 있도록 구조화된 이미지 생성 프롬프트를 작성하십시오.
[!NOTE] 4. 선택적 패턴 조회 (토큰 보존):
references/component-design-patterns.md의 라우팅 테이블을 확인하고references/patterns/아래의 일치하는 컴포넌트 파일만 로드하십시오(예:hero.md). 일치하는 경우, 적응형 인터뷰 중에 사용자에게 해당 패턴을 구현할지 질문하십시오.
워크플로우 개요
flowchart TD
Start["/component-design 호출<br/>(페이지 + 컴포넌트 이름)"] --> Step1["1단계: 동적 컨텍스트 및 토큰 게이트<br/>(docs/**, CONTEXT.md, 토큰 및 대상 패턴 스캔)"]
Step1 --> CheckTokens{"docs/project.json에<br/>디자인 토큰이<br/>완전한가?"}
CheckTokens -- "토큰 누락" --> GrillTokens["누락된 토큰 질문<br/>(컨텍스트 기반 3가지 선택지)"]
GrillTokens --> SaveTokens["docs/project.json에 저장"]
SaveTokens --> Step2
CheckTokens -- "확인됨" --> Step2["2단계: 다중 라운드 적응형 질문<br/>(1~3라운드 + 대상 패턴 질문)"]
Step2 --> Step3["3단계: 시각적 에셋 프롬프트 작성<br/>(사용 준비 완료된 이미지 프롬프트 제공)"]
Step3 --> Step4["4단계: design-spec.md 생성 및 작성<br/>(docs/design/components/[page]/[component]/)"]
Step4 --> Step5["5단계: 하위 에이전트 감사 및 자동 수리<br/>(invoke_subagent가 가드레일 및 토큰 확인)"]
Step5 --> Finish["다운스트림 핸드오프 준비 완료<br/>(시각적 프로토타이핑 / 구현)"]
실행 런북
1단계: 동적 컨텍스트 발견 및 디자인 토큰 검증 게이트
- 프로젝트 컨텍스트 스캔:
docs/및 루트CONTEXT.md의 모든 파일을 동적으로 검사하여 대상 페르소나, 비즈니스 목표, 기존 디자인 북마크를 추출합니다. - 지원되는 로케일 스캔:
docs/project.json에서project_context_and_metadata.supported_languages를 읽습니다. - 디자인 토큰 확인:
docs/project.json의"design_system"을 token-verification-matrix.md와 대조하여 감사합니다. - 누락된 토큰 질문: 토큰이 없으면 프로젝트에 맞춤화된 3가지 옵션(하나는
(Recommended)로 표시)을 작성하고 사용자에게 질문한 후"design_system"아래에 저장합니다. - 대상 디자인 패턴 조회:
references/component-design-patterns.md의 라우팅 테이블을 스캔하고, 설계 중인 컴포넌트와 일치하는 패턴이 있으면references/patterns/아래의 해당 컴포넌트 패턴 파일만 봅니다.
2단계: 진보적 다중 라운드 컴포넌트 질문
ask_question(또는 대화형 채팅)을 사용하여 적응형 3라운드 인터뷰를 실행하고, 각 라운드 사이에 멈춰 사용자 답변을 수집합니다. 전체 질문 구성은 adaptive-grilling-rounds.md를 참조하십시오.
- 일치하는 패턴이
references/patterns/에서 발견된 경우, 해당 패턴의 질문지를 1라운드 또는 2라운드에 통합하여 사용자에게 구현 여부를 명시적으로 질문합니다. - 1라운드 (의도 및 스토리): 컴포넌트 목적, 사용자 작업(jobs-to-be-done), 감정적 톤을 명확히 합니다.
- 2라운드 (공간 계층 구조 및 그리드): 1라운드 응답을 기반으로 다중 열 레이아웃, 밀도 척도, 초점 시선 흐름을 조정합니다.
- 3라운드 (상호작용 및 악센트): 1, 2라운드를 기반으로 호버/포커스 상태 역학, 미디어 에셋, BiDi/RTL 미묘한 차이를 설정합니다.
3단계: 사전 예방적 시각적 에셋 프롬프트 작성
컴포넌트에 맞춤형 그래픽, 배경 또는 아이콘이 필요한 경우, generate_image를 호출하는 대신 사용자를 위한 구조화된 생성 프롬프트를 작성하십시오. 프롬프트 블록 형식은 adaptive-grilling-rounds.md를 참조하십시오.
4단계: 컴포넌트 폴더 및 design-spec.md 생성
- 디렉토리 생성:
docs/design/components/[page name]/[component name]/ - design-spec.template.md의 표준 9개 섹션 레이아웃을 사용하여
design-spec.md생성:- §1 실행 요약 및 스토리
- §2 시각적 계층 구조 및 공간 흐름
- §3 레이아웃 그리드 및 반응형 중단점 (모바일, 태블릿, 데스크탑)
- §4 디자인 토큰 및 색상 매핑 (라이트 및 다크)
- §5 타이포그래피 스케일 (지원되는 각 로케일별)
- §6 상호작용 상태 매트릭스 (기본, 호버, 활성, 포커스, 비활성, 스켈레톤)
- §7 양방향 (RTL) 적응
- §8 접근성 및 인간공학 (WCAG AA/AAA, $\ge 44\text{px}$ 터치 대상)
- §9 권장 시각적 에셋 및 프롬프트
5단계: 독립적 하위 에이전트 품질 감사 (invoke_subagent)
편향되지 않은 품질을 보장하기 위해 결과를 사용자에게 제시하기 전에 독립적인 검토 하위 에이전트를 호출하십시오.
- 감사 하위 에이전트 생성 (
TypeName: "self",Role: "Independent Design & UX Auditor",Model: "inherit"). - subagent-audit-protocol.md의 구조화된 감사 프롬프트를 사용합니다.
ISSUES_FOUND인 경우, 마무리하기 전에design-spec.md에서 플래그가 지정된 모든 문제를 즉시 해결합니다.
다운스트림 핸드오프
design-spec.md가 승인되고 확인되면:
- 시각적 프로토타이핑: Google Stitch에서 UI 화면 및 레이아웃 변형을 생성하도록
stitch-design을 트리거합니다. - 코드 구현: 컴포넌트 구현 스킬(예:
nextjs-component-dev/nextjs-create-component)에design-spec.md를 제공합니다.
실행 확인 체크리스트
실행을 완료하기 전에 다음을 확인하십시오.
- 결과물에 코드 또는 라이브러리 설치 명령(React, Next.js, shadcn CLI 없음)이 없습니다.
-
docs/project.json의 표준 디자인 토큰이 확인되고 완전합니다. - 출력 디렉토리가
docs/design/components/[page]/[component]/로 구성되었습니다. - 질문 옵션이 하드코딩된 저장소 가정 없이 동적으로 합성되었습니다.
- 컴포넌트 질문이 진보적 적응형 라운드를 따랐습니다.
-
generate_image가 직접 호출되지 않았습니다. 에셋 프롬프트가 사용자에게 제공되었습니다. -
design-spec.md에 필요한 9개 섹션이 모두 포함되었습니다. -
invoke_subagent를 통해 독립적인 하위 에이전트 감사가 호출되었고 모든 문제가 해결되었습니다.