현재 사용법 (2026-09-10, 6fbaee7f): 공통 화면·디자인 시스템 · 기능 마스터. 아래는 작성 당시의 변경 설명이며 현재 전체 동작·재측정 결과를 뜻하지 않습니다.

DS 문서 Playground 전환 — 이어서 하기 (2026-09-08 기준)

새 세션에 이 문서를 붙여 넣고 「이어서 진행」이라고 하면 됩니다.

지금 상태

브랜치 design/docs-DS-review-improvements (origin과 동기화됨, develop 대비 27커밋). 로컬 문서 서버: cd docs && pnpm dev → http://localhost:5174/

컴포넌트 문서 13개를 「Interactive playground + 탭」 형식으로 전환 완료.

buttons · labels · notice · spinner · tooltip · sub-tab · tab-nav
page-header · workspace-switcher · bottom-nav · app-header · lnb-sidebar · form-controls

이 포맷이 뭔가

각 컴포넌트 문서가 이렇게 생겼습니다.

# 컴포넌트 이름
한 줄 안내 (이 페이지에서 뭘 찾는지)
**구현 방식 · 지원 환경** · 진행 중(WIP) · 문서 포맷 시범 적용
<span id="live-preview">          ← 예전 주소 유지용 빈 앵커
## Interactive playground {#playground}
<DemoXxxPlayground />              ← 미리보기 · 코드 · 모아보기 3탭
::: details 규칙 (강제) · 코딩 에이전트용
<DocTabs>  사용 가이드 · 변형·상태 · 적용 방법 · API·규격 · 변경·전환

공통 부품은 셋입니다.

docs/.vitepress/theme/components/DocPlayground.vue — 미리보기/코드/모아보기 탭, 초기화·코드 복사, 속성 패널
docs/.vitepress/theme/components/DocTabs.vue — 슬롯이 있는 탭만 노출(내용 없는 탭은 자동으로 안 뜸)
docs/internal/component-docs-template.md — 포맷 규격 정본

컴포넌트마다 DemoXxxPlayground.vue 어댑터를 하나 만들어 DocPlayground에 축을 넘깁니다.

사용자가 정한 규칙 (계속 지킬 것)

기존 데모는 Playground로 통합하되 축·기본값·클래스 조합은 그대로. 표시 형태만 바꿉니다
내용이 없는 탭은 만들지 않습니다
본문 문구는 바꾸지 않고 위치만 옮깁니다. 옮길 때마다 유실 0을 기계적으로 대조해 보고합니다
「모아보기」 = 예전 라이브 미리보기 그리드. 그 그리드의 축이 되는 컨트롤은 disabled 처리하고 라벨도 흐리게
모아보기 탭에서는 속성 패널이 뷰 아래로 내려가고 뷰가 전체 폭(686px)을 씁니다 — DocPlayground에 공통 적용됨
상단 표기는 buttons 형태, 금지 가이드는 사용 가이드 탭에서 ::: danger로 강조
DS 문서를 고치면 docs/ko/design-system/resources/changelog.md도 같이 갱신(사용자 지시)

매번 밟은 함정

docs에는 Tailwind가 없습니다. flex-1·font-medium·animate-spin 같은 유틸은 ds-tailwind-shim.css의 .demo-tw 스코프 안에서만 동작 → 데모 래퍼에 demo-tw를 붙여야 합니다
인라인 <svg>는 pnpm check:icons가 차단합니다 → getIcon()/$icon() 사용. .ds-notice__icon 같은 평범한 클래스 선택자는 <span class="ds-ico ds-notice__icon">로 규격이 그대로 걸립니다
게이트는 스테이지 기준입니다 — git add 후 다시 확인해야 합니다
죽은 앵커를 VitePress 빌드가 안 잡아줍니다. 실제로 lnb-sidebar에서 #panel-nav-demo가 죽을 뻔했습니다(modal.md가 페이지 간 링크로 참조). 섹션을 옮길 때 그 앵커를 참조하는 다른 문서를 반드시 grep할 것
사용자에게 보고할 때 검사 실패가 검사 자체의 문제인지 먼저 확인할 것. Alpine 컴포넌트 페이지는 코드가 클래스가 아니라 xxx({…}) 호출이라 「미리보기↔코드 클래스 일치」 검사가 성립하지 않습니다

검증 방법

Playwright 공용 스크립트를 매 페이지 돌립니다(스크래치패드에 있었으므로 새로 만들어야 함).

node verify-doc.mjs <경로> <미리보기셀렉터> <앵커,앵커,…> [기대클래스]

보는 것: Playground 렌더 · 페이지 내 죽은 앵커 0 · 탭 렌더 · 숨은 탭 앵커 직접 접속 · 키보드 탭 이동(→/End/Home) · 미리보기↔코드 일치 · 초기화 · 모아보기 스크린샷 · 375px 가로 넘침 · 콘솔 에러.

그리고 매번 cd docs && pnpm build.

남은 일

1. 문서화 커버리지 표의 🔴 준비중 9개 — 진짜 비어 있는 것들. 전부 4줄 「준비 중」 스텁인데 프로덕션에서 돌고 있습니다.

LoginForm · RegisterForm · ChangePasswordForm · ForgotPasswordForm · AuthGate
AddEmployeeWizard · EditEmployeeWizard · MyInfoForm
Messenger · PermissionDeniedModal

현황표: http://localhost:5174/ko/design-system/resources/coverage.html

2. 🟡 부분 3개 — 다른 문서에 언급만 있고 자기 규격이 없습니다.

Segment — sub-tab의 tip에 「SubTab과 다른 형태」 비교만. 조합 축이 있는 시각 컴포넌트라 이 포맷에 잘 맞습니다
AiAssistant · CsReport — chat-widget에 FAB 배치 계약만

3. 미결로 남긴 것 둘

tab-nav의 fill 옵션이 API 표에 빠져 있습니다. TabNav.ts·파셜·CSS에 구현돼 있고 Playground에는 넣었는데, 표에 행을 추가할지 확인 대기
notice의 「사용법」 코드 예시가 인라인 <svg class="ds-notice__icon">입니다. 지금 앱 코드에 쓰면 check:icons가 커밋을 막는 형태 — 고칠지 확인 대기

4. Playground를 만들지 않기로 한 것 — coverage(현황표) · notification-bell · chat-widget(FAB 배치 계약). 조합을 골라 보는 대상이 아닙니다.

참고

사용자는 비개발자입니다. 단계별 검증과 시각 변화에 민감하고, 「진행」·「ㄱㄱ」 같은 짧은 신호로 답합니다
산문은 한국어. 새 !important 금지
커밋은 영문 Conventional Commits 제목 + 한글 본문. git 계정은 mirangpark-doris, gh 명령은 GH_TOKEN=$(gh auth token --user mirangpark-doris)
Documents/New project/hereby-dhub에도 같은 브랜치의 클론이 있습니다 — 거기서 작업하려면 git pull 먼저

DS 문서 Playground 전환 — 이어서 하기 (2026-09-08 기준) ​

지금 상태 ​

이 포맷이 뭔가 ​

사용자가 정한 규칙 (계속 지킬 것) ​

매번 밟은 함정 ​

검증 방법 ​

남은 일 ​

참고 ​