### 작업과 관련된 정보를 제공할 때 사용하세요 (Assistive button) 주요 동작(Action button) 이외에 사용자의 행동을 보조하는 기능을 제공합니다. 닫기 버튼으로 사용하지 않습니다.

### 작업과 관련된 정보를 제공할 때 사용하세요 (Scroll) 작업과 관련된 정보를 제공합니다. 정해진 높이(Max-height)를 넘길 경우 스크롤을 제공합니다.

### 사용자의 정보 입력이 필요할 경우 사용하세요 페이지를 벗어나지 않고 사용자로부터 입력을 받습니다. 다음 단계를 진행하기 위해 사용자의 입력 값이 필수적으로 필요한 경우 사용합니다.

## Best practices ### Scroll ### Close button ### Button label ### Title ## Patterns ### Dialog에서 발생한 오류는 인라인 메시지를 사용해 알리세요 Dialog에서 발생한 오류는 인라인 메시지로 알립니다. Alert dialog나 Toast를 사용하지 마세요. ## Guidelines ### Height Dialog의 최대 높이(Max-height)는 전체 화면 높이의 80%로 설정됩니다. ### Close behavior * **Close button**: Dialog는 헤더의 Close 버튼으로 닫을 수 있습니다. * **Backdrop 클릭 / ESC**: 배경을 클릭하거나 키보드 ESC를 눌러 Dialog를 닫을 수 있습니다. ### Scroll behavior # Composition URL: /docs/getting-started/composition Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/getting-started/(handbook)/composition.mdx 기본 props로 해결되지 않을 때, Vapor UI 컴포넌트의 구조를 직접 제어하는 방법을 설명합니다. 기본 props로 해결되지 않을 때 두 가지 방법으로 커스터마이징할 수 있습니다. Primitive는 Vapor UI 컴포넌트의 내부 구조를 이루는 최소 단위 컴포넌트입니다. * **Primitive가 없는 컴포넌트** (`Button`, `Badge`, `TextInput` 등): `render` prop으로 커스터마이징합니다. * **Primitive가 있는 컴포넌트** (`Dialog`, `Sheet`, `Tabs` 등): Primitive를 직접 조합해 내부 구조를 제어합니다. 컴포넌트에 Primitive가 있는지 확인하려면 각 컴포넌트 문서의 Props Table에서 `XxxPrimitive` 항목을 찾으세요. ## render prop으로 렌더링 제어하기 `render` prop은 두 가지 형태로 사용할 수 있습니다. **ReactElement 형태** — HTML 태그나 외부 컴포넌트로 교체할 때 사용합니다. ```tsx import { Button, Card, Dialog } from '@vapor-ui/core'; import Link from 'next/link'; // div → article로 교체 } /> // Next.js Link로 교체 ``` **함수 형태** — 컴포넌트의 내부 state에 따라 렌더링 내용을 동적으로 바꿀 때 사용합니다. 함수는 `(props, state)` 두 인자를 받습니다. ```tsx import { Switch } from '@vapor-ui/core'; import { DarkIcon, LightIcon } from '@vapor-ui/icons'; export default function Example() { return ( ( {state.checked ? : } )} /> ); } ``` ## Primitive 직접 조합하기 Primitive를 직접 조합하면 Portal 위치, Overlay 렌더링 순서 등 레이어 구조 전체를 제어할 수 있습니다. ```tsx import { Button, Dialog } from '@vapor-ui/core'; export default function Example() { return ( 열기 제목 내용 닫기} /> ); } ``` # Styling URL: /docs/getting-started/styling Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/getting-started/(handbook)/styling.mdx Vapor UI 컴포넌트를 스타일링하고 커스터마이징하는 방법을 설명합니다. Vapor UI는 단순한 스타일 오버라이드부터 컴포넌트 구조 변경까지 단계별 커스터마이징을 지원합니다. ## 1. 기본 스타일링 (className, style) 가장 익숙한 방식인 `className`과 `style`을 사용합니다. 빠른 스타일 수정이 필요하거나 기존 CSS 체계를 유지해야 할 때 적합합니다. ### className 외부 CSS 파일이나 CSS 모듈의 클래스를 적용합니다. ```tsx import { Button } from '@vapor-ui/core'; export default function Example() { return ; } ``` ### style 인라인 스타일을 통해 동적인 스타일을 직접 주입합니다. ```tsx import { Button } from '@vapor-ui/core'; export default function Example() { return ( ); } ``` ## 2. `$css` 속성 Vapor UI가 권장하는 기본 방식입니다. 별도의 CSS 파일 없이 컴포넌트에서 직접 스타일을 제어할 수 있습니다. ### 기본 CSS 속성 수정 CSS 속성을 객체 형태로 전달하여 스타일을 수정합니다. ```tsx import { Button } from '@vapor-ui/core'; export default function Example() { return ( ); } ``` ### 토큰 기반 스타일링 디자인 토큰을 사용해 일관된 스타일을 유지하세요. 타입 지원을 통해 오타를 방지할 수 있습니다. ```tsx import { Button } from '@vapor-ui/core'; export default function Example() { return ( ); } ``` ### 반응형 및 가상 선택자 반응형 조건(breakpoints)과 가상 선택자(`_hover` 등)를 `$css` 안에서 한 번에 정의할 수 있습니다. ```tsx import { Button } from '@vapor-ui/core'; export default function Example() { return ( ); } ``` ## 3. 상태 기반 스타일링 컴포넌트의 상태(checked, invalid 등)에 따라 스타일을 유연하게 변경할 수 있습니다. ### 함수형 className, style `className`과 `style`에 함수를 전달하여 현재 상태에 맞는 스타일을 동적으로 반환합니다. ```tsx import { Checkbox } from '@vapor-ui/core'; export default function Example() { return ( (state.checked ? 'checkbox-checked' : 'checkbox-unchecked')} style={(state) => ({ backgroundColor: state.invalid ? 'color-mix(in srgb, red 12%, transparent)' : undefined, })} /> ); } ``` ### Data Attributes 컴포넌트 상태는 `data-*` 속성으로 노출됩니다. 상태별 스타일 로직을 CSS 파일로 분리할 때 유용합니다. ```css /* 데이터 속성을 활용한 스타일 정의 */ .checkbox[data-checked] { background-color: var(--vapor-color-background-primary-200); } .checkbox[data-invalid] { border-color: var(--vapor-color-border-danger); } ``` ### 함수형 render `render` prop을 사용하면 렌더링되는 엘리먼트 자체와 클래스 구성을 직접 제어할 수 있습니다. ```tsx import { NavigationMenu } from '@vapor-ui/core'; export default function Example() { return ( ( )} /> ); } ``` # Tailwind CSS v4 URL: /docs/getting-started/tailwindcss-v4 Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/getting-started/(handbook)/tailwindcss-v4.mdx Vapor UI와 함께 Tailwind CSS v4를 사용하세요. 이 문서에서는 Vapor UI와 Tailwind CSS v4를 함께 설정하는 방법을 설명합니다. 설정을 완료하면 Vapor UI 컴포넌트와 Tailwind 유틸리티 클래스를 함께 사용할 수 있습니다. ## 설정 메인 CSS 파일(예: `global.css`)에 아래 코드를 추가합니다. ```css /* global.css */ /* 1. 스타일 우선순위 정의 */ @layer tw-theme, vapor, tw-utilities; @import '@vapor-ui/core/tailwind.css'; /* 2. Tailwind CSS 연결 */ @import 'tailwindcss/theme.css' layer(tw-theme); @import 'tailwindcss/utilities.css' layer(tw-utilities); ``` 설정이 완료되면 Vapor UI 컴포넌트와 Tailwind 유틸리티를 함께 사용할 수 있습니다. ## Vapor 유틸리티 클래스 `v-` 접두사가 붙은 Vapor 전용 유틸리티 클래스를 사용할 수 있습니다. ### 디자인 토큰 클래스 Vapor의 색상, 간격, 둥근 모서리를 Tailwind 문법으로 사용합니다. `v-` 접두사를 추가하여 Vapor 디자인 토큰을 적용합니다. * **색상**: `bg-v-blue-500`, `text-v-red-300`, `border-v-gray-900` * **간격**: `p-v-100`, `m-v-200`, `gap-v-400`, `w-v-400` * **둥근 모서리**: `rounded-v-200`, `rounded-t-v-400` * **폰트 굵기**: `font-v-400`, `font-v-700` Tailwind의 모든 [유틸리티 클래스](https://tailwindcss.com/docs/theme#theme-variable-namespaces)와 조합할 수 있습니다. ### 시맨틱 유틸리티 클래스 의미 기반 색상 클래스를 제공합니다. Primary, Success, Warning 등의 역할에 맞는 색상을 적용합니다. * **배경색**: `bg-v-primary`, `bg-v-secondary`, `bg-v-success`, `bg-v-warning`, `bg-v-danger` * **텍스트색**: `text-v-primary`, `text-v-success`, `text-v-warning`, `text-v-danger`, `text-v-accent` * **테두리색**: `border-v-primary`, `border-v-success`, `border-v-warning`, `border-v-danger` ## 스타일 우선순위 CSS `@layer` 규칙으로 스타일 우선순위 계층을 정의합니다. 1. Vapor 컴포넌트 기본 스타일 2. Vapor 유틸리티 클래스 3. Tailwind 유틸리티 (가장 높은 우선순위) Tailwind 유틸리티가 가장 높은 우선순위를 가지므로 `className="bg-blue-500"`와 같은 클래스로 Vapor 컴포넌트를 커스터마이징할 수 있습니다. ## CSS Reset 설정 Vapor UI는 필요한 스타일 초기화를 포함합니다. Tailwind의 `preflight.css`는 사용하지 않는 것을 권장합니다. `preflight.css`가 필요한 경우 레이어 순서를 다음과 같이 조정합니다. ```css /* preflight를 사용해야 하는 경우 */ @layer tw-theme, vapor.theme, tw-base, vapor.reset, vapor.components, vapor.utilities, tw-utilities; @import '@vapor-ui/core/tailwind.css'; @import 'tailwindcss/theme.css' layer(tw-theme); @import 'tailwindcss/preflight.css' layer(tw-base); @import 'tailwindcss/utilities.css' layer(tw-utilities); ``` > 이 설정은 스타일 충돌 가능성이 있으므로 필요한 경우에만 사용합니다. # Theming URL: /docs/getting-started/theming Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/getting-started/(handbook)/theming.mdx Vapor UI의 테마 시스템에 대해 설명합니다. # Design Tokens URL: /docs/getting-started/tokens Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/getting-started/(handbook)/tokens.mdx Vapor UI의 디자인 토큰에 대해 설명합니다. # Design Principles URL: /docs/getting-started/principles Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/getting-started/(overview)/principles.mdx Vapor UI의 컴포넌트 아키텍처와 개발 철학을 이끄는 핵심 디자인 원칙 이 문서에서는 Vapor UI의 설계 철학과 6가지 핵심 원칙을 설명합니다. 이 원칙들을 이해하면 컴포넌트를 더 효과적으로 활용할 수 있습니다. ## 1. Preset 기반의 컴파운드 패턴 Vapor UI는 합성 컴포넌트 패턴을 채택하여 편의성과 유연성을 함께 제공합니다. 빠른 구현이 필요할 때는 Preset 컴포넌트를, 세밀한 제어가 필요할 때는 Primitive 컴포넌트를 사용합니다. ```tsx // Preset 패턴 (빠르고 간편) Trigger Contents // Primitive 패턴 (완전한 제어) Trigger Contents ``` 이 접근법의 장점은 다음과 같습니다. * **빠른 시작**: Preset 컴포넌트로 즉시 구현할 수 있습니다. * **세밀한 제어**: Primitive 컴포넌트로 커스텀 동작을 구현할 수 있습니다. * **혼합 사용**: 같은 애플리케이션에서 두 패턴을 함께 사용할 수 있습니다. ## 2. 접근성 Vapor UI는 [Base UI](https://base-ui.com/react/overview/quick-start)를 기반으로 [WCAG 2.2](https://www.w3.org/TR/WCAG22/) AA를 준수합니다. [키보드 네비게이션](https://www.w3.org/TR/WCAG22/#keyboard-accessible)과 [포커스 표시](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance)를 기본으로 지원합니다. ### 접근성 기능 * **Base UI 통합**: ARIA 속성, 키보드 내비게이션, 스크린 리더를 자동으로 지원합니다. * **색상 대비 준수**: 자체 개발한 Color Generator가 WCAG AA/AAA 대비 비율을 보장합니다. * **수학적 디자인 토큰**: 일관된 시각적 위계를 위해 수학적 비율로 생성된 토큰을 사용합니다. ```tsx // 적절한 ARIA 속성과 키보드 처리가 자동으로 포함됨 설정 열기 ``` ### Color Generator 시스템 Color Generator는 지각적 색상 모델을 사용하여 접근성을 충족하는 색상 팔레트를 생성합니다. ```tsx // 색상이 자동으로 대비 요구사항을 충족함 Primary Success Warning ``` ## 3. 일관된 네이밍 규칙 모든 컴포넌트는 일관된 네이밍 규칙을 따릅니다. 이 규칙을 통해 컴포넌트 사용법을 예측할 수 있습니다. * **독립 컴포넌트**: 단일 이름을 사용합니다. * **합성 컴포넌트**: Dot Notation 표기법을 사용합니다. ```tsx // 단일 컴포넌트 상태 // 합성 컴포넌트 프로젝트 상태 현재 개발 진행상황 섹션 1 섹션 2 섹션 3 ``` ## 4. 예측 가능한 속성 명명 컴포넌트 속성은 시각적 옵션과 논리적 상태를 기반으로 체계적인 규칙을 따릅니다. ### 시각적 옵션 ```tsx // 크기 변형은 일관된 스케일을 따름