설치 및 사용

저장소를 로컬에서 실행하고 UI 컴포넌트를 프로젝트에 적용하는 방법을 안내합니다. Nuxt 4 + Vue 3로 개발·빌드하며, 문서는 src/doc/ 의 Vue SFC로 관리합니다.

사전 요구사항

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

도구	버전	비고
Node.js	22.19+ / 24.11+	Nuxt 4.5.1이 지원하는 LTS 버전 사용
pnpm	9.15.9	package.json의 packageManager 필드 기준

빠른 시작

저장소를 복제하고 의존성을 설치한 뒤 개발 서버를 실행합니다. 브라우저에서 http://localhost:3000/getting-started에 접속하면 이 페이지를 확인할 수 있습니다.

# 저장소 클론
git clone git@github.com:uxkm/guide.git
cd guide

# 의존성 설치
pnpm install

# 개발 서버 실행
pnpm dev

pnpm 스크립트

루트 package.json의 스크립트입니다.

명령	설명
`pnpm dev`	Nuxt 개발 서버 실행 (기본 주소: http://localhost:3000)
`pnpm build`	Nitro 프로덕션 서버 빌드
`pnpm generate`	정적 사이트 생성 (.output/public/)
`pnpm preview`	build 또는 generate 결과를 로컬에서 미리보기
`pnpm deploy:main`	nuxt 브랜치의 정적 결과물을 main/nuxt/에 배포

빌드 및 미리보기

서버 배포에는 build를, 정적 호스팅에는 generate를 사용합니다. 두 방식 모두 결과 생성 후 preview로 확인할 수 있습니다.

# Nitro 서버용 빌드
pnpm build

# 또는 정적 사이트 생성
pnpm generate

# 생성 결과 확인
pnpm preview

스타일 적용

이 가이드는 Nuxt 빌드 시 src/scss/main.scss가 자동으로 번들됩니다.

다른 프로젝트에서 SCSS 소스를 직접 쓰려면 자체 빌드 도구(Vite, Webpack 등)에 src/scss/main.scss 를 포함합니다. 필요한 컴포넌트만 가져올 때도 공통 토큰·테마·리셋을 먼저 불러와야 합니다.

// 전체 스타일 — Vite의 SCSS loadPaths에 src/scss를 등록한 경우
@use "main";

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

컴포넌트 마크업 사용

각 컴포넌트 문서의 마크업 섹션 HTML은 어떤 프로젝트에도 복사해 사용할 수 있습니다. 클래스 이름과 ARIA 속성을 그대로 쓰면 스타일이 적용됩니다. 모달·드로어·아코디언 등 인터랙션이 필요한 컴포넌트는 Vue 컴포넌트 구현을 참고하거나, data-* 속성과 JS를 함께 포함합니다.

변경 사항이 저장되었습니다.

HTML 마크업 예시

Vue 없이 HTML·CSS만으로도 동일한 UI를 구성할 수 있습니다. 아래 마크업을 복사해 사용하세요.

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

테마

라이트/다크 테마는 data-theme 속성으로 전환됩니다. useTheme composable이 헤더 토글과 localStorage 의 guide-theme 값을 관리합니다. 저장된 값이 없으면 운영체제의 색상 설정을 따릅니다.

<!-- 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 변수로 정의됩니다. 전역 토큰의 기본값·사용 방법은 디자인 토큰 문서를 참고하세요.

새 컴포넌트 추가

컴포넌트를 새로 등록할 때 추가·수정하는 파일입니다.

파일	역할
`src/doc/components/{name}.vue`	컴포넌트 문서 페이지
`src/components/{Name}.vue`	재사용 UI 컴포넌트 (Vue SFC)
`src/scss/components/_{name}.scss`	컴포넌트 스타일
`src/scss/components/_index.scss`	@use "{name}" 등록
`src/data/navigation.js`	사이드바 메뉴 항목 추가
`src/pages/components/[slug].vue`	Nuxt 동적 문서 라우트