Files
clean-architecture-frontend…/PRODUCT.md
T
DongHyeonka bdc32b6198 docs: PRODUCT.md의 예제 제거 주장을 드릴 범위에 맞춘다 (14-04)
PRODUCT.md가 "예제 기능과 라우트는 지울 수 있고, 예제 화면에만 있는
디자인은 남지 않는다"고 적었다. 실제 제거 드릴(test:sample-removal)은
참조 기능만 지운다. 예제 라우트 4개와 홈은 기본 구성이라 남는다. 이
주장을 믿고 예제 화면에 디자인을 넣으면 제품 빌드에 그대로 남는다.

PRODUCT.md를 드릴 범위대로 고쳤다. 접근성 수동 검토의 근거를 지워도
되는 SPEC.md에서 docs/accessibility/manual-checklist.md로 바꿨다.
README의 "복사 뒤 지워도 되는 파일" 표에 PRODUCT.md를 CLAUDE.md처럼
"제품 것으로 바꾼다"로 넣었다. 예제 화면을 지울 수 있게 만드는 일은
별도 선택이라 하지 않았다(0929/14-03).

위험: 문서만 바뀐다.
검증: deletable-history-documents 테스트 통과, verify:documentation
PASS_SCOPED.
2026-11-01 18:56:56 +09:00

4.4 KiB

Product

Platform

web

Users

  • 템플릿을 가져다 쓰는 개발자: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 예제 화면(홈, 플랫폼 구성, UI 구성요소, 화면 상태, 인증 연동, Reference feature)은 이 사람이 실행 구조와 공통 동작을 확인하는 용도입니다.
  • 파생 서비스의 최종 사용자: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 합니다.

Product Purpose

도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둡니다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것입니다.

Positioning

화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트입니다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않습니다.

Operating Context

  • 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다.
  • 파생 서비스는 운영 중인 desktop 서버에 배포됩니다.
  • 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다.

Capabilities and Constraints

  • 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다.
  • 디자인 시스템 위치는 src/presentation/design-system/입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(tokens/primitive.css, semantic.css, component.css).
  • 시각 회귀 골든이 tests/visual/__snapshots__/에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다.
  • 참조 기능(src/features/reference-feature/)은 test:sample-removal로 지울 수 있습니다. 예제 라우트 4개(/examples/platform, ui, states, auth)와 홈은 기본 구성이고 제거 드릴이 없습니다. 그래서 예제 화면에만 넣은 디자인은 파생 서비스에 그대로 남습니다.
  • 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다.

Brand Commitments

브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자입니다.

Evidence on Hand

  • 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다.
  • 예제 문구는 템플릿 기능 설명뿐입니다(src/presentation/i18n/catalog.ts).
  • 현재 화면 기록: tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/, Storybook(src/presentation/design-system/design-system.stories.tsx).

Product Principles

  1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다.
  2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다.
  3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복제하지 않습니다.
  4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다.
  5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다.

Accessibility & Inclusion

WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킵니다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있습니다(docs/accessibility/manual-checklist.md).