UI Components
Nuxt 4와 Vue 3로 구현한 UI 컴포넌트 가이드입니다. 마크업과 클래스 조합으로 버튼·폼·피드백·네비게이션 등 50여 개 컴포넌트를 확인할 수 있으며, 컴포넌트 자체는 HTML·CSS만으로도 다른 프로젝트에 적용할 수 있습니다.
개요
Nuxt의 파일 기반 라우팅과 Nitro 사전 렌더링으로 제공하는 디자인 시스템 문서이자 재사용 가능한 UI 패턴 모음입니다. 각 컴포넌트 페이지에서 라이브 데모, 마크업 예시, 클래스·속성 표, 디자인 토큰을 함께 제공합니다.
OOCSS 구조 — 블록(.btn) + 파트(.btn_label) + 스킨·크기·상태 클래스를 조합해 사용합니다.
디자인 토큰 — 색상·간격·타이포 등은
_tokens.scss 의 CSS 변수로 관리하며, 라이트/다크 테마를 지원합니다.
디자인 토큰 문서에서 기본값과 사용 방법을 확인할 수 있습니다.
접근성 — role · aria-* 속성과 키보드·포커스 패턴을 컴포넌트별로 안내합니다.
Nuxt 정적 사이트 — Nuxt 4 + Vue 3로 개발하며, nuxt generate로 정적 사이트를 생성합니다. 문서는 src/doc/ 의 Vue SFC로 관리합니다.
기본 Vue 방식과 Nuxt 방식의 차이
기본 Vue SPA는 브라우저에서 하나의 앱을 실행하고 모든 화면 전환을 처리합니다. 현재 가이드는 Nuxt가 문서별 정적 HTML과 메타데이터를 만들고, Vue가 필요한 데모 상호작용만 담당하도록 구성했습니다.
- 시작
- index.html · src/main.js
- 경로
- Vue Router에서 처리
- 출력
- Vite → dist/
장점
- 구조와 설정이 단순합니다.
- 프레임워크 의존성이 낮고 정적 호스팅이 쉽습니다.
단점
- 초기 화면이 JavaScript 실행에 의존합니다.
- 검색·공유 메타데이터와 직접 URL 접근을 별도로 구성해야 합니다.
- 시작
- app.vue · pages/ · layouts/
- 경로
- Nuxt 파일 기반 라우팅
- 출력
- nuxt generate → .output/public/
장점
- 문서별 HTML과 메타데이터를 빌드 시 생성합니다.
- 파일 라우팅·내부 링크·baseURL을 Nuxt에서 일관되게 관리합니다.
단점
- 서버와 클라이언트의 실행 환경을 구분해야 합니다.
- 동적 서버 기능은 정적 생성 시 별도 배포 전략이 필요합니다.
즉, 컴포넌트와 상태 관리는 동일한 Vue 방식으로 작성하고, 페이지 생성·정적 생성·배포 경로 같은 애플리케이션 구조는 Nuxt가 담당합니다.
빠른 시작
이 가이드 저장소를 클론한 뒤 의존성을 설치하고 Nuxt 개발 서버를 실행합니다. 서버가 시작되면 http://localhost:3000에서 확인할 수 있습니다. 자세한 내용은 설치 및 사용을 참고하세요.
설치 및 사용
# 의존성 설치
pnpm install
# Nuxt 개발 서버
pnpm dev
# Nitro 프로덕션 빌드
pnpm build
컴포넌트 카테고리
왼쪽 사이드바에서 컴포넌트를 선택하거나, 아래 카테고리 카드로 바로 이동할 수 있습니다.
레이아웃
Container, Grid, Flex, Divider, Space
5개 컴포넌트기본 요소
Button, Typography, Icon, Link
4개 컴포넌트데이터 표시
Avatar, Badge, Tag, Card, Table, List, Stat, Calendar, Timeline, Tree
10개 컴포넌트폼
Form Layout, Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Rate, Date Picker, Upload
11개 컴포넌트피드백
Alert, Modal, Drawer, Popover, Tooltip, Progress, Spin, Skeleton, Empty
9개 컴포넌트네비게이션
Navbar, Menu, Tabs, Breadcrumb, Pagination, Steps, Dropdown
7개 컴포넌트기타
Accordion, Collapse, Carousel, Affix, Back Top
5개 컴포넌트이 저장소 구조
아래는 이 가이드 저장소의 디렉터리 구성입니다. SCSS·Vue 문서 소스와 Nuxt 페이지·레이아웃은 src/에서 관리합니다.
src/
├── components/ # 재사용 UI 컴포넌트 (Vue SFC)
├── doc/
│ ├── components/ # 컴포넌트 문서 페이지
│ └── pages/ # 소개·설치 페이지
├── pages/ # Nuxt 파일 기반 라우트
├── layouts/default.vue # 가이드 공통 레이아웃
├── plugins/ # Nuxt 클라이언트 플러그인
├── scss/
│ ├── _tokens.scss # 디자인 토큰 (:root CSS 변수)
│ ├── _themes.scss # 라이트/다크 테마
│ ├── components/ # 컴포넌트별 스타일
│ └── main.scss # SCSS 진입점
└── app.vue # Nuxt 앱 루트
nuxt.config.js # 앱·정적 배포 설정
.output/ # Nuxt 빌드·정적 생성 결과
컴포넌트 마크업·SCSS는 다른 프로젝트에도 가져다 쓸 수 있습니다. Vue 데모는 src/scss/main.scss 를 import해 동일한 디자인 시스템을 공유합니다.
네이밍 · 클래스 규칙
컴포넌트 스타일은 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/doc/components/의 Vue SFC로 작성하며, docMeta로 제목·네비게이션 활성 상태를 지정합니다.
<script>
export const docMeta = {
title: 'Button | HTML Components',
activeNav: 'button',
pageTitle: 'Button',
};
</script>
<template>
<div class="page_intro">
<h1>Button</h1>
<p class="lead">…</p>
</div>
…
</template>