# 블록 작성 규칙

Figma 1:1 HTML을 재사용 가능한 블록으로 전환할 때, 이 규칙을 따른다.
figma_to_html_agent와 design_agent 간의 **계약서**.

---

## 1. HTML 규칙

### 구조 스타일은 OK
블록의 배치/정렬을 위한 CSS는 블록 안에 있어야 한다.
```css
/* OK */
display: flex;
grid-template-columns: repeat(3, 1fr);
align-items: center;
overflow: hidden;
position: relative;
```

### 직접값은 금지
하드코딩된 폰트/색/여백은 블록 안에 넣지 않는다.
```css
/* NG */
font-size: 11px;
color: #475569;
padding: 16px;

/* OK — 토큰 참조 */
font-size: var(--font-body);
color: var(--color-body);
padding: var(--card-padding);
```

---

## 2. 클래스명 규칙

### 공통 클래스 (모든 블록에서 사용)
| 클래스 | 용도 | 토큰 참조 |
|--------|------|-----------|
| `.zone-title` | 중목차 제목 | `--font-zone-title`, `--color-zone-title` |
| `.sub-title` | 소목차 제목 | `--font-sub-title` |
| `.bul` | 본문 블릿 (hanging indent) | `--font-body`, `--bullet-indent` |
| `.body-text` | 본문 텍스트 | `--font-body`, `--color-body` |
| `.caption` | 캡션/보조 | `--font-caption`, `--color-caption` |

### 블록 고유 클래스
블록별 고유 요소는 블록 prefix를 붙인다.
```
.p3c-bar        (prerequisites-3col의 gradient 바)
.pp2-col        (process-product-2col의 컬럼)
.cid-card       (card-icon-desc의 카드)
```

---

## 3. 슬롯 규칙

블록이 받아들이는 콘텐츠 슬롯. catalog에 명시.

| 슬롯 | 용도 | 예시 |
|------|------|------|
| `zone_title` | 중목차 제목 | "DX의 궁극적 목표" |
| `sub_title` | 소목차 제목 | "안전과 품질" |
| `body` | 본문 텍스트 | 설명 문장 |
| `bullets` | 블릿 리스트 | D2: 항목들 |
| `image` | 이미지 | 시각 앵커 |
| `preview` | 상세 preview | 표 헤더+행 |
| `detail_link` | 자세히보기 링크 | 첨부 파일 연결 |

---

## 4. 토큰 참조 방법

### 토큰 파일 위치
```
templates/styles/tokens/
├── typography.css   ← 글자 위계
├── spacing.css      ← 여백/간격
└── colors.css       ← 색상
```

### 사용법
```css
/* 블록 CSS에서 */
.my-block-title {
  font-size: var(--font-sub-title);
  font-weight: var(--weight-sub-title);
  line-height: var(--lh-sub-title);
  color: var(--color-zone-title);
  margin-bottom: var(--heading-gap);
}

.my-block-body {
  font-size: var(--font-body);
  color: var(--color-body);
  padding-left: var(--bullet-indent);
  text-indent: calc(var(--bullet-indent) * -1);
}
```

### 블록 의미색이 필요할 때
공통 테마색으로 안 되는 역할색은 colors.css의 2층 의미색을 참조.
```css
/* 3열 비교의 열별 색상 */
.col-1 .bar { background: linear-gradient(180deg, var(--color-col-1-from), var(--color-col-1-to)); }
.col-2 .bar { background: linear-gradient(180deg, var(--color-col-2-from), var(--color-col-2-to)); }
```

---

## 5. 블록 HTML 예시

### 좋은 예
```html
<section class="block block-3col">
  <div class="col">
    <div class="sub-title">{{ col.title }}</div>
    <div class="bul">• {{ col.desc }}</div>
  </div>
</section>

<style>
.block-3col {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: var(--card-gap);
}
.block-3col .col {
  padding: var(--card-padding);
  background: var(--color-bg-subtle);
  border: 1px solid var(--color-border);
  border-radius: var(--card-radius);
}
</style>
```

### 나쁜 예
```html
<!-- NG: 직접값 하드코딩 -->
<div style="font-size:12px; color:#1e293b; padding:16px; background:#f8fafc; border-radius:6px;">
```

---

## 6. 전환 체크리스트

Figma 1:1 HTML → 재사용 블록으로 전환할 때:

- [ ] font-size 직접값 → `var(--font-*)` 교체
- [ ] color 직접값 → `var(--color-*)` 교체
- [ ] padding/margin 직접값 → semantic spacing 또는 `var(--space-*)` 교체
  - 카드 내부: `var(--card-padding)`
  - 블릿 들여쓰기: `var(--bullet-indent)`
  - 소제목 아래: `var(--heading-gap)`
  - 일반 여백: `var(--space-sm)`, `var(--space-md)` 등
- [ ] gap → `var(--card-gap)`, `var(--flex-gap)` 등
- [ ] border-radius → `var(--card-radius)` 교체
- [ ] 공통 클래스 사용 (`.bul`, `.sub-title` 등)
- [ ] 블록 고유 요소에 prefix 클래스
- [ ] catalog에 슬롯/구조/호환 정보 등록