wasely/ui-max

UI Max

제품 사용성을 장식적 효과보다 우선시하세요. 요구사항을 충족하는 가장 단순하고 일관된 시스템을 선택하십시오. 컴포넌트 라이브러리를 무분별하게 쌓지 마십시오.

제품부터 시작하세요

코드를 변경하기 전에:

1. 프레임워크, 라우터, CSS 시스템, 컴포넌트 라이브러리, 아이콘 및 애니메이션 라이브러리, 폼 스택, 디자인 토큰, 다크 모드, 그리고 기존 패턴을 검사하십시오.
2. 사용자의 목표, 주요 워크플로우, 정보 계층 구조, 기본 및 보조 작업, 필요한 상태, 반응형 표면, 키보드 동작을 정의하십시오.
3. 다음 순서로 재사용하십시오: 로컬 컴포넌트, 기존 디자인 시스템 프리미티브, shadcn/ui, Radix UI, 21st.dev, 특화된 개선 라이브러리, 커스텀 구현.
4. 기존의 안정적인 UI 시스템을 유지하십시오. 하나의 매력적인 컴포넌트를 위해 경쟁하는 전체 시스템을 도입하지 마십시오.

하나의 기반을 선택하세요

새로운 React 제품 인터페이스의 경우, 다음을 기본값으로 사용하십시오:

React + TypeScript + Tailwind CSS
shadcn/ui -> Radix UI 프리미티브
Lucide 아이콘
Motion for React (유용한 경우에만)
React Hook Form + Zod (복잡한 폼)
TanStack Table (고급 테이블 동작에만)

이 스택을 기존 시스템이 있는 프로젝트나 Vue/Svelte 프로젝트에 강제로 적용하지 마십시오. 해당 프로젝트에는 생태계 네이티브 라이브러리를 사용하십시오.

추가 기능을 선택하기 전에 표면을 분류하십시오:

• 핵심 제품 UI: shadcn/ui + Radix UI + Tailwind CSS.
• AI 제품 UI: 실제 AI 워크플로우 패턴에만 Cult UI를 추가하십시오. 절제된 전환 효과에는 Motion Primitives를 사용하십시오.
• 마케팅 페이지: 구조에는 21st.dev를, 신중하게 Magic UI를, 그리고 진정으로 영향력이 큰 섹션에만 Aceternity를 사용하십시오.
• 데이터 밀집 애플리케이션: 정렬, 필터링, 페이지네이션, 선택, 가시성, 가상화 또는 복잡한 데이터 모델이 필요한 경우에만 TanStack Table을 추가하십시오.
• 마이크로 인터랙션: Motion Primitives 또는 Motion을 사용하십시오. UIverse는 접근성 및 유지보수성 검토 후에만 사용하십시오.

라이브러리/컴포넌트를 선택, 설치, 소싱하거나, 대안을 비교하거나, 시각적 패턴을 조사할 때는 references/component-selection.md를 참조하십시오.

일관되게 구현하세요

재사용하거나 복사한 모든 컴포넌트를 프로젝트의 다음 항목에 맞게 정규화하십시오:

• 의미론적 색상 토큰
• 타이포그래피, 간격, 둥글기, 그림자 스케일
• 아이콘 패밀리
• 접근성 규칙
• 반응형 동작
• 라이트 및 다크 테마

산발적인 하드코딩된 값 대신 의미론적 토큰을 사용하십시오. 관련 컨트롤을 가깝게 유지하고, 관련 없는 섹션을 분리하십시오. 부당한 중첩 카드를 피하고, 비교를 위해 목록/테이블을 사용하고, 개별적으로 액션 가능하고 이질적인 항목에는 카드를 사용하십시오. 기본 작업을 명확하게 유지하고, 파괴적인 작업은 일상적인 작업과 멀리 떨어뜨리십시오.

브랜딩에서 달리 요구하지 않는 한 하나의 인터페이스 폰트와 하나의 아이콘 패밀리를 사용하십시오. 모션은 상태, 계층, 연속성, 원인/결과, 진행 상황 또는 포커스를 전달하는 경우에만 사용하십시오. prefers-reduced-motion을 존중하십시오.

실질적인 시각적 구현, 반응형 작업, 상태 설계, 폼, 테이블 또는 접근성 작업 전에 references/design-standards.md를 읽으십시오.

실제 상태를 다루십시오

비동기 또는 데이터 기반 UI의 경우 다음을 고려하십시오:

• 초기 로딩 및 백그라운드 새로고침
• 빈 결과 및 검색 결과 없음
• 성공, 경고, 오류 및 부분 실패
• 비활성화 및 오프라인 상태
• 누락된 권한 또는 통합
• 오래된 데이터

구조를 알 수 있을 때는 스켈레톤을 선호하십시오. 오류 메시지는 무엇이 실패했는지, 알고 있다면 이유, 작업이 보존되었는지 여부, 그리고 문제를 해결하는 방법을 명시하십시오. 완성된 제품에서 의미 없는 모의 데이터, 가짜 분석, 조작된 에이전트 활동 또는 기능하지 않는 컨트롤을 절대 사용하지 마십시오.

기존 UI 정리하기

중복, 간격, 색상, 타이포그래피, 변형, 아이콘, 중첩 레이아웃, 반복되는 유틸리티, 반응성, 접근성, 사용되지 않는 코드/의존성, 애니메이션 과부하, 누락된 상태를 감사하십시오.

버튼, 입력, 상태 배지, 대화상자, 메뉴, 탭, 페이지 헤더, 빈/오류/로딩 상태, 사이드바 항목, 프로젝트 행과 같이 반복되거나 동작을 포함하는 프리미티브를 통합하십시오. 일관성, 로직, 재사용 또는 테스트 이점 없이 일회성 마크업을 추상화하지 마십시오.

반복되는 값을 토큰화하십시오. 불필요한 래퍼, 중첩 카드, 장식용 구분선, 반복되는 레이블, 중복된 동작/상태, 과도한 설명 및 부당한 모션을 제거하십시오.

렌더링된 출력 검증하기

다음을 확인하십시오:

• 의미론적 HTML, 접근 가능한 이름, 레이블, 논리적 탭 순서, 키보드 작동, 대화상자 포커스, 가시적 포커스 및 대비
• 로딩, 빈, 비활성화, 오류, 성공, 긴 텍스트 및 파괴 확인 상태
• 좁은 및 넓은 레이아웃에서 잘림, 읽을 수 없는 테이블, 레이아웃 이동 또는 가로 오버플로우 없음
• 축소 모션 동작, 라이트/다크 테마 및 반응형 내비게이션
• 포맷터, 린트, TypeScript, 테스트, 프로덕션 빌드 및 콘솔 출력

해당되는 경우 320, 375, 768, 1024, 1280 및 1440 px에서 테스트하십시오. 브라우저 확장 프로그램의 경우 약 320–420 px의 팝업 너비와 약 320–600 px의 사이드 패널도 테스트하십시오.

완료를 주장하기 전에 실제로 렌더링된 UI를 좁은 너비와 넓은 너비에서 검사하십시오. 스크린샷 루프 또는 프로젝트의 기존 시각적 검증 워크플로우를 사용하고, 실제 대상에서 플랫폼별 표면을 확인하십시오.

UI 작업 보고하기

페이지를 설계하거나 재구축하라는 요청을 받으면 다음에 대한 간결한 섹션을 제공하십시오:

1. 제품 해석: 목표, 주요 워크플로우, 핵심 정보, 기본 작업.
2. 컴포넌트 계획: 구조, 재사용 가능한 컴포넌트, 기반, 특화된 추가 기능, 반응형 동작, 중요한 상태.
3. 구현: 기존 스택에서 작동하는 코드.
4. 검증: 접근성, 반응형, 상태, 키보드 동작, 디자인 토큰 일관성 및 렌더링된 시각적 검토.

사용자가 옵션을 요청하지 않는 한 라이브러리 카탈로그를 반환하지 마십시오.