Files
clean-architecture-frontend…/PRODUCT.md
T
DongHyeonka 11530b1adf docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
2026-11-08 21:57:47 +09:00

57 lines
4.5 KiB
Markdown

# Product
<!-- impeccable:product-schema 1 -->
## Platform
web
## Users
- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람이다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도다.
- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 한다.
## 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__/`에 있다. 화면을 바꾸면 골든도 의도적으로 갱신해야 한다.
- 템플릿에는 샘플 기능이 없다(참조 기능과 예제 화면은 2026-11-07에 지웠다). 기능은 `create:feature`로 만든다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상이다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남는다.
- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았다.
## 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`).