권장 / 비권장 사례

이 문서는 권장되는 UI 구조와 네이밍 방식, 그리고 지양해야 할 사례를 비교하여 설명하는 Reference 문서입니다.

이 문서의 목적은 정답 코드를 제시하는 것이 아니라, 올바른 판단 기준을 명확히 하는 것입니다.

권장되는 구조의 정상 스니펫은 네이밍 예제에서 정본으로 관리하며, 이 문서에서는 비권장 사례를 대비로 보여 판단 기준을 명확히 합니다.

컴포넌트 구조

권장 사례

컴포넌트는 하나의 책임만 가집니다
접두사를 사용하지 않습니다
내부 요소(i_)는 컴포넌트 내부에서만 사용됩니다

정상 스니펫은 네이밍 예제를 참고하세요.

비권장 사례

하나의 컴포넌트가 여러 역할을 가집니다
시각적 의미가 클래스명에 포함됩니다
내부 요소가 단독으로 사용됩니다

<h3 class="i_title">Title</h3>
<div class="card big_red">
  <p>Description</p>
</div>

수정자 사용

권장 사례

수정자(m_)는 상태나 변형만 표현합니다
구조는 변경하지 않습니다
기존 블록 클래스와 함께 사용됩니다

정상 스니펫은 네이밍 예제를 참고하세요.

비권장 사례

수정자가 구조를 대체합니다
수정자만 단독으로 사용됩니다
시각적 표현만을 위한 수정자가 사용됩니다

<div class="m_selected">
  <h3>Title</h3>
</div>

페이지와 컴포넌트 관계

권장 사례

페이지(page_)는 컴포넌트를 조합합니다
페이지 내부 요소(p_)는 페이지 전용으로 사용됩니다
컴포넌트는 페이지에 종속되지 않습니다

정상 스니펫은 네이밍 예제를 참고하세요.

비권장 사례

페이지 전용 구조가 컴포넌트로 분리됩니다
컴포넌트가 특정 페이지 의미를 포함합니다

<div class="home_card">
  <h3 class="i_title">Title</h3>
</div>

레이아웃 구조

권장 사례

레이아웃(layout_)은 전역 구조만 담당합니다
배치와 틀 역할에 집중합니다
페이지/컴포넌트 의미를 포함하지 않습니다

정상 스니펫은 네이밍 예제를 참고하세요.

비권장 사례

레이아웃 안에 레이아웃이 중첩됩니다
레이아웃이 페이지 또는 컴포넌트 역할을 겸합니다

<div class="layout_header">
  <section class="layout_main">
    <h1>Title</h1>
  </section>
</div>

상태 표현 방식

권장 사례

상태는 data-* 속성으로 표현합니다
클래스는 구조만 담당합니다
CSS가 상태를 해석해 스타일을 적용합니다

정상 스니펫은 네이밍 예제를 참고하세요.

비권장 사례

상태를 클래스명으로 직접 표현합니다
구조 클래스가 상태 의미를 포함합니다

<div class="accordion is_open">
  <button>Toggle</button>
  <div>Content</div>
</div>

구조 중첩

권장 사례

구조 단위는 조합으로만 사용됩니다
같은 구조 단위끼리 중첩되지 않습니다

정상 스니펫은 네이밍 예제를 참고하세요.

비권장 사례

컴포넌트 안에 같은 컴포넌트가 중첩됩니다
페이지 안에 다른 페이지가 중첩됩니다

<div class="card">
  <div class="card"></div>
</div>

<section class="page_home">
  <section class="page_about"></section>
</section>

지양 패턴 — 규칙 문서 포인터

위 사례들을 관통하는 지양 패턴과 각각의 정본 규칙 문서입니다.

역할이 모호한 클래스 — 하나의 클래스가 구조·스타일·상태를 동시에 담당하면 수정 범위를 예측할 수 없습니다. → 역할 분리 원칙
과도한 중첩 선택자 — 상위 구조에 의존한 깊은 선택자는 구조 변경 시 연쇄적으로 깨집니다. → 중첩 구조 규칙
시각적 표현 중심 네이밍 — 표현이 바뀔 때마다 구조 수정으로 이어집니다. 네이밍은 접두사 기준표, 값은 토큰으로 관리합니다.
구조를 대체하는 JavaScript — UI 구조를 임의로 생성·삭제하면 구조를 추적하기 어렵습니다. → 상태 기반 UI
임의 값 사용 — 기준 없는 값이 늘어날수록 일관성이 저하됩니다. → 토큰

판단 기준 요약

아래 질문에 “예”라고 답할 수 없다면 해당 구조는 재검토가 필요합니다.

이 클래스는 구조를 표현하고 있는가
상태와 역할이 분리되어 있는가
이 구조는 재사용 가능한가
접두사만 보고 구조 범위를 판단할 수 있는가

문서의 역할

이 문서는 “이렇게 쓰세요”를 강제하는 문서가 아니라, “이게 맞는 구조인가?”를 판단하기 위한 기준 문서입니다.

권장 사례를 통해 방향을 제시하고, 비권장 사례를 통해 실수를 예방합니다.