Mise UI
스스로를 설명하는 UI. 모든 컴포넌트는 그 형태 뒤에 있는 원칙과 언제 사용하지 말아야 하는지에 대한 규칙을 함께 제공합니다. 컴포넌트를 설치하거나 수정할 때 이 둘을 유지하세요.
사용 시기
- 프로젝트가 React + Tailwind CSS v4이며 shadcn 스타일의
components.json을 사용하는 경우 - 화면에 AI 단계(모델 대기, 스트리밍 텍스트, 도구 호출, 추론, 음성 입력)가 포함된 경우
- 디자인 리뷰에서 근거를 설명할 수 있는 기본 키트(버튼, 다이얼로그, 셀렉트 등)가 필요한 경우
설치
- 테마 (프로젝트당 한 번):
npx shadcn@latest add https://miseui.junsu4621.workers.dev/r/theme.json - 각 컴포넌트:
npx shadcn@latest add https://miseui.junsu4621.workers.dev/r/<name>.json(의존성은 자동으로 설치됨) - 컴포넌트를 처음 사용하기 전에
references/<name>.md를 읽으세요.
규칙
prefers-reduced-motion을 존중하세요. 모든 Mise 컴포넌트는 이미 이를 지원하며, 수정 시에도 유지하세요.- 화면당 하나의
mise강조 색상. 이는 기본 동작 또는 활성 AI 활동을 표시하며, 장식 용도로 사용하지 마세요. - 대기를 명명하세요. 약 1초 이상 걸리는 모든 모델 호출에는
thinking-indicator를 사용하고, 그 레이블에 현재 상황을 표시하세요. - 다크 패턴 금지: 가짜 카운트다운, 숨겨진 취소, 미리 체크된 동의는 없습니다. 각 레퍼런스의 사용하지 마세요 항목은 필수로 준수해야 합니다.
data-slot속성을 유지하세요. 테스트와 스타일링 훅이 이에 의존합니다.
증상 → 컴포넌트
| 상황 | 사용할 컴포넌트 |
|---|---|
| 사용자가 약 1초 이상 모델 호출을 기다림 | thinking-indicator |
| 토큰이 하나씩 도착하며, 멈춘 블록이 아닌 타이핑 중인 것처럼 읽혀야 함 | streaming-text |
| 에이전트가 도구를 실행했고, 사용자가 결과를 신뢰할 수 있어야 함 | tool-call-card |
| 다단계 계획으로 사용자가 검사하고 싶을 수 있지만, 반드시 읽을 필요는 없음 | reasoning-steps |
| 마이크가 활성화되어 있으며 사용자가 이를 알아야 함 | voice-wave |
| 콘텐츠가 로딩 중이며 최종 레이아웃이 알려져 있음 | skeleton |
| 화면의 나머지 부분보다 더 중요한 하나의 동작 | button |
| 한 곳에 너무 많은 옵션 | select |
| 하나의 트리거 뒤에 숨겨진 짧은 동작 목록 | dropdown-menu |
| 사용자가 다른 작업을 하기 전에 결정해야 함 | dialog |
| 일부 사용자만 필요한 추가 세부 정보 | tooltip |
| 함께 속한 관련 컨트롤 | card |
AI 상태
- 추론 단계 (
reasoning-steps): 접힌 상태의 모델 단계 타임라인; 헤더는 현재 단계의 이름을, 본문은 모든 단계를 보여줍니다. — 점진적 공개 · 레퍼런스 - 스트리밍 텍스트 (
streaming-text): 읽기 속도로 문자 하나씩 도착하는 텍스트를 표시하며, 커서가 다음 단어가 위치할 곳을 표시합니다. — 지연 시간 지각 · 레퍼런스 - 생각 표시기 (
thinking-indicator): 세 개의 숨쉬는 점과 실시간 레이블로 모델이 작업 중이며 무엇을 하고 있는지 사용자에게 알려줍니다. — 시스템 상태 가시성 · 작업 착각 · 레퍼런스 - 도구 호출 카드 (
tool-call-card): 하나의 도구 호출 기록(이름, 상태, 지속 시간, 그리고 요청 시 정확한 입력 및 출력)을 접을 수 있는 형태로 보여줍니다. — 투명성은 신뢰를 구축합니다 · 레퍼런스 - 음성파 (
voice-wave): 마이크 레벨에 따라 올라가는 막대로 사용자가 자신의 목소리가 들리고 있음을, 그리고 들리지 않을 때를 볼 수 있게 합니다. — 시스템 상태 가시성 · 레퍼런스
핵심 컴포넌트
- 배지 (
badge): 다섯 가지 변형이 있는 작은 상태 칩; 따뜻한 mise 변형은 눈에 띄어야 하는 하나의 항목에만 사용합니다. — 폰 레스토르프 효과 · 레퍼런스 - 버튼 (
button): 150ms 정착과 2% 눌림 효과로 클릭이 인지되도록 하는 누름 대상. — 도허티 임계값 · 레퍼런스 - 카드 (
card): 헤더, 콘텐츠 및 푸터 슬롯이 있는 테두리 표면으로, 텍스트를 읽기 전에 하나의 영역으로 읽힙니다. — 공통 영역의 법칙 · 레퍼런스 - 체크박스 (
checkbox): 누름 후 150ms 이내에 채워지고 체크 표시를 그리며,aria-checked를 통해 변경 사항을 알리는 사각형 토글. — 즉각적인 피드백 · 레퍼런스 - 다이얼로그 (
dialog): 다른 모든 것을 어둡게 하고 사용자가 하나의 질문에 답할 때까지 포커스를 유지하는 모달 표면. — 주의 집중 깔때기 · 레퍼런스 - 드롭다운 메뉴 (
dropdown-menu): 버튼에서 열리고 선택 시 닫히는 동작의 간결한 메뉴로, 화살표 키 탐색과 파괴적 변형을 제공합니다. — 힉의 법칙 · 레퍼런스 - 입력 (
input): 버튼과 일치하도록 36px 높이의 한 줄 텍스트 필드로, 잘못된 상태를 테두리와 링으로 이동시킵니다. — 피츠의 법칙 · 레퍼런스 - 레이블 (
label): 컨트롤에 연결된 캡션; 클릭하면 필드에 포커스가 가고, 필드가 비활성화되면 희미해집니다. — 근접성의 법칙 · 레퍼런스 - 팝오버 (
popover): 여는 컨트롤에 고정된 작은 부동 패널로, 전체 다이얼로그가 필요하지 않은 양식이나 세부 정보에 사용됩니다. — 공간 기억 · 레퍼런스 - 셀렉트 (
select): 목록에서 하나를 선택하기 위한 드롭다운으로, 플레이스홀더, 그룹, 선택된 행의 체크 표시 및 전체 키보드 지원을 제공합니다. — 기본값 효과 · 레퍼런스 - 스켈레톤 (
skeleton): 로딩 중인 콘텐츠 모양의 맥동하는 플레이스홀더로, 스피너보다 대기 시간이 짧게 느껴지게 합니다. — 지각된 성능 · 레퍼런스 - 스위치 (
switch): 150ms 동안 16px 이동하는 슬라이딩 켜기/끄기 컨트롤로, 모방하는 물리적 토글을 반영합니다. — 어포던스 · 레퍼런스 - 탭 (
tabs): 한 패널을 다른 패널로 제자리에서 교체하는 분할 컨트롤로, 관련 뷰가 화면의 한 지점을 공유하게 합니다. — 청킹 · 레퍼런스 - 텍스트영역 (
textarea): 64px에서 시작하여 콘텐츠에 따라 커지는 여러 줄 텍스트 필드로, 답변이 스크롤바 뒤에 숨겨지지 않게 합니다. — 청킹 · 레퍼런스 - 툴팁 (
tooltip): 호버 또는 포커스 시 지연 없이 나타나고 포인터가 떠나면 사라지는 한 줄 힌트로, 화면 공간을 차지할 가치가 없는 세부 정보에 사용됩니다. — 점진적 공개 · 레퍼런스
출처 및 이슈: https://github.com/kimjusnu/miseui