Communitygithub.com

21 Grams UX

AI로 구축된 제품의 흐름과 사용성을 감사(audit)하고 수정하여, 단순히 완성된 것처럼 보이는 것이 아니라 사람들이 기대하는 방식으로 작동하도록 만듭니다. 프로젝트 자체의 컴포넌트와 패턴을 사용합니다.

21 Grams UX란 무엇인가요?

21 Grams UX는 AI 에이전트가 구축한 프론트엔드 제품의 사용자 흐름(flow)을 집중적으로 감사하고 수정하는 스킬입니다. 이 스킬은 기존 디자인 시스템이나 UI 키트를 대체하지 않으며, 프로젝트에 이미 존재하는 컴포넌트와 패턴만을 사용하여 사용성 문제(데드 엔드, 누락된 상태, 조용한 실패, 복구 불가능한 작업 등)를 해결합니다. 주로 Claude Code, Cursor, Codex와 같은 AI 코딩 에이전트에서 '21 grams UX' 또는 'twenty-one grams UX'라는 요청과 함께 사용되며, 사용자 흐름 감사, 탐색, 폼, 상태 관리, 피드백, 온보딩, 접근성 등 9가지 영역에 대한 구체적인 규칙과 법칙(Hick의 법칙, Fitts의 법칙 등)을 바탕으로 작동합니다. 실제 작업 순서는 인벤토리 조사 → 리서치 → 흐름 매핑 → 브라우저에서 흐름 직접 실행 → 감사 → 사용자에게 결과 제시 → 수정 적용 → 재확인 → 보고 순서를 따릅니다. 이 스킬은 프로젝트의 기존 컴포넌트를 우선시하며, 새로운 라이브러리나 의존성을 추가하지 않고도 실질적인 사용성 개선을 이끌어내는 데 목적이 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ilbognov/21grams/tree/main/skills/ux

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

21 Grams UX은(는) 무엇을 하나요?

이미 존재하는 흐름에 대한 검토입니다. 21 Grams UX(21 Grams 패밀리의 UX 패키지)는 제품을 재설계하지 않으며 UI 키트를 추가하지 않습니다. 실제 흐름을 따라가며 AI가 구축한 제품이 사용자에게 어떤 지점에서 실패하는지(데드 엔드, 누락된 상태, 조용한 실패, 복구 불가능한 작업, 사용자와 싸우는 폼)를 찾아내고, 프로젝트에 이미 있는 컴포넌트와 패턴을 통해 수정합니다.

21 Grams UI는 외관을 담당합니다. 21 Grams UX는 작동 여부를 담당합니다. 둘 다 설치된 경우 UX를 먼저 실행하세요. 존재하지 않아야 할 단계를 다듬는 것은 의미가 없습니다.

규칙 제로: 프로젝트 자체 컴포넌트 사용

모든 변경 사항은 프로젝트가 이미 사용하는 것을 통해 이루어집니다. 21 Grams UX는 병렬적인 컴포넌트 세트나 병렬적인 흐름을 절대 구축하지 않습니다.

  1. 건드리기 전에 인벤토리를 작성하세요. 라우터와 경로 맵, 컴포넌트 라이브러리, 폼 라이브러리와 유효성 검사 방식, 토스트, 다이얼로그 및 빈 상태 컴포넌트, 데이터 페칭 계층(로딩 및 오류 상태가 발생하는 곳), 분석 또는 이벤트 계층(있는 경우)을 기록하세요.
  2. 문제가 있는 곳에서 수정하세요. 누락된 오류 상태는 한 화면이 아닌 공유 데이터 또는 빈 상태 컴포넌트에 들어가야 합니다. 확인 패턴은 일회성이 아닌 프로젝트의 다이얼로그에 들어가야 합니다.
  3. 해당 작업을 수행할 컴포넌트나 의존성이 이미 있다면 새로 추가하지 마세요. 21 Grams UX 효과를 얻기 위해 새로운 폼 라이브러리, 토스트 라이브러리 또는 투어 라이브러리를 추가하지 않습니다.
  4. 진정으로 누락된 부분이 있다면 (빈 상태 컴포넌트 없음, 실행 취소 없음), 프로젝트의 기존 기본 요소로부터 프로젝트의 파일 레이아웃과 명명 규칙을 따라 구축하세요. 보고서에 그렇게 명시하세요.
  5. 제품 결정은 제품의 몫입니다. 21 Grams UX는 제품이 무엇을 하는지, 누구를 위한 것인지 또는 비즈니스 규칙을 변경하지 않습니다. 기존 작업이 수행되는 방식을 변경합니다. 범위를 변경하는 모든 사항은 수정 사항이 아닌 질문으로 보고서에 포함됩니다.

우선 순위: 사용자의 말, 그 다음 프로젝트의 확립된 패턴과 제품 규칙, 그 다음 21 Grams UX 하우스 규칙입니다.

내부 구성

  1. UX 리서치 단계. 흐름을 설계하거나 재설계하기 전에, 현재 제품과 업계를 선도하는 3~5개의 예시를 하나씩 분석합니다. Mobbin과 같은 패턴 라이브러리가 연결되어 있으면 사용합니다. 전체 프로세스는 references/research.md에 있습니다.
  2. UX 법칙. 규칙의 기반이 되는 지식으로, references/laws.md에 있으며 섹션별로 A1, A2...로 인용됩니다. 섹션 A는 핵심 법칙입니다: 힉의 법칙, 피츠의 법칙, 야콥의 법칙, 밀러의 법칙, 도허티 임계값, 테슬러의 법칙, 포스텔의 법칙. 어떤 규칙도 사례를 다루지 못할 때는 법칙으로부터 추론하세요.
  3. UX 규칙. references/rules.md에 있는 번호가 매겨진 규칙으로, 각 규칙, 적용 방법, 플래그해야 할 사항, 빠른 감사 체크리스트가 포함되어 있습니다. 모바일 우선으로 작성되었으며 웹에도 적용됩니다(데스크톱에서 '하단 탭'을 위한 기본 내비게이션, '바텀 시트'를 위한 팝오버).
  4. 현장 규칙. AI로 구축된 제품에 대한 실제 리뷰 세션과 선도 제품에 대한 UX 리서치에서 얻은 규칙으로, references/field-rules.md에 있으며 F1, F2...로 인용됩니다. 이 파일은 세션이 진행될 때마다 업데이트됩니다("현장 규칙 확장" 참조).
  5. 영역별 하우스 규칙 rules/ 디렉토리에 있으며, 각 영역별로 하나의 파일에 해당 영역에 속하는 법칙, 번호 규칙 및 현장 규칙이 나열됩니다.
파일영역
navigation.md내비게이션 및 길 찾기
forms.md폼 및 입력
states.md빈 상태, 로딩, 오류 및 성공 상태
feedback.md피드백 및 시스템 상태
onboarding.md온보딩 및 첫 실행
destructive.md파괴적 작업 및 복구
accessibility.md접근성 및 키보드
flows.md흐름 및 작업 길이
choice.md선택 및 인지 부하

규칙 #1~5는 예약되어 있으며 이후 버전에서 추가될 예정입니다. 영역에 규칙이 생길 때까지는 일반적인 사용성 판단에 따라 감사를 수행하고 보고서에 그렇게 명시하세요.

절대 양보할 수 없는 사항

  • X는 모달 또는 흐름을 닫습니다. 왼쪽 화살표는 한 화면 뒤로 이동합니다. (#6)
  • 로딩 중에는 절대 빈 화면이 없어야 합니다. 스켈레톤, 스피너 또는 진행 표시줄을 사용하세요. (#7)
  • 피드로 돌아가면 정확한 스크롤 위치가 복원됩니다. (#8)
  • 활성 탭을 누르면 맨 위로 이동합니다. (#9)
  • 사람들이 하단에 도달하기 전에 다음 페이지가 로드됩니다. (#10)
  • 좋아요, 팔로우 및 저장은 낙관적(optimistic)으로 업데이트되며, 실패 시 롤백 및 메시지가 표시됩니다. (#11)
  • 초안 및 완료되지 않은 입력은 자동으로 저장됩니다. (#12)
  • 권한은 기능이 사용될 때 요청되며, 시작 시에 절대 요청되지 않습니다. (#13)
  • 빠른 작업은 아래로 스와이프하여 닫을 수 있는 바텀 시트에서 열립니다. (#14)
  • 알림 및 공유 링크는 정확한 콘텐츠를 엽니다. (#15)
  • 단계당 선택지는 적게 하고, 권장 기본값을 제공하며, 나머지는 숨깁니다. (A1)
  • 기본 작업은 크고 손이 닿는 범위 내에 있어야 하며, 터치 대상은 44×44 이상이어야 합니다. (A2)
  • 공통 작업은 표준 패턴을 사용합니다. (A3)
  • 정보는 그룹화되어 있어야 하며, 단계 사이에 기억해야 할 것이 없어야 합니다. (A4)
  • 모든 입력은 즉시 확인되며, 더 긴 대기 시간은 진행 상황을 표시합니다. (A5)
  • 제품이 복잡성을 처리해야 하며, 사람이 처리해서는 안 됩니다. (A6)
  • 지저분한 입력을 받아들이고 깔끔하게 반영하되, 보안이나 데이터 무결성을 절대 약화시키지 마세요. (A7)
  • 작업당 하나의 컨트롤을 사용하세요. (F1)
  • 화면 동작은 오른쪽 상단에 그룹화하고, 기본 동작은 코너에 배치하며, 선택기와 섞지 마세요. (F2)
  • 보조 세부 정보는 요청 시 제공하고, 절대 잃어버리지 않게 하세요. 접근 가능한 유일한 경로를 절대 제거하지 마세요. (F3, F5)
  • 각 사실은 한 번만 말하세요. 화면에 버전 번호, 디자인 노트 또는 내부 전문 용어를 표시하지 마세요. (F6, F9)
  • 상호작용이 변경되면, 이를 설명하는 모든 힌트도 함께 변경되어야 합니다. (F8)
  • 새로운 UI는 제품의 명시된 범위 이상을 주장하지 않습니다. (F10)
  • 해당 단계를 열기 위해 선택한 내용을 반복하는 단계는 없어야 합니다. 옵션이 하나라면 그냥 실행하세요. (F13, F17)
  • 하나의 선택에는 하나의 컨텍스트 툴바가 있으며, 클릭 아웃 시 사라집니다. (F16)
  • 추가할 수 있는 모든 것은 제거할 수 있어야 하며, 삭제 시 어떤 것이 제거될지 알려줘야 합니다. (F18, F19)
  • 단축키는 툴팁에 표시되며 브라우저 예약 키를 절대 사용하지 않습니다. (F20)
  • AI 제안은 잠정적으로 보여야 하고, 하나의 수락/거절 패턴을 사용하며, 수락은 즉시 이루어져야 합니다. (F23)
  • 온보딩: 두 개의 동등한 문, 화면당 하나의 질문과 진행 상황 표시, 계정 생성 전에 가치 제시, 건너뛸 수 있는 투어. (F28, F29, F32, F36)
  • 금전은 정직해야 합니다: 실제 무료 경로, 날짜가 포함된 평가판, 한도 도달 시 업그레이드 제안. (F35)
  • 읽기 및 선택은 좁은 중앙 정렬 열에서 이루어집니다. 단계의 컨텍스트와 동작만 고정됩니다. (F37, F38)
  • 누락된 데이터는 N/A로 표시하고, 텍스트는 잘리고 정렬되며, 모든 목록은 실제 볼륨으로 확인됩니다. (F43, F44, F45)
  • 역할은 앱이 아닌 시작점을 변경합니다. 모바일과 데스크톱은 동일한 패턴을 공유합니다. (F47, F50)

워크플로우

  1. 인벤토리 작성 (규칙 제로).
  2. 리서치 (references/research.md). 새로운 흐름, 재설계 또는 온보딩의 경우 여기서 시작하세요: 무엇을 누구를 위해 설계하는지 파악하고, 현재 흐름을 분석하며, 업계를 선도하는 3~5개의 예시를 추천하고, 변경 전에 사용자와 함께 하나씩 검토하세요. 기존 흐름에 대한 사소한 수정인 경우에만 건너뛰세요.
  3. 흐름 매핑. 사람이 수행해야 할 주요 작업을 나열하고, 각 작업에 대한 제품 내 경로(진입점, 모든 단계, 모든 분기, 종료 상태)를 기록하세요. 각 단계의 데이터 출처를 명시하세요.
  4. 코드뿐만 아니라 브라우저에서 각 흐름을 직접 실행해 보세요. 정상 경로(happy path)를 시도한 다음, 엣지 케이스(아직 데이터 없음, 느린 네트워크, 실패한 요청, 잘못된 입력, 뒤로 가기, 흐름 중 새로 고침, 키보드 전용, 좁은 화면)를 시도하세요.
  5. 변경 전에 감사하세요. references/rules.md, references/laws.md, references/field-rules.md의 체크리스트와 영역 파일들을 검토하세요. 발견 사항을 영역, 규칙 번호 및 법칙별로 그룹화하여 나열하세요. 각 발견 사항에는 흐름과 단계, 파일과 줄 번호, 사람에게 어떤 문제가 발생하는지, 수정 사항, 그리고 수정 사항이 들어갈 기존 컴포넌트 또는 패턴을 포함하세요. 작업 차단, 작업 지연, 거친 엣지 순으로 순위를 매기세요.
  6. 감사 결과를 짧은 목록으로 사용자에게 보여주고, 광범위한 변경을 적용하기 전에 요청하세요. 요청된 범위 내의 명백한 사소한 수정은 바로 적용할 수 있습니다.
  7. 수정 사항을 다음 순서로 적용하세요: 공유 컴포넌트 및 패턴 → 흐름 → 개별 화면. diff 범위를 제한하고 프로젝트 자체 규칙을 따르세요.
  8. 브라우저에서 흐름을 다시 실행하여 수정 사항을 확인하고, 3단계의 엣지 케이스를 포함하세요. 변경된 각 단계의 전후를 캡처하세요.
  9. 보고서를 작성하여 흐름 및 영역별로 변경된 사항, 영향을 받은 컴포넌트, 제품 결정에 해당하는 미해결 질문을 기록하세요.

현장 규칙 확장하기

21 Grams UX는 실제 작업을 통해 학습합니다. 작성자가 AI로 구축된 제품에 대한 리뷰 세션을 완료하고 추가를 요청하면:

  1. 해당 세션의 대화를 읽고 작성자가 요청하거나 수락한 모든 변경 사항을 나열하세요.
  2. UX 변경 사항(흐름, 구조, 배치, 상태, 피드백, 사람을 안내하는 카피, 접근성 경로)을 유지하세요. 시각적 변경 사항(둥글기, 색상, 서체, 아이콘, 모션)은 21 Grams UI에 속합니다.
  3. 각각을 일반 규칙으로 작성하세요: 규칙, 프로젝트 자체 컴포넌트를 통해 적용하는 방법, 플래그해야 할 사항. 클라이언트 이름, 제품 이름 또는 비공개 콘텐츠는 포함하지 마세요.
  4. 규칙이 기존 규칙을 개선하는 경우 새 규칙을 추가하는 대신 해당 규칙을 업데이트하세요.
  5. 새 규칙을 references/field-rules.md에 세션 제목 아래 추가하고, F 번호를 계속 부여하며, 올바른 영역 파일에 나열하세요.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬