# 컴포넌트 문서 템플릿

## AI Contract

- status: `source required`
- exactHtml: `source required`
- catalogRoute: `site/index.html#components`
- rootSelector: `source required`
- figma: `UI-5.1`
- baseCss: `site/sonar5.css`
- gapCss: `site/component-css/component.css`
- sourcePointer: `ui/docs/components/컴포넌트-문서-템플릿.md`
- sonarLock: `site/sonar5.css` is read-only; do not add or mutate product CSS from this component doc.
- qaStatus: `mismatch=- light mode checked:`
- usage: Read this block first for AI screen generation. Expand detailed sections only when this contract is insufficient.

## 작성 원칙

- 이 템플릿은 `design.md`, 각 `Component.md`, 퍼블리싱된 component HTML을 함께 사용해 Logpresso 제품과 같은 룩의 화면 HTML을 생성하기 위한 계약 문서 구조다.
- `Component.md`는 긴 HTML handoff가 아니라 usage contract, source pointer, selector contract, do/don't를 기록한다.
- 실제 DOM, class, data attribute 기준은 퍼블리싱된 exact component page에서 확인한다.
- 문서는 QA mismatch count `0` 이후에만 갱신한다.
- Figma `UI-5.1`이 정답이다. Figma node가 없거나 후보가 여러 개면 확정 전까지 구현과 문서화를 하지 않는다.
- `sonar5.css`는 읽기 전용 reference다. 새 visual rule이나 gap 보정은 `component-css/component.css`에만 기록한다.
- 다른 문서를 참조할 때는 현재 문서 기준 상대 경로를 사용한다. 저장소 절대 경로는 문서 본문에 남기지 않는다.

## 문서 구조

아래 구조를 기본으로 사용한다. 컴포넌트 성격상 해당하지 않는 항목은 `해당 없음` 또는 `확인 필요`로 명시하고 추정해서 채우지 않는다.

```md
# Component Name

## 목적

- 이 컴포넌트가 제품 화면에서 맡는 역할을 적는다.
- primitive, composition, shell, surface, pattern 중 어떤 성격인지 적는다.

## Figma evidence

- Figma file: `UI-5.1`
- node id / URL:
- confirmed scope:
- confirmed variants:
- confirmed states:
- not confirmed:

## 구현 기준

- exact page:
- catalog route:
- source helper:
- generated owner:
- root selector / data attribute:
- base CSS selector from `sonar5.css`:
- gap CSS selector from `component-css/component.css`:

## anatomy

- root:
- required slot:
- optional slot:
- child component:
- overlay / trigger relation:

## variants / states

- variant:
- size:
- state:
- interaction:
- light / dark:

## usage guidance

- 사용해야 하는 경우:
- 함께 사용해야 하는 컴포넌트:
- 화면 조립 시 확인해야 하는 exact page:
- 접근성 계약:

## boundary / do not infer

- Figma에 없는 variant/state를 만들지 않는다.
- exact page와 다른 HTML snippet을 문서에 유지하지 않는다.
- `sonar5.css`를 수정하거나 수정된 것처럼 설명하지 않는다.
- `component-css/component.css`의 gap selector를 새 visual language로 확장하지 않는다.
- specimen-only ornament를 실제 제품 화면의 기본 surface로 해석하지 않는다.

## QA status

- QA issue:
- exact page checked:
- catalog route checked:
- Figma-to-HTML mismatch count:
- light mode checked:
- dark mode checked:
- remaining uncertainty:
```

## 작성 체크리스트

- Figma evidence가 정확한 node id 또는 URL로 남아 있다.
- exact page와 catalog route가 문서에 연결되어 있다.
- source helper 또는 generator owner가 명시되어 있다.
- HTML root selector와 data attribute 계약이 명시되어 있다.
- `sonar5.css` 재사용 selector와 `component-css/component.css` gap selector가 구분되어 있다.
- variants와 states는 확인된 범위만 적혀 있다.
- light mode와 dark mode 검증 여부가 적혀 있다.
- do not infer 항목이 컴포넌트별 위험을 막는다.
- QA mismatch count `0` 근거가 없으면 공식 문서 갱신 상태를 complete로 쓰지 않는다.

## 화면 생성자가 읽는 방법

1. `design.md`에서 화면 family와 shell/layout 규칙을 확인한다.
2. 필요한 컴포넌트의 `Component.md`에서 목적, 경계, 금지사항을 확인한다.
3. exact page를 열어 실제 DOM/class/data attribute를 확인한다.
4. `sonar5.css` selector를 먼저 사용한다.
5. 확인된 gap만 `component-css/component.css` selector로 보정한다.
6. 렌더 QA에서 제품 룩, light/dark, overflow, clipping, state를 확인한다.

## 관련 문서

- `ai-generation/SCREEN_GENERATION_ENTRYPOINT.md`
- `ai-generation/screen-html-generation/component-readiness/COMPONENT_MD_READINESS.md`