C.E.L_Slide_test2/docs/architecture/BLOCK-RULES.md

블록 작성 규칙

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

---

1. HTML 규칙

구조 스타일은 OK

블록의 배치/정렬을 위한 CSS는 블록 안에 있어야 한다.

/* OK */
display: flex;
grid-template-columns: repeat(3, 1fr);
align-items: center;
overflow: hidden;
position: relative;

직접값은 금지

하드코딩된 폰트/색/여백은 블록 안에 넣지 않는다.

/* 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에서 */
.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층 의미색을 참조.

/* 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 예시

좋은 예

<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>

나쁜 예

<!-- 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에 슬롯/구조/호환 정보 등록