@design-ai/cli 4.55.0

package/examples/print-packaging-spec.md

@@ -0,0 +1,285 @@
+<!-- hand-written -->
+# Print spec: folding carton (Korean cosmetics, mid-tier)
+
+> Worked example: spec for a Korean skincare brand's primary product carton. Covers dieline, regulatory content, color, finish, sustainability, and Korean labeling. Pairs with [`knowledge/print/packaging.md`](../knowledge/print/packaging.md) and [`knowledge/print/korean-print-conventions.md`](../knowledge/print/korean-print-conventions.md).
+
+## Brief
+
+- **Product**: 50ml moisturizer in glass jar, secondary carton
+- **Brand**: Reun (가상의 한국 화장품 브랜드)
+- **Tier**: Mid-premium (clean beauty, eco-aware audience)
+- **Channel**: Korean online (Olive Young, Coupang) + retail (boutique stores)
+- **Audience**: KR primary; some EN secondary copy for export potential
+- **Volume**: 10,000 cartons initial run
+- **Sustainability**: FSC-certified board, soy ink
+
+## Specs
+
+| Spec | Value |
+| --- | --- |
+| **Style** | Tuck-end folding carton (TT — top-tuck-bottom-tuck) |
+| **Size** | 70mm × 70mm × 80mm (W×D×H) |
+| **Material** | 350gsm SBS (solid bleached sulfate), FSC-certified |
+| **Inside coat** | None (uncoated interior) |
+| **Color** | CMYK + 1 spot Pantone (brand color) |
+| **Finish** | Matte aqueous coating |
+| **Special** | Spot UV on logo (front panel only); deboss on brand wordmark |
+| **Inks** | Soy-based |
+| **File** | PDF/X-1a, fonts outlined, dieline on separate non-printing layer |
+
+### Color tokens
+
+```
+--brand-primary:       PANTONE 5807 C  (sage green)
+--brand-text:          90% K
+--brand-meta:          60% K (regulatory text)
+--accent:              PANTONE warm gray 5 C (very subtle accent line)
+```
+
+### Dieline
+
+```
+                        Top tuck
+                ┌──────────────────────┐
+                │                      │
+                │      TOP PANEL       │
+                │      70 × 70mm       │
+                │                      │
+                ├───────────┬──────────┤
+        ─ ─ ─ ─ │           │          │ ─ ─ ─ ─
+                │           │          │
+        Side    │   FRONT   │   RIGHT  │   Side
+        panel   │  70 × 80  │  70 × 80 │   panel
+        70×80   │           │          │   70×80
+                │   PANEL   │   PANEL  │
+        ─ ─ ─ ─ │           │          │ ─ ─ ─ ─
+                ├───────────┴──────────┤
+                │                      │
+                │     BOTTOM PANEL     │
+                │     70 × 70mm        │
+                │                      │
+                └──────────────────────┘
+                       Bottom tuck
+
+Lay flat with glue tab on outside-right; folds in.
+Dotted lines = creases. Solid = cuts.
+```
+
+Total flat dimensions including bleed: ~330mm × 240mm.
+
+## Panel content
+
+### Front panel — brand-defining
+
+```
+┌─────────────────────────────┐
+│                             │
+│        ▣ REUN                │  ← logo, deboss + spot UV
+│                             │     (top center, 30mm)
+│                             │
+│                             │
+│      Calming Moisturizer    │  ← product name, 11pt
+│      카밍 모이스처라이저        │  ← 10pt KR
+│                             │
+│                             │
+│           50ml              │  ← net contents, 9pt 600
+│                             │
+└─────────────────────────────┘
+```
+
+### Right panel (and Left, symmetric) — story
+
+```
+┌─────────────────────────────┐
+│                             │
+│  센텔라와 약쑥이 진정시키는      │  ← KR copy, 8.5pt
+│  데일리 수분 크림.             │
+│                             │
+│  Centella + mugwort calm    │  ← EN secondary, 8pt
+│  irritated skin.            │
+│                             │
+│  • 7가지 식물 추출물            │  ← bullet feature list
+│  • 무향료, 무알코올              │
+│  • 비건 인증                   │
+│                             │
+└─────────────────────────────┘
+```
+
+### Back panel — regulatory + ingredient
+
+KFDA-compliant cosmetics labeling:
+
+```
+┌─────────────────────────────┐
+│ 화장품의 명칭                  │  ← 6.5pt headers
+│ Calming Moisturizer          │
+│                             │
+│ 내용량 50ml                   │
+│                             │
+│ 제조판매업자                   │
+│ (주)르운, 서울시 강남구 ...      │
+│ 화장품 제조업 신고 제2024-...호  │
+│                             │
+│ 사용기한: 박스 측면 표기         │
+│ (개봉 후 12개월)                │
+│                             │
+│ 전성분                        │
+│ 정제수, 글리세린, 센텔라아시아티카  │  ← 6pt; all listed
+│ 추출물, 인삼뿌리추출물,          │
+│ 베타글루칸, 히알루론산, ...        │
+│                             │
+│ 사용 시 주의사항                │
+│ 1. 화장품을 사용하여 다음과       │  ← KFDA-mandated text
+│ 같은 이상이 있는 경우에는 ...      │
+│                             │
+│ 소비자 상담실 080-1234-5678     │
+│                             │
+│ 원산지: 한국                  │
+│                             │
+│ ┌─┐ ┌─┐  분리배출 표시:        │  ← recycling marks
+│ │종│ │플│  종이/플라스틱           │     mandatory
+│ └─┘ └─┘                      │
+│                             │
+│ [barcode 1.5cm × 3cm]       │
+└─────────────────────────────┘
+```
+
+### Top panel — utility
+
+```
+┌─────────────────────────────┐
+│                             │
+│         ▣ REUN               │  ← small logo
+│   Calming Moisturizer       │
+│                             │
+└─────────────────────────────┘
+```
+
+### Bottom panel
+
+```
+┌─────────────────────────────┐
+│                             │
+│  제조번호 / Lot:               │  ← will be ink-jet printed
+│  사용기한 / Best by:           │     by manufacturer at fill
+│                             │
+│  Made in Korea              │
+│                             │
+└─────────────────────────────┘
+```
+
+## Regulatory checklist (Korean cosmetics)
+
+- [x] **화장품의 명칭** (product name in Korean)
+- [x] **내용량** (net contents) prominent
+- [x] **제조판매업자** (manufacturer/distributor name + address)
+- [x] **화장품 제조업 신고번호** (manufacturing license)
+- [x] **사용기한 / 개봉 후 사용기간** (use-by or PAO)
+- [x] **전성분** (full ingredients in INCI Korean naming)
+- [x] **사용 시 주의사항** (KFDA-mandated standard text)
+- [x] **소비자 상담실** (customer service phone)
+- [x] **원산지** (country of origin)
+- [x] **분리배출 표시** (recycling marks for paper + any plastic component)
+- [x] **바코드** (barcode for retail)
+
+## Sustainability + ESG callouts
+
+Visible on packaging:
+- **FSC certification mark** (small, on bottom panel or near recycling marks).
+- **"100% recycled paperboard"** if applicable; for this case using FSC virgin fiber.
+- **"Soy-based ink"** mentioned on product website + occasionally on packaging back.
+- **No plastic window** — full opaque carton.
+
+## Production rationale
+
+| Decision | Why |
+| --- | --- |
+| Tuck-end folding carton | Standard, cost-effective for cosmetics |
+| 350gsm SBS, FSC-certified | Premium feel + eco-aware audience |
+| Matte aqueous coating | Soft, premium look without plastic-feel of UV varnish |
+| Spot UV on logo only | Tactile signal; subtle |
+| Deboss wordmark | Premium tactile detail |
+| Soy ink | Aligns with eco brand voice |
+| Pantone 5807 C (sage) | Brand consistency across runs; CMYK fallback for less critical surfaces |
+| KR primary, EN secondary | Domestic primary audience; export-ready secondary |
+
+## Cost estimate
+
+| Item | Per unit (KRW) |
+| --- | --- |
+| 350gsm SBS, CMYK + 1 spot, matte aqueous, spot UV, deboss | 280-350 KRW |
+| 10,000 unit run | 2,800,000-3,500,000 KRW |
+| Dieline + setup (one-time) | 200,000-400,000 KRW |
+| Press proof | 50,000 KRW |
+| **Total initial run** | ~3,000,000-3,900,000 KRW |
+
+For high-volume reorders (50,000+), per-unit drops to ~180-220 KRW.
+
+## File delivery
+
+1. **PDF/X-1a** with:
+   - Dieline on separate non-printing layer (named `dieline`)
+   - All artwork on print layers
+   - 3mm bleed
+   - Crop marks + dieline output marks
+   - Fonts outlined
+   - All images 300 DPI at final size, embedded
+   - CMYK color + Pantone 5807 C as spot
+   - ICC: Japan Color 2001 Coated
+2. **Source files**: AI master + INDD if used; layered PSD for any photographic elements
+3. **Spec sheet** (this document)
+4. **Press proof** required before bulk run
+
+## Pre-press checklist
+
+- [ ] Dieline on separate layer, set non-printing
+- [ ] Color mode: CMYK + Pantone 5807 C as spot
+- [ ] Pantone color defined as spot (not silently converted)
+- [ ] All fonts outlined
+- [ ] All images embedded, 300+ DPI
+- [ ] Bleed: 3mm all sides
+- [ ] No critical content within 5mm of cut/fold lines
+- [ ] All regulatory content present (checklist above)
+- [ ] Recycling marks at minimum 8mm × 8mm
+- [ ] Barcode scannable (test with phone)
+- [ ] Total ink coverage: ≤ 280%
+- [ ] Black: 100K for body, no rich black for small text
+- [ ] Korean copy proofread by native speaker
+- [ ] Korean regulatory text matches KFDA template exactly
+- [ ] Spell check KR + EN
+
+## Press proof approval
+
+- [ ] Color matches Pantone 5807 C (visually + by colorimeter if available)
+- [ ] Spot UV positioned correctly (only on logo)
+- [ ] Deboss depth feels premium (not too shallow)
+- [ ] Matte coating uniform (no streaks)
+- [ ] Trim and crease lines clean
+- [ ] Box folds correctly without breaking print
+- [ ] Inside (uncoated) doesn't show through to outside
+- [ ] Recycling marks legible
+
+## Common things that go wrong
+
+- **Sage green prints muddy** — Pantone match critical; press proof + sign-off mandatory.
+- **Crease lines crack the print** — too-thick coating + sharp creases. Solution: ask printer to use scoring rule that pre-conditions paper.
+- **Deboss feels weak** — depth too shallow. Specify minimum impression depth.
+- **Regulatory text 6pt is too small to read at retail** — push to 7pt minimum where possible while staying within total panel content limits.
+- **Korean ingredient list mistranslated** — INCI naming has standard Korean translations; use KFDA-approved table.
+
+## Don't
+
+- Don't skip the dieline. Designing without one means wrong fold positions.
+- Don't put critical content within 5mm of cut or crease lines.
+- Don't use rich black for ingredient text — registration shifts cause unreadable fringes.
+- Don't approve a digital proof for color-critical packaging. Press proof is mandatory.
+- Don't shrink regulatory text below KFDA minimum (typically 6pt for ingredients on small packages).
+- Don't skip recycling marks. KFDA / Ministry of Environment can require recall.
+
+## Cross-reference
+
+- [`knowledge/print/print-fundamentals.md`](../knowledge/print/print-fundamentals.md) — CMYK, bleed, DPI
+- [`knowledge/print/packaging.md`](../knowledge/print/packaging.md) — packaging fundamentals
+- [`knowledge/print/korean-print-conventions.md`](../knowledge/print/korean-print-conventions.md) — KR regulatory
+- [`knowledge/patterns/brand-identity.md`](../knowledge/patterns/brand-identity.md) — brand foundation
+- [`knowledge/i18n/korean-document-style.md`](../knowledge/i18n/korean-document-style.md) — Korean voice

package/examples/report-example.md

@@ -0,0 +1,228 @@
+# Worked example: design audit report
+
+> Generated by `skills/ux-audit` (or `skills/design-system-qa`). Demonstrates the canonical audit report format — TL;DR pyramid, severity-aggregated findings, citations.
+
+---
+
+```markdown
+# UX Audit: 신규 가입 흐름
+
+> 검토일: 2026.05.08
+> 검토자: design-ai (skills/ux-audit)
+> 사용자 목표: 첫 화면에서 30초 안에 가입 완료
+> 플랫폼: 모바일 웹 (iOS Safari + Android Chrome)
+> 검토 기준: WCAG 2.1 AA + design-ai PRINCIPLES.md
+
+## TL;DR
+
+신규 가입 흐름에 12개 문제가 있습니다 (Critical 3 / High 4 / Medium 3 / Low 2). 가입 성공률이 32% 떨어지는 주된 원인은 (1) 비밀번호 필드가 IME 영향 받음, (2) 이메일 검증 후에도 form이 reset됨, (3) 마케팅 동의가 default-checked로 들어가 있어 한국 e-commerce 법 위반입니다.
+
+**최우선 권장사항**: 마케팅 동의 default-checked 즉시 해제. 법적 리스크 + 사용자 신뢰 양쪽 회복.
+
+## 핵심 발견
+
+1. **마케팅 동의 default-checked로 체크됨** 🔴 — 정보통신망법 위반 가능
+2. **비밀번호 입력 시 IME 활성화** 🔴 — 한글 자모가 비밀번호로 인식되어 검증 실패
+3. **이메일 인증 후 form reset** 🔴 — 사용자가 입력한 값을 잃음 (이탈 발생)
+4. **휴대폰 번호 검증 regex가 미국 형식** 🟠 — 한국 010-####-#### 거부
+5. ~~기타 8건~~ (아래 상세)
+
+## 권장사항
+
+| 권장사항 | 담당 | 마감 |
+| --- | --- | --- |
+| 마케팅 동의 unchecked로 변경 | 프론트엔드 팀 | **즉시** |
+| 비밀번호 필드 IME 비활성화 | 프론트엔드 팀 | 이번 sprint |
+| 이메일 인증 후 form state 보존 | 풀스택 | 이번 sprint |
+| 휴대폰 regex 한국 형식으로 변경 | 프론트엔드 팀 | 이번 sprint |
+
+---
+
+## 상세
+
+### Critical (3건 — 출시 전 반드시 수정)
+
+#### 1. 마케팅 동의 default-checked
+**위치**: `src/screens/Signup.tsx:147`
+
+**문제**: 마케팅 정보 수신 동의 체크박스가 페이지 로드 시 체크 상태로 표시됩니다.
+
+**왜 문제인가**:
+- 한국 정보통신망법 제50조의2: 마케팅 동의는 사용자가 명시적으로 opt-in해야 하며, default-checked는 명백한 위반.
+- 사용자 신뢰 손상.
+- 신고 시 과태료 (최대 3,000만원).
+
+**해결**:
+```diff
+- <Checkbox defaultChecked label="마케팅 정보 수신 동의" />
++ <Checkbox label="마케팅 정보 수신 동의" />
+```
+
+또한 약관 동의(필수)와 분리해 별도 checkbox로 두어야 함.
+
+**참고**:
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — 마케팅 동의 분리 규칙
+- [`knowledge/i18n/korean-publishing.md`](../knowledge/i18n/korean-publishing.md) — 약관/동의 패턴
+- [정보통신망법 제50조의2](https://www.law.go.kr/...)
+
+---
+
+#### 2. 비밀번호 필드 IME 활성화
+**위치**: `src/screens/Signup.tsx:198`
+
+**문제**: 비밀번호 입력 필드에 IME(한글 입력)이 활성화되어, 사용자가 영문 비밀번호 입력 시 한글 자모가 섞여 검증 실패.
+
+**재현**:
+1. 사용자가 비밀번호 `Hello123` 입력 의도
+2. 한글 키보드 켜진 상태에서 `H`를 누르면 `ㅗ` 또는 `ㅎ` 입력됨
+3. 사용자는 `Hello123`을 보고 있다고 생각하지만 서버는 `ㅗㅔㅣㅣㅗ123` 받음
+4. 검증 실패 → 사용자 이탈
+
+**왜 문제인가**:
+- 사용자에게 보이지 않는 silent failure
+- "분명 맞게 입력했는데 왜 안 되지?" → 이탈
+
+**해결**:
+```diff
+- <input type="password" />
++ <input type="password" inputMode="text" lang="en" autoCapitalize="off" />
+```
+
+iOS Safari에서는 `lang="en"` 속성이 IME를 영문 모드로 전환합니다.
+
+**참고**:
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — IME composition handling
+- [`examples/component-input.md`](component-input.md) — Input spec
+
+---
+
+#### 3. 이메일 인증 후 form state reset
+**위치**: `src/screens/Signup.tsx:312` (state management)
+
+**문제**: 이메일 인증 코드 입력 단계에서 페이지 navigate 되면, 이전 form 입력값(이름, 휴대폰, 비밀번호)이 모두 초기화됩니다.
+
+**재현**:
+1. 사용자가 1페이지에 모든 정보 입력 완료
+2. 이메일 코드 받기 위해 2페이지 navigate
+3. 코드 입력 후 1페이지로 돌아오면 모두 빈 칸
+
+**왜 문제인가**:
+- 입력 다시 처음부터 — 정확한 이탈 트리거
+- A/B 테스트 결과 (신규 가입 다단계의 default 이탈률) ~28% (n=4,521)
+
+**해결**:
+- React Router 사용 시 form state를 URL search params 또는 localStorage에 보관.
+- 이메일 인증을 별도 화면 navigate 하지 말고 modal로 처리.
+
+```tsx
+// Option A: URL state
+useSearchParams().set("email-verify", "true")
+
+// Option B: in-place modal
+<Modal open={verifyOpen}>...</Modal>  // Form state preserved
+```
+
+**참고**:
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md) — multi-step form 패턴
+- [`examples/component-form.md`](component-form.md) — Form spec
+- [`examples/component-modal.md`](component-modal.md) — modal 사용
+
+---
+
+### High (4건 — 이번 sprint 수정)
+
+#### 4. 휴대폰 번호 검증 regex가 미국 형식
+**위치**: `src/lib/validators.ts:23`
+
+**문제**: 한국 010-####-#### 형식이 거부됩니다.
+
+**해결**:
+```ts
+- /^\d{3}-\d{3}-\d{4}$/  // (123) 456-7890 ← US 형식
++ /^01[0-9]-?\d{3,4}-?\d{4}$/  // KR 010-####-####
+```
+
+**참고**: [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md)
+
+---
+
+#### 5. Submit button이 disabled로 시작
+**위치**: `src/screens/Signup.tsx:405`
+
+**문제**: 사용자가 모든 필드 채우기 전엔 submit button이 disabled 상태. 사용자가 button 클릭하면 무엇이 잘못됐는지 알려주지 않음.
+
+**해결**: button을 항상 enabled로 두고, 클릭 시 invalid field로 focus 이동 + 에러 메시지 표시.
+
+cite [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md).
+
+---
+
+#### 6. (이하 4건 생략)
+...
+
+### Medium (3건)
+...
+
+### Low (2건)
+...
+
+---
+
+## 잘 작동하는 부분
+
+- 헤더의 "회원가입" 타이틀이 명확하고 위치가 좋음 (h1 with proper hierarchy)
+- 약관 링크가 새 탭으로 열려 form state 유지됨
+- 입력 필드의 focus ring이 명확함 (3:1 contrast clear)
+- 한글 입력 — 비밀번호 외 — 모두 정상
+
+---
+
+## Methodology
+
+- **검토 기준**:
+  - WCAG 2.1 AA
+  - design-ai/PRINCIPLES.md 30 rules
+  - 한국 정보통신망법 + e-commerce 법
+- **테스트 환경**:
+  - iOS 17.4 Safari (iPhone 14)
+  - Android 14 Chrome (Galaxy S24)
+  - 데스크톱 Chrome 124
+- **Responsive scope**: mobile 360px / 390px, tablet 768px, and desktop 1440px viewports. Findings must state whether the issue is mobile-only, desktop-only, or cross-breakpoint.
+- **Assistive technology scope**: screen reader pass covers field labels, error announcements, `aria-describedby`, and route-change focus restoration.
+- **Tools**: axe-core, manual review, A/B 테스트 데이터 (Mixpanel)
+- **Sample**: production 데이터 2026-04-01 ~ 2026-05-01, n=4,521 신규 가입 시도
+
+---
+
+## Appendix
+
+- A. 12 발견 사항 전체 목록 (severity / location / cite)
+- B. 각 발견에 대한 스크린샷 / 재현 동영상
+- C. axe-core 자동 스캔 raw 결과
+- D. A/B 테스트 데이터 raw
+
+(Appendix omitted in this example — would be 5+ pages of detail.)
+```
+
+---
+
+## Why this is a good audit report example
+
+- **TL;DR가 답을 먼저 제시** — 12 문제, 우선 마케팅 동의부터.
+- **Severity로 정렬** (Critical → High → Medium → Low), file-by-file 아닌 severity-by-severity.
+- **각 발견은 위치 / 문제 / 왜 / 해결 / 참고** 5가지 항목 일관.
+- **법적 issue를 별도 강조** (정보통신망법 위반).
+- **Code diff 제공** — 즉시 적용 가능.
+- **Knowledge file 인용** — 이유 + 참고로.
+- **"잘 작동하는 부분"** — 균형 잡힌 보고서.
+- **Methodology가 마지막** — 신뢰도 검증 가능하지만 본질은 위에 있음.
+- **Don't bury the decision** — avoid putting methodology before TL;DR in audit reports.
+
+Cite [`knowledge/patterns/report-design.md`](../knowledge/patterns/report-design.md) for the canonical structure.
+
+## Cross-reference
+
+- [`skills/ux-audit/PLAYBOOK.md`](../skills/ux-audit/PLAYBOOK.md)
+- [`skills/design-system-qa/PLAYBOOK.md`](../skills/design-system-qa/PLAYBOOK.md)
+- [`knowledge/patterns/report-design.md`](../knowledge/patterns/report-design.md)
+- [`knowledge/i18n/korean-document-style.md`](../knowledge/i18n/korean-document-style.md) — Korean voice for reports