본문으로 건너뛰기

JunkBox 공통 UI 가이드

1. 문서 목적​

  • 이 문서는 JunkBox 관리자 화면 구현 시 공통 UI 원칙을 일관되게 적용하기 위한 기준 문서임.
  • 운영 화면의 레이아웃, 버튼, 그리드, 토스트, 여백, 메시지 사용 규칙을 정의함.
  • 새로운 화면은 화면 전용 CSS 없이 shared-ui 공통 자산만으로 구현하는 것을 기본 원칙으로 삼음.
  • JunkBox의 UI 원칙은 이 문서를 단일 소스 오브 트루스로 삼으며, 다른 가이드는 UI 원칙을 중복 정의하지 않고 필요 시 이 문서를 참조함.

2. 최우선 원칙​

2.1 스타일 중앙화​

  • 앱별 CSS 파일을 만들지 않음.
  • 화면별 CSS 파일을 만들지 않음.
  • 특별한 사유가 없으면 모듈별 CSS 파일도 만들지 않음.
  • <style> 태그와 style="" 인라인 스타일을 사용하지 않음.
  • 모든 스타일은 libs/shared-ui에서 관리함.
  • PC/모바일 전환 폭 같은 반응형 기준값도 스타일과 마찬가지로 libs/shared-ui 한 곳에서만 정의하고, 화면·앱·CSS 규칙에 숫자를 직접 쓰지 않음. 세부 규칙은 4.4를 따름.
  • 화면 구현 시 템플릿은 jb-* 공통 클래스만 조합해서 사용함.
  • 화면별로 필요한 보정이 있더라도 먼저 shared-ui 공통 클래스로 승격할 수 있는지 검토함.
  • 공통 적용 가치가 없는 화면 전용 스타일은 추가하지 않고, 가능한 한 기존 공통 클래스 조합으로 해결함.

2.2 구조와 스타일 분리​

  • 각 화면은 데이터 구조와 마크업 구조만 정의함.
  • 색상, 여백, 폰트, 버튼, 반응형 규칙은 shared-ui가 담당함.
  • 화면에서 새로운 모양이 필요하면 먼저 shared-ui에 공통 클래스를 추가한 뒤 사용함.
  • 실제 역할이 없는 중복 wrapper div를 추가하지 않음.
  • 선택 상태를 설명하지 않아도 되는 화면에 관성적으로 status chip을 추가하지 않음.

2.3 시각 톤 기준​

  • JunkBox 공통 다크 UI 톤은 현재의 검은 배경 운영 콘솔 감성을 유지하되, ChatGPT 또는 Open WebUI 다크모드와 유사한 저대비 톤앤톤 체계를 기준으로 삼음.
  • 순백에 가까운 강한 외곽선, 과한 대비, 화면마다 제각각인 강조색 사용을 지양함.
  • 패널, 카드, 입력창, 보조 버튼, 칩, 바텀시트는 모두 저채도 회색 경계 + 아주 약한 레이어 배경 + 절제된 그림자 규칙 안에서 일관되게 구성함.
  • 구분은 가능한 한 강한 테두리보다 배경 톤 차이, 간격, 깊이감으로 해결함.
  • 새로운 운영 화면을 만들 때는 임의의 시각 스타일을 만들기보다 shared-ui 공통 다크 톤 규칙을 그대로 따르는 것을 우선함.
  • Android 네이티브 앱은 웹과 별개로 검정·흰색·민트 3색만 사용함. 앱 색상 원칙은 네이티브 앱 가이드 3.2절이 소유하며 웹의 4색과 jb-* 클래스를 네이티브에 쓰지 않음.
  • 성공·실패처럼 즉시 식별이 필요한 상태는 shared-ui 공통 상태 아이콘을 사용함. 성공은 녹색 IconCircleCheck와 jb-status-icon-success, 실패는 적색 IconCircleX와 jb-status-icon-failure 조합을 사용함.
  • 상태 아이콘의 색상과 제목 사이 간격은 shared-ui 클래스가 담당하며 화면별 색상·여백 CSS를 추가하지 않음.

2.4 TypeScript 우선 구현​

  • 운영 화면 인터랙션 소스는 .ts 또는 .tsx로만 작성함.
  • 신규 화면 로직을 .js로 직접 작성하지 않음.
  • TypeScript strict 기준을 유지함.
  • API 응답, 테이블 행, 페이지 props는 명시적 타입으로 선언함.
  • 타입 선언 없이 any를 광범위하게 사용하지 않으며 strict 기준을 깨는 임시 완화 설정을 추가하지 않음.
  • 브라우저 전역 변수 주입을 기본 구조로 사용하지 않으며, 환경값은 import.meta.env와 타입 선언을 통해 관리함.

2.5 PC 우선 운영 화면 기준​

  • hub-api 성격의 운영 화면은 FHD 기준 PC 우선으로 설계함.
  • 전체 페이지 스크롤보다 내부 그리드와 패널 스크롤을 우선함.
  • 한 화면에서 더 많은 데이터를 보여주는 밀도를 우선함.
  • 운영 화면은 FHD 기준에서 브라우저 바깥 세로 스크롤이 생기지 않도록 구성함.
  • 스크롤이 필요하면 페이지 전체가 아니라 그리드, 우측 편집 패널, 모달 본문 같은 내부 작업 영역에서만 발생하도록 설계함.
  • PC 전용 본문은 최소 1440px 폭을 유지함. 뷰포트가 이보다 좁으면 공통 메뉴바는 현재 뷰포트 폭을 유지하고 본문 .jb-main 안에서만 가로 스크롤하여 오른쪽 끝까지 접근함. 대시보드와 모바일 전용 본문에는 이 최소 폭을 적용하지 않음.
  • 로그인, 포털, health 모바일 화면처럼 모바일 전용으로 정의된 화면은 이 규칙의 예외이며, 공통 360px 고정 폭 기준을 사용함.
  • 대시보드처럼 PC/모바일 겸용으로 정의된 운영 화면은 PC FHD 밀도와 모바일(뷰포트 1440px 미만) 360px 고정 폭 세로 카드 목록을 모두 만족해야 함.

2.6 화면 문구 작성 기준​

  • 사용자가 화면에서 보는 버튼, 라벨, 토스트, 확인창, 상태 문구는 소스 코드에 한국어 문구를 직접 작성함.
  • 텍스트만을 위해 DB 메시지 마스터를 추가하지 않음.
  • 같은 의미의 공통 표현은 문서화된 표현 규칙과 현재 화면 문구를 우선 재사용함.
  • 공통코드 라벨, 메타 설정값처럼 데이터 자체가 DB 마스터데이터인 값은 현재 코드/메타 조회 구조를 사용함.
  • 로그, 콘솔, 주석, 개발자 디버그 문자열은 사용자 노출 UI 텍스트 기준에 포함하지 않음.

2.7 날짜 표기 표준​

  • 날짜만 표기할 때의 기본 형식은 YYYY-MM-DD임.
  • 날짜와 시간을 함께 표기할 때의 기본 형식은 YYYY-MM-DD HH24:MI:SS임.
  • 연도(YYYY)를 생략하고 월·일만 표기할 때의 표준 형식은 MM-DD임. MM.DD, MM/DD, M월 D일 등 다른 구분자나 형식을 쓰지 않음.
  • 월·일로 날짜 범위를 표기할 때는 MM-DD ~ MM-DD처럼 ~ 앞뒤에 공백을 두어 날짜 내부의 -와 범위 기호를 구분함. 요일을 함께 표기하면 MM-DD (요일) ~ MM-DD (요일)처럼 요일을 한 글자로 각 날짜 뒤에 붙임.
  • 웹은 @shared-ui/utils/datetime의 formatDateWithWeekdayInKst(YYYY-MM-DD (요일)), formatMonthDayWithWeekdayInKst(MM-DD (요일)), formatMonthDayRangeWithWeekdayInKst(MM-DD (요일) ~ MM-DD (요일))를 사용함. 화면에서 slice 등으로 월일 표기를 직접 만들지 않음.
  • 신규 화면과 기존 기능 변경 모두 날짜·시각의 기본값, 사용자 입력, 날짜 필터 및 표시에 Asia/Seoul을 사용함. 날짜 전용 문자열과 SQLite의 offset 없는 KST 일시는 그대로 표시하고, offset 포함 일시는 KST로 변환함.
  • 웹은 @shared-ui/utils/datetime 또는 이를 사용하는 공통 포맷 함수를 사용함. datetime-local 입력의 값은 KST로 해석하고, 새 API 계약에서 시점을 전송할 때는 +09:00을 명시함. 브라우저 로컬 시간대에 의존하는 파싱과 UTC toISOString()의 날짜 부분을 업무일에 사용하지 않음.
  • locale 기본 문자열이나 화면별 임의 포맷을 사용하지 않고 공통 포맷 함수 기준으로 통일함.
  • 외부 사이트가 제공한 게시물 날짜처럼 원본 문자열 자체가 사용자에게 의미 있는 source metadata이면, 명확하게 해석 가능한 날짜/시간만 공통 표준으로 정규화하고 해석이 모호한 형식은 원본 문자열을 보존함.
  • health 세션 목록 카드의 운동일은 사용자가 운동 요일을 빠르게 구분해야 하므로 YYYY-MM-DD (요일) 형식을 사용함.

2.8 단위 표기 표준​

  • 신규 화면과 기존 기능 변경 모두, 웹 화면·서버가 만드는 안내문과 알림 문구·Android 네이티브 화면 문구의 숫자 단위 표기에 이 표준을 적용함. 별도 요청이 없어도 따름.
  • 의도는 국제 단위 표기(숫자와 단위 사이 한 칸)와 한글 맞춤법 제43항(단위 의존 명사는 붙여 쓸 수 있음)을 함께 지켜, 표준을 지키면서 한국어 화면에서 어색하지 않게 하는 것임.
구분규칙예
기호 단위숫자와 줄바꿈 방지 공백(U+00A0)으로 띄움1,197 kcal, 72.5 kg, 5.2 km, 250 mL, 120 ms, 5 km/h, 36.5 °C, 512 MB
한글 단위숫자에 붙임12,000원, 3회, 5건, 30분, 2세트, 4명
붙이는 기호%, 각도 °, 각분 ′, 각초 ″은 붙임. °C는 기호 단위 규칙으로 띄움85%, 45°, 5′30″
범위단위를 끝에 한 번만 씀10~20 kg, 3~5회
예정 포함 합계합계 뒤 괄호에 예정분을 적음2,087 kcal (890 kcal 예정 포함)
라벨·헤더이름 뒤 공백과 괄호로 단위를 적음중량 (kg), 금액 (원)
시간·페이스콜론 표기는 단위 없이 유지함45:30, 5:30/km
  • 기호의 대소문자를 정확히 씀(kcal, kg, mL, km/h, MB). 공통 스타일로 대문자 변환을 걸지 않음.
  • 천 단위 구분 쉼표를 씀. 연도·식별자·소수부에는 쓰지 않음.
  • 숫자와 단위가 서로 다른 요소(큰 숫자와 작은 단위 글자, 입력창 옆 단위)이면 간격은 공통 스타일이 맡고 문자열에 공백을 넣지 않음. 접근성 문구와 툴팁처럼 한 줄 문구는 위 표를 따름.
  • 적용 제외는 사용자 입력 원문, 외부 서비스 원문, DB 마스터데이터 값, 음성(TTS) 읽기 문구, 로그·주석·디버그 문자열임.
  • 문자열을 직접 이어 붙이지 않고 공통 포매터를 사용함: 웹은 @shared-ui/utils/units의 formatQuantity·withUnit·formatPlannedIncluded·formatPlannedNote, Python은 junkbox_shared_core.units의 format_quantity·with_unit, Android는 JunkboxUnits.withUnit임.
  • 예정분을 따로 표기하는 모든 화면(Health 음식, Hub 대시보드, QuestLog 미션)은 숫자를 합계와 (예정분 예정 포함) 형태로 표기하고, 바·게이지의 구간 색 분리와 판정은 먹은 양 기준으로 유지함.

2.9 안내·빈 상태·오류 표기​

  • 신규 화면과 기존 기능 변경 모두, 웹 화면의 안내 코멘트·빈 상태·오류 문구는 shared-ui의 NoticeCard로만 표기함. 카드 없이 텍스트만 두거나 화면마다 클래스를 조립하지 않음.
  • 의도는 같은 역할의 문구가 한 가지 외형과 한 가지 접근성 역할(role)로 보이게 하는 것임.
tone용도외형·역할
note설정의 적용 시점처럼 화면 맥락을 알려 주는 안내 코멘트. 선택 label로 작은 제목을 둠소프트 카드, role="note"
empty목록·화면이 비었을 때의 안내(확정된 이력이 없습니다. 등)note와 같은 소프트 카드, role="status"
error오류·경고(조회 실패, 판정 불가 사유, 검증 문구)상태 색 표준의 실패 색, role="alert"
  • 문자열 자식은 문단으로 감싸 표시하고, 버튼 같은 요소는 그대로 넣음. 문단을 나누려면 문자열을 {"…"}로 나눠 자식으로 전달함.
  • 백그라운드 진행을 나타내는 NoticeCard에는 inProgress를 사용함. 공통 진행 색(IN_PROGRESS)과 role="status"가 적용됨.
  • jb-mobile-empty, jb-mobile-error, jb-empty-text는 없으며, jb-status-notice는 NoticeCard 내부에서만 사용함. just check-notices(scripts/check_notice_rules.py)가 앱 화면의 직접 사용을 검사함.
  • 카드나 모달 안에서 제목 아래에 붙는 부제, 날짜·출처처럼 항목 옆에 붙는 보조 텍스트는 안내 코멘트가 아니므로 NoticeCard로 감싸지 않음. 로딩 문구는 SkeletonBlock·LoadingModal이 맡음.

3. 공통 자산 위치​

3.1 CSS​

  • 공통 앱 셸, 패널, 폼, 버튼, 레이아웃 규칙은 libs/shared-ui의 공통 스타일에서 관리함.
  • Tabulator 공통 스타일도 shared-ui가 관리함.
  • 앱은 빌드된 산출물만 링크함.
  • 공통 CSS 링크는 shared-ui의 stylesheet 매크로에서만 선언함.
  • 공통 베이스 템플릿과 standalone 템플릿은 같은 shared-ui stylesheet 매크로를 호출해 CSS 조합만 선택함.
  • 개별 화면 템플릿에서 hub-ui-base.css, hub-ui-mobile.css, hub-ui-desktop.css, Tabulator vendor CSS, junkbox-tabulator.css를 중복 링크하지 않음.
  • 모바일 화면은 기본적으로 hub-ui-base.css + hub-ui-mobile.css 조합을 사용하고, 데스크탑 운영 화면은 hub-ui-base.css + hub-ui-desktop.css 조합을 사용함.
  • Tabulator 화면은 vendor/tabulator/tabulator_simple.min.css + junkbox-tabulator.css 조합을 shared-ui stylesheet 매크로의 Tabulator 옵션으로 함께 로드함.
  • SPA 라우트 전환, skeleton, 터치 피드백, reduced motion 대응처럼 화면 크기와 무관한 상호작용 규칙은 hub-ui-base.css에서 제공함.
  • 모바일 고정 폭, 모바일 바텀 액션바, 모바일 시트처럼 실제 모바일 레이아웃에 종속된 규칙은 hub-ui-mobile.css에서 제공함.
  • 공통 베이스 템플릿은 별도 <style> 블록을 소유하지 않으며, 모든 시각 규칙은 shared-ui CSS 산출물로만 공급됨.

3.2 템플릿​

  • 공통 베이스 템플릿을 사용함.
  • 공통 그리드 헤더 마크업을 사용함.
  • 앱 템플릿은 공통 베이스를 extends 하고 필요한 블록만 채움.
  • 로그인, Chess 화면처럼 공통 앱 셸을 직접 상속하지 않는 standalone HTML 템플릿도 CSS 링크를 직접 쓰지 않고 shared-ui stylesheet 매크로를 import해 사용함.
  • standalone 템플릿은 화면 구조만 소유하고, 공통 CSS 파일 조합과 vendor CSS 링크 선언은 shared-ui 템플릿 책임으로 둠.

3.3 스크립트​

  • Tabulator 공통 헬퍼와 토스트 처리는 shared-ui 공통 스크립트를 사용함.
  • 공통 앱 셸 동작도 shared-ui 스크립트를 사용함.
  • 화면별 TypeScript 코드는 데이터 로딩, 이벤트 연결, API 호출만 담당함.
  • 서버는 초기 props만 주입하고, 브라우저는 이를 읽어 React 화면을 마운트하는 구조를 기본으로 함.
  • 빌드 자산 참조는 고정 파일명 하드코딩이 아니라 Vite manifest 해석 구조를 사용함.
  • SPA 화면은 공통 앱 셸 링크 클릭을 junkbox:spa-navigate 이벤트로 전환하고, React Router navigation과 shared-ui SPA 유틸로 실제 본문 전환을 처리할 수 있음.

3.4 SPA 상호작용 기준​

  • SPA 적용은 서버 라우트가 같은 앱 셸을 반환하고, 클라이언트 React Router가 화면 선택을 담당하는 구조를 기준으로 함.
  • SPA 화면의 라우트 본문은 SpaRouteTransition으로 감싸고, route settling은 useSpaRouteSettling으로 처리함.
  • 브라우저 View Transition API는 runSpaViewTransition을 통해 사용하며, 지원하지 않는 브라우저에서도 동일 navigation callback이 실행되어야 함.
  • 빠르게 끝나는 데이터 요청의 로딩 깜빡임은 useStableLoading으로 제어함.
  • 최상위 데이터 로딩 placeholder는 SkeletonBlock을 우선 사용함.
  • reduced motion 환경에서는 라우트 전환, skeleton shimmer, 오브젝트 안착 애니메이션이 사용자 설정을 존중해야 함.
  • SPA 전환 체계는 모바일 전용이 아니며, PC 운영 화면도 앱 단위 SPA 구조가 필요한 경우 같은 공통 체계를 사용할 수 있음.

4. 화면 레이아웃 기준​

4.1 전역 앱 셸​

  • Hub를 제외한 웹앱의 상단 브랜드 이름(brand_title)과 app_name은 JunkBox {Portal menu_name} 형식으로 통일함. Portal 카드는 짧은 앱 이름을 유지하고 상단에서도 해당 대소문자를 사용함(예: JunkBox Health, JunkBox Track, JunkBox SipMon). 신규 앱과 앱 명칭 변경 시 이를 확인하며 접두어를 중복하지 않음. Hub의 기존 이름과 화면별 본문 제목·내비게이션·모듈 코드·아이콘 slug·PWA 표시명에는 이 규칙을 확대하지 않음.
  • 전역 메뉴 체계는 공통 셸 기준으로 구성함.
  • 뷰포트 폭 1440px 이상(PC)에서는 상단 메뉴를 기본으로 함.
  • 뷰포트 폭 1440px 미만(모바일)에서는 토글형 드로어 메뉴를 사용함.
  • 공통 메뉴바의 반응형 기준은 각 화면 본문 폭 정책과 분리함.
  • PC-only 본문 화면도 모바일 뷰포트에서는 공통 메뉴바가 드로어 메뉴로 전환됨.
  • 모바일 전용 본문 화면이더라도 글로벌 헤더는 필요한 경우 반응형 메뉴 체계를 그대로 유지할 수 있음.
  • 모바일 전용 본문 화면은 shared-ui의 고정 폭 클래스와 safe-area 대응 규칙을 그대로 사용함.

4.2 본문 여백​

  • 상단 메뉴바와 본문 좌우 여백은 기본 1rem 기준임.
  • 모바일 전용·겸용 본문 카드의 외부 좌우 여백은 shared-ui의 --jb-mobile-content-gutter 한 값으로 관리하며 기본값은 양쪽 각각 6px임. 공통 jb-main이 한 번 적용하고 페이지 래퍼는 외부 좌우 여백을 중복 추가하지 않음. Chess 단일 열과 모바일 대시보드도 같은 값을 사용함.
  • 과한 패딩, 중첩 래퍼, 불필요한 감싸기 div를 만들지 않음.
  • 동일한 결과를 낼 수 있다면 더 얇은 마크업 구조를 우선함.
  • jb-panel 같은 공용 래퍼가 화면 구조를 한 번 더 감싸서 실질적 이점이 없다면 제거함.
  • 대표 작업 화면은 jb-workspace-screen과 jb-workspace-grid 중심의 얇은 구조를 우선 사용함.
  • 공통 루트 컨테이너와 화면 마운트 루트는 부모 높이를 끝까지 물고 있어야 하며, 화면마다 다른 높이 계산이 생기지 않도록 공통 규칙으로 관리함.

4.3 작업형 화면​

  • FHD 기준 화면은 좌우 폭을 넓게 사용함.
  • 데이터 관리 화면은 패널 간 여백을 최소화함.
  • 페이지 전체 스크롤보다 내부 패널 스크롤을 우선함.
  • 상단 공용 페이지 헤더가 실질적 작업 정보를 늘리지 못하면 숨기고, 화면 본문 안에 간결한 제목만 배치함.
  • 운영 화면 제목은 과도한 display 타이포그래피를 사용하지 않고, h2 수준의 절제된 크기를 기본으로 함.
  • 동일 계열의 관리 화면은 제목 크기와 표기 방식을 통일함.
  • 작업형 화면 제목과 바로 아래 작업 영역 사이에는 너무 붙어 보이지 않도록 공통 간격을 둠.
  • 좌측 선택 그리드와 우측 편집 패널 구조에서는 기본적으로 6:4 비율을 우선 검토함.
  • 상단 요약 패널, 필터/상태 패널, 하단 그리드 패널이 함께 있는 화면은 상단 패널이 내용 높이만큼만 차지하고, 하단 그리드 패널이 남는 높이를 모두 차지하도록 구성함.
  • 상단 요약이나 메타 영역이 줄바꿈으로 높이가 늘어나면 그만큼 아래 그리드 높이가 줄어들어야 하며, 아래 영역 위로 겹치거나 침범하면 안 됨.
  • 포털처럼 카드형 소비 화면은 일반 작업형 화면과 다른 예외 패턴이며, 공통 shared-ui 클래스 내에서만 전용 레이아웃을 제공함.
  • 포털 카드형 소비 화면은 모바일에서도 기본 2열 구조를 유지하며, 카드 내부 타이포와 아이콘 크기만 모바일 기준으로 보정함.
  • 대시보드 화면은 카드형 동적 데이터 화면이며 PC 기준 4열 x 2행 고정 슬롯 배치와 모바일(뷰포트 1440px 미만) 기준 1열 세로 배치를 모두 지원함.
  • 대시보드 큰 카드는 PC 기준 항상 한 슬롯만 차지하고, 카드 수가 한 행보다 적어도 카드 높이를 화면 남은 높이 전체로 늘리지 않음.
  • 대시보드 카드 내부 목록은 고정 카드 높이를 넘으면 카드 내부 스크롤을 사용하고, 페이지 전체 스크롤보다 카드 내부 밀도 조정을 우선함.
  • 대시보드처럼 외부 수집 데이터를 표시하는 화면은 카드별 갱신 시각, 오류 상태, 외부 전체보기 링크를 자체적으로 표현해야 함.
  • 대시보드처럼 홈서버/시스템 메트릭을 표시하는 화면은 요약 수치, 게이지, 세부 목록을 같은 카드 그리드 안에서 배치하고 페이지 전체 스크롤보다 카드 내부 밀도 조정을 우선함.
  • 대시보드의 카드형 정보 행과 지표 타일은 플랫한 저대비 배경과 얇은 경계선만 사용하며, 특정 카드만 강한 색상 음영이나 그라데이션으로 분리하지 않음.

4.4 반응형 전환 기준​

  • 신규 웹 화면과 기능 UI의 기본 본문은 공통 360px 고정 폭을 사용하는 모바일 레이아웃 한 벌임. 화면 구성 예외를 제안하는 조건은 junkbox/AGENTS.md의 웹 화면 구현 규칙을 따름.
  • 반응형 본문은 PC와 모바일 두 벌만 관리함. 중간 단계는 Chess 전용 예외를 따름.
  • PC/모바일 전환점은 뷰포트 폭 1440px임. 1440px 이상은 PC, 1439px 이하는 모바일로 처리함. PC 화면은 FHD(1920px) 전체화면을 기준으로 설계하고, 배율 125%의 FHD(1536px) 환경에서도 PC로 유지되도록 1440px를 최소 보장 폭으로 삼음.
  • 전환 기준은 높이나 기기 종류가 아니라 뷰포트 폭만 사용함. 공통 앱 셸 네비게이션, Hub 대시보드, 워크스페이스 상세 오버레이는 모두 이 한 기준으로 전환됨. PC 전용 본문은 1440px 미만에서 본문 정책을 유지하고 공통 메뉴바만 드로어로 전환됨.
  • 기준값의 단일 정의 위치는 libs/shared-ui/src/junkbox_shared_ui/breakpoints.json임. Tailwind preset의 screens가 이 값을 읽어 CSS는 @media (min-width: theme('screens.pc')), @media (width < theme('screens.pc'))로 참조하고, app-shell.ts 같은 스크립트는 같은 JSON을 import함.
  • 화면·앱·CSS·스크립트에서 1440 등 폭 숫자를 직접 쓰지 않음. 새 @media 폭 조건, window.innerWidth·matchMedia 폭 비교, Tailwind 기본 반응형 접두어(sm:, md:, lg: 등)를 추가하지 않음.
  • (hover: none) and (pointer: coarse) 같은 입력 방식 판별과 prefers-reduced-motion은 해상도 전환점이 아니므로 별도 규칙으로 허용함.
  • Chess는 예외이며 3단계 전용 기준을 사용함. 이 값도 같은 breakpoints.json의 chessSplit(900px)과 chessWide(1500px)로 이름을 붙여 관리하고, Preset의 chess-split·chess-wide screens로 Chess 전용 CSS에서만 참조함. 다른 화면은 이 값을 사용하지 않음.
  • 기준값을 바꿀 때는 breakpoints.json만 수정한 뒤 shared-ui를 다시 빌드해 산출 CSS·JS를 함께 갱신하고, 이 절과 관련 가이드의 수치를 같은 변경에서 갱신함. 변경 후 rg로 하드코딩된 폭 조건이 없는지, 1439px·1440px 경계에서 셸 메뉴·Hub 대시보드·오버레이가 함께 전환되는지 확인함.

5. 공통코드 화면 레퍼런스​

5.1 권장 구조​

  • 공통코드 화면은 좌측 코드 타입 목록, 우측 메타 및 코드 목록 구조를 기준으로 함.
  • 좌측은 작은 마스터 목록 그리드임.
  • 우측은 선택된 항목의 메타 편집과 상세 그리드를 함께 관리하는 작업 영역임.
  • 좌측과 우측 그리드 높이는 화면 하단에서 맞춰 끝나야 함.
  • 대표 레퍼런스 구조는 현재 /codes, /metas, /users 화면 계열임.
  • 같은 관리 콘솔 계열 화면은 제목 위치, 패널 밀도, 액션 배치 톤을 가능한 한 동일하게 유지함.

5.2 좌측 패널​

  • 좌측은 별도 검색 폼을 두지 않음.
  • 그리드 상단 headerFilter 같은 Tabulator 자체 검색을 우선 사용함.
  • 타입 추가, 타입 저장, 새로고침 같은 최소 액션만 둠.
  • 좌측이 목록 선택과 신규 진입 역할을 담당하는 화면이라면 좌측 액션은 신규, 새로고침처럼 목록 책임에 맞는 버튼만 둠.
  • 우측 편집 데이터와 직접 관련된 저장, 삭제 버튼을 좌측 헤더에 섞어 두지 않음.

5.3 우측 패널​

  • 상단에는 꼭 필요한 액션 버튼만 배치함.
  • 메타 입력과 하단 그리드 사이에는 경계선을 둠.
  • 메타 편집과 하위 목록은 한 작업 영역으로 보고 함께 관리함.
  • 우측이 실제 편집 책임을 가지는 화면이라면 저장, 삭제 같은 CUD 버튼은 우측 헤더에 둠.
  • 선택 상태를 보여주는 칩이 실제 작업 판단에 도움이 되지 않으면 두지 않음.
  • 우측 헤더 제목은 h3 수준의 공통 detail title 톤을 사용함.

6. 그리드 표준​

6.1 공통 헤더 배치​

  • 그리드 상단 좌측에는 총 건수나 상태 텍스트를 둠.
  • 그리드 상단 우측에는 버튼 영역을 둠.
  • 이 구조는 모든 그리드가 동일하게 따름.

6.2 그리드 폭과 높이​

  • 특별한 사유가 없으면 가로 스크롤이 생기지 않도록 컬럼 폭을 먼저 조정함.
  • 컬럼은 필요한 최소 폭만 사용함.
  • 그리드는 부모 패널 높이를 채우도록 구성함.
  • 상태성 컬럼은 좁게 유지하고, 설명/본문형 컬럼은 가능한 범위에서 줄여서 편집 영역이나 핵심 데이터 영역에 더 많은 폭을 배정함.
  • Tabulator 높이는 임의의 고정 px 값보다 부모 패널 기준 100% 채움 방식을 우선 사용함.
  • 화면 전체 높이를 맞춰야 하는 운영 화면에서는 고정 높이 수치로 레이아웃을 밀어 올리지 않음.

6.3 Tabulator 사용 방식​

  • 조회, 인라인 수정, 추가, 삭제, 저장은 가능한 한 Tabulator 중심으로 처리함.
  • 새 Tabulator 화면은 TabulatorFull을 직접 생성하지 않고 @shared-ui/utils/tabulator-header-filter의 JunkboxTabulator를 사용함. 컬럼을 나중에 추가하거나 교체할 때도 같은 인스턴스를 사용함.
  • 화면 바깥에 별도 입력 폼을 두기보다, 그리드 자체 편집 UX를 우선 검토함.
  • 상위 메타와 하위 목록처럼 의미상 다른 데이터는 패널을 분리할 수 있음.
  • 여러 행 삭제를 지원하는 관리 화면은 Tabulator 맨 앞에 선택 체크박스 컬럼을 배치하고, 실제 삭제는 선택 삭제 버튼을 통해 수행함.
  • 행 클릭으로 상세 패널을 갱신하는 화면에서도 체크박스 선택 상태와 상세 편집 대상 선택은 함께 동작할 수 있어야 함.
  • 전체 폭 목록에서 행을 선택해 오른쪽 상세를 여는 화면은 shared-ui의 WorkspaceDetailOverlay와 공통 CSS를 사용함. 오버레이는 목록 왼쪽 영역의 스크롤·행 선택을 막지 않으며 불투명한 배경으로 뒤의 목록 텍스트를 가림.
  • list editor 같은 선택형 편집 셀은 평상시에도 편집 가능성을 드러낼 수 있도록 공통 chevron affordance를 사용할 수 있음.
  • 선택형 편집 드롭다운은 브라우저 기본 흰색 팝업이 아니라 공통 다크 테마 규칙을 사용함.
  • 일반 select option도 브라우저 기본 흰색 배경을 노출하지 않도록 공통 다크 필드 옵션 색상 규칙을 사용함.

6.4 그리드 로딩 정책​

  • 운영 화면의 그리드 로딩 방식은 데이터 성격과 편집 방식에 따라 표준을 구분함.
  • 기준정보 또는 마스터 데이터이면서 그리드 내부에서 직접 수정, 추가, 삭제가 일어나는 화면은 기본적으로 전체 로딩을 사용함.
  • 이 경우 사용자는 현재 로드된 전체 집합을 한 번에 보고 비교하거나 수정할 수 있어야 하며, 스크롤 로딩으로 편집 대상 범위를 나누지 않음.
  • 계속 데이터가 누적되는 로그, 이력, 사용량 집계 성격의 화면은 기본적으로 서버 페이징을 사용함.
  • 이 경우 전체를 한 번에 로딩하거나 점진 스크롤로 끝없이 붙이는 구조를 기본 표준으로 삼지 않음.
  • 기준정보 또는 마스터 데이터이지만 그리드 내부 인라인 편집이 없고, 목록 선택이나 조회 역할만 담당하는 화면은 점진적 스크롤 로딩을 사용할 수 있음.
  • 이 경우 초기 일부 데이터만 로드한 뒤, 내부 그리드 스크롤이 하단에 가까워질 때 다음 청크를 추가 로드하는 방식을 표준으로 함.
  • 점진적 스크롤 로딩 대상 화면의 검색은 가능하면 Tabulator headerFilter를 유지하되, 구현은 서버 재조회 방식으로 설계할 수 있음.
  • 점진적 스크롤 로딩을 구현할 때는 Tabulator 내부 tableholder가 초기 프레임 뒤에 생성될 수 있는 전제를 고려해야 함.
  • 한 화면 안에 목록 선택용 그리드와 실제 편집용 그리드가 함께 있다면, 각 그리드는 역할에 따라 서로 다른 로딩 정책을 사용할 수 있음.
  • 예를 들어 좌측 선택 목록은 점진적 스크롤, 우측 인라인 편집 목록은 전체 로딩을 적용할 수 있음.
  • 이 기준은 단순 구현 취향이 아니라 화면 사용성과 저장 안정성을 위한 공통 설계 원칙으로 간주함.
  • 따라서 새 관리 화면을 설계할 때는 먼저 해당 그리드가 인라인 편집형 마스터, 누적형 조회, 비편집형 마스터 목록 중 어디에 속하는지 분류한 뒤 로딩 방식을 결정함.
  • 현재 rename 계열 화면은 운영 데이터 규모와 사용 패턴을 기준으로 Rename, Favorites, Logs 모두 풀 로딩 방식을 사용함.
  • 따라서 rename 화면 구현과 유지보수에서는 점진 로딩 또는 서버 페이징보다 전체 로드 후 내부 필터와 선택 작업을 우선함.

6.5 검색 기준​

  • 별도 검색 폼보다 Tabulator의 headerFilter를 우선 사용함.
  • 같은 목적의 검색 UI를 중복 배치하지 않음.
  • 단순 조회형 리스트 화면은 별도 상단 검색 패널 없이 headerFilter만으로 해결하는 방식을 우선 검토함.
  • 입력형 헤더 검색은 일반 입력에 일부 포함 검색을 적용하고, =값은 정확 일치로 처리함. 숫자·날짜 컬럼의 >값, <값, >=값, <=값은 크기 비교로 처리하며 날짜 비교 입력은 YYYY-MM-DD 형식임.
  • 원격 조회 그리드는 현재 로드된 행만 검색하지 않고 입력 원문을 서버로 전달하는 원격 필터 계약을 사용함. 서버 API는 junkbox_shared_core.header_filter로 같은 검색 문법을 해석하고 목록과 총 건수에 동일한 필터를 적용함.
  • 숫자·날짜 컬럼의 타입을 자동으로 판별하기 어려우면 headerFilterFuncParams.kind를 명시함. 날짜는 YYYY-MM-DD로 입력함.
  • 같은 기능의 검색 UI를 화면 바깥과 그리드 안에 중복 배치하지 않음.

6.6 불린 컬럼 표현​

  • Tabulator 내부의 is_active 같은 불린 컬럼은 기본적으로 체크박스형 tickCross 표현을 사용함.
  • 동일한 의미의 불린 상태를 화면마다 pill, badge, 텍스트로 제각각 표현하지 않음.
  • 별도 사유가 없으면 운영 화면의 활성 여부 컬럼 폭은 좁게 유지함.

6.7 Tabulator 셀 정렬​

  • Tabulator 셀의 세로 정렬은 기본 셀 흐름을 해치지 않는 범위에서만 보정함.
  • 셀 내부 vertical 정렬이 필요하더라도 .tabulator-cell 자체를 flex 같은 다른 레이아웃 모델로 바꾸지 않음.
  • 컬럼 줄바꿈, formatter, ellipsis, 폭 계산에 영향을 줄 수 있는 셀 레이아웃 변경은 피함.

6.8 점수형 셀 표현​

  • 점수형 데이터는 가능하면 pill이나 과한 장식보다 플랫한 숫자 표기를 우선함.
  • 점수 단계 구분은 숫자 색상으로 표현할 수 있음.
  • 미확정 상태처럼 별도 주의가 필요한 경우에는 숫자 장식보다 셀 배경 강조를 우선 사용함.

7. 버튼 규칙​

7.1 의미 기준 스타일​

  • 버튼 색은 이 클릭이 즉시 저장소에 일으키는 결과를 나타내며, 의미는 라벨과 아이콘이 전달함. 색은 아래 4단계 체계를 따름.
  • 흰색 jb-button(primary): 클릭 즉시 DB 또는 YAML 정책 저장소에 생성·수정이 확정되는 버튼임.
  • 빨강 jb-button jb-button-danger(danger): 클릭 즉시 삭제가 확정되는 버튼임. 소프트 삭제(deleted_at 설정)도 삭제로 취급하며, 하단 액션바·카드 내부·그리드 툴바 등 위치와 무관하게 빨강을 사용함. 사용 빈도가 낮은 삭제라도 즉시 확정이면 빨강임.
  • 노랑 jb-button jb-button-warning(warning): 삭제는 아니지만 즉시 반영되며 아래 중 하나에 해당하는 주요 but 위험 버튼임.
    • 비가역: 되돌릴 수 없음 (초기화, 덮어쓰기, 파일 Process, 세션·대국 종료, 기권).
    • 광범위: 대량·일괄 적용임 (전체 갱신, 점수 갱신).
    • 외부 부작용: DB 밖으로 영향이 나가며 회수할 수 없음 (메시지 발송·재발송, 외부 API 호출을 동반한 AI 재인식).
    • 단순 저장은 위험해 보여도 노랑이 아니라 흰색임. 노랑은 화면마다 남용하지 않고 이 기준에 해당할 때만 사용함.
  • 검정 jb-button-ghost(ghost): 위에 해당하지 않는 모든 버튼임. 단순 UI 변경, 화면 전환, 새로고침, 조회, Export(다운로드), 패널·시트 열기, 선택, 임시 편집 상태 변경이 여기에 속함.
  • 판단 순서는 다음과 같음.
    1. 클릭이 곧바로 삭제를 확정하는가 → 빨강.
    2. 클릭이 곧바로 생성·수정을 저장소에 확정하는가 → 비가역·광범위·외부 부작용에 해당하면 노랑, 아니면 흰색.
    3. 저장소 변경 없이 화면 상태만 바꾸는가 → 검정.
  • 한 화면 안에서 여러 버튼이 함께 있을 때도 사용자가 무엇이 실제 저장을 일으키는지 즉시 구분할 수 있어야 함. 한 액션 영역(툴바·하단 액션바)의 흰색 버튼은 가능하면 1개로 둠.
  • 이 기준의 판단 포인트는 지금 이 클릭이 즉시 저장소에 반영되는가임.
  • 화면에 행을 추가하거나, 운동 그룹을 열거나, 픽커를 띄우거나, 임시 편집 상태만 바꾸는 버튼은 결과적으로 저장 화면에 포함되더라도 즉시 DB/YAML에 반영되지 않으므로 jb-button-ghost를 사용함.
  • 임시 삭제(저장 전까지 화면에서만 제거되는 행·카드·세트·그룹 삭제)도 검정임. 빨강은 실제 삭제 확정에만 사용해 빨강만 보고도 되돌릴 수 없는 삭제임을 알 수 있어야 함. 그 화면의 저장 버튼은 삭제를 포함해 확정하더라도 흰색이며, 삭제가 포함되면 확인창으로 알림.
  • 서버 상태를 바꾸는 상태 전이 버튼(세션 재개, 비활성화, 대국 제안·거절 등)은 수정으로 보아 흰색을 사용하되, 비가역이거나 운영에 즉시 영향을 주면 노랑임. 예를 들어 세션 종료, 운영 프롬프트 버전 적용, 대국 기권·무승부 수락은 노랑임. 외부 계정 연동 해제처럼 실제로 데이터를 삭제하는 버튼은 이름과 무관하게 빨강임.
  • 서버에 세션·결과 레코드를 만드는 시작·생성 버튼(학습 시작, 문제 풀기, 계획 생성, 대국 생성)은 생성이므로 흰색임. 저장하지 않는 미리보기·분석·조회는 검정임.
  • 저장과 이동이 결합된 버튼(저장 후 러닝 시작)은 저장소에 쓰므로 부가 동작이 이동이어도 흰색임.
  • 재시도 버튼은 원래 동작의 색을 따름. 조회 재시도는 검정, 쓰기·덮어쓰기 재시도는 흰색, 비용·부작용이 크면 노랑임.
  • 바텀시트·모달 안의 선택값 확인 버튼은 임시 선택만 확정하므로 검정임.
  • 새 항목, 신규처럼 신규 입력 화면으로 이동하거나 폼을 초기화할 뿐 저장소를 바꾸지 않는 버튼도 검정임.
  • rename의 추가는 임시 행 생성만 수행하므로 검정, 저장은 흰색, 삭제는 빨강, Fetch·Process·초기화는 파일 상태를 바꾸는 노랑임.
  • 빨강(삭제) 버튼은 항상 확인창을 거침. 노랑 버튼은 비가역이거나 회수할 수 없는 외부 발송이면(세션·대국 종료, 기권, 무승부 수락, 메시지 발송·재발송, 운영 프롬프트 버전 적용 등) 확인창을 거치고, 반복 실행하는 갱신·조회성 작업(Fetch, 점수·기록 갱신, 재인식 등)은 매번 확인창을 띄우지 않음. 흰색 저장 버튼은 확인창이 필요 없음. 비활성 상태는 4색 모두 같은 색상 계열의 낮은 채도로 표시함(공통 CSS가 제공).
  • 선택 트리거, 카드 이동, 탭, 칩, 토글처럼 액션이 아닌 선택·탐색 컨트롤은 위 4색 체계의 대상이 아니며 아래 7.1.1의 전용 컴포넌트를 사용함.

7.1.1 버튼 중앙화와 공통 컴포넌트​

  • 버튼 외형은 shared-ui에서 중앙 관리함. PC와 모바일은 같은 클래스·컴포넌트를 사용하며, 모바일 하단 액션바의 폭 규칙만 jb-mobile-bottom-bar-*가 추가로 담당함.
  • React 화면은 @shared-ui/components/Button의 Button(variant="primary|danger|warning|ghost", 기본 ghost, compact)과 IconButton(아이콘 전용, aria-label 필수)을 사용함. 링크를 버튼 외형으로 표시할 때는 같은 파일의 buttonClassName(variant, { compact, className })을 사용함. Button은 type="button"을 기본으로 함.
  • 액션이 아닌 컨트롤은 @shared-ui/components/ChoiceControls의 SelectTrigger(선택 시트·목록을 여는 jb-select 버튼), CardButton(목록 카드 전체를 누르는 버튼), ToggleButton(pressed가 aria-pressed와 is-active를 자동 제공하며 variant는 chip·pill·segment·choice·icon), Switch(사용·미사용처럼 즉시 켜고 끄는 조작 요소. checked가 role="switch"·aria-checked를 제공하고 aria-label 필수, 외형은 jb-switch), Checkbox(목록 항목을 여러 개 고르는 선택 요소. checked가 role="checkbox"·aria-checked를 제공하고 aria-label 필수, 외형은 jb-checkbox)를 사용함.
    • 켜짐·꺼짐을 뱃지형 ToggleButton으로 표시하면 상태 표시와 구분되지 않으므로 조작은 Switch를 사용함.
  • 화면 코드에서 <button className="jb-button...">처럼 클래스를 직접 쓰지 않음. 선택 상태 표시에 흰색 jb-button을 쓰지 않으며, 선택 상태는 ToggleButton의 choice 변형을 사용함.
  • 서버 템플릿(Jinja)은 컴포넌트를 쓸 수 없으므로 같은 4색 클래스 조합만 사용함. 삭제 버튼은 jb-button jb-button-danger임.
  • just check-buttons(scripts/check_button_rules.py)가 raw jb-button 클래스 직접 사용, 삭제된 Chess 전용 버튼 클래스, aria-label 없는 아이콘 전용 Button, 템플릿의 허용되지 않은 클래스 조합과 흰색 삭제 버튼을 검사함. 버튼을 추가·수정한 뒤 실행함.
  • Chess는 보드·카드·로그 레이아웃만 전용 jb-chess-* 자산을 사용하고, 버튼은 공통 4색 체계와 compact 수정자를 사용함.

7.2 크기 기준​

  • 버튼 크기는 작고 촘촘한 운영 화면 기준을 유지함.
  • 특정 화면만 더 크거나 더 두꺼운 버튼을 만들지 않음. 좁은 영역에 쓰는 작은 버튼은 화면 전용 CSS가 아니라 공통 jb-button-compact 수정자(Button의 compact)를 사용함.

7.3 액션 묶음 정렬​

  • 같은 액션 영역 안에서는 버튼 이름보다 동작 성격을 기준으로 삭제(빨강), 위험(노랑), 조회(검정), 저장(흰색) 순서로 배치함.
  • 삭제 계열은 선택 삭제, 현재 항목 삭제처럼 저장소에서 데이터를 제거하는 액션을 의미함.
  • 조회 계열은 새로고침, 재조회, 선택 항목 로드, 다운로드처럼 저장소 상태를 변경하지 않는 액션을 의미함.
  • 저장 계열은 저장, 일괄 저장, 적용처럼 생성 또는 수정 결과를 저장소에 확정하는 액션을 의미함.
  • 삭제 계열과 조회 계열이 같은 버튼 영역에 있으면 jb-action-divider로 시각적 칸막이를 둘 수 있음.
  • portal-menus, codes, metas, users 같은 hub 관리자 화면은 이 액션 묶음 정렬을 기본으로 사용함.

7.4 모바일 하단 고정 액션바​

  • 모바일 전용 편집 화면의 주요 액션은 가능하면 하단 고정 액션바에 모아 배치함.
  • 모바일 전용·겸용 웹 화면의 jb-mobile-bottom-bar는 shared-ui 공통 앱 셸이 감지함. 셸은 실제 액션바 높이를 관찰하고 --jb-mobile-bottom-bar-clearance와 비교해 큰 값만 jb-main 하단 여백으로 적용하므로, 화면별 래퍼가 빠져도 본문 마지막 콘텐츠가 가려지지 않음. 액션바가 제거되면 셸의 여백도 해제됨.
  • jb-mobile-page는 일반 모바일 화면의 flex 배치와 고정 폭, jb-mobile-bottom-bar-page는 flex 간격을 강제하지 않는 모바일 폭·좌우 여백에 사용함. 액션바가 있는 화면에서 두 클래스의 기존 하단 여백은 공통 셸이 해제해 중복을 막음. 두 클래스는 액션바 여백을 얻기 위한 필수 조건이 아님.
  • 페이지별 pb-* 유틸리티, 인라인 스타일, 앱 전용 CSS로 하단 고정 액션바 여백을 추가하거나 공통 여백을 취소하지 않음. 신규·수정 화면은 스크롤 끝, 긴 버튼 문구, SPA 라우트 전환에서 실제 가림 여부를 확인함.

신규 개발과 기존 화면 수정에 모두 적용하는 하단 버튼 폭 원칙: 버튼 종류의 조합을 먼저 판별하고, 어느 경우에도 액션바의 사용 가능한 가로폭을 모두 채움.

  1. 텍스트 버튼만 있으면 버튼 수 n에 관계없이 각 버튼이 전체 가로폭의 1/n을 차지함. 버튼 하나면 전체 폭을 차지함.
  2. 아이콘 버튼만 있으면 버튼 수 n에 관계없이 각 버튼이 전체 가로폭의 1/n을 차지함. 목록·삭제 두 버튼만 있으면 각각 절반이며, 이력 상세처럼 목록 버튼 하나만 남으면 전체 폭을 차지함. 아이콘 버튼을 최소 폭으로 왼쪽에 모아 두지 않음.
  3. 텍스트 버튼과 아이콘 버튼이 섞여 있으면 아이콘 버튼은 개수와 관계없이 각각 높이와 너비가 같은 고정 정사각형을 차지함. 텍스트 버튼 수 n은 아이콘 버튼과 간격을 제외한 남은 가로폭을 각각 1/n씩 균등하게 차지함. 목록·삭제 아이콘과 추가·저장 텍스트 버튼이 함께 있으면 아이콘 둘은 각각 고정 정사각형, 텍스트 둘은 남은 폭의 절반씩 사용함.
  • 위 원칙은 버튼의 색상·위험도·우선순위와 별개임. 삭제 버튼도 아이콘만 있는 액션바에서는 다른 아이콘 버튼과 같은 폭을 사용함. 아이콘만 있는지 여부는 현재 실제로 표시된 버튼을 기준으로 판단함.
  • 모바일 웹은 버튼에 jb-mobile-bottom-bar-button을 붙이고 아이콘 전용 버튼에는 jb-mobile-bottom-bar-icon을 함께 붙임.
    • shared-ui의 hub-ui-mobile.css가 실제 표시된 버튼 조합을 감지해 위의 세 폭 규칙을 자동 적용함.
    • 화면별 너비·최소 너비 지정으로 분배를 재정의하지 않음.
    • 기존 마크업에 flex-1·shrink-0이 남아 있어도 공통 CSS가 하단 액션바 안에서 폭을 결정하며, 신규·수정 화면은 폭 유틸리티에 의존하지 않음.
    • 신규 기능 추가와 기존 화면 수정에서 텍스트 전용, 아이콘 전용, 혼합 상태와 조건부 버튼 표시 상태를 각각 확인함.
  • 하단 고정 액션바 안에서도 버튼 색상 규칙은 동일하게 유지함.
  • 따라서 목록 이동, 추가 패널 열기, 단순 UI 전환 버튼은 jb-button-ghost를 사용하고, 저장처럼 즉시 CUD를 일으키는 일반 버튼은 jb-button을 사용함. 모바일 하단 액션바에서 실제 기록·항목을 삭제하는 휴지통 아이콘 버튼은 jb-button jb-button-danger의 빨간 배경을 표준으로 사용함. 흰 배경 jb-button이나 고스트 배경으로 표시하지 않음. 신규·수정 화면은 활성 상태의 선명한 빨강과 비활성 상태의 낮은 채도 빨강을 모두 확인함.
  • 삭제가 하단 고정바에 배치되더라도 항상 텍스트 버튼일 필요는 없으며, 사용 빈도가 낮으면 쓰레기통 아이콘 버튼으로 축약할 수 있음. 그 폭은 위의 버튼 조합 원칙을 따름.
  • 러닝 실행 화면처럼 타이머 조작 자체가 주요 액션인 화면은 모든 하단 액션을 아이콘 버튼으로 구성할 수 있음. 이때도 각 버튼은 1/n 균등 분할로 액션바 전체 폭을 채움.
  • 시작, 일시정지처럼 아이콘 의미가 명확한 실행 조작은 텍스트 라벨을 화면에 함께 표시하지 않고 aria-label로 접근성 이름을 제공함.
  • 처음, 이전, 다음, 마지막 같은 순차 조작은 실행 위치를 직접 바꾸는 버튼으로 취급하며, 저장소 변경을 즉시 확정하지 않으면 jb-button-ghost를 사용함.

웹·네이티브 적용과 기존 사례 확인​

  • 모바일 기능 개선 시 저장·시작·계획 선택·목록 복귀처럼 화면 단위의 주요 액션은 하단 고정 액션바를 우선 사용함. 본문 카드 안에 화면 전체의 주요 액션을 중복 배치하지 않음. 현재 카드에만 적용되는 보조 조작은 해당 카드 문맥에 둘 수 있음.
  • AI는 구현 전에 현재 코드에서 유사한 기존 화면과 공통 컴포넌트를 확인하고 버튼 순서·아이콘·높이·여백을 재사용함. 버튼 폭은 위의 공통 자동 규칙을 따르고 삭제 아이콘은 빨간 배경을 확인함. 새 화면마다 별도 버튼 영역과 개별 스타일을 만들지 않음.
  • 목록·홈 복귀는 맨 왼쪽의 아이콘 버튼으로 두고 접근성 이름을 제공함. 텍스트 버튼과 섞일 때만 고정 정사각형 폭을 사용하며, 아이콘 버튼만 있으면 다른 아이콘 버튼과 전체 폭을 균등 분할함. 저장·시작·선택 같은 텍스트 버튼은 혼합 상태에서 아이콘 버튼을 제외한 남은 폭을 균등 분할함.
  • 이 배치·폭 원칙은 모바일 웹과 Android 네이티브에 공통 적용함. 위의 jb-* 클래스와 CSS 변수는 웹 구현용이며 네이티브에 그대로 적용하지 않음. Android는 JunkboxDesign.kt와 공통 Compose 컴포넌트를 사용하며 색은 네이티브 앱 가이드 3.2절의 3색 원칙을 따름.
  • Android는 Scaffold의 bottomBar와 본문의 contentPadding으로 실제 하단 영역 높이를 반영하고 시스템 내비게이션·키보드 inset을 처리함. 스크롤·키보드·안내 메시지·글자 크기 변화에도 본문과 버튼이 가려지지 않는지 검증함.
  • 네이티브 참고 사례는 러닝 선택 전의 홈 아이콘 → 웹에서 계획 선택, 러닝 준비의 홈 아이콘 → 계획 다시 선택 → 러닝 시작, 운동 설정의 홈 아이콘 → 저장임.
    • 홈 이동은 집 모양 아이콘, 실제 목록 이동은 세 줄 목록 아이콘으로 구분함.
    • 선택·준비·설정은 앱의 JunkboxBottomActionBar를 재사용하고, 타이머 실행 전용 아이콘 조작은 기존 JunkboxRunControls를 참고함.
    • 상세 연결은 네이티브 앱 가이드의 모바일 화면 액션 배치 기준을 따름.

7.4.1 모바일 카드 목록 선택​

  • 하나의 모바일 화면에서 상단 등록·수정 폼과 하단 카드 목록을 함께 제공하는 경우, 카드 선택은 현재 폼의 수정 대상을 바꾸는 표준 방식임.
  • 선택 카드는 화면 전용 색상·inline style·상태 텍스트를 추가하지 않고 shared-ui의 jb-mobile-card--selected를 사용함. 이 클래스는 기본 카드보다 명확한 청색 계열 테두리와 내부 강조로 선택 상태를 표시함.
  • 카드의 선택 영역은 버튼으로 구성하고 aria-pressed로 선택 상태를 제공함. 카드 내부의 삭제처럼 별도 동작은 독립 보조 버튼으로 구성함.
  • 신규 입력 전환은 IconPlus 같은 아이콘 버튼으로 제공할 수 있으며, 하단 액션바에 두면 폭은 위의 자동 분배를 따름. 이 동작은 선택 상태와 폼 값을 신규 기본값으로 초기화할 뿐 저장소를 변경하지 않으므로 jb-button-ghost를 사용함.
  • 폼 제목·상태 칩은 신규 등록과 기존 데이터 수정을 구분할 수 있어야 하나, 선택 카드 자체에는 중복 상태 텍스트를 표시하지 않음.

7.4.2 모바일 카드 상태 배지​

  • 모바일 카드 목록의 활성·비활성 같은 운영 상태는 Message 앱의 상태 배지를 표준으로 사용함.
  • 상태 배지는 카드 제목 영역의 우측에 배치하고, 상태 변경 여부와 관계없이 동일한 크기·간격을 유지함.
  • 공통 레이아웃 클래스는 shrink-0 whitespace-nowrap rounded-full border px-2.5 py-1 text-[0.72rem] 조합을 사용함. shrink-0과 whitespace-nowrap는 좁은 화면에서 활성, 비활성 텍스트가 두 줄로 분리되는 것을 방지하는 필수 제약임.
  • 활성 상태는 border-emerald-400/20 bg-emerald-400/10 text-emerald-100, 비활성 상태는 border-red-500/20 bg-red-500/10 text-red-100 조합을 사용함.
  • 카드 제목·설명 컨테이너에는 min-w-0을 적용해 제목이 상태 배지를 밀어내지 않도록 함. 상태를 카드 본문에 별도 텍스트로 중복 표시하지 않음.
  • 상태 변경 입력은 모바일에서 네이티브 체크박스 대신 jb-select 외형과 BottomOptionPicker 선택 시트 조합을 우선 사용함. 이 규칙은 Message 일정·반복 설정과 Raid 공대 구인 프로필처럼 모바일 카드 목록으로 상태를 보여 주는 화면에 적용함.

7.5 모바일 그룹 액션 정렬​

  • 모바일 편집 화면의 카드 내부 보조 액션은 기본적으로 우측 정렬을 사용함.
  • 직전 기록, 추가, 삭제처럼 현재 카드 문맥에만 적용되는 보조 액션은 좌측 정렬보다 우측 묶음 배치를 우선함.
  • 모바일 바텀시트나 모달 헤더에 배치되는 닫기 같은 짧은 텍스트 버튼은 줄바꿈되지 않도록 whitespace-nowrap 계열 조합과 충분한 가로 패딩을 사용함.
  • 모바일 시트 헤더의 버튼은 제목/설명 영역과 나란히 배치되더라도 버튼 자체가 줄어들어 두 줄로 표시되지 않아야 함.

7.6 모바일 하단 선택 시트​

  • 모바일 폭에서 탭, 필터, 보기 전환 옵션이 한 줄 안에 안정적으로 표시되지 않거나 항목 수가 늘어날 수 있으면 인라인 탭을 유지하지 않고 현재 선택값 버튼과 하단 선택 시트 조합을 우선 검토함.
  • PC 화면에서 인라인 탭이 정보 밀도와 발견성을 유지하는 경우에도 모바일 화면은 같은 옵션 집합을 BottomOptionPicker 기반 하단 선택 시트로 표시할 수 있음.
  • 모바일 전용 화면에서 루틴 모드, 운동 부위, 러닝 단계 유형처럼 선택 후보를 고르는 UI는 네이티브 <select>보다 jb-select 외형의 선택 버튼과 BottomOptionPicker 하단 선택 시트 조합을 우선 사용함.
  • jb-select 외형 선택 버튼은 공통 select chevron 배경을 그대로 사용하며, 버튼 내부에 ⌄, ▾, ▼ 같은 별도 텍스트 화살표를 추가하지 않음.
  • 하단 선택 시트는 배경 컨텐츠와 겹쳐도 옵션 텍스트를 안정적으로 읽을 수 있도록 불투명한 다크 패널, 얇은 경계선, 저대비 옵션 카드 톤을 사용함.
  • 하단 선택 시트의 선택 후보는 내부 scroll container를 사용하며, 현재 선택값이 열림 시점에 목록 중앙 근처로 정렬되어야 함.
  • 숫자 선택처럼 값 타입이 특수한 경우에도 시트 외형과 스크롤 동작은 공통 선택 시트 계약을 재사용함.
  • 숫자 선택 하단 시트는 옵션 텍스트를 중앙 정렬함.
  • 텍스트형 보기 전환이나 설명이 있는 옵션 목록은 좌측 정렬을 기본으로 함.

7.7 공통 segmented tab​

  • 탭, 필터, 보기 전환, 페이지 크기처럼 같은 옵션 집합 중 하나를 선택하는 UI는 shared-ui의 SegmentedTabs를 우선 사용함.
  • 표준 segmented tab 외형은 대시보드 PC 탭과 같은 낮은 대비, 얇은 경계선, rounded-jb-sm 반경을 사용함.
  • 과하게 둥근 pill 형태는 표준 탭 외형으로 사용하지 않음.
  • APP/SERVICE 같은 2개 탭은 fill 폭 정책으로 컨테이너 폭을 균등 분할할 수 있음.
  • 운동 부위처럼 항목 수가 늘어날 수 있는 필터 탭은 scrollable 폭 정책으로 가로 스크롤을 허용할 수 있음.
  • 대시보드처럼 PC에서는 인라인 탭이 적합하지만 모바일에서는 화면 폭을 넘는 경우, PC 인라인 탭은 SegmentedTabs를 사용하고 모바일 선택은 BottomOptionPicker 하단 선택 시트로 분리함.
  • 각 항목의 아이콘, 이모지, 보조 표식은 화면별 옵션 데이터의 책임이며 공통 탭 표준의 필수 요소가 아님.

7.8 비동기 작업의 모달 로딩​

  • 사용자 조작으로 실행하는 조회·생성·저장·채점·재시도 작업의 진행 메시지는 공통 LoadingModal로 표시함. 버튼의 텍스트와 아이콘은 원래 의미를 유지하고 관련 버튼·입력은 비활성화함.
  • LoadingModal은 LoadingBlock의 오버레이 표현을 재사용하고 body portal에서 하단 고정 버튼·SPA 전환 영역 위에 표시함. 배경 조작은 inert로 차단하고 종료 시 기존 상태와 포커스를 복원함.
  • 진행 문구는 현재 작업에 맞게 작성하며, 성공·실패·취소 모두 요청 종료 시 모달을 해제함. 오류 문구는 공통 오류 영역에서 표시함.
  • 요청이 끝난 뒤 저장소에 남은 PREPARING·GRADING 상태는 재조회·재시도를 할 수 있는 상태 안내로 표현함. 최초 데이터 로딩 skeleton과 사용자 조작 없이 실행하는 백그라운드 조회는 해당 정책을 따름.
  • 구현·검증 시 버튼 이름 유지, 연속 클릭과 키보드 중복 실행 차단, 성공·실패 후 해제와 포커스 복원, 이력 화면·모바일 하단 고정 버튼 위 표시를 확인함.

7.9 모바일 입력 모달​

  • 모바일 화면에서 이름, 결과·비고처럼 짧은 입력을 받는 모달은 shared-ui의 FormModal을 사용함.
    • 확인 버튼 색은 7.1 기준(저장·생성은 primary, 즉시 삭제는 danger, 조회처럼 저장소를 바꾸지 않는 확인은 ghost)을 따르고 취소와 함께 모달 하단에 둠.
    • 취소와 확인 사이에 보조 버튼(예: 입력값 초기화)이 필요하면 middleAction(label·onClick·variant)을 사용하며 색은 같은 기준을 따름.
    • 선택 시트의 확인이 즉시 저장·삭제로 이어지는 흐름은 시트 확인(검정)을 임시 선택으로만 쓰고, 이어서 FormModal 확인 모달(저장·추가 primary, 삭제 danger)에서 확정함.
  • PC 화면의 jb-modal-* 클래스는 hub-ui-desktop.css에 있어 모바일 화면에서는 로드되지 않으므로 모바일 입력 모달에 사용하지 않음.
  • FormModal은 가상 키보드가 가리지 않도록 화면 세로 중앙에 배치하고, 키보드로 화면이 줄어도 dvh 기준 최대 높이와 내부 스크롤로 넘치지 않게 함. 하단에 붙는 시트는 선택 후보 전용(BottomOptionPicker)으로만 사용함.
  • 배경 조작 차단(inert)·본문 스크롤 잠금·포커스 복원은 useModalLock 훅이 담당하며 LoadingModal과 FormModal이 공유함. 새 body portal 모달도 이 훅을 사용함.
  • 본문 스크롤 잠금은 body.jb-body-modal-lock과 함께 html:has(> body.jb-body-modal-lock)에도 overflow: hidden을 적용함. 공통 html이 overflow-x: hidden이라 overflow-y가 auto로 계산되므로 body의 overflow만으로는 화면 스크롤이 잠기지 않기 때문임. FormModal의 내부 스크롤 영역은 overscroll-contain으로 모달 끝에서의 스크롤이 부모 화면으로 넘어가지 않게 함.
  • 저장 같은 비동기 작업은 모달을 닫은 뒤 LoadingModal로 진행 상태를 표시하고, 실패하면 입력값을 유지한 채 모달을 다시 엶(7.8).

7.10 상태 배지와 상태 선택 색​

  • 진행 중·성공·실패·판정 불가 상태 표시는 shared-ui의 StatusBadge와 jb-status-badge--* 색을 사용함. 상태에 따라 선택하는 버튼은 jb-choice-accent--* 수식어를 붙이며, 두 곳의 색은 CSS에서 같은 규칙을 공유함. 수식어 값은 statusToneSuffix로 만들고 앱 CSS로 상태 색을 따로 정의하지 않음.
  • 상태 이름(예: 성공)이 화면 의미와 다르면(예: 직접 입력한 단순 체크 커스텀 미션의 달성) 색과 tone은 그대로 두고 화면의 텍스트만 바꿈.
  • 상태 색 표준: 진행 중 파랑, 성공 초록, 실패 빨강, 판정 불가 회색이며 신규 기능과 이후의 모든 수정에 예외 없이 적용함.
    • 값은 libs/shared-ui/src/junkbox_shared_ui/status-colors.json 한 곳에서만 정의하고, CSS는 tailwind preset의 colors.status.<tone>.<role>(solid·text·tint·border·soft) 토큰으로만 참조함.
    • jb-status-badge--*, jb-choice-accent--*, 진행 막대, 반원 게이지가 모두 같은 토큰을 사용함.
  • 색을 정하는 기준은 화면 문구가 아니라 판정 상태임. 이하 유지는 넘으면 실패(빨강), 이상 달성은 달성하면 성공(초록), 그 전은 진행(파랑)임. 판정 규칙이 따로 있는 기능(예: QuestLog)은 그 판정 상태를 그대로 쓰고 값만 보고 색을 새로 정하지 않음.
  • 진행 막대와 반원은 ProgressBar, SemicircleGauge의 tone(색 값을 받지 않음)과 progressGeometry를 사용함. 눈금 끝은 max(목표, 값 + 예정)이며 값(예정 포함)이 목표를 넘을 때만 목표 위치에 텍스트 없는 짧은 표시선을 그림. 기준에 못 미치거나 딱 맞으면 표시선이 없음.
  • 아직 확정되지 않은 구간(예: 오늘 아직 먹지 않은 예정분)은 같은 tone의 옅은 색(soft)으로 이어 그리며 판정에는 쓰지 않음.
  • 강제: libs/shared-ui/scripts/check-status-colors.mjs가 shared-ui 빌드(npm run build)에서 shared-ui/src와 apps/*/src에 상태 색 hex를 직접 쓴 경우 실패시킴. 새 상태 색이 필요하면 JSON에만 추가하고 화면·CSS에는 hex를 쓰지 않음.
  • jb-choice-accent 기본 선택색과 jb-feedback-panel의 민트는 상태 색이 아닌 일반 강조색임. 이 표준은 웹에만 적용하며 Android 네이티브 앱은 네이티브 앱 가이드 3.2절의 3색 원칙을 따름.

8. 드래그 정렬 규칙​

8.1 공통 드래그 핸들​

  • 드래그 정렬 UI는 shared-ui의 공통 SortableDragHandle과 공통 sortable 옵션을 우선 사용함.
  • 드래그 핸들 외형은 2열 3행의 6점 핸들 형태를 기준으로 함.
  • 화면별로 GripVertical 같은 별도 아이콘을 직접 사용하지 않음.
  • 드래그 핸들은 정렬 가능한 항목의 앞쪽 또는 카드 헤더 액션 영역처럼 사용자가 자연스럽게 잡을 수 있는 위치에 배치함.
  • 드래그 핸들에는 항목 또는 카드 이름을 포함한 접근성 라벨을 부여함.

8.2 드래그 감도와 잔상​

  • Sortable 기반 정렬은 공통 옵션의 1초 지연 규칙을 사용함.
  • 클릭 즉시 드래그 모드로 진입하지 않으며, 사용자가 핸들을 길게 누른 뒤 이동할 때 정렬이 시작됨.
  • 드래그 중 선택 상태, ghost, fallback 잔상은 shared-ui 공통 클래스가 담당함.
  • 화면별로 delay, ghost class, chosen class, fallback class를 임의로 다르게 지정하지 않음.
  • 포털 카드, 대시보드 큰 카드, 대시보드 투자 항목처럼 같은 상호작용 성격의 정렬 UI는 같은 공통 옵션을 사용함.

9. 폼 규칙​

9.1 입력 필드​

  • 운영 화면 폼은 컴팩트하게 구성함.
  • 메타 정보는 가능하면 한 줄에 최대한 많이 배치함.
  • 식별자와 짧은 보조 정보는 read-only input 구조를 허용함.
  • 두 컬럼 인라인 필드에서 좌측 텍스트 입력과 우측 active 체크박스를 같이 배치할 때는 라벨 행과 입력 행이 각각 나란히 맞도록 공통 그리드를 사용함.
  • 이 경우 기본 비율은 8:2를 우선 사용함.

9.2 설명 문구​

  • 별도 설명 문구를 늘리기보다 입력 필드 구조 안에서 맥락을 해결함.
  • 장식성 헤더 카피를 줄이고 작업 정보 위주로 구성함.
  • 모바일 편집 화면에서는 제목 바로 아래 설명 문구를 기본 전제로 두지 않음.
  • 설명이 없어도 문맥이 충분하면 보조 카피 영역을 생략함.

10. 토스트와 메시지 규칙​

10.1 메시지 표시 방식​

  • 페이지 본문을 밀어내는 인라인 메시지 영역을 두지 않음.
  • 저장, 실패, 안내는 공통 토스트로 표기함.
  • 토스트는 화면 하단 중앙 기준을 사용함.

10.2 의미 기준 스타일​

  • 단순 안내, 조회, UI 상태 메시지는 중립 스타일 토스트를 사용함.
  • 실제 CUD 성공 메시지는 강조 스타일 토스트를 사용함.
  • 오류 메시지는 에러 전용 스타일을 사용함.
  • Android 네이티브 앱의 토스트는 빨강·노랑 없이 네이티브 앱 가이드 3.2절의 형태 구분을 사용함. 성공은 민트 채움과 ✓, 오류는 흰색 채움과 !, 안내는 어두운 면과 윤곽임.

10.3 문체​

  • 문장형 사용자 메시지는 하십시오체를 사용함.
  • 문장형 메시지는 마침표를 붙임.
  • 버튼, 메뉴, 라벨 같은 단어형 텍스트는 문장형으로 억지 변환하지 않음.

10.4 장시간 작업 로딩 표시​

  • 외부 연동이나 파일 작업처럼 사용자가 즉시 결과를 기다려야 하는 액션은 공통 로딩 오버레이를 사용함.
  • 로딩 오버레이는 플랫한 다크 배경과 단색 패널 구조를 사용함.
  • 화면별 임의 로딩 모달을 만들지 않고 공통 로딩 컴포넌트를 재사용함.

11. 타이포그래피 기준​

  • 기본 폰트는 Pretendard Variable을 사용함.
  • 모든 화면 텍스트는 서버에서 제공되는 PretendardVariable.woff2 자산을 기준으로 렌더링함.
  • Tailwind font-mono 유틸리티와 shared-ui의 mono 토큰도 Pretendard를 가리킴.
  • 필드 라벨, eyebrow, 통계 라벨, 테이블 헤더, JSON/코드/AI 로그 상세 텍스트도 별도 모노 폰트를 사용하지 않음.
  • 폰트 선언은 shared-ui의 공통 base CSS에서 중앙화하며, 앱별 CSS나 개별 클래스에서 font-family를 중복 선언하지 않음.
  • 입력, 버튼, 테이블, Tabulator 내부 UI는 공통 루트 폰트를 상속함.
  • 사용자 로컬에 설치된 Pretendard, 유사 sans 폰트, 브라우저 기본 monospace를 우선 사용하지 않음.
  • 전체 폰트 크기는 운영 화면에서 많은 정보를 한 번에 보여줄 수 있도록 작게 유지함.
  • Tabulator 내부 폰트도 같은 공통 스케일을 따름.
  • 기본 텍스트는 밝은 계열을 사용하고, 보조 텍스트만 muted 색상을 사용함.
  • 관리 화면의 페이지 제목은 h2 수준의 공통 클래스 기반 스타일을 사용함.
  • 페이지 제목은 화면마다 임의의 크기로 조정하지 않고 공통 클래스 기준으로 통일함.
  • 장식용 eyebrow, 과한 소개 문구, 불필요한 보조 카피는 작업형 화면에서 기본적으로 생략함.
  • 날짜와 시간 텍스트도 locale 기본 문자열에 의존하지 않고 공통 포맷 표준을 따름.
  • JSON, 코드, AI 로그 상세 텍스트 뷰어도 별도 모노 폰트를 강제하지 않고 기본 Pretendard 기준을 사용함.

11.1 입력 필드와 선택 필드 구분​

  • 텍스트 입력은 jb-input을 사용함.
  • 선택 입력은 jb-select 또는 Tabulator list editor 공통 클래스를 사용함.
  • jb-select는 네이티브 <select>뿐 아니라 모바일 하단 선택 시트를 여는 선택 버튼 외형에도 사용할 수 있음.
  • 플랫한 다크 톤 카드/패널 내부에서 input/select를 동일 톤으로 처리해야 하는 화면은 jb-dark-field를 사용할 수 있음.
  • jb-input에는 select chevron, 우측 구분선, 드롭다운 표시 배경을 적용하지 않음.
  • jb-select에만 chevron과 드롭다운 성격의 시각 표시를 적용함.
  • jb-select를 버튼에 사용할 때도 공통 chevron 배경과 우측 구분선이 이미 포함되어 있으므로 화면 컴포넌트가 별도 화살표 아이콘이나 텍스트를 중복 렌더링하지 않음.
  • jb-dark-field가 select에 사용될 때 option과 optgroup은 다크 배경과 밝은 글자를 유지해야 함.
  • 입력창, select, 버튼의 텍스트 selection 색상은 shared-ui 공통 규칙을 사용함.

12. 참고 화면​

  • 대표 레퍼런스 화면은 apps/hub-api의 /codes 화면임.
  • 단일 그리드형 화면 예시는 portal-menus 계열임.
  • 좌측 선택 + 우측 작업형 화면 예시는 codes, users임. 전체 폭 목록 위에 오른쪽 상세를 여는 화면 예시는 metas, prompts임.
  • /codes, /metas, /users는 현재 공통 제목 톤, 얇은 wrapper 구조, Tabulator active 체크박스 표현을 공유하는 기준 화면임.
  • /users는 6:4 분할을 사용함. /metas, /prompts는 초기 전체 폭 목록과 오른쪽 50% 상세 오버레이를 사용함. 이들 화면은 목록 액션과 편집 액션의 책임 분리, 삭제/조회/저장 성격 순서, 인라인 active 8:2 정렬 패턴을 공유함.
  • 로딩 정책 관점에서 /codes 우측 상세 그리드는 인라인 편집형 전체 로딩 기준 화면으로 봄.
  • 로딩 정책 관점에서 /users, /metas 목록은 비편집형 마스터 목록의 점진적 스크롤 로딩 기준 화면으로 확장할 수 있음.
  • 로딩 정책 관점에서 /ai-logs는 누적형 데이터의 서버 페이징 기준 화면으로 봄.