release: v0.10.0

apps/site/research/showcase-duo-learning-ledger-2026-08-29.md

@@ -0,0 +1,150 @@
+# 두 쇼케이스 학습 원장
+
+> 목적: 두 디자인을 만들며 얻은 교훈을 증거와 함께 누적하고, 구현과 검증을 마친 뒤 10개 이상을 designpaca 규칙으로 승격한다.
+> 현재 항목은 연구 단계의 가설이다. 구현이나 실제 브라우저 증거가 없는 항목은 최종 교훈으로 세지 않는다.
+
+## 승격 기준
+
+각 교훈은 다음을 모두 가져야 한다.
+
+1. 이번 두 쇼케이스 중 어디에서 발견했는가
+2. 어떤 화면, 코드, 사용자 동작, 검사 결과가 증거인가
+3. 기존 designpaca 규칙과 충돌하는가
+4. 충돌한다면 근본 규칙을 보존할지, 새 교훈에 맞게 근본 규칙을 고칠지
+5. 규칙을 바꾼 뒤 어떤 검사로 회귀를 막을 것인가
+
+## 연구 단계 가설
+
+| 번호 | 관찰 | 후보 규칙 | 기존 규칙과 긴장 | 상태 |
+|---:|---|---|---|---|
+| 1 | 고급 마케팅 화면의 어두운 브랜드 톤을 운영 관리자까지 복제하면 상태와 경고가 약해진다. | 같은 제품이어도 마케팅 화면과 운영 화면의 시각 밀도 다이얼을 따로 정한다. | 하나의 토큰 체계와 화면별 판독성 사이의 긴장 | 구현 증거 대기 |
+| 2 | 검정과 금색은 면적보다 역할을 제한할 때 더 고급스럽다. | 고급 팔레트는 강조색 점유율과 허용 역할을 함께 기록한다. | 팔레트 자유와 절제 사이의 긴장 | 구현 증거 대기 |
+| 3 | AI 설명만 추가하면 신뢰가 생기지 않고 수정과 사람 검토가 함께 있어야 한다. | AI 결과 컴포넌트는 이유, 불확실성, 수정, 사람 검토를 하나의 게이트로 묶는다. | 디자인 범위와 제품 안전 범위 사이의 긴장 | 구현 증거 대기 |
+| 4 | 같은 업종 구조, 다른 업종 톤, 구체 상호작용을 분리해 조사하면 복제 위험이 줄어든다. | R1, R2, R3마다 가져올 축과 버릴 축을 의무적으로 기록한다. | 기존 3슬롯 규칙의 구체화 | 조사 증거 있음, 구현 검증 대기 |
+| 5 | 고객과 가맹 희망자는 같은 브랜드라도 성공 행동이 다르다. | 서로 다른 주 행동을 가진 사용자군은 한 화면의 동등 CTA가 아니라 경로 분리를 먼저 검토한다. | 단일 랜딩 압축과 정보 구조 분리 사이의 긴장 | 구현 증거 대기 |
+| 6 | 생성 이미지 안에 가짜 UI를 넣으면 상호작용과 접근성을 증명할 수 없다. | 생성 이미지는 물성과 분위기를 소유하고 데이터와 제어는 HTML이 소유한다. | 강한 비주얼과 실제 제품성 사이의 긴장 | 국내 방향 시안 2장에 UI를 배제한 증거 있음, 구현 검증 대기 |
+| 7 | 법정 공개 항목은 푸터 문구보다 관리자 게시 상태에 연결할 때 실효성이 생긴다. | 규제 필드는 고지 목록과 함께 게시 차단 상태 머신으로 모델링한다. | 시각 디자인 스킬의 범위를 운영 구조로 넓히는 문제 | 구현 증거 대기 |
+| 8 | 생성 음식 사진은 한 장의 품질보다 여러 장의 재료와 포장 일관성이 더 어렵다. | 이미지 생성 전에 자산 역할, 재료 고정값, 조명, 카메라, 금지 목록을 이미지 성경으로 만든다. | 생성 속도와 일관성 관리 사이의 긴장 | 기준 이미지 오류와 크롭 감사 완료, 추가 자산 검증 대기 |
+| 9 | 표현 강도는 사이트 전체에서 하나가 아니라 화면 임무별로 달라져야 한다. | 표현, 움직임, 정보 밀도 다이얼을 주요 화면군마다 기록한다. | 하나의 방향 보드와 화면별 변주 사이의 긴장 | 구현 증거 대기 |
+| 10 | 인간 검증 게이트가 추상적인 감상 질문이면 다음 구현을 잠그지 못한다. | 게이트마다 승인할 이름, 문장, 색, 이미지, 정보 구조를 열거하고 승인 전 금지 행동을 기록한다. | 자율 구현 속도와 사용자 통제 사이의 긴장 | 게이트 응답 대기 |
+| 11 | 프리미엄 화면에서 모든 카드를 장식하면 위계가 사라진다. | 장식이 필요한 단 하나의 지배 표면을 지정하고 나머지는 선, 여백, 타입으로 구분한다. | high-end 보조 규칙과 designpaca의 반복 억제 사이의 충돌 | 구현 증거 대기 |
+| 12 | 지도나 시각화만 제공하면 동일 데이터를 키보드와 보조기술로 탐색하기 어렵다. | 지도와 시각화에는 동일 데이터의 목록 또는 표 보기를 필수 짝으로 둔다. | 몰입형 시각과 접근성 사이의 긴장 | 구현 증거 대기 |
+| 13 | 국내 서비스를 만들면서 해외 사례를 시각 주축으로 두면 한국어를 얹어도 번역된 해외 템플릿처럼 읽힌다. | 지역 적합성은 장식이 아니라 단위, 용어, 정보 순서, 상담과 주문 행동, 상업 사진으로 검사한다. R1과 R2의 주 레퍼런스를 목표 지역 사례로 우선한다. | 세계적 레퍼런스 품질과 지역 사용자 맥락 사이의 긴장 | 사용자 피드백 증거 있음, 구현 검증 대기 |
+
+## 실제 사용자 피드백 1
+
+- 피드백: `주 레퍼런스가 너무 서양스럽다. 국내의 디자인 감각에 맞아야 한다.`
+- 확인된 원인: 부동산은 Sotheby's와 Hennessy, 햄버거는 Teenage Engineering이 시각 중심축이었다.
+- 저장소 충돌: 검정과 앰버, 한남 고급 거실, 에디토리얼 아카이브, 검정과 코발트 기술 화면이 기존 쇼케이스에 이미 존재한다.
+- 수정 행동: 국내 부동산, 프롭테크, 주거 브랜드, 햄버거, 프랜차이즈, 국내 이종 업종을 병렬 재조사한다.
+- 이미지 행동: 실내 중심 부동산과 어두운 해외 푸드 사진을 폐기하고 서울 공동주택 외관과 밝은 도심 철판 주방 시안을 재생성한다.
+- 최종 판정 조건: 전통 장식을 모두 지워도 국내 단위, 용어, 흐름, 행동만으로 한국 서비스임을 식별할 수 있어야 한다.
+
+## 구현 중 기록 형식
+
+각 후보 아래에 다음 증거를 추가한다.
+
+- 화면과 상태:
+- 관련 파일:
+- 실제 브라우저 동작:
+- 실패 또는 수정 전 상태:
+- 수정 후 검사:
+- 기존 규칙과의 조정:
+- 최종 승격 여부:
+
+## 구현 증거 누적
+
+### 증거 A — 정적 검사의 재귀 범위
+
+- 화면과 상태: 공개 홈뿐 아니라 `admin/`, `franchise/` 하위 페이지가 추가된 직후
+- 관련 파일: `apps/site/tools/verify.mjs`, 신규 HTML 네 경로
+- 수정 전 상태: 깊이가 고정된 HTML glob은 앞으로 더 깊어진 하위 페이지를 놓칠 수 있었다.
+- 실제 검사: 재귀 glob으로 바꾸자 미완성 신규 화면의 ARIA 오용, label 다중 연결, figure 자식 순서 오류 8건을 바로 검출했다.
+- 수정 후 검사: 기존 추적 HTML은 그대로 PASS, 신규 오류만 RED로 분리됐다.
+- 후보 교훈: 페이지 수가 아니라 경로 깊이가 변하는 제품에서는 정적 게이트 입력 자체를 재귀·명시 목록으로 검증한다.
+
+### 증거 B — 철판클럽 첫 실렌더
+
+- 화면과 상태: 홈과 가맹, 320 / 390 / 768 / 1440 실제 Chrome 렌더
+- 관련 파일: `public/work/griddle-club/styles/site.css`, `styles/franchise.css`
+- 실패 또는 수정 전 상태: PASS 0 / FAIL 8. 모바일 지도 장식이 문서 폭을 421px와 497px로 밀었고, 768px 제품 사진은 934px까지 넘쳤다. 작은 코발트·보조 글자는 최저 2.09:1, 두 Hero 제목은 3줄이었다.
+- 수정: 지도 장식의 확대·회전을 제거하고 같은 경계 안에서 자르기, 중간폭 이미지에 `min-width: 0`과 절대 채움, 보조색 역할 토큰 상향, 제목 최대 크기와 폭 조정.
+- 수정 후 검사: 한 번 더 남은 10px 푸터 문구 3.89:1을 교정한 뒤 PASS 8 / FAIL 0.
+- 후보 교훈: 장식의 transform도 실제 경계 밖 픽셀을 만들 수 있으며, 강조색 토큰은 큰 CTA뿐 아니라 가장 작은 실제 사용 크기에서 검증해야 한다.
+
+### 증거 C — 모바일 전용 생성 이미지
+
+- 화면과 상태: 두 공개 Hero의 390px 전용 사진
+- 관련 파일: `showcase-duo-image-bible-2026-08-29.md`, 두 사이트의 모바일 WebP
+- 실패 또는 수정 전 상태: 가로 원본의 중앙 강제 크롭은 부동산 현관·경사 골목과 버거의 손·트레이를 동시에 보존하지 못했다.
+- 수정: 같은 물성과 카메라 세계관으로 1122×1402 세로 원본을 별도 생성하고 `<picture>`의 좁은 폭 source로 연결했다.
+- 후보 교훈: 모바일 Hero가 별도 시선 경로를 요구하면 CSS 크롭을 미세 조정하는 대신 생성·촬영 원본 단계에서 구도를 분기한다.
+
+### 증거 D — 자율 승인과 게이트
+
+- 화면과 상태: 사용자가 모든 중간 게이트를 자율 승인한다고 명시한 뒤
+- 관련 파일: 방향 보드, 구현 청사진, 자동 검사 리포트
+- 실제 동작: 게이트 질문을 반복하지 않고 구현은 진행했지만, 철판클럽과 한남자리의 첫 실렌더가 RED일 때 다음 단계로 승인 처리하지 않고 즉시 수정 루프로 돌아갔다.
+- 후보 교훈: 자율 승인은 검사 면제가 아니라 의사결정 대기만 제거한다. 합격 증거와 실패 시 복귀 조건은 그대로 유지한다.
+
+### 증거 E — 구조 게이트 뒤의 시각 RED
+
+- 화면과 상태: 철판클럽 홈 390×844, 구조 감사 PASS 8 / FAIL 0 직후의 실제 상태 캡처
+- 관련 파일: `public/work/griddle-club/styles/site.css`, `tools/.gen/showcase-duo/burger-home-mobile-hero.png`, `burger-home-mobile-stores.png`
+- 실패 또는 수정 전 상태: 모바일 `.store-map { position: static }` 때문에 절대 배치된 격자·강·핀의 기준이 BODY로 바뀌었다. 지도 장식이 Hero 전체를 덮고 실제 매장 구간에는 빈 회색판만 남았다. 데스크톱 사진 크롭은 첫 844px에서 직원 얼굴만 보여 버거를 폴드 아래로 밀었다.
+- 수정: 지도 부모의 containing block을 `position: relative`로 복원하고 목록을 지도보다 먼저 배치했다. 모바일 전용 4:5 이미지를 절대 채움·하단 중심으로 배치해 첫 화면에 손과 버거가 함께 보이게 했다.
+- 수정 후 검사: 390 실측에서 Hero 사진 y=511.7~873.2, 첫 화면에 제품 노출. 새 상태 캡처를 직접 열어 오버레이 누수와 빈 지도판이 사라졌음을 확인.
+- 후보 교훈: 기하·오버플로 PASS는 시각 PASS가 아니다. absolute/fixed 자식은 containing block을 단언하고, 기본 화면과 핵심 상태의 실제 캡처를 열어 봐야 한다.
+
+### 증거 F — 90/350/12 하드락 E2E의 첫 RED
+
+- 화면과 상태: 공개·관리·가맹 네 URL, Chromium 16폭, WebKit 8폭, axe, JS 없음, 감소 모션, 사용자 여정
+- 관련 파일: `tools/showcase-duo-e2e.mjs`, `tools/showcase-duo-e2e-report.md`
+- 계약: 90/90 시나리오, 350/350 단언, 12/12 캡처의 개수·규격·10KB 이상·SHA-256·상호작용 전후 해시 차이를 잠갔다.
+- 실제 RED: 한남자리 대비·SVG 중첩 인터랙션, 관리자 새 초안이 같은 클릭의 outside-click으로 즉시 닫힘, 철판클럽 비용표의 키보드 초점 누락, 빈 메뉴 복구가 0개에 머무는 결함을 분리했다.
+- 후보 교훈: 대규모 E2E는 시나리오·단언·캡처 수를 모두 hard-lock해야 검사 삭제가 GREEN으로 위장되지 않는다. 화면 존재가 아니라 행동 뒤 기대 상태와 부작용 없음을 단언한다.
+
+### 증거 G — 인간 게이트가 잡은 세 가지 계측 공백
+
+- H01: 철판클럽 가맹 Hero의 채운 버튼과 텍스트 링크가 `align-items:center` 행 안에서도 시각 중심이 달랐다. 공용 버튼의 `margin-top:34px`와 한 줄 링크 hitbox가 원인. 둘을 48px hitbox로 통일한 뒤 1440/390 centerY 차이 0px.
+- H02: 한남자리 상세 04·05·06이 전부 `왼쪽 큰 제목 + 오른쪽 선형 목록/표` 5:7 골격이었다. 카피가 달라도 같은 섹션을 세 번 복제한 인상. 장소=생활권 도식, 비용=원장, 검토=분기 흐름으로 역할별 토폴로지를 분리한다.
+- H03: 관리자 인스펙터를 닫아도 2열 grid track가 남아 큰 빈 회색 면이 생겼다. 닫힘 상태에서 표가 작업대 전체 폭을 회수하고, 재선택 때 분할을 복원하도록 상태 레이아웃 계약을 바꾼다.
+- 기존 규칙과의 조정: 일관성을 버리고 모든 섹션을 다르게 만드는 규칙으로 굽히지 않는다. **의미 역할이 다르면 읽는 동작도 달라야 한다**는 조건부 규칙으로 조화시킨다. `align-items`나 `display:none` 선언을 보는 대신 실제 hitbox 중심과 surface edge를 측정한다.
+- 회귀 게이트: H01 hitbox ≥44px·centerY 차이 ≤2px. H03 닫힘 queue/workbench right edge 차이 ≤2px, 재선택 split 복원. H02는 전후 상태 캡처를 사람이 다시 판정한다.
+
+### 증거 H — 진실성 문구가 제품 가치를 덮은 공개 화면
+
+- 화면과 상태: 사용자가 한남자리 공개 페이지 전체를 보고 `중복되는 내용도 많고 이상하다`며 전면 재설계를 요청한 상태
+- 관련 파일: `public/work/hannam-jari/index.html`, `scripts/landing.js`
+- 수정 전 계수: 공개 HTML 한 파일에 `예시` 49회, `조건` 31회, `실제` 28회, `확인` 27회, `쇼케이스` 15회, `검토` 12회, `데모` 11회. 7개 상위 섹션 안에 상세 6장이 다시 들어가 사실상 13개 장을 읽게 했다.
+- 구조 원인: 공개 고객의 결정에 필요한 조건·후보·현장 확인과, 관리자의 게시 채널·법정 검수·내부 출처 원장이 한 IA에 겹쳤다. 진실성 장치가 주장 가까이에 놓인 것이 아니라 모든 장의 주제가 됐다.
+- 로직 원인: 화면에 없는 면적·엘리베이터 조건을 적합 수에 포함하고, 입력하지 않은 입주 충돌을 강제했으며, 분석 실행 전에도 완료 결과가 보였다. 월세는 보증금만으로 예산 적합을 판정했다. 카피 중복과 계산 SSOT 불일치가 함께 있었다.
+- 수정 계약: 공개 페이지를 `Hero+조건 도크 / AI 브리핑 / 세 집 비교 / 선택 집 검토 서류철 / 사람 확인` 5개로 압축한다. 내부 게시 게이트와 개발자 용어는 관리자에만 둔다. 전역·분석·후보 부모·이미지·폼·대화상자·푸터마다 오해가 실제 생기는 경계 한 번만 남긴다.
+- 기존 규칙과의 조정: `오해 지점 가까이에 진실 라벨`이라는 근본 규칙을 약화하지 않는다. 같은 경계를 자식 값마다 반복하지 않고, 가장 가까운 공통 부모가 의미 범위를 정확히 소유하면 한 번으로 묶는다. 정직함은 경고문 수가 아니라 입력·계산·출처·행동의 일치로 측정한다.
+- 회귀 게이트 후보: 공개/관리자 콘텐츠 소유권 표, 반복 핵심어 계수, 분석 전 빈 상태, 보이는 입력 목록과 계산 조건 목록의 동일성, 월세 복합 비용의 미확정 처리, 실제 게시 상수의 공개 DOM 부재를 단언한다.
+
+### 증거 I — 다른 고위험 업종으로 돌린 스킬 전향 테스트
+
+- 화면과 상태: 새 규칙을 한국형 AI 피부 상담 쇼케이스와 임상의 관리자 브리프에 그대로 재적용
+- 관련 파일: `packages/skill/SKILL.md`, `references/trustworthy-showcases.md`, `references/preflight.md`, `references/audit-gate.md`
+- 첫 RED: 규제 행동을 일반화한 문장과 달리 코드 예제는 모든 행동을 같은 세 불리언으로 열었다. 사용자 자기보고 값을 도메인 사실로 읽을 여지가 있었고, 가장 가까운 공통 부모 라벨과 공개/관리 콘텐츠 소유권이 정본에 없었다.
+- 근본 수정: 행동별 `requiredByAction`, 미등록 행동 기본 거절, 합성 자료의 실제 행동 차단을 코드 예제에 반영했다. 사실을 주장 문장 단위로 정의하고, 모델 출력 내용은 추론·버전과 시각만 시스템 상태로 분리했다. 공통 부모/예외 자식/보조기술 연결과 공개 해석/관리 내부 증거의 소유권을 단계·감사·통과 조건에 함께 넣었다.
+- 조정 원칙: `오해 지점 가까이에 라벨`을 약화하지 않았다. 의미 경계가 명확한 가장 가까운 부모가 같은 범위를 한 번 소유하게 해 정확도를 높였고, 사용자 행동에 영향을 주는 제한은 공개에서 숨기지 않았다.
+- 재검 결과: 독립 전향 테스트 전 항목 PASS, 새 P1·P2 없음. 저장소 공식 skill lint도 경고 0건으로 통과했다.
+
+## 최종 산출물
+
+- [x] 확정 교훈 **21개** — `packages/skill/references/trustworthy-showcases.md` §12
+- [x] 교훈별 코드, 캡처, 검사 증거 — 이 원장의 증거 A~I와 `tools/showcase-duo-e2e-report.md`
+- [x] `packages/skill`의 근본 규칙과 단계별 참고 문서 수정 — SKILL, preflight, audit-gate, layout, images, reference-method
+- [x] 기존 규칙과의 조화 기록 — 사실성·접근성 우선, R2 다른 업종 유지, 예외는 페이지 계약으로 좁게 선언
+- [x] skill 테스트, CLI 패키지 검증, 타입 검사 — 경고 0, core 22/22, CLI 9/9, 배포 점검 통과
+- [x] 실제 설치본 동기화 — Codex·Claude·Cursor 등 사용자 대상 10곳 모두 v0.10.0 doctor 정상
+
+## 최종 게이트 판정
+
+- 사이트 전체 L0~L6: 17계층 전부 PASS, 배포 금지 항목 0개
+- 새 듀오 실제 브라우저 E2E: 90/90 시나리오 · 350/350 단언 · 12/12 캡처
+- 메인 디자인 게이트: 178개 PASS
+- WebKit: 8개 PASS · 시각 회귀: 30개 PASS · 탐색/키보드: 14개 PASS
+- 쇼케이스 갤러리: 21개 카드와 메타 수치 일치, 한남자리·철판클럽 카드/하위 경로 연결 완료