# gen-html 프로젝트 문맥

`/gen-html` 은 Figma 디자인을 이 저장소 프론트엔드 규칙에 맞는 React/SCSS 코드로 해석하되, 실제 산출은 local-server Storybook 실행환경에 맞춰 생성한다.

## 참조 조건

- 저장소 프론트엔드 기술 스택, 공통 패키지, 아이콘 시스템 문맥을 확인해야 할 때 이 문서를 읽는다.
- 생성 결과를 TypeScript + React + `module.scss` 기준으로 해석해야 할 때 이 문서를 읽는다.

## 수행 계약

- 결과물은 TypeScript + React + `module.scss` 기준으로 작성한다.
- 공통 UI/아이콘/토큰 패키지는 이 문서에 적힌 우선순위에 따라 재사용한다.
- 이 문서는 저장소 문맥을 설명하는 기준이며, 출력 형식과 local-server 제약이 충돌하면 해당 전용 문서를 우선 적용한다.

## 기본 기술 스택

- 언어: TypeScript
- UI: React 기반 프론트엔드
- 스타일: `module.scss` + `sales-frontend-design-system/design-system-context`
- 데이터 처리: React Query, React Hook Form, Zod 를 사용하는 구조가 많다.

## 공통 패키지 기준

UI 레이어에서 아래 공통 패키지를 우선 활용한다.

| 패키지                              | 용도                                |
| ----------------------------------- | ----------------------------------- |
| `sales-frontend-design-system`      | 공통 UI 컴포넌트, 디자인 토큰       |
| `sales-frontend-assets`             | 아이콘 SVG React 컴포넌트           |
| `sales-frontend-components`         | 도메인 공통 컴포넌트                |
| `sales-frontend-hooks`              | 공통 커스텀 훅                      |
| `sales-frontend-utils`              | 유틸 함수                           |
| `sales-frontend-stores`             | 전역 상태                           |
| `sales-frontend-api`                | API 서비스                          |
| `sales-frontend-server-side-helper` | 서버 사이드 헬퍼                    |

## 디자인 토큰 기준

- SCSS 디자인 토큰은 `@use 'sales-frontend-design-system/design-system-context' as *;` 를 기준으로 사용한다.
- 색상, 간격, radius, shadow 값은 디자인 시스템 함수로 표현하고 하드코딩을 최소화한다.

## 아이콘 시스템

아이콘은 인라인 SVG 태그로 직접 구현하지 않는다.

### 방식 1: `sales-frontend-assets` SVG React 컴포넌트

시스템 아이콘(`sub-ui/*`, `main-ui/*`)은 이 방식을 우선 사용한다.

```tsx
import { IconSubUiArrowRightWhite } from 'sales-frontend-assets';

<IconSubUiArrowRightWhite width={20} height={20} />;
```

### 피그마 아이콘 경로 -> export명 변환 규칙

SVG 파일 경로를 PascalCase로 변환하고 `Icon` 접두사를 붙인다.
경로 구분자(`/`), 하이픈(`-`), 언더스코어(`_`)를 단어 구분으로 처리한다.

| 피그마 아이콘 경로         | SVG 파일 위치                        | export명                   |
| -------------------------- | ------------------------------------ | -------------------------- |
| `sub-ui/arrow/right_white` | `icons/sub-ui/arrow/right_white.svg` | `IconSubUiArrowRightWhite` |
| `sub-ui/calendar`          | `icons/sub-ui/calendar.svg`          | `IconSubUiCalendar`        |
| `main-ui/home`             | `icons/main-ui/home.svg`             | `IconMainUiHome`           |

### 방식 2: 아이콘 CSS 클래스

`design-system` 에서 제공하는 CSS 클래스로 아이콘을 표시할 수 있다.

```tsx
<span className={cx('dsp-icons', 'dsp-icons-icons-sub-ui-calendar')} />
```

### 방식 3: `Icon` 컴포넌트

```tsx
import { Icon } from 'sales-frontend-design-system';

<Icon name="sub-ui/arrow/right_white" width={20} height={20} />;
```

### 선택 기준

| 조건                                                    | 사용 방식                    |
| ------------------------------------------------------- | ---------------------------- |
| 시스템 아이콘 (`sub-ui/*`, `main-ui/*`)                 | `sales-frontend-assets` 우선 |
| className 기반 아이콘 처리                              | 아이콘 CSS 클래스            |
| 그래픽/일러스트 (`graphics/*`, `images/*`, `illust/*`) | `Icon` 컴포넌트             |

## 주의사항

- 이 문서는 저장소의 프론트엔드 문맥을 설명한다.
- 실제 출력 파일 형식과 local-server 제약은 `gen-html-rule.md` 가 우선한다.
