컴포넌트 문서 템플릿

Buttons에 시범 적용한 문서 전용 포맷입니다. Foundation 및 다른 컴포넌트에는 아직 적용하지 않습니다.

편집 범위

기존 제품 UI, CSS, 토큰, 크기, 색, 동작, 옵션 기본값을 임의로 변경하지 않습니다.
기존 규칙과 코드 예제는 그대로 두고 문서 내 위치만 변경합니다.
기존 내용의 수정이 필요하면 항목별로 사용자에게 확인받습니다. 승인 전에는 수정하거나 별도 검토 기록을 남기지 않습니다.
문서만 재구성한 경우 기존 데모를 레거시로 간주해 삭제하지 않습니다.
기존 URL과 제목의 명시적 id를 유지합니다. 한국어 제목에 새 링크를 만들 때는 ASCII id를 지정합니다.

페이지 순서

이름, 한 문장 소개, 구현 방식과 지원 환경.
Interactive playground: 기본 조합, 미리보기/코드, 속성, 초기화, 코드 복사.
기존 규칙 (강제) 원문 한 곳. 접힌 상태로 제공하고 각 탭에서는 링크로 참조합니다.
사용 가이드 → 변형·상태 → 적용 방법 → API·규격 → 변경·전환.

중요한 사용 금지나 필수 전제는 탭 밖에도 드러내되 규칙 전체를 복제하지 않습니다. 상태는 확인된 것만 표시하며 문서 정리 여부를 제품 안정성으로 표현하지 않습니다.

공통 컴포넌트

docs/.vitepress/theme/components/DocTabs.vue: 이름 있는 슬롯이 있는 탭만 표시합니다. 기본 순서는 위 5개이며, id는 페이지 안에서 유일하고 안정적인 ASCII 문자열입니다.
docs/.vitepress/theme/components/DocPlayground.vue: 미리보기/코드, 복사, 초기화 버튼, 속성 영역을 제공합니다. code는 미리보기와 같은 옵션 상태에서 생성하고, reset 이벤트는 데모가 처리합니다.
docs/.vitepress/theme/components/DemoButtonPlayground.vue: Buttons용 어댑터입니다. 문서용 Vue 상태와 제품 HTML/Alpine 코드를 구분하며 실제 제품 CSS와 아이콘 원본을 참조합니다.

문서 탭은 VitePress 문서 탐색용 UI입니다. 제품의 Alpine TabNav나 SubTab을 대체하거나 변경하지 않습니다.

Markdown 골격

다음 상대 import는 docs/ko/design-system/components/<category>/<name>.md 깊이 기준입니다. Playground 어댑터는 대상 컴포넌트에 맞게 연결합니다.

---
outline: false
---

<script setup>
import DocTabs from '../../../../.vitepress/theme/components/DocTabs.vue';
</script>

# 컴포넌트 이름

한 문장 소개와 확인된 지원 환경.

## Interactive playground {#playground}

이 위치에 대상 컴포넌트의 Playground 어댑터를 배치합니다.

::: details 규칙 (강제)
기존 규칙 원문을 한 곳에 유지합니다.
:::

<DocTabs id="component-docs">

<template #guide>

## 사용 기준 {#usage}

언제 쓰는지, 어떤 조합을 고르는지, 접근성 및 금지 사례.

</template>

<template #variants>

## 변형과 상태 {#variants}

기존 데모와 비교표.

</template>

<template #installation>

## 적용 방법 {#installation}

기존 프로젝트에서 필요한 CSS, 등록과 최소 예제.

</template>

<template #api>

## API와 규격 {#api}

기존 옵션, 기본값, 클래스 및 상세 규격.

</template>

<template #changes>

## 변경과 전환 {#migration}

기존 전환표와 변경 이력.

</template>

</DocTabs>

모든 설명은 Markdown과 서버 렌더 HTML에 남습니다. 탭 제목과 슬롯 id는 일치해야 합니다. 초기 로딩, 검색 결과, 같은 페이지 링크 및 뒤로/앞으로 탐색에서 대상 앵커가 있는 탭을 열고 이동합니다. 접힌 상세 안의 제목이면 상세도 엽니다.

탭은 방향키·Home·End로 이동하며 Tab은 활성 탭과 패널로 이동합니다. 설명 탭은 URL을 갱신하지만 Playground 보기 탭은 URL을 변경하지 않습니다. 오른쪽 기본 목차는 숨겨 다른 탭의 제목이 동시에 나열되는 것을 피합니다. 인쇄 시 모든 패널을 표시합니다.

검증 체크리스트

기본 미리보기, 변형별 옵션, 초기화와 코드 복사.
미리보기 및 복사 코드의 클래스·텍스트·disabled·아이콘 일치.
기존 앵커 보존, 숨겨진 탭으로 직접 접속, 같은 앵커 재클릭, 뒤로/앞으로 이동.
키보드 탭 이동, 좁은 화면에서 탐색 가능 여부.
코드 예제와 강제 규칙의 원문 보존.
문서 빌드 및 프로젝트 검증. 기존 문제는 이번 변경과 구분하여 보고합니다.

Buttons 시범 범위

Playground의 기본값은 Solid · primary · md이며, 원본 DS의 기본값을 바꾸는 설정이 아닙니다. 색 옵션 전체와 Text의 기본 10px 옵션을 Playground에서 확인합니다. 중복 탐색기와 라이브 미리보기는 제거하고, 변형·상태 탭에는 규격 표와 설명을 둡니다. 과거 #explorer·#preview 주소는 Playground 위치에서 유지하고 새 링크는 #playground를 사용합니다.

컴포넌트 문서 템플릿 ​

편집 범위 ​

페이지 순서 ​

공통 컴포넌트 ​

Markdown 골격 ​

링크·검색·접근성 ​

검증 체크리스트 ​

Buttons 시범 범위 ​