# Local Server 실행환경 보정 규칙 v4

이 문서는 `figma-to-code4.md` 의 Figma 변환 원칙을 유지하면서, `/gen-html` 과 `/gen-html-multiple` 이 사용하는 local-server Storybook 산출물 형식에 맞게 출력 계약만 보정하기 위한 문서다.

`project-context.md`, `coding-convention.md`, `naming-rule.md`, `figma-to-code4.md` 의 일반 프론트엔드 규칙은 참고하되, 출력 파일 형식, 실행환경, Storybook export 계약이 충돌하면 **이 문서가 우선**이다.

## 참조 조건

- `figma-to-code4.md` 가 말하는 `page.tsx + page.module.scss` 지시를 `/gen-html` 전용 `*.stories.tsx + *.module.scss` 지시로 보정해야 할 때 이 문서를 읽는다.
- `figma-to-code4.md` 의 `'use client'` 지시를 local-server Storybook 실행환경에 맞게 제외해야 할 때 이 문서를 읽는다.
- Code Connect와 Storybook MCP(`storybook-mcp`) 기준의 컴포넌트 구현 원칙을 유지하면서 독립 story bundle을 생성해야 할 때 이 문서를 읽는다.

## 우선순위

구현 근거의 우선순위는 `figma-to-code4.md` 와 동일하다.

1. Figma MCP와 Code Connect에서 디자인 값과 컴포넌트 후보를 식별한다.
2. Storybook MCP(`storybook-mcp`)에서 실제 props, variant, children 구조, Compound 조립, event/ref 패턴을 확인한다.
3. 디자인 시스템 컴포넌트로 표현하기 어려운 영역만 HTML + module.scss로 직접 구현한다.

단, 최종 파일 구조와 Storybook export 형식은 항상 이 문서와 `story-bundle-contract.md` 를 따른다.

## 수행 계약

- 결과물은 local-server에서 바로 실행 가능한 `*.stories.tsx` + `*.module.scss` 2파일로만 구성한다.
- `page.tsx`, `page.module.scss`, `layout.tsx`, `page-container/` 구조를 생성하지 않는다.
- 별도 컴포넌트 파일, 테스트 파일, asset 파일, fixture 파일은 생성하지 않는다.
- 모든 임시 컴포넌트, 상수, mock 데이터, helper 함수는 `*.stories.tsx` 안에 작성한다.
- Storybook preview에서 즉시 렌더링되는 독립 실행 환경을 기준으로 코드를 작성한다.
- `story-bundle-contract.md` 의 `ComponentPreview`, `AccessibilityChecklist`, `WebStandardsChecklist` export 계약을 지킨다.

## 실행환경

- 결과물은 `.ju-hong-e/local-server/generated/...` 아래에 저장된다.
- Storybook + Vite 환경에서 실행된다.
- local-server preview decorator가 이미 아래 환경을 제공한다.
  - `QueryClientProvider`
  - `<div id="wrap" className="wrap">`
  - `<div id="ds-portal">`
- 따라서 생성물은 앱 라우터 엔트리나 페이지 파일이 아니라, **독립 실행 가능한 Storybook story 파일** 이어야 한다.

## figma-to-code4 보정 규칙

- `figma-to-code4.md` 의 `page.tsx` 지시는 `*.stories.tsx` 로 바꿔 적용한다.
- `figma-to-code4.md` 의 `page.module.scss` 지시는 `*.module.scss` 로 바꿔 적용한다.
- `figma-to-code4.md` 의 `'use client'` 지시는 Storybook story 파일에 추가하지 않는다.
- `figma-to-code4.md` 의 "모든 임시 컴포넌트, 상수, mock 데이터, 헬퍼 함수는 page.tsx 안에 작성" 지시는 "모두 `*.stories.tsx` 안에 작성"으로 보정한다.
- `figma-to-code4.md` 의 최종 응답 형식은 유지하되, 생성 파일 경로는 story/scss 파일 기준으로 보고한다.

## Storybook 파일 계약

- story 파일은 named export를 정확히 3개 제공한다.
  - `ComponentPreview`
  - `AccessibilityChecklist`
  - `WebStandardsChecklist`
- Story meta의 `title` 은 정적 문자열이어야 하며, 작업 입력값에 명시된 Storybook title prefix로 시작한다.
- `ComponentPreview` 는 실제 Figma 변환 결과를 렌더링한다.
- `AccessibilityChecklist` 와 `WebStandardsChecklist` 는 이름만 선언하지 말고, 실제 체크리스트 UI와 항목 데이터를 가진 story로 작성한다.
- checklist UI와 데이터 구조는 `story-bundle-contract.md` 의 샘플 형식을 따른다.

## import / 런타임 제약

- `next/image`, `next/link`, `next/navigation`, `next/router` 를 import 하지 않는다.
- `@/`, `~`, `src/` 같은 앱 전용 path alias import 를 사용하지 않는다.
- 로컬 워크스페이스 내부 상대경로 import 에 의존하지 않는다.
- local-server 기본/추가 dependency로 해석 가능한 패키지 import 만 사용한다.
- 디자인 시스템 컴포넌트는 `sales-frontend-design-system` 에서 import한다.
- 시스템 아이콘은 `sales-frontend-assets` 에서 import한다.
- Code Connect snippet의 import가 local-server에서 해석 가능한 배포 패키지라면 그대로 사용한다.
- Code Connect snippet의 import가 앱 내부 alias나 미배포 상대경로라면 Storybook MCP(`storybook-mcp`) 문서의 배포 패키지 import로 보정한다.
- CSS Module className은 `classnames/bind` 패턴으로 적용한다.

## SCSS 작성 규칙

```scss
@use 'sales-frontend-design-system/design-system-context' as *;
```

- `.module.scss` 상단에는 위 `@use`를 선언한다.
- Figma auto-layout은 `display: flex`, `flex-direction`, `align-items`, `justify-content`, `gap`으로 변환한다.
- Figma의 spacing, color, typography, radius, shadow 값은 `figma-to-code4.md` 의 디자인 토큰 매핑을 따른다.
- 반응형 정보가 Figma에 있거나 화면 특성상 필요한 경우 `@include media(tablet|pc|pc-wide)`를 사용한다.
- 디자인 시스템 컴포넌트 내부 스타일을 무리하게 override하지 않는다. 필요한 경우 wrapper spacing만 조정한다.
- SCSS에서 `padding(xlarge)`, `margin(card)`, `radius-basic(medium)` 같은 토큰 함수나 CSS 변수 기반 값을 Sass 산술식으로 직접 계산하지 않는다. 배수 계산이 필요하면 `calc(#{padding(medium)} * 12)` 형태의 CSS calc로 옮긴다.

## 컴포넌트 구현 보정

- Code Connect snippet은 최종 구현 코드가 아니라 컴포넌트 후보와 Figma 값 추출용 힌트로 사용한다.
- 디자인 시스템 컴포넌트를 사용한다면 Storybook MCP(`storybook-mcp`)에서 실제 사용법을 확인한 뒤 구현한다.
- 같은 컴포넌트는 한 번만 조회하고 결과를 재사용한다.
- 조회 로그에는 최소한 `컴포넌트명`, `조회 이유`, `참조한 Story/문서 title`, `확인한 props/패턴`을 남긴다.
- Storybook MCP(`storybook-mcp`)에서 확인되지 않은 prop, variant, size, appearance 값은 사용하지 않는다.
- Code Connect와 Storybook MCP에서 적합한 디자인 시스템 컴포넌트를 찾지 못한 영역만 HTML + module.scss로 직접 구현한다.

## 검증 및 최종 응답

- PLACEHOLDER 문자열이 남아 있지 않은지 확인한다.
- 사용한 디자인 시스템 prop과 variant가 Code Connect 또는 Storybook MCP(`storybook-mcp`)에서 확인된 값인지 확인한다.
- 가능하면 Figma screenshot과 생성 결과를 비교해 레이아웃, 간격, 색상, 타이포, 누락 요소를 점검한다.
- 가능하면 프로젝트의 lint/typecheck 명령을 실행한다. 명령을 알 수 없거나 실행이 불가능하면 최종 응답에 미실행 사유를 남긴다.
- 최종 응답에는 아래를 간단히 보고한다.
  - 생성한 story/scss 파일 경로
  - 사용한 주요 DS 컴포넌트
  - Storybook MCP(`storybook-mcp`) 조회 로그. 조회하지 않았다면 `조회 없음`으로 명시
  - 실행한 검증 명령과 결과, 또는 미실행 사유
  - 원본과 남은 차이가 있으면 구체적인 차이
