문서 및 스타일 가이드 통합

문서가 없으면 개발자마다 규칙을 다시 만듭니다. 어떤 제목 순서를 사용할지, 어떤 클래스 이름이 존재하는지, 모달과 서랍 중 언제 무엇을 사용할지 등을 각자 결정하게 됩니다. 문서화된 스타일 가이드는 올바른 답을 쉽게 찾게 하고, 규모가 커져도 추측할 필요를 없애 줍니다.

Storybook, Histoire(Vue), Ladle 같은 도구는 문서와 함께 각 컴포넌트를 독립적으로 렌더링하므로 예시가 실제 코드와 항상 동기화됩니다. 위키나 저장소에 있는 정적 문서 파일은 필연적으로 실제 코드와 어긋나지만, 계속 갱신되는 문서는 그렇지 않습니다.

각 컴포넌트를 사용하는 데 필요한 최소한의 HTML을 보여 주세요. <app-button variant="primary">Save</app-button> 변형(기본, 보조, 위험), 상태(로드 중, 비활성화), 예외 상황(긴 텍스트, 아이콘 포함, 전체 너비)도 보여 주세요. 실제 페이지에 그대로 복사해 붙여 넣을 수 있는 예시를 팀이 실제로 사용합니다.

가장 좋은 문서는 소스 코드 옆에 예시를 렌더링합니다. Storybook은 이를 기본으로 지원하고, mdx-deck, Docusaurus, Astro Starlight은 실시간 JSX를 사용하는 MDX를 지원합니다. 마크업을 읽는 동안 실제 결과를 보면 “이게 작동할까요?”라는 의문이 바로 해소됩니다.

각 컴포넌트에 내장된 접근성 동작을 문서화하세요. 어떤 키보드 상호작용을 지원하는지, 어떤 ARIA 역할을 사용하는지, 포커스를 어떻게 관리하는지 기록해야 합니다. 컴포넌트를 도입한 사용자는 별도 비용 없이 접근성 동작을 얻고, 검토자는 계약을 위반하지 않았는지 확인할 수 있습니다.

명확한 안티패턴을 보여 주세요. “중요한 일시적 피드백에 모달을 사용하지 말고 토스트를 사용하세요.” 부정적인 예시는 긍정적인 예시보다 기억에 더 잘 남는 경우가 많습니다. 실패 상황을 드러낼 수 있도록 모든 해야 할 일에 명확한 하지 말아야 할 일을 짝지으세요.

이름 지정 패턴을 문서화하세요. BEM, 원자적 CSS, CSS Modules, Tailwind 유틸리티 조합 등이 있습니다. 클래스 이름, 사용자 지정 속성 이름, 파일 경로에 적용되는 규칙을 명시하세요. 일관된 이름은 인지 부하를 줄이지만, 일관되지 않은 이름은 모든 개발자의 시간을 계속해서 빼앗습니다.

결정의 결과뿐 아니라 결정한 이유도 기록하세요. “Vue보다 React를 선택한 이유는…”과 같은 기록은 미래의 기여자에게 맥락을 보존해 줍니다. 코드 옆에 마크다운으로 작성한 아키텍처 결정 기록은 팀 구성원이 바뀌어도 유지되는 가벼운 형식입니다.

새 팀 구성원은 하루 안에 첫 컴포넌트를 배포할 수 있어야 합니다. 점검 목록에는 저장소 설정, 의존 항목 설치, Storybook 실행, 적절한 컴포넌트 템플릿 찾기, 문서 작성, PR 열기가 포함됩니다. 첫 PR까지 걸리는 시간을 지표로 추적하세요. 짧을수록 좋습니다.

가장 좋은 문서는 새로 검색하는 사람과 숙련자 모두가 쉽게 찾을 수 있습니다. 검색을 지원하는 문서 사이트를 사용하세요(Docusaurus에는 Algolia, Starlight에는 기본 제공 검색). 컴포넌트에 여러 별칭을 태그로 지정하면 “모달”을 대화 상자, 팝업, 오버레이로 검색해도 찾을 수 있습니다.

문서에 시각적 회귀 테스트를 함께 적용하세요. Chromatic은 모든 PR에서 모든 Storybook 사례의 스냅샷을 만들고 시각적 차이를 표시합니다. 문서 전반의 버튼 스타일을 실수로 변경한 병합 PR은 스스로 차단됩니다. 이 방식은 문서화와 디자인 시스템의 적극적인 테스트를 결합합니다.

유지 관리자만 아는 사항을 문서화하세요. 주의할 점, 절반만 만들어진 추상화, 나중에 정리해야 할 임시방편 등을 기록해야 합니다. 잊기 전에 이런 조직 지식을 기록해 둔 현재의 자신에게 미래의 자신이나 후임자가 감사할 것입니다.

코드와 함께 렌더링되는 계속 갱신되는 문서를 정적 문서 파일보다 선호하는 이유는 무엇인가요?

문서화는 디자인 시스템의 가치를 크게 높이는 요소입니다. 실제 컴포넌트 코드를 불러오는 계속 갱신되는 문서(Storybook, Histoire, Ladle)를 사용하세요. 최소한으로 실행 가능한 예시를 보여 주고, 접근성을 문서화하며, 결정을 기록하고, 해야 할 일과 하지 말아야 할 일의 짝을 작성하고, 시각적 회귀 테스트를 함께 적용하세요. 문서를 나중에 덧붙이는 작업이 아니라 핵심 산출물로 다루세요.