---
document_type: frontend
priority: HIGH
---
# 프론트엔드 및 UI 제어 명세

## 🎨 테마 및 디자인 규약
- **[DON'T]** 하드코딩된 Hex 색상 코드나 임의의 스타일 직접 입력 금지.
- **[MUST]** 테마(라이트/다크) 전환 호환을 위해 `ui_template/ui_template_theme.css`에 선언된 CSS 변수(`var(--color-...)`)만 참조.
- **공통 레이아웃 (3단 분리 준수):**
  1. 상단 영역: 페이지 타이틀 및 진행 상태 (헤더)
  2. 좌측 패널: 데이터 입력 폼 및 제어 설정 창 (고정 너비)
  3. 우측 영역: WebCAD 도면 뷰어 (Canvas/WebGL) 또는 데이터 그리드 (가변 너비)

## 🌐 다국어 지원 (i18n)
- **[DON'T]** UI 문자열(라벨, 버튼 명, 툴팁, 안내 메시지 등)의 코드 내 하드코딩 절대 금지.
- **[MUST]** 동시 수정 프로토콜:
  1. 신규 텍스트 발생 시 `ui_template/ui_template_locale.ts` 최하단에 키(Key)와 번역 배열(`[한국어, 영어]`) 선 등록.
  2. 컴포넌트 내에서는 `ui_locales.키값[현재언어인덱스]` 형태로만 호출한다.
  3. UI 수정 PR시 다국어 업데이트 내역 누락은 심각한 에러로 취급한다.

## ⚙️ TypeScript 및 로직 제어
- **이벤트 핸들러 명명법:** `on[페이지명]_[기능명]_[액션]` 규칙 준수.
  - 예: `onB04_Surface_Calculate_Click`
- **상태 제어 피드백:** API 비동기 호출 시작 시 전체 로딩 스피너(Overlay) 활성화, 통신 완료(성공/에러) 시 반드시 해제 보장.
- **1차 검증:** 백엔드 전송 전 빈 값, 최대 길이, 숫자 범위 검증은 프론트엔드(`common_util_validate.ts`)에서 우선 처리하며, 에러 시 입력창 주변에 명시한다.