AI 코딩에서 UI 컴포넌트 고르는 법 예제를 제품에 맞게 적용하기
상태, 키보드 조작, 프레임워크 지원을 살피며 컴포넌트를 선택해요.
AI에게 “모달을 만들어줘”라고 요청하면 화면은 금방 나옵니다. 하지만 그 모달이 Escape 키로 닫히는지, 포커스가 안에 머무는지, 확인과 취소 뒤에 어떤 상태가 되는지는 이름만으로 알 수 없습니다. 컴포넌트 선택은 모양을 고르는 일이 아니라 사용자가 해야 할 일과 상태를 맞추는 일입니다.
이 글은 컴포넌트 라이브러리의 예제를 제품 코드에 적용할 때 확인할 순서를 안내합니다. Quark 카탈로그를 기준으로 실제 구현이 어디까지 제공되는지도 함께 짚습니다.
1. 사용자 과업과 UI 패턴 선택
요청을 “탭을 넣는다”에서 멈추지 말고 사용자의 목표로 바꿔 적습니다. 예를 들면 “청구 내역과 결제 수단을 전환해도 같은 화면 영역에서 정보를 확인한다”입니다. 이 설명을 바탕으로 탭인지, 필터인지, 별도의 페이지 링크인지 판단할 수 있습니다.
- 탭은 같은 맥락 안에서 서로 연결된 콘텐츠 패널을 전환합니다. 키보드 화살표 이동, 선택 상태, 탭과 패널의 연결 관계가 필요합니다.
- 필터는 목록의 결과 범위를 좁히거나 정렬 기준을 바꿉니다. 선택이 여러 개 가능한지, 결과 수가 바뀌는지 확인합니다.
- 아코디언은 화면 안에서 부가 정보를 펼치고 접습니다. 여러 항목을 동시에 열 수 있는지, 제목 버튼이 상태를 알리는지 정합니다.
- 모달 또는 다이얼로그는 작업을 잠시 분리해 확인이나 입력을 받습니다. 닫기, 취소, 제출 이후의 초점과 데이터 상태까지 설계합니다.
겉모양이 비슷해도 사용자 기대와 키보드 동작은 다릅니다. 어떤 컴포넌트가 맞는지 불분명하면 AI에게 구현부터 시키기보다 선택지를 비교하고 각 선택의 상호작용을 먼저 설명하게 하세요.
2. 컴포넌트 상태와 전환
컴포넌트를 고른 뒤에는 정상 상태 하나만 설명하지 않습니다. 아래처럼 상태와 전환을 써두면 디자이너·개발자·AI가 같은 동작을 논의하기 쉬워집니다.
| 대상 | 시작 상태 | 사용자 동작 | 기대 결과 |
|---|---|---|---|
| 탭 | 첫 탭 선택 | 오른쪽 화살표 또는 다른 탭 클릭 | 선택 표시와 콘텐츠 패널이 함께 변경 |
| 검색 필드 | 빈 값 | 검색어 입력 후 지우기 | 목록이 갱신되고, 지우면 전체 결과 복원 |
| 날짜 선택기 | 날짜 없음 | 날짜 선택 후 취소 | 적용을 눌렀을 때만 값 확정 |
| 파일 업로드 | 파일 없음 | 파일 선택 중 오류 | 이유와 가능한 해결 방법을 표시 |
기본·선택·비활성 외에 로딩, 빈 결과, 입력 오류, 성공 알림 중 필요한 상태를 추가합니다. 특히 비동기 동작은 버튼을 눌렀을 때 화면이 어떻게 변하고, 중복 제출을 어떻게 막고, 실패 뒤에 다시 시도할 수 있는지 적어야 합니다.
3. 프레임워크와 프로젝트 규칙
라이브러리에서 지원한다고 표시한 프레임워크가 곧바로 현재 제품과 맞는다는 뜻은 아닙니다. 프로젝트가 사용하는 React 버전, 스타일 방식, 아이콘 패키지, 폼 처리 규칙을 먼저 확인합니다. 그 다음 해당 프레임워크 예제를 골라 기존 규칙에 맞게 적용합니다.
Quark에는 저장소의 컴포넌트 항목 80개의 메타데이터가 Svelte, React, Vue, Vanilla JS를 지원 프레임워크로 표시하고, 네 가지 예제 파일도 둡니다. Vanilla 예제는 패키지 컴포넌트가 아니라 기본적으로 DOM 요소를 돌려주는 자바스크립트 모듈 형태입니다.
이 표시는 네 프레임워크용 제품 패키지가 있거나 모든 예제가 같은 수준으로 검증됐다는 뜻은 아닙니다. 일부 상세 명세는 프레임워크별로 “먼저 프로젝트의 기존 컴포넌트나 UI 라이브러리를 사용하고, 직접 만들 때 참고하라”는 구현 지침을 제공합니다. 또 Quark playground는 카탈로그를 그룹으로 묶어 미리보기하므로 그룹·변형과 개별 폴더 수를 혼동하지 않아야 합니다. 선택한 항목의 실제 코드, 구현 지침, 미리보기, 의존성을 각각 확인하고 앱에 통합해 검증하세요.
4. 컴포넌트 코드 검토
예제의 이름과 설명만 복사하지 말고 최소한 다음을 찾으세요.
- 상태와 이벤트: 선택, 열림, 오류가 어떤 이벤트로 바뀌는가? 값을 부모가 관리하는가, 내부 상태인가?
- 접근성 구조: 버튼의 이름, 역할,
aria-*관계가 적절한가? 탭·다이얼로그·메뉴처럼 키보드 패턴이 중요한 요소는 조작법도 구현되어 있는가? - 스타일 의존성: 전역 CSS, 변수, 폰트, 아이콘, 래퍼 요소 중 반드시 필요한 것은 무엇인가?
- 프로젝트 계약: 제출 데이터의 형식, 유효성 검사, 로딩 처리, 서버 오류 등 앱이 이미 정한 규칙과 충돌하지 않는가?
- 반응형과 긴 콘텐츠: 작은 화면, 긴 라벨, 번역된 문구, 확대된 글자에서도 사용할 수 있는가?
AI에는 “이 예제를 복사해”보다 “프로젝트에서 비슷한 패턴과 의존성을 찾고, 선택한 프레임워크의 예제를 비교한 다음 기존 상태 관리와 접근성 규칙에 맞춰 조정해”라고 요청하는 편이 낫습니다.
5. 디자인 토큰과 브랜드 적용
공통 토큰은 간격과 색상처럼 반복되는 선택을 한 곳에서 관리하게 해 줍니다. 새 컴포넌트에 임의의 HEX 색상이나 간격을 박아 넣기 전에 프로젝트 토큰이 있는지 확인하고, 이미 정의된 의미에 맞춰 적용합니다.
Quark의 예제는 공유 preview.css와 --q-* 토큰, q-preview 래퍼를 전제로 합니다. 이 스타일을 다른 프로젝트에 쓸 경우 공통 스타일을 함께 로드하거나, 앱의 토큰에 대응시켜야 합니다. 일부 예제가 아이콘 패키지를 import할 수 있으므로 실제 소스의 의존성도 확인합니다. Quark의 테마 미리보기는 공유 토큰과 버튼의 일부 동작을 연결하는 어댑터이며, 모든 브랜드 컴포넌트를 공식 구현으로 완전히 변환하는 기능은 아닙니다.
토큰을 연결했다고 제품의 타이포그래피, 메시지 톤, 상호작용까지 자동으로 브랜드에 맞춰지는 것도 아닙니다. 그 부분은 디자이너가 결정하고 검수해야 합니다.
6. 삭제 확인 다이얼로그 예시
사용자가 저장된 결제 수단을 삭제한다고 가정해 봅시다. 무조건 모달을 띄우기 전에 삭제가 되돌릴 수 있는지, 대체 수단이 필요한지, 완료 뒤에 어디로 돌아가야 하는지 확인합니다. 되돌릴 수 없는 작업이면 확인 다이얼로그가 적합할 수 있지만, 초안처럼 복구 가능한 항목은 실행 취소 토스트가 더 빠르고 덜 방해될 수 있습니다.
AI가 제안한 다이얼로그를 적용한다면 다음을 검토합니다.
- 제목이 작업과 대상을 정확히 말하는가?
- 기본 포커스가 안전한 행동에 놓였는가?
- 취소, 닫기, Escape가 같은 정책으로 동작하는가?
- 삭제 중에는 확인 버튼이 중복 제출을 막는가?
- 서버 실패 시 다이얼로그가 닫혀 버리지 않고 오류와 재시도 방법을 보여주는가?
- 완료 후 초점이 삭제한 항목의 다음 위치나 목록 제목처럼 예측 가능한 곳으로 이동하는가?
컴포넌트 샘플이 이런 제품 정책을 대신 결정해 주지는 않습니다. 샘플은 시작점이며, 제품의 실제 데이터 흐름과 사용자 기대에 맞게 수정해야 합니다.
7. AI 코딩 프롬프트 예시
먼저 프로젝트의 프레임워크, 기존 컴포넌트, 토큰, 폼과 접근성 규칙을 살펴봐.
요구사항: [사용자 목표와 해야 할 일]
필요한 상태: [기본, 로딩, 빈 결과, 오류, 성공 등]
제약: [지원 브라우저, 화면 폭, 데이터 계약, 의존성]
후보 컴포넌트의 구조와 키보드 동작을 비교한 뒤 가장 적합한 것을 골라.
기존 규칙에 맞춰 구현하고, 반응형·이름·포커스·오류 흐름을 확인해.
사용한 예제와 새 의존성, 확인하지 못한 부분을 결과에 적어줘.
UI 컴포넌트 출시 전 체크리스트
- 컴포넌트가 사용자의 실제 과업에 맞는가?
- 예상 가능한 입력과 서버 응답 상태를 설명했는가?
- 키보드와 보조기기로 주요 흐름을 완료할 수 있는가?
- 실제 프로젝트의 프레임워크와 스타일·데이터 규칙을 따르는가?
- 작은 화면, 긴 문구, 다국어에서도 동작하는가?
- 샘플에 포함되지 않은 의존성이나 검증 범위를 알고 있는가?
- 사람이 확인해야 할 제품 정책과 시각적 세부를 분명히 했는가?
컴포넌트 라이브러리는 재사용 가능한 출발점을 제공합니다. 좋은 선택은 목록에서 이름을 찾는 데서 끝나지 않습니다. 그 컴포넌트가 어떤 상태를 표현하고, 기존 제품에서 어떻게 동작해야 하는지를 확인하는 데서 완성됩니다.