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

이 문서는 원본 프론트엔드 변환 규칙을 수정하지 않고, `/gen-html` 과 `/gen-html-multiple` 프롬프트에서만 local-server Storybook 산출물에 맞게 규칙을 보정하기 위한 문서다.

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

## 참조 조건

- Code Connect 기반 Figma 변환 규칙을 local-server Storybook 산출물로 바꿔 적용해야 할 때 이 문서를 읽는다.
- `figma-to-code2.md` 가 말하는 `page.tsx + page.module.scss` 지시를 `/gen-html` 전용 `*.stories.tsx + *.module.scss` 지시로 보정해야 할 때 이 문서를 읽는다.
- Next.js 앱 코드 대신 독립 story bundle을 생성해야 할 때 이 문서를 읽는다.

## 참조 우선순위

컴포넌트 구현 근거는 아래 순서를 따른다. 네이밍 기반 추론은 이 순위를 모두 확인한 뒤 마지막 보조 수단으로만 사용한다.

1. Figma Code Connect 샘플 코드
   - Figma MCP 응답의 `<CodeConnectSnippet>` 또는 Code Connect example JSX를 최우선으로 사용한다.
   - 컴포넌트명, import 경로, props는 샘플 코드를 기준으로 유지한다.
   - 단, 샘플이 `page.tsx` 전제나 앱 라우터 구조를 포함하면 구조만 story bundle 형식으로 옮긴다.

2. 배포된 Storybook MCP의 컴포넌트 정보
   - Code Connect 샘플만으로 props, compound 구조, child 조립 순서가 불충분하면 Storybook MCP에서 해당 컴포넌트 문서와 가장 가까운 story를 조회한다.
   - 문서와 story에 있는 props, variant, size, compound child만 사용한다.
   - Code Connect 샘플과 Storybook 문서가 충돌하면 Code Connect 샘플을 출발점으로 삼되, 실제 런타임 props 검증은 Storybook 문서 기준으로 보정한다.

3. Pure CSS 직접 구현
   - Code Connect와 Storybook MCP에서 적합한 디자인 시스템 컴포넌트를 찾지 못한 영역만 HTML + module.scss로 직접 구현한다.
   - 직접 구현 시에도 Figma 토큰, 레이아웃, 텍스트, 아이콘 의미를 최대한 보존한다.
   - 디자인 시스템 컴포넌트가 존재하는데 props를 몰라서 직접 구현하는 것은 금지한다. 먼저 Storybook MCP를 조회한다.

## 수행 계약

- 결과물은 local-server에서 바로 실행 가능한 `*.stories.tsx` + `*.module.scss` 2파일로만 구성한다.
- `page.tsx`, `page.module.scss`, `layout.tsx`, `page-container/` 구조를 생성하지 않는다.
- Next.js 앱 라우터 구조, `next/*` import, 앱 전용 alias import는 사용하지 않는다.
- 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 파일** 이어야 한다.

## 파일 구조

- 결과물은 정확히 2개 파일만 생성한다.
  - `*.stories.tsx`
  - `*.module.scss`
- 화면 본체, 하위 UI 블록, mock data, helper 함수는 모두 `*.stories.tsx` 안에 인라인으로 작성한다.
- 추가 ts/tsx/scss 파일을 분리 생성하지 않는다.
- Code Connect 샘플이 여러 파일 구조를 암시하더라도 `/gen-html` 산출물에서는 story 파일 하나로 접어 넣는다.

## import / 런타임 제약

- `next/image`, `next/link`, `next/navigation`, `next/router` 를 import 하지 않는다.
- `'use client'` 지시어를 추가하지 않는다.
- `@/`, `~`, `src/` 같은 앱 전용 path alias import 를 사용하지 않는다.
- 로컬 워크스페이스 내부 상대경로 import 에 의존하지 않는다.
- local-server 기본/추가 dependency로 해석 가능한 패키지 import 만 사용한다.
- Code Connect 샘플의 import가 local-server에서 해석 가능한 패키지라면 그대로 사용한다.
- Code Connect 샘플의 import가 앱 내부 alias나 미배포 상대경로라면 Storybook MCP 문서의 배포 패키지 import로 보정한다.
- 디자인 토큰 SCSS는 `@use 'sales-frontend-design-system/design-system-context' as *;` 기준으로 작성한다.

## 레이아웃 / 상태 처리

- 일반적인 네이밍·구조화 원칙은 참고하되, `page.tsx -> page-container` 같은 App Router 전용 규칙은 적용하지 않는다.
- story 파일 안에서 필요한 `useState`, `useMemo`, `useEffect` 등 React 훅 사용은 허용한다.
- 단, Storybook preview 안에서 바로 동작해야 하므로 외부 앱 상태나 라우터 컨텍스트를 전제로 하지 않는다.
- 모달/드롭다운처럼 portal이 필요한 컴포넌트는 preview shell에 `#ds-portal` 이 이미 존재한다고 가정하고 사용한다. story 안에서 portal root를 다시 만들지 않는다.

## 산출물 목표

- 최종 목표는 “앱 코드 구조 재현”이 아니라 “local-server Storybook에서 즉시 실행 가능한 미리보기”다.
- 따라서 앱 레이어 분리보다도 아래를 우선한다.
  - Code Connect 샘플을 최대한 보존할 것
  - Storybook MCP로 props와 compound 구조를 검증할 것
  - Storybook에서 오류 없이 렌더링될 것
  - 디자인 레이아웃을 최대한 보존할 것
  - 필요한 import가 local-server dependency로 해석 가능할 것
  - 지정된 story export 계약을 정확히 지킬 것
