본문으로 건너뛰기
Dot Design System
v0.3.1

Dot Design System Domain Contract

패키지, 문서, 에셋과 제품 코드의 책임 경계를 고정합니다.

Package boundary

  • 이 저장소의 root가 유일한 publishable package다. 별도 runtime package로 나누지 않는다.
  • public API는 package.json#exports를 통해서만 제공한다.
  • 일반 제품 UI는 character·motion asset graph와 분리된 ./ui subpath를 제공한다.
  • 제품 도메인의 API response, backend interface, 권한 모델, 라우터와 상태 관리를 포함하지 않는다.
  • PermissionGuard처럼 제품 인증에 결합되는 컴포넌트는 소비 저장소가 소유한다.

Canonical inputs

  • docs/, tokens/tokens.json, src/styles/tokens.css, assets/catalog.json, assets/motion/manifest.json이 구현 기준이다.
  • docs/catalog.json은 canonical 문서의 route, 종류, 상태, component source와 agent context 포함 여부를 관리한다. 문서 사이트와 snapshot은 이 catalog에서 파생한다.
  • 개인 로컬 경로, 외부 디자인 문서, 이전 대화가 빌드나 사용의 전제 조건이 되어서는 안 된다.
  • token JSON과 CSS variable은 같은 semantic 이름과 값을 유지한다.

Agent context boundary

  • docs/는 agent context의 canonical source다. docs/agent-context.md와 docs/catalog.json에서 agent: true인 참조 문서는 package version 및 각 문서의 SHA-256과 함께 소비 저장소에 snapshot으로 고정된다.
  • dot-ds agents init과 dot-ds agents sync만 소비 저장소의 managed snapshot, Codex/Claude skill, 짧은 adapter를 생성·갱신한다. package 설치와 postinstall은 소비 저장소 파일을 변경하지 않는다.
  • snapshot manifest는 package 이름·version과 source hash를 기록한다. dot-ds agents check은 version 또는 hash drift를 실패로 보고하지만 파일을 수정하지 않는다.
  • dot-ds agents prompt new-screen은 설치된 version의 self-contained 화면 설계 prompt를 출력할 뿐 소비 저장소를 수정하지 않는다.
  • Codex와 Claude adapter는 소비 저장소 소유 지시를 보존하고 표시된 managed section만 갱신한다. unmanaged skill 또는 managed 영역 밖의 내용을 덮어쓰지 않는다.

Asset boundary

  • package에는 제품 전달용 derivative만 포함한다.
  • 승인 logo SVG는 public dotLogoUrl과 provenance source로 유지하고, 작은 제품 시그니처인 DotIcon은 source hash가 고정된 192×233 lossless sRGB WebP derivative를 사용한다.
  • ui entry는 dotIconUrl을 제공하되 원본 logo SVG, character와 motion asset graph를 포함하지 않는다.
  • 편집 원본, 대형 render master, 임시 export는 npm allowlist에 들어갈 수 없다.
  • quarantined asset에는 배포 파일이 없어야 한다.
  • catalog path, byte size, SHA-256, dimension과 alpha는 CI에서 검증한다.
  • DotIcon derivative는 Lanczos3 resize, lossless WebP effort 6, embedded sRGB ICC와 24KiB budget을 CI에서 검증한다.
  • embedded motion raster는 source profile에서 sRGB로 명시적으로 변환하고 sRGB ICC profile을 배포 파일에 포함한다.
  • motion manifest는 브랜드 팀이 관리하는 원본의 hash와 재생성 옵션을 기록하되 로컬 절대 경로를 포함하지 않는다.
  • Lottie 최적화는 delivery field, embedded payload와 manifest에 사전 선언된 호환성 패치 외의 애니메이션 구조를 바꾸지 않는다.
  • expression 호환성 패치는 정확한 원본 SHA-256, patch ID와 기대 expression 집합·개수를 가진 allowlist로 제한한다. 하나라도 일치하지 않으면 변환과 배포를 중단한다.
  • 적용한 expression 패치는 manifest의 transform.compatibilityPatches와 결과물의 dotTransform.expressionPatches에 ID, 적용 개수, 입력·출력 expression SHA-256으로 감사 가능하게 기록한다.
  • allowlist에 없는 unresolved expression reference는 fail closed하며 임의의 layer 이름 치환이나 expression 삭제로 우회하지 않는다.
  • 손상된 asset을 crop, paint, 생성형 보정으로 조용히 수정하지 않는다.

Compatibility

  • 배포 형식은 browser bundler가 소비하는 ESM으로 고정한다.
  • root, ui, motion entry는 React client module boundary를 배포 파일에도 보존하며, tokens와 tailwind-preset은 server-safe entry로 유지한다.
  • React 18.3과 19를 peer 범위로 지원한다.
  • package component CSS는 Tailwind content scan 없이 동작한다.
  • token, reset, utility와 animation keyframe은 .dot-theme 경계 밖의 소비 앱에 영향을 주지 않는다.
  • compiled utility의 theme selector는 :where()로 specificity를 추가하지 않아 소비 앱의 responsive·상태 utility를 덮어쓰지 않는다.
  • 디자인 시스템 overlay는 DotTheme 내부 portal root를 사용해 theme 경계를 벗어나지 않는다.
  • Tailwind preset은 제품 코드의 semantic utility 사용을 위한 선택 기능이다.
  • Sidebar의 cookie 저장과 전역 keyboard shortcut은 소비 제품이 명시적으로 설정할 때만 활성화한다.
  • interactive target은 40px 이상, 정보 텍스트는 12px 이상을 기본 계약으로 삼는다.
  • 모션은 reduced-motion fallback과 텍스트 상태를 제공한다.
  • active motion은 배포 전 실제 lottie-web SVG renderer smoke에서 data_failed, Lottie error와 runtime console error 없이 frame을 렌더해야 한다.

Documentation surface

  • website/는 publishable npm package와 분리된 private documentation surface다.
  • 사이트는 canonical Markdown, catalog와 실제 package public API를 읽고 별도 설계 원칙 사본을 유지하지 않는다.
  • 모든 stable public component는 목적, 선택 기준, 구조, 변형·크기, 상태·동작, 콘텐츠, 접근성, 좁은 화면·긴 콘텐츠, 공개 API, 실행 가능한 예제와 금지 사례를 제공한다.
  • package build가 끝난 뒤 site typecheck와 production build가 통과해야 한다.

Release

  • package version과 tag가 일치해야 한다.
  • 발행 전 format, lint, typecheck, test, build, asset verification, Lottie renderer smoke, tarball audit를 모두 통과한다.
  • tarball은 12MiB unpacked budget을 넘지 않고 비배포 원본을 포함하지 않는다.
  • agent snapshot source, manifest schema, Codex/Claude skill과 adapter는 같은 package version으로 배포하고 version·hash drift 검사를 통과한다.