HTML Components

순수 HTML과 SCSS로 구성된 UI 컴포넌트 가이드입니다. 프레임워크 없이 마크업과 클래스 조합만으로 버튼·폼·피드백·네비게이션 등 50여 개 컴포넌트를 확인할 수 있으며, 컴포넌트 자체는 어떤 프로젝트에도 HTML·CSS만으로 적용할 수 있습니다.

개요

이 사이트는 디자인 시스템 문서이자 재사용 가능한 UI 패턴 모음입니다. 각 컴포넌트 페이지에서 라이브 데모, 마크업 예시, 클래스·속성 표, 디자인 토큰을 함께 제공합니다.

OOCSS 구조 — 블록(.btn) + 파트(.btn_label) + 스킨·크기·상태 클래스를 조합해 사용합니다.
디자인 토큰 — 색상·간격·타이포 등은 _tokens.scss의 CSS 변수로 관리하며, 라이트/다크 테마를 지원합니다. 자세한 목록은 디자인 토큰을 참고하세요.
접근성 — role · aria-* 속성과 키보드·포커스 패턴을 컴포넌트별로 안내합니다.
이 저장소의 빌드 — 문서 사이트 생성은 Gulp로 수행합니다. SCSS 컴파일, HTML 조립, 이미지 압축, JS 복사 후 결과물을 html/에 출력합니다.

빠른 시작

이 가이드 저장소를 클론한 뒤 의존성을 설치하고 Gulp 개발 태스크를 실행합니다. pnpm 스크립트는 내부적으로 Gulp를 호출합니다. 자세한 내용은 설치 및 사용을 참고하세요.

# 의존성 설치
pnpm install

# Gulp 개발 (빌드 + watch + BrowserSync)
pnpm dev

# Gulp 프로덕션 빌드
pnpm build

컴포넌트 카테고리

왼쪽 사이드바에서 컴포넌트를 선택하거나, 아래 카테고리 카드로 바로 이동할 수 있습니다.

레이아웃

Container, Grid, Flex, Divider, Space

5개 컴포넌트

기본 요소

Button, Typography, Icon, Link

4개 컴포넌트

데이터 표시

Avatar, Card, Table, List, Stat, Calendar 등

10개 컴포넌트

폼

Input, Select, Checkbox, Switch, Upload 등

11개 컴포넌트

피드백

Alert, Modal, Spin, Skeleton, Empty 등

9개 컴포넌트

네비게이션

Navbar, Tabs, Breadcrumb, Pagination, Steps 등

7개 컴포넌트

기타

Accordion, Collapse, Carousel, Affix, Back Top

5개 컴포넌트

이 저장소 구조

아래는 이 가이드 저장소의 디렉터리 구성입니다. 소스는 src/에서 관리하고, Gulp 빌드 결과물이 html/에 출력됩니다. 배포 시 html/ 폴더 전체를 사용합니다.

gulpfile.js                   # Gulp 태스크 정의 (빌드·watch·서버)
scripts/html-assembler.js     # Gulp html 태스크 — 레이아웃 조립

src/                          # 소스
├── _layouts/                 # 레이아웃 템플릿 (base, header)
├── components/               # 컴포넌트별 문서 페이지
├── images/                   # 이미지 소스 (Gulp images 태스크로 압축)
├── js/
│   ├── nav.js                # 사이드바 메뉴 렌더링
│   ├── theme.js              # 라이트/다크 테마 전환
│   └── demo.js               # 데모 인터랙션 (모달, 아코디언 등)
├── scss/
│   ├── _tokens.scss          # 디자인 토큰 (:root CSS 변수)
│   ├── _themes.scss          # 라이트/다크 테마
│   ├── _variables.scss       # SCSS 전용 변수
│   ├── components/           # 컴포넌트별 스타일
│   └── main.scss             # SCSS 진입점 (Gulp styles 태스크)
├── index.html                # 소개 (이 페이지)
├── getting-started.html      # 설치 및 사용
└── design-tokens.html        # 디자인 토큰

html/                         # Gulp build 결과물 (배포용)
├── components/               # 조립된 컴포넌트 페이지
├── css/main.css              # Gulp styles — 컴파일된 CSS
├── images/                   # Gulp images — 압축된 이미지
├── js/                       # Gulp scripts — 복사된 스크립트
├── index.html
├── getting-started.html
└── design-tokens.html

컴포넌트 마크업·SCSS는 다른 프로젝트에도 가져다 쓸 수 있습니다. 다만 src/ → html/ 변환과 문서 페이지 조립은 이 저장소의 Gulp 설정에 따릅니다.

네이밍 · 클래스 규칙

컴포넌트 스타일은 OOCSS 패턴을 따릅니다. 아래 규칙을 익혀 두면 문서와 소스를 일관되게 읽을 수 있습니다.

패턴	예시	설명
`블록`	`.btn` · `.alert` · `.empty`	컴포넌트 루트 구조 클래스
`블록_파트`	`.btn_label` · `.empty_desc`	하위 요소 (언더스코어 1개)
`블록_변형`	`.btn_filled` · `.alert_sm`	스킨·크기·레이아웃 변형
`color_*`	`.color_primary` · `.color_danger`	공통 의미 색상 (여러 컴포넌트에서 재사용)
`is-*`	`.is-open` · `.is-loading`	JS·상태 토글 클래스

문서 페이지 마크업

이 가이드 사이트의 문서 페이지는 src/에 HTML 조각을 두고, 상단 @meta 주석으로 제목·네비게이션 활성 상태를 지정합니다. Gulp html 태스크가 _layouts/base.html과 조립해 html/에 완성 페이지를 생성합니다.

<!-- @meta
title: Button | HTML Components
activeNav: button
pageTitle: Button
-->
<div class="page_intro">
  <h1>Button</h1>
  <p class="lead">…</p>
</div>

<section class="section demo_section" aria-labelledby="basic-heading">
  …
</section>