디자인 원칙

PLY UI는 개발자가 예측 가능하게 조합하고 수정하며, 사용자가 명확하게 이해하고 사용할 수 있는 UI를 만듭니다.

일관성은 모든 것을 똑같이 보이게 만드는 것이 아닙니다. 같은 의미와 상황에 예측 가능한 규칙을 적용하는 것입니다.

이 원칙은 신규 설계와 기존 컴포넌트 개선에 적용하는 기준입니다. 모든 기존 구현이 이미 충족했다는 선언은 아닙니다. 지원 범위와 확인된 제한은 각 컴포넌트 문서에 구분해서 기록합니다.

대상과 범위

PLY UI는 게임·커뮤니티 웹 서비스를 만드는 한국어 개발자가, Roblox의 친숙한 감성으로 완성된 화면을 빠르게 만들 수 있는 React UI 킷입니다.

• 주 사용자: 관리자 본인의 프로젝트가 먼저입니다. 다른 개발자도 원하면 같은 품질로 사용할 수 있게 배포합니다.
• 대상 환경: 웹 React 19입니다. Roblox 게임 안 UI(Luau)는 범위가 아닙니다. Roblox 로고·에셋과 픽셀 단위 복제도 목표가 아닙니다.
• 구성: 어디서나 쓰는 기본 층(Button, Field, Dialog 등)과, 특정 화면을 위한 선택형 도메인 층(게임 카드, 채팅, 배경 등)으로 나눕니다. 완성도는 기본 층부터 확보합니다.
• 배포: npm 패키지가 주 경로입니다. 컴포넌트를 크게 고쳐 쓸 때는 복사 CLI를 사용합니다. 일상적인 스타일 변경은 props → 토큰 → className 순서로 지원해서 복사 없이 해결되게 합니다.
• 대표 화면: 설계와 점검은 실제 화면 기준으로 판단합니다. 현재 기준은 AI 채팅 서비스의 채팅 시작·대화·대화 기록·기억과 설정, 게임 사이트의 탐색·상세 화면입니다. 모든 화면에서 빈 상태·로딩·오류, 좁은 화면, 다크 테마, 긴 한국어 문구를 함께 확인합니다.

기본 조건

다음 조건은 모든 원칙에 공통으로 적용합니다.

• 접근성: 다양한 입력 방식과 보조기기로 정보와 핵심 기능에 접근할 수 있습니다.
• 작업 완결성: 환경이 달라져도 필요한 작업을 끝낼 수 있습니다.
• 사용자 통제권: 진행 중인 작업에서 벗어나거나 취소할 수 있습니다. 취소가 불가능한 행동은 실행 전에 결과를 알립니다.
• 오류 예방과 복구: 실수를 줄이고, 실패했을 때 원인과 해결 방법을 안내합니다. 되돌릴 수 있는 작업에는 적절한 복구 수단을 제공합니다.

1. 환경과 조합이 달라져도 안정적으로

컴포넌트부터 완성된 화면까지 구조와 사용성을 유지합니다. 기본 사용은 안전하고, 변경 방법은 명확해야 합니다.

• 다른 컴포넌트와 함께 사용해도 의도하지 않은 늘어남·축소·겹침·잘림이 발생하지 않습니다.
• 단독 예제가 아니라 대표 화면에서 함께 쓰일 때 일관되게 보이고 동작하는지로 판단합니다.
• 버튼과 입력창뿐 아니라 다이얼로그·메뉴·사이드바·토스트 등 모든 컴포넌트를 반응형 설계 대상으로 다룹니다.
• 화면 너비와 높이, 확대, 콘텐츠 양, 가상 키보드, 입력 방식의 변화를 고려합니다.
• 환경에 따라 배치·크기·표현 방식은 바꿀 수 있지만, 작업 목적·정보·핵심 기능은 유지합니다.
• 기본값만으로 일반적인 사용이 가능해야 합니다. 일상적인 수정에 내부 구조를 우회하는 코드를 요구하지 않습니다.
• 속성·스타일·상태를 누가 제어하는지 명확히 합니다. 지원하는 환경과 조합, 제한과 대안을 문서화합니다.

판단 질문: 개발자가 문서 예제 밖에서도 의도한 화면을 만들고, 사용자가 그 화면에서 작업을 끝낼 수 있나요?

2. 정보와 동작을 명확하게

무엇이 중요하고, 무엇을 할 수 있으며, 조작 결과가 무엇인지 이해할 수 있게 합니다.

• 같은 역할과 상태에는 일관된 표현을 사용하고, 다른 중요도와 의미는 구분합니다.
• 크기·색·명암·간격·배치로 정보의 우선순위와 관계를 드러냅니다.
• 한 묶음으로 놓인 작업 버튼(텍스트 버튼, 아이콘 버튼, 토글)은 같은 size를 씁니다. 중요도는 크기가 아니라 variant(색·강조)로 나눕니다. 짧은 수치 정보(추천률, 접속자 수 등)는 같은 모양(아이콘 + 숫자)으로 맞추고, 뜻은 보조기기용 글자로 전합니다.
• 선택·포커스·비활성·로딩·오류 상태를 구분합니다. 중요한 정보는 색상이나 모션 하나에만 의존하지 않습니다.
• 시각적 표현, 실제 동작, 보조기기에 전달하는 의미를 일치시킵니다.
• 의미에 맞는 HTML 요소(button, a, nav, ul/li, h2, table 등)를 먼저 사용하고, HTML로 표현할 수 없을 때만 ARIA를 보완합니다. 래퍼나 합성 때문에 지키기 어려운 곳은 render, 헤딩 레벨 같은 변경 수단을 제공하고 제약을 문서에 기록합니다. 확실하지 않은 요소와 패턴은 MDN HTML 요소와 WAI-ARIA 작성 가이드를 확인하고 근거를 남깁니다.
• 기본 문구는 한국어입니다. 한국어 문구의 길이·줄바꿈과 날짜·숫자 표기를 기본값으로 맞추고, 다른 언어는 label 속성으로 바꿀 수 있게 합니다.
• 익숙한 사용 관례를 존중합니다. 새로운 방식은 구체적인 문제를 개선할 이유와 근거가 있을 때 도입합니다.
• 필요한 정보와 행동은 찾기 쉽게 제공합니다. 짧고 구체적인 문구를 사용하되, 간결함을 위해 필요한 설명을 없애지 않습니다.

판단 질문: 처음 사용하는 사람도 현재 상태와 가능한 행동을 이해하고, 조작 결과를 확인할 수 있나요?

3. 모션으로 변화를 연결하기

모션은 조작에 반응하고, 상태와 공간의 변화를 이해하도록 돕습니다.

• 등장·퇴장·이동·펼침·교체의 관계를 보여줍니다.
• 같은 역할에는 공통된 모션 규칙을 적용하되, 거리·크기·반복 사용 빈도에 맞게 조정합니다.
• 조작에는 빠르게 피드백합니다. 연출을 위해 불필요한 대기 시간을 만들지 않습니다.
• 연속 조작·중단·반전에도 올바른 상태로 이어집니다.
• 내용의 가독성, 배치의 안정성, 조작 가능성을 해치지 않습니다.
• 모션 감소 설정에서도 정보와 기능을 유지합니다.
• 실제 환경에서 성능을 확인하고, 이해에 도움이 되지 않는 움직임은 줄이거나 제거합니다.

판단 질문: 이 움직임은 변화를 설명하며, 사용자의 작업을 방해하지 않나요?

우선순위

안정성을 먼저 확보하고, 명확성을 함께 충족하며, 모션으로 둘을 지원합니다.

안정성을 이유로 이해하기 어려운 UI를 허용하지 않습니다. 명확성을 위해 기능이나 접근성을 없애지 않습니다. 모션은 앞의 조건을 충족하는 범위에서 설계합니다.

예를 들어 작은 화면에서 다이얼로그를 전체 화면으로 바꾸는 것은 가능합니다. 그러나 확인 버튼이 가려지거나 입력 내용이 사라져서는 안 됩니다.

문서와 검증 체계

원칙을 실제 작업에 적용할 수 있도록 문서를 세 단계로 나눕니다.

사람과 AI 모두 변경 전에 관련 문서를 확인합니다. 변경 후에는 해결한 문제, 설계 이유, 기존 사용에 미치는 영향, 검증한 범위와 남은 한계를 기록합니다.

확정된 결정과 제안은 구분합니다. 자동 테스트, 시각 검사, 실제 사용 관찰은 서로 보완하며, 테스트 통과만으로 좋은 UX가 검증됐다고 판단하지 않습니다.

공통 규칙은 반응형과 조합, 모션, 각 컴포넌트 문서에서 확인합니다. 변경 절차와 검증 명령은 개발 안내를 참고하세요. 아직 정리되지 않은 규칙과 검증 조건은 관련 컴포넌트를 개선할 때 명시하며, 확인하지 않은 범위를 지원한다고 선언하지 않습니다.