디자인 브리프

디자인 브리프은(는) 무엇을 하나요?

코딩 에이전트를 혼자 두면, 에이전트는 기억에 의존해 디자인합니다. 그리고 기억은 모든 것의 평균을 냅니다: 중앙에 배치된 히어로, 보라색 그라데이션, 각각 아이콘이 있는 세 개의 카드. 하지만 실제 제품은 여러분이 만들 모든 스크린에 대한 해결책을 이미 가지고 있고, 한 번에 즉흥적으로 만든 것보다 더 나은 완성된 컴포넌트도 이미 존재합니다. 그러니 자신의 디자인 감각을 평균이라고 생각하고 발명을 멈추세요. 여러분의 임무는 찾고, 비교하고, 선택하고, 적응시키는 것입니다.

두 가지 소스가 이 작업을 수행하며, 각각 다른 역할을 담당합니다:

소스	제공하는 것	사용 목적
Refero	실제 출시된 제품의 스크린, 플로우 및 스타일	스크린이 무엇을 해야 하고 어떻게 보여야 하는지 결정
21st.dev	사람들이 만들고 커뮤니티가 평가한 완성된 컴포넌트	코드에 실제로 들어갈 컴포넌트

Refero는 무엇을 만들지 알려주고, 21st.dev는 부품을 제공합니다. 둘 다 사용하세요. 레퍼런스 없이 선택된 컴포넌트는 종종 예쁘지만 스크린에 맞지 않고, 레퍼런스만 있고 컴포넌트가 없으면 수작업으로 다시 만들어야 하며 결과는 형편없습니다.

설정

# Refero (MCP 서버). 그런 다음 /mcp를 실행하고 로그인하세요.
claude mcp add --transport http refero https://api.refero.design/mcp

# 21st.dev CLI
npx @21st-dev/cli login     # 브라우저가 열립니다. 이후 명령어는 `21st`입니다.
21st whoami                 # 로그인되었는지 확인

21st.dev에서 검색과 미리보기는 무료입니다. 컴포넌트 코드를 가져오는 것은 일일 할당량을 사용합니다(21st usage로 잔여량 확인). 따라서 먼저 비교하고 선택한 것만 가져오세요.

도구가 없거나 로그아웃된 경우, 사용자에게 수정 명령어와 함께 한 번 알리고 작동하는 도구로 계속 진행하세요. 수제작 UI로 조용히 대체하지 마세요.

작업 순서

1. 방향 설정: 색상과 타이포그래피.
2. Refero에서 각 스크린과 플로우에 대한 패턴 찾기.
3. 21st.dev에서 각 섹션에 맞는 컴포넌트 선택.
4. 모든 것을 하나의 토큰 세트로 조정.
5. 실행 중인 앱에서 품질 기준에 맞는지 결과 확인.

하나의 컴포넌트보다 큰 작업의 경우, 코딩 전에 UI 계획을 작성하세요(템플릿은 마지막에 있음). 작은 테이블로, 스크린이 빌드 도중 즉흥적으로 만들어지는 것을 방지합니다.

1. 방향

• 색상과 타이포그래피는 사용자가 이미 가진 것에서 비롯됩니다: DESIGN.md, 기존 디자인 시스템, 또는 사용자가 지명한 레퍼런스. 이를 덮어쓰지 마세요.
• 사용자가 아무것도 제공하지 않은 경우, 최고 수준 제품의 Refero 스타일에서 방향을 잡으세요: refero_search_styles로 검색한 다음, 가장 강력한 두세 개 스타일에 대해 refero_get_style을 사용하세요. 프레임워크의 기본 테마나 플랫폼의 브랜드 팔레트를 기본값으로 사용하지 마세요. 그렇게 하면 해당 플랫폼의 모든 프로젝트가 똑같이 보이게 됩니다.
• 하나의 지배적인 스타일을 선택하고 그 선명한 특성을 유지하세요. 다른 스타일에서 한두 가지 세부 사항을 빌려오세요. 여러 레퍼런스를 평균내면 피하려고 했던 안전한 중간 지점이 나옵니다.
• 라이트 모드와 다크 모드를 지원하세요.
• 하나의 디자인을 제공하세요. 사용자가 요청하지 않는 한 세 가지 옵션 세트를 주지 마세요. 선택하는 것은 사용자가 여러분에게 맡긴 작업입니다.
• 컴포넌트를 설치하기 전에 결과를 토큰(색상 역할, 타이포그래피 스케일, 간격, 반경, 그림자)으로 작성하세요. 그러면 이후의 모든 선택이 토큰으로 해결됩니다.

2. Refero에서 패턴 찾기

도구	답변하는 질문	예제 쿼리
refero_search_styles, 이어서 refero_get_style	어떻게 보이고 느껴져야 하는가?	절제된 타이포그래피를 가진 프리미엄 핀테크 웹사이트
refero_search_screens, 이어서 refero_get_screen	이 스크린에는 무엇이 들어가고, 어떤 상태가 있는가?	대시보드 빈 상태, 데이터 테이블 필터
refero_search_flows, 이어서 refero_get_flow	이 여정의 단계는 무엇인가?	회원가입 온보딩, 구독 취소

스크린과 플로우 검색에는 platform이 필요합니다: web 또는 ios.

• 스크린에 문자 그대로 있는 것을 검색하세요("가격 페이지 연간/월간 토글"). 형용사는 스타일 검색에 속합니다.
• 스크린당 세 가지에서 다섯 가지 각도로 시도하고, 잘하는 알려진 제품도 포함하세요. 첫 번째 결과가 최상인 경우는 드뭅니다.
• 상태도 확인하세요. 행복한 스크린뿐만 아니라 빈 상태, 로딩, 오류, 성공 상태도요.
• 하나의 스크린이 근접하면 refero_get_similar_screens로 관련 스크린을 빠르게 찾습니다.
• 스크린당 두세 개의 레퍼런스를 유지하고 각각에서 무엇을 가져올지 기록하세요: 구조, 계층, 상태, 표현. 레퍼런스는 스크린에 정보를 제공합니다. 복사할 템플릿이 아닙니다.

3. 21st.dev에서 컴포넌트 선택

21st.dev는 AI 생성이 아닌, 완성된 컴포넌트의 큐레이션된 카탈로그입니다. 모든 UI 조각(헤더, 입력, 카드, 드롭다운, 채팅, 로딩 상태, 애니메이션)에 대해 검색, 비교하고 최상의 것을 사용하세요.

21st search "<컴포넌트>" --type c --limit 10     # 컴포넌트만
21st get <id>                                     # 선택한 컴포넌트의 코드와 데모 출력
21st add <author>/<slug>                          # 설치 (내부적으로 shadcn 사용)
npx shadcn@latest add "https://21st.dev/r/<author>/<slug>"   # 기본 shadcn으로 동일 설치
21st logo <brand>                                 # 실제 브랜드 로고를 SVG로, 무료

선택 방법:

1. 분위기가 아닌 슬롯으로 검색하세요. "모던한 깔끔한 섹션"이 아니라 "가격 테이블", "명령 메뉴", "파일 업로드"처럼요. 두세 가지 다른 표현을 시도해보세요.
2. 여러 개를 비교하고, 첫 번째 결과를 절대 선택하지 마세요. 미리보기를 열어보세요. 이름과 설명만으로는 컴포넌트가 어떻게 보이고 움직이는지 알 수 없습니다.
3. 가장 많이 다운로드되거나 북마크된 것을 선호하세요. 수치는 21st.dev의 각 컴포넌트 페이지에 있습니다. 인기는 컴포넌트가 실제 프로젝트에서 작동한다는 증거입니다. 적합성을 보장하지는 않으므로 다음 확인이 필요합니다.
4. 해당 스크린의 Refero 레퍼런스와의 적합성을 확인하세요. 동일한 작업을 적절한 밀도로 수행해야 하며, 필요한 상태(호버, 포커스, 비활성화, 로딩, 빈 상태)를 가지고 있어야 합니다. 모바일 너비와 키보드에서도 잘 작동하는지, 그리고 가져오는 종속성을 확인하세요.
5. 한두 가지를 여러분의 토큰에 맞게 조정하세요: 색상, 반경, 폰트. 컴포넌트를 다시 작성하고 있다면 잘못 선택한 것입니다. 돌아가서 다시 선택하세요.
6. 형제 컴포넌트의 일관성을 유지하세요. 다른 작성자의 컴포넌트도 스킨을 다시 입히면 같은 제품처럼 읽혀야 합니다.
7. 후보가 없는 접착 코드만 수제작하고, 그 이유를 명시하세요.

각 선택을 사용자가 교체할 수 있도록 보고하세요: 섹션 · 컴포넌트 · 작성자 · 한 줄 이유.

4. 품질 기준

• 일반 아이콘과 색깔 점 대신 실제 로고.
• 적은 텍스트. 설명문의 벽은 없애고 인터페이스가 전달하도록 하세요.
• 실제 UI 패턴: 탭, 드롭다운, 모달, 토글, 차트. 모든 것이 카드 더미가 되어서는 안 됩니다.
• 좋은 로딩, 빈 상태, 오류 상태, 느린 작업에 대한 진행 표시.
• 모션, 그리고 적합한 경우 사운드와 햅틱.
• 모든 것이 발견 가능해야 함: 모든 페이지는 사용자가 이미 있는 곳에서 도달할 수 있어야 하고, 클릭 가능한 모든 것은 클릭 가능해 보여야 함.
• 마찰이 적은 온보딩.
• 플로우는 사용자를 타사 사이트로 보내지 않고 앱 내에 머무름.
• 반응형, 모바일이 데스크톱을 축소한 것처럼 느껴지지 않고 네이티브처럼 느껴져야 함.
• 한 번의 불만은 패턴입니다. 사용자가 한 가지를 지적하면, 앱 전체에서 그 형제들을 찾아 수정하세요.

평범함은 절대 선택 사항이 아닙니다.

5. 실행 중인 앱에서 확인

브라우저나 시뮬레이터에서 앱을 열고 사용해보세요: 라이트/다크, 데스크톱/모바일 너비, 빈 상태와 로딩 상태. 각 스크린을 레퍼런스와 비교하고 차이를 수정하세요. 연구가 종착점이 아닙니다. 렌더링된 스크린이 종착점입니다.

UI 계획 템플릿

**방향:** <사용자의 DESIGN.md, 또는 Refero 스타일: 이름, 이름> · 라이트 및 다크
**토큰:** <색상 역할, 폰트, 반경, 간격>

| 스크린 또는 플로우 | Refero 레퍼런스 | 가져올 것 | 21st.dev 컴포넌트 |
|---|---|---|---|
| 온보딩 | <앱: 스크린>, <앱: 플로우> | 세 단계, 진행 표시줄, 건너뛰기 | <author>/<slug> |

**수제작 (후보 없음):** <내용, 그리고 이유>