디자인 시니어의 스킬 ux-ui-agent-skills 설명

https://github.com/plugin87/ux-ui-agent-skills

UX UI 디자인 스킬 설명 및 사용 방법

문서 목적

이 문서는 현재 Codex 환경에 설치된 plugin87/ux-ui-agent-skills 계열 스킬과 함께 사용할 수 있는 핵심 UX/UI 스킬을 한눈에 이해하고 실제 작업에 적용하기 위한 안내서입니다. 스킬은 디자인 방향을 정하거나, 화면을 설계하고, 코드를 만들고, 접근성과 품질을 검증하는 작업을 역할별로 나누어 줍니다.

가장 안정적인 사용 순서는 방향 정의 → 토큰 설계 → 화면·컴포넌트 설계 → 코드 구현 → QA와 검토입니다. 한 번에 모든 스킬을 호출하기보다 현재 작업의 단계에 맞는 스킬만 선택하면 결과가 더 일관되고 검증하기 쉽습니다.

스킬을 호출하는 기본 방법

Codex에게 일반 문장으로 요청하면 작업 내용에 맞는 스킬이 자동으로 선택될 수 있습니다. 특정 스킬을 반드시 적용하려면 프롬프트에 $스킬이름을 직접 적습니다.

$design-doctrine 먼저 프로젝트 디자인 원칙을 확인하고
$design-tokens 마켓 화면의 색상·간격·타이포그래피 토큰을 정리해줘.

좋은 요청에는 다음 네 가지가 들어갑니다.

1. 대상: 화면, 컴포넌트, 디자인 시스템 또는 기존 코드
2. 목적: 새로 만들기, 개선하기, 검토하기, 구현하기
3. 기술 범위: Blade/CSS, React/Tailwind 등 프레임워크와 파일 경로
4. 완료 기준: 반응형, 접근성, 브라우저 테스트, 시각 회귀 검증 등

예시:

$redesign 현재 /market 화면을 기존 기능은 유지한 채 개선해줘.
Blade와 css를 사용하고, 모바일 390px과 데스크톱에서 확인한 뒤
변경 파일과 브라우저 검증 결과를 알려줘.

핵심 스킬 분류

1. 디자인 원칙과 방향

스킬	역할	사용 시점	결과물
design-doctrine	모든 UI 작업의 기본 원칙과 검증 절차를 적용	새 화면, 리디자인, 테마 작업 시작 전	디자인 원칙, 상태·토큰·검증 기준
frontend-design	템플릿처럼 보이지 않는 시각 방향과 레이아웃 제안	새로운 웹 화면이나 기존 화면의 시각적 개편	팔레트, 서체, 레이아웃, 시각적 차별화 방향
apply-aesthetic	특정 분위기나 디자인 시스템을 실제 토큰에 반영	프리미엄, 에디토리얼, 다크 테크 등 명확한 분위기가 필요할 때	선택된 미학에 맞춘 토큰과 UI 적용안
ui-ux-pro-max	스타일·팔레트·폰트·컴포넌트·UX 규칙을 폭넓게 탐색	여러 디자인 대안을 비교하거나 빠르게 방향을 찾을 때	추천 스타일, 색상 조합, 폰트 페어링, UX 체크리스트
design-taste-frontend	랜딩·포트폴리오·리디자인의 안티 슬롭 규칙 적용	화면이 지나치게 일반적이거나 AI 템플릿처럼 보일 때	구체적인 디자인 의도와 개선 방향

design-doctrine는 다른 디자인 스킬보다 먼저 적용하는 것이 좋습니다. 반면 design-taste-frontend는 대시보드·데이터 테이블보다 랜딩 페이지와 브랜드 화면에 적합합니다.

2. 문제 정의와 화면 설계

스킬	역할	사용 시점	결과물
brief-to-ui-board	기획서나 PRD를 화면 구성과 사용자 흐름으로 변환	여러 화면을 한 번에 설계할 때	화면 목록, 플로우, 카피, 토큰, 구현용 보드
design-component	컴포넌트의 구조·변형·크기·8가지 상태·접근성 정의	버튼, 카드, 모달, 탭 등을 코드 전에 명세할 때	컴포넌트 사양서
design-tokens	primitive → semantic → component 3단계 토큰 설계·점검	색상, 타입, 간격, 반경, 그림자, 모션을 표준화할 때	DTCG 토큰 파일 또는 토큰 변경안
ux-writing	버튼·레이블·오류·빈 상태·알림 문구 작성	화면 카피가 모호하거나 일관성이 없을 때	명확한 UI 문구와 상태별 마이크로카피
image-to-code	스크린샷·목업에서 디자인 시스템을 추출해 코드화	참고 이미지와 같은 화면을 구현할 때	토큰 기반 접근성 UI 코드

3. 구현과 시각 자산

스킬	역할	사용 시점	결과물
design-code	프레임워크에 맞는 접근성·토큰 기반 컴포넌트 코드 생성	실제 동작하는 화면이나 컴포넌트가 필요할 때	React, Vue, Svelte, Blade/CSS 등 구현 코드
visual-web-builder	이미지 생성·편집과 프론트엔드 구현을 연결	제품 이미지, 히어로 비주얼, 목업이 필요한 웹 작업	시각 자산과 이를 반영한 UI 코드
imagegen	래스터 이미지 생성·편집	제품 이미지나 배경 비주얼을 새로 만들 때	이미지 파일 또는 수정된 이미지
figma-integration	Figma와 코드의 토큰·컴포넌트 연결	Figma 산출물을 코드와 동기화할 때	매핑 규칙과 동기화 계획

4. 검토와 품질 보증

스킬	역할	사용 시점	결과물
design-review	6개 차원과 Nielsen 10가지 휴리스틱으로 화면 평가	구현 전후의 UX 품질을 객관적으로 점검할 때	우선순위가 있는 발견 사항과 개선안
a11y-audit	WCAG 2.2와 ARIA 패턴 기준으로 접근성 검사	키보드, 명도 대비, 스크린 리더를 확인할 때	기준 조항·심각도·수정 방법
design-qa	토큰 린트, axe, 명도 대비, 시각 회귀, 수동 점검 구성	배포 전 또는 CI에 품질 게이트를 넣을 때	자동·수동 QA 게이트
performance	UI 성능 병목을 찾아 개선	화면이 느리거나 애니메이션·자산이 무거울 때	측정 항목과 최적화 제안
web-design-guidelines	웹 인터페이스 구현을 가이드라인 관점에서 검토	웹 UI의 기본 완성도를 빠르게 확인할 때	구현 개선 의견

작업 유형별 추천 조합

마켓 화면 새로 만들기

$design-doctrine → $frontend-design → $design-tokens →
$design-component → $design-code → $a11y-audit → $design-qa

먼저 사용자와 화면의 목적을 정하고, 색상·타입·간격을 토큰으로 확정한 뒤 컴포넌트와 화면을 구현합니다. 마지막에는 접근성과 시각 QA를 실행합니다.

기존 화면 리디자인

$design-doctrine → $redesign → $apply-aesthetic →
$ux-writing → $design-code → $design-review → $a11y-audit

리디자인은 기능을 먼저 보존해야 하므로 현재 화면을 진단한 뒤 변경 범위를 정합니다. 카피와 시각 방향을 함께 조정하되, 라우트·폼·결제 흐름은 회귀 테스트로 확인합니다.

스크린샷과 동일한 UI 구현

$image-to-code → $design-tokens → $design-component →
$design-code → $design-review

이미지의 픽셀을 그대로 복사하는 것이 아니라 색상, 서체, 간격, 그리드, 상태라는 시스템을 추출해 재사용 가능한 코드로 바꿉니다.

접근성 점검만 수행

$a11y-audit → $design-qa

검사 대상 URL·컴포넌트와 지원 브라우저, 키보드·스크린 리더 범위를 함께 알려주면 결과가 구체적입니다.

프로젝트에 적용하는 예시

마켓 상단과 내역 페이지 검토

$design-review http://127.0.0.1:8002/market을 검토해줘.
현재 수령 자격이 상단에 잘 보이는지, 내역 버튼이
/market/history로 명확히 연결되는지, 모바일에서 정보 우선순위가 유지되는지 확인해줘.

결제 컴포넌트 명세

$design-component
BNB USDT 입금 주소와 보내는 지갑 주소 컴포넌트를 설계해줘.
기본·포커스·오류·복사 완료·읽기 전용·모바일 상태와 WCAG 기준을 포함해줘.

구현과 검증

$design-code
현재 컴포넌트 명세를 Laravel Blade와 css로 구현해줘.
그 다음 $a11y-audit와 $design-qa를 실행하고
/market 및 /market/history에서 브라우저로 확인해줘.

스킬 사용 시 주의사항

• 스킬 이름만 나열하기보다 화면·파일·완료 기준을 함께 제시합니다.
• design-doctrine와 토큰 규칙을 먼저 정해 작업 중 색상과 간격이 임의로 늘어나지 않게 합니다.
• 스킬은 코드를 자동으로 안전하게 배포한다는 뜻이 아닙니다. 라우트, 결제, 지갑 주소 같은 기능은 별도로 동작을 확인해야 합니다.
• 접근성 결과는 자동 검사만으로 끝내지 말고 키보드 이동과 실제 빈 상태·오류 상태를 수동으로 확인합니다.
• 리디자인에서는 기존 기능과 데이터 연결을 먼저 보존하고, 시각 변경은 작은 단위로 나누어 검증합니다.

권장 팀 작업 순서

1. 기획 또는 요구사항을 brief-to-ui-board로 화면·플로우로 정리합니다.
2. design-doctrine와 frontend-design으로 디자인 방향을 확정합니다.
3. design-tokens로 색상·타입·간격·상태 토큰을 만듭니다.
4. design-component로 반복 UI의 상태와 접근성을 명세합니다.
5. design-code로 실제 스택에 구현합니다.
6. design-review, a11y-audit, design-qa 순서로 검토하고 수정합니다.
7. 브라우저의 실제 라우트에서 핵심 흐름을 다시 실행한 뒤 변경 내역을 기록합니다.

이 순서를 지키면 “예쁜 화면”과 “실제로 유지보수 가능한 화면”을 분리하지 않고 하나의 디자인 시스템으로 관리할 수 있습니다.