design-system v2.2: content fundamentals, dual palette, magazine tokens

[thxforall]

배경

claude.ai/design 생성 번들(핸드오프 ID sJT8lNdxaDa6tyzTYezHvw)을 검토한 결과, 현재 디자인 시스템은 토큰·컴포넌트 레벨에서는 이미 잘 정렬되어 있다. 실제 갭은 다음 두 축에 있다.

1. 토큰 SSOT 드리프트 — globals.css에 --mag-* magazine palette가 정의돼 있으나 tokens.ts의 colors 객체에 매핑되지 않아 TS에서 접근 불가.
2. 문서 누락 — Content Fundamentals(보이스·캐이싱·언어·이모지 등), Dual Palette 사용 규칙, Animation 카탈로그가 문서화되지 않음. 에이전트용 SSOT(docs/agent/design-system-llm.md)도 현재 코드 상태와 드리프트(예: 실제 nav HOME/EXPLORE/UPLOAD/LAB + Try On pill, DecodedLogo WebGL + IBM Plex Mono).

현재 디자인을 전면 수정하지 않고, 번들에서 제시된 형식화 내용 중 적용 가능한 부분만 반영하여 v2.2로 올리는 작업.

목표

• docs/design-system/ 2.2.0 업데이트
• docs/agent/design-system-llm.md 1-pager SSOT로 재작성
• tokens.ts에 magazine palette 매핑 추가

범위

A. Tokens (코드 미세 보강)

• packages/web/lib/design-system/tokens.ts colors 객체에 magPrimary / magAccent / magBg / magText 4개 키 추가 (CSS var는 이미 globals.css에 있음)
• ColorToken 타입 자동 확장 확인

B1. docs/design-system/ v2.2.0

• README.md
  • Version 2.2.0, v2.2 Changes 섹션
  • Content Fundamentals 요약 + 상세 파일 링크
  • Dual Palette Usage 요약 + patterns.md 링크
  • Navigation & Layout Facts 신규: 실제 nav(HOME / EXPLORE / UPLOAD / LAB + Try On pill), Home sequence(HeroItemSync → EditorialMagazine → EditorialCarousel → StyleMoods → EditorPicks → TrendingListSection → DomeGallerySection), DecodedLogo WebGL + IBM Plex Mono
  • Tech Stack 표 IBM Plex Mono 추가
• content-fundamentals.md 신규: Voice / Casing / Person / Language mix / Pricing(₩ + ko-KR locale) / Numbers(toLocaleString + 단복수) / Emoji Policy — 각 규칙 Do/Don't 예시 + 코드 앵커
• animations.md 신규: animate-spot-reveal, animate-spot-glow, animate-spot-float, animate-reveal-scan, animate-hologram-*, animate-slide-up, animate-shimmer, animate-marquee-c, animate-card-glow, animate-ai-summary-*, .js-observe, .fs-connector 카탈로그 테이블 (keyframe/duration/easing/용도/reduce-motion). 상단 원칙 문단: default ease cubic-bezier(0.22, 1, 0.36, 1) 300–400ms, subtle/purposeful/editorial
• patterns.md: "Dual Palette Usage" 헤딩 추가
  • Editorial(fixed dark) 서피스: home, magazine, post detail(spot view)
  • Product UI(semantic OKLCH + .dark flip) 서피스: explore, profile, rankings, admin, auth, upload, settings
  • 규칙: 같은 페이지 혼용 금지 / next-themes .dark는 Product UI에만 영향 / Editorial 서피스 ThemeToggle 숨김

B2. docs/agent/design-system-llm.md 재작성

• 번들 README의 VISUAL FOUNDATIONS / CONTENT FUNDAMENTALS / ICONOGRAPHY를 1-pager로 압축
• 모든 상세는 docs/design-system/ 크로스 링크
• 맨 아래 <!-- keep in sync with docs/design-system/README.md@2.2.0 --> 주석

Out of Scope

• 기존 컴포넌트 내부 리팩터(CVA variant, props, 클래스 이름)
• 새 컴포넌트 추가
• 번들의 27개 HTML 프리뷰 갤러리를 /design-system 라우트로 이식 → 별도 이슈 제안(C안)
• 페이지 레이아웃 변경
• DecodedLogo.tsx WebGL 내부 수정
• decoded.pen 원본 동기화
• Storybook/Ladle 도입
• VRT/Playwright visual 테스트 추가
• 모바일(Expo) 디자인 시스템 반영
• Admin surface JetBrains Mono 실제 적용
• Orval / API 관련 어떠한 것도

Success Criteria

코드

• tokens.ts의 colors에서 magPrimary/magAccent/magBg/magText 접근 가능
• ColorToken 타입에 신규 키 반영
• bun run lint / bun tsc --noEmit / bun run build 통과, warn 증가 없음
• 빌드 CSS에서 --main-*/--mag-* 값 변경 없음

문서

• docs/design-system/README.md Version 2.2.0, Last Updated 2026-04-23
• content-fundamentals.md 7개 섹션 Do/Don't 예시 포함
• animations.md 12+ 엔트리 카탈로그
• patterns.md에 "Dual Palette Usage" 헤딩 존재
• docs/agent/design-system-llm.md 재작성, 상세는 전부 docs/design-system/로 링크
• 모든 마크다운 내부 링크 유효(깨진 링크 0)
• 문서 내 코드 앵커(app/page.tsx:L) 전부 resolvable

비회귀

• /, /explore, /magazine, /profile/[username], /admin 5개 라우트 렌더 정상
• 색상/폰트 시각 변경 없음
• prefers-reduced-motion 환경에서 애니메이션 정상 차단 유지

커밋 분할 (Conventional Commits)

1. feat(design-system): map magazine palette to colors tokens — tokens.ts
2. docs(design-system): add content fundamentals guide — content-fundamentals.md
3. docs(design-system): add animation catalog — animations.md
4. docs(design-system): document dual palette usage rules — patterns.md
5. docs(design-system): README v2.2.0 — sync with current codebase — README.md
6. docs(agent): rewrite design-system-llm SSOT — docs/agent/design-system-llm.md

참고 링크

• 번들 출처: https://api.anthropic.com/v1/design/h/sJT8lNdxaDa6tyzTYezHvw (claude.ai/design 핸드오프)
• 기존 v2.1: docs/design-system/README.md
• 에이전트 SSOT: docs/agent/design-system-llm.md
• Tokens: packages/web/lib/design-system/tokens.ts
• Globals CSS: packages/web/app/globals.css

후속 이슈 후보

• C안: 번들의 27개 HTML 프리뷰를 내부 /design-system 라우트(Storybook-lite)로 이식
• D안: Admin surface JetBrains Mono 실제 적용 + 폰트 로드 최적화
• E안: VRT 도입으로 위 SSOT 회귀 감지 자동화