설치 및 사용 | HTML Components

사전 요구사항

아래 환경이 설치되어 있어야 합니다.

도구	버전	비고
Node.js	18 이상 권장	LTS 버전 사용
pnpm	9.x	`packageManager` 필드에 명시된 버전
Gulp	5.x	`devDependencies` — `pnpm install` 시 함께 설치

설치

이 가이드 저장소를 클론한 뒤 프로젝트 루트에서 의존성을 설치합니다. Gulp 및 관련 플러그인이 devDependencies로 함께 설치됩니다.

# 저장소 클론
git clone <repository-url>
cd guide

# 의존성 설치
pnpm install

Gulp

이 저장소의 빌드·감시·로컬 서버는 루트 gulpfile.js에 정의된 Gulp 태스크로 동작합니다. HTML 조립 로직은 scripts/html-assembler.js에서 처리합니다.

Gulp 태스크	설명
`gulp build`	프로덕션 빌드 — `html/` 폴더를 비운 뒤 styles · scripts · html · images · staticFiles를 병렬 실행
`gulp` (기본)	`build` 후 BrowserSync 서버 기동 + 파일 watch
`gulp watch`	기본 태스크와 동일
`gulp styles`	`src/scss/main.scss` → `html/css/main.css` (Sass 컴파일, source map)
`gulp html`	`src/*/.html` → 레이아웃 조립 후 `html/` 출력
`gulp scripts`	`src/js/` → `html/js/` 복사
`gulp images`	`src/images/` → 압축 후 `html/images/` 출력
`gulp clean`	`html/` 폴더 삭제

# Gulp 직접 실행
pnpm exec gulp build
pnpm exec gulp
pnpm exec gulp styles

pnpm 스크립트

package.json의 스크립트는 Gulp 태스크를 호출합니다.

명령	실행되는 Gulp 태스크	설명
`pnpm dev`	`gulp`	Gulp build + BrowserSync + watch
`pnpm build`	`gulp build`	Gulp 프로덕션 빌드 → `html/` 생성
`pnpm watch`	`gulp watch`	Gulp build + watch (서버 없음)

개발 서버

개발 중에는 pnpm dev로 Gulp 기본 태스크를 실행합니다. Gulp가 src/의 SCSS · HTML · JS · 이미지 변경을 감지해 해당 태스크를 다시 실행하고, BrowserSync가 브라우저를 새로고침합니다.

pnpm dev   # gulp 와 동일

로컬 서버가 시작되면 터미널에 접속 URL이 표시됩니다. 서버 설정은 gulpfile.js의 BrowserSync 옵션을 따릅니다.

프로덕션 빌드

pnpm build는 Gulp build 태스크를 실행합니다. 배포용 결과물은 html/ 폴더에 생성되며, 이 폴더 전체를 정적 호스팅에 업로드하면 됩니다.

pnpm build   # gulp build 와 동일

Gulp build 태스크가 수행하는 작업:

clean — html/ 초기화
styles — src/scss/main.scss → html/css/main.css
html — src/**/*.html 레이아웃 조립 → html/
scripts · vendorScripts — JS 복사
images — 이미지 압축 출력
staticFiles — 폰트·기타 정적 파일 복사

스타일 적용

이 가이드 사이트에서 Gulp build 후 생성된 CSS를 연결하는 방법입니다.

<!-- Gulp build 결과 — 루트 페이지 -->
<link rel="stylesheet" href="css/main.css">

<!-- Gulp build 결과 — components/ 하위 페이지 -->
<link rel="stylesheet" href="../css/main.css">

다른 프로젝트에서 SCSS 소스를 직접 쓰려면 자체 빌드 도구(Webpack, Vite, Gulp 등)에 src/scss/main.scss를 포함하거나, 필요한 컴포넌트만 선택 import합니다. 이 경우에도 컴포넌트 클래스·마크업 규칙은 동일하게 적용됩니다.

// 전체 스타일
@use "main";

// 또는 필요한 컴포넌트만 선택
@use "tokens";
@use "themes";
@use "reset";
@use "components/button";
@use "components/input";
@use "components/alert";

문서 페이지 추가 (Gulp html)

이 가이드에 새 문서 페이지를 추가할 때는 src/ 또는 src/components/에 HTML 조각을 만들고 상단에 @meta 주석을 작성합니다. Gulp html 태스크가 _layouts/base.html · header.html과 조립합니다.

<!-- @meta
title: My Page | HTML Components
activeNav: my-page
pageTitle: My Page
-->
<div class="page_intro">
  <h1>My Page</h1>
  <p class="lead">페이지 설명</p>
</div>

<section class="section" aria-labelledby="section-heading">
  <h2 id="section-heading">섹션 제목</h2>
  <p>본문 내용</p>
</section>

사이드바의 1뎁스 메뉴는 src/js/nav.js의 NAV_TOP_LEVEL에, 카테고리별 하위 메뉴는 NAV_GROUPS에 등록합니다.

// src/js/nav.js
{
  title: '내 카테고리',
  items: [
    {
      label: 'My Page',
      href: 'components/my-page.html',
      slug: 'my-page',   // @meta activeNav와 일치
    },
  ],
}

컴포넌트 마크업 사용

각 컴포넌트 문서의 마크업 섹션 HTML은 Gulp와 무관하게 어떤 프로젝트에도 복사해 사용할 수 있습니다. 클래스 이름과 ARIA 속성을 그대로 쓰면 스타일이 적용됩니다.

<!-- Button 예시 -->
<button type="button" class="btn btn_filled color_primary">
  <span class="btn_label">저장</span>
</button>

<!-- Alert 예시 -->
<div class="alert color_info" role="alert">
  <div class="alert_body">
    <p class="alert_desc">변경 사항이 저장되었습니다.</p>
  </div>
</div>

모달·드로어·아코디언 등 인터랙션이 필요한 컴포넌트는 demo.js의 동작을 참고하거나, 해당 data-* 속성과 JS를 함께 포함합니다.

가이드 사이트 스크립트

이 가이드 사이트의 레이아웃(사이드바·테마·데모)을 쓰려면 아래 스크립트가 필요합니다. Gulp html 태스크가 빌드된 HTML에 자동 삽입합니다.

<!-- 테마 초기화 (FOUC 방지) — head 내 link 앞에 삽입 -->
<script>
  !function () {
    try {
      var t = localStorage.getItem("guide-theme");
      if ("light" !== t && "dark" !== t) {
        t = window.matchMedia("(prefers-color-scheme: dark)").matches
          ? "dark" : "light";
      }
      document.documentElement.setAttribute("data-theme", t);
    } catch (e) {}
  }();
</script>

<!-- body 하단 -->
<script src="js/theme.js"></script>
<script src="js/nav.js"></script>
<script src="js/demo.js"></script>

컴포넌트만 단독으로 사용하는 경우 CSS만 연결해도 되며, 인터랙션이 필요한 경우에만 해당 JS를 포함하면 됩니다.

테마

라이트/다크 테마는 data-theme 속성으로 전환됩니다. theme.js가 헤더의 토글 버튼과 localStorage를 관리합니다.

<!-- HTML 루트에 테마 지정 -->
<html lang="ko" data-theme="light">
<html lang="ko" data-theme="dark">

<!-- JS로 전환 -->
document.documentElement.setAttribute("data-theme", "dark");

색상·간격 등 디자인 값은 src/scss/_tokens.scss와 _themes.scss에서 CSS 변수로 정의됩니다. 커스텀 테마를 만들 때는 이 파일의 변수를 수정하세요.

이미지 (Gulp images)

src/images/에 추가한 이미지는 Gulp images 태스크가 압축해 html/images/에 출력합니다.

src/images/
├── avatar-sample.svg
└── hero-banner.webp

# HTML에서 참조 (루트 페이지)
<img src="images/avatar-sample.svg" alt="아바타">

# components/ 하위 페이지
<img src="../images/avatar-sample.svg" alt="아바타">

지원 형식: jpg, jpeg, png, gif, svg, webp, avif

새 컴포넌트 문서 추가

이 가이드에 컴포넌트 문서를 새로 등록할 때 추가·수정하는 파일입니다. Gulp build 또는 html · styles 태스크가 변경을 반영합니다.

파일	역할
`src/components/{name}.html`	데모·문서 페이지
`src/scss/components/_{name}.scss`	컴포넌트 스타일
`src/scss/components/_index.scss`	`@use "{name}"` 등록
`src/js/nav.js`	사이드바 메뉴 항목 추가
`src/scss/_tokens.scss`	필요 시 디자인 토큰 추가

파일 추가 후 pnpm dev(Gulp watch) 또는 pnpm build(Gulp build)를 실행하면 html/components/{name}.html이 생성됩니다.