구조·기술 선택·ADR

모듈과 데이터 흐름

• docs/: 한국어 문서 원본. JSON 형식 frontmatter는 YAML에서도 유효한 객체입니다.
• evidence/: Carbon pin·해시와 로컬 선택 파일의 해시. 비밀값·전체 제품 소스는 포함하지 않습니다.
• scripts/: Markdown 컴파일·링크 검사·소스 해시 확인·실행 예제 소스 추출·정적 HTML 생성.
• lib/generated-docs.json: 원본에서 생성한 문서/검색 데이터. 직접 편집하지 않습니다.
• web/: 메인 사이트의 디자인을 따르는 React 열람 화면과 50개 실행형 예제.
• licenses/: 참고한 Carbon 라이선스 고지.
• deploy/: teamwicked.me/designsystem 정적 배포·nginx 경로·복구 절차.
• archive/sites-v0.1/: 이전 Sites 뷰어와 연결 정보. 현재 실행·배포에 사용하지 않습니다.

Markdown+출처 목록 → 검증/컴파일 → HTML/검색 데이터 → Vite 빌드와 React 정적 사전 렌더 → nginx의 designsystem 경로. 예제는 브라우저 상태만 변경하며 제품 DB·API로 쓰는 경로가 없습니다. 공개 문서와 원본 다운로드도 같은 정적 릴리스에 포함됩니다.

ADR-001 — 문서 표준과 시각 디자인 분리

[Decision Log]

• 목적과 의도: Carbon 수준의 규정 범위를 활용하면서 우리 외형·브랜드를 유지한다.
• 기존 구현 및 제약 조건: 세 제품의 기술·토큰·폼 소유권이 서로 다르다.
• 검토한 주요 대안: Carbon 전체 테마 이식, 텍스트만 복사, 제품별 근거가 있는 공통 규정.
• 선택한 방식: 원칙·사용·상태·접근성 구조를 한국어로 재작성하고 제품별 값을 연결한다.
• 다른 대안 대신 이 방식을 선택한 이유: 사용자의 요구는 디자인 교체가 아니라 디자인의 문서화다.
• 장점, 단점 및 영향: 브랜드와 운영 위험을 보존하지만 제품별 준수 검증은 별도 작업으로 남는다.

ADR-002 — Markdown 단일 원본

[Decision Log]

• 목적과 의도: 저장소 문서와 열람 사이트가 같은 내용을 보여 주게 한다.
• 기존 구현 및 제약 조건: 문서·사이트를 각각 편집하면 규칙이 쉽게 달라진다.
• 검토한 주요 대안: 위키 수동 편집, MDX 실행, Markdown 빌드.
• 선택한 방식: Markdown을 빌드 단계에서 정적 HTML로 변환하고 검색 인덱스를 생성한다.
• 다른 대안 대신 이 방식을 선택한 이유: 검토·차이 비교·오프라인 읽기가 쉽고 문서에 임의 스크립트를 실행할 필요가 없다.
• 장점, 단점 및 영향: 실행형 MDX 예제는 없지만 HTML·위험 URL은 차단하고 재현 가능한 검사로 drift를 잡는다.

ADR-003 — 제품 런타임과 독립

[Decision Log]

• 목적과 의도: 기존 주문·결제·서버 관리에 영향을 주지 않는다.
• 기존 구현 및 제약 조건: 운영과 개발 위치가 다르고 기존 작업 트리에 사용자 변경이 있다.
• 검토한 주요 대안: 기존 제품에 문서 라우트 추가, 기존 문서 서비스 덮어쓰기, 독립 저장소/문서 사이트.
• 선택한 방식: 별도 문서 저장소의 React/Vite 정적 뷰어를 메인 도메인의 지정 경로에 게시한다. 이전 Sites 방식은 2026-09-12 사용자 요청으로 대체했다.
• 다른 대안 대신 이 방식을 선택한 이유: 운영 프레임워크·DNS·DB를 수정하지 않고 열람·검색을 제공한다.
• 장점, 단점 및 영향: Node 서버 추가나 메인 앱 재시작 없이 문서를 배포한다. 원본 컴포넌트 전체의 업무 로직을 문서에서 실행하지 않으므로 API 연결과 운영 권한 경로는 각 제품에 남는다.

ADR-004 — 실제 디자인과 실행형 예제

[Decision Log]

• 목적과 의도: 텍스트만 있는 기준서가 아니라 실제 모습을 보고 조작할 수 있게 한다.
• 기존 구현 및 제약 조건: 최초 뷰어는 제품과 다른 기본 스타일이었고 실물 컴포넌트가 없었다.
• 검토한 주요 대안: 정적 스크린샷만 추가, 운영 화면 iframe, 격리된 실행형 예제.
• 선택한 방식: 메인 사이트의 배경 #f4f5ef/#0a0a0a, Geist/Pretendard, 기존 WICKED 로고와 CTA 구조를 재사용한다. 30개 컴포넌트에 로컬 상태 기반 예제를 제공하고 VPS/Panel/Blesta 원본 CSS 발췌는 미디어 조건까지 보존한다.
• 다른 대안 대신 이 방식을 선택한 이유: 운영 세션·서버·결제 없이 실제 hover/focus/disabled/오류·선택·대화상자 동작을 검증할 수 있다.
• 장점, 단점 및 영향: 업무 API를 실행하지 않는다. 원본 스타일 연결 범위와 문서용 파생 상태를 구분한다. 긴 기술문서의 읽기 대비를 위해 메인의 애니메이션 dither 배경은 생략하고 같은 색·글꼴·여백 계층을 사용한다.

ADR-005 — TeamWicked와 WickedHost의 체계 분리

[Decision Log]

• 목적과 의도: 사용자가 구분한 TeamWicked 자체 브랜드와 WickedHost 호스팅 제품군의 소유권을 문서·예제·탐색에 일관되게 반영한다.
• 기존 구현 및 제약 조건: 네 제품 선택이 한 목록에 섞여 있었고 문서 이동 시 제품 선택이 유지되지 않았다. 규칙 원문은 59개 문서에 공유되어 있었다.
• 검토한 주요 대안: 표시명만 변경, 문서 저장소 두 개로 복제, 하나의 저장소에서 독립 경로·적용 범위 관리.
• 선택한 방식: /designsystem/은 체계 선택 허브, teamwicked/와 wickedhost/는 독립 문서 루트다. web/types.ts의 소유권·제품 집합을 탐색, 검색, 링크 생성, 정적 내보내기가 함께 사용한다. TeamWicked 토큰 문서는 별도 원본이며 기존 제품 지도·청구·사용량 문서는 WickedHost에 속한다.
• 다른 대안 대신 이 방식을 선택한 이유: 공통 행동·접근성 규칙의 수정 누락 없이 브랜드 토큰과 제품 예제를 분리할 수 있다.
• 장점, 단점 및 영향: 기존 비분류 링크는 삭제하지 않고 체계 선택 화면으로 유지한다. 제품 쿼리는 해당 체계의 허용 목록으로 제한하고, 본문·검색·메뉴 링크는 체계와 제품 선택을 보존한다. 다른 체계 전용 자료의 링크는 소유 체계로 이동한다. 동일 문서의 규칙 원문은 공유되며 다른 제품 사례는 비교 근거이지 브랜드 상속이 아니다.

ADR-006 — 실물 스위치와 복합 라이브러리 확장

[Decision Log]

• 목적과 의도: WickedHost 실물과 다른 스위치를 수정하고 문서의 입력·상태·업무 예시 공백을 줄인다.
• 기존 구현 및 제약 조건: 공통 원형 스위치의 Panel 모서리만 바꾼 예제는 checked 트랙·손잡이의 원본 계약을 정확히 반영하지 않았다. 운영 패널은 로그인 상태가 없어 전체 설정 화면은 확인하지 못했다.
• 검토한 주요 대안: 원형 예제의 radius만 수정, 운영 컴포넌트 전체 이식, 확인한 원본 스타일과 API 미연결 구조 연결.
• 선택한 방식: 해시가 일치하는 Panel 운영/로컬 Switch CSS와 vPanel Mantine 규칙을 범위만 바꿔 추출한다. 접근 가능한 DemoSwitch를 공통 요소로 만들고 저장 중·실패 복구·읽기 전용 상태를 제공한다. Store의 각진 스위치는 운영 미확인 제안으로 구분한다.
• 다른 대안 대신 이 방식을 선택한 이유: 원본 선언값을 추적하면서 제품 세션·실제 서버·결제 없이 상태를 검증할 수 있다.
• 장점, 단점 및 영향: expanded-specimens.tsx에 공통 입력·상태 10종과 WickedHost 업무 예제 10종을 분리했다. snippet 생성과 전체보기는 동일한 실행 코드·문서 목록을 사용한다. 새 20개 규칙 문서는 자체 작성 기준이며 Carbon 공식 컴포넌트라고 표시하지 않는다. 예제 개수가 늘어나도 운영 기능의 전면 구현·검증이라는 뜻은 아니다.

ADR-007 — WickedHost 세 제품의 시각 기준 통일

[Decision Log]

• 목적과 의도: 사용자가 지시한 vPanel/Pterodactyl 디자인을 Blesta까지 같은 기준으로 적용한다.
• 기존 구현 및 제약 조건: 문서의 제품 선택이 vPanel 38px 버튼·Panel 40px 버튼·Blesta 42px/8px 버튼과 별도 토큰을 전환했다. 이는 두 체계 분리 이후에도 WickedHost 안에 세 스킨이 남은 상태였다.
• 검토한 주요 대안: Blesta만 색상 변경, 모든 제품에 복제 CSS 추가, 하나의 시각 family와 공통 요소 적용.
• 선택한 방식: data-family=wickedhost에 공통 팔레트·Pretendard·4px 모서리를 두고 Panel 버튼·스위치 선언을 한 번만 추출해 세 제품에 연결한다. 제품 선택은 업무 맥락만 바꾸고 TeamWicked family는 그대로 보존한다.
• 다른 대안 대신 이 방식을 선택한 이유: 제품마다 분기한 CSS가 다시 달라지는 것을 막고 같은 동작·상태의 계산된 스타일을 직접 비교할 수 있다.
• 장점, 단점 및 영향: Blesta의 문서 기준은 제안에서 확정 기준으로 바뀐다. 과거 제품 소스는 이행 전 근거로만 남기고 운영 변경 완료로 표시하지 않는다. 실제 PHP/PDT·CSRF·거래·서버 런타임은 이번 문서 배포로 수정하지 않는다.

실행·테스트·배포 명령

설치와 명령·현재 게시 결과는 저장소 README.md를 따릅니다. npm lockfile을 유지합니다. build 결과만 패키징하고 소유자 전용 게시를 유지합니다. 의존성 검사 결과는 배포 기록에서 별도 표기합니다.