도입 가이드

설치

소비 저장소의 .npmrc에 사내 scope registry가 설정되어 있어야 한다.

@classum:registry=https://registry.classum.com

pnpm add @classum/dot-design-system

패키지는 ESM 전용이다. Vite, Next.js 등 ESM을 처리하는 현대적인 React toolchain에서 사용한다.

앱 entry에서 한 번 CSS를 불러오고 적용 범위를 DotTheme로 묶는다.

import { DotTheme } from '@classum/dot-design-system/ui';
import '@classum/dot-design-system/styles.css';

export function App() {
  return <DotTheme>{/* routes */}</DotTheme>;
}

DotTheme는 앱 shell이나 body를 소유하지 않는다. 기존 reset이 없는 제품은 portal된 overlay의 reset 범위를 함께 검토한다.

에이전트 컨텍스트

설치된 디자인 시스템 버전의 문서와 규칙을 Codex·Claude 작업에 고정하려면, 소비 저장소 root에서 명시적으로 실행한다.

pnpm exec dot-ds agents init

이 명령은 docs/dot-design-system/에 package version과 문서 SHA-256을 기록한 snapshot을 만들고, .agents/skills/dot-design-system/와 .claude/skills/dot-design-system/에 동일한 skill을 만든다. AGENTS.md와 CLAUDE.md에는 marker로 구분된 짧은 adapter만 추가한다. 기존 소비 저장소 지시와 managed 영역 밖의 내용은 보존한다.

설치된 버전 또는 snapshot 문서가 바뀌면 다음처럼 확인하고 갱신한다.

pnpm exec dot-ds agents check
pnpm exec dot-ds agents sync

check은 version·hash drift를 보고만 하며 파일을 수정하지 않는다. sync는 managed snapshot과 marker 안의 adapter만 갱신한다. unmanaged skill이 이미 있으면 명령은 덮어쓰지 않고 실패한다.

새 화면 작업의 시작 prompt가 필요하면 다음을 실행한다.

pnpm exec dot-ds agents prompt new-screen
pnpm exec dot-ds agents prompt new-screen --copy

이 명령은 설치된 @classum/dot-design-system version에 맞는 self-contained prompt를 표준 출력으로 제공하며, --copy를 지정하면 같은 원문을 OS clipboard에 복사한다. clipboard 도구가 없는 환경에서도 원문은 표준 출력에 남는다. 이 통합은 의도적으로 명시적이다. package 설치와 postinstall은 어떠한 consumer file도 만들거나 변경하지 않는다.

컴포넌트

import { Button, PageHeader, PageScaffold, StatusPill } from '@classum/dot-design-system/ui';

export function CurriculumPage() {
  return (
    <PageScaffold>
      <PageHeader title="커리큘럼" badge={<StatusPill tone="success">운영 중</StatusPill>} />
      <Button>새 커리큘럼 만들기</Button>
    </PageScaffold>
  );
}

ui entry는 theme, primitive와 composition만 제공하며 3D character·motion payload를 초기 제품 bundle에 포함하지 않는다. DotCharacter가 필요한 화면만 root entry를 별도로 사용한다.

기존 컴포넌트가 URL 형태의 작은 Dot identity를 필요로 하면 dotIconUrl을 사용한다. 이 export는 최적화된 WebP만 소비 bundle에 넣으며, 원본 SVG URL인 dotLogoUrl은 root entry의 호환 API로 유지된다.

import { dotIconUrl } from '@classum/dot-design-system/ui';

<img src={dotIconUrl} alt="" />;

모션

Lottie renderer가 초기 bundle에 들어오지 않게 별도 entry를 사용한다.

import { DotMotion } from '@classum/dot-design-system/motion';

<DotMotion variant="processing" ariaLabel="답변을 채점하고 있어요" />;

접근 가능한 텍스트 상태를 함께 제공하고 실제 AI 작업이 끝나면 모션도 종료한다.

Tailwind

패키지 컴포넌트에 필요한 utility는 styles.css에 미리 컴파일되어 있다. 제품 코드에서도 semantic utility를 사용하려는 Tailwind 3 앱만 preset을 추가한다.

import dotTailwindPreset from '@classum/dot-design-system/tailwind-preset';

export default {
  presets: [dotTailwindPreset],
  content: ['./src/**/*.{ts,tsx}'],
};

업그레이드

• patch: 시각 버그, 문서 보완, 호환되는 에셋 최적화
• minor: 호환되는 컴포넌트·토큰·asset ID 추가
• major: public prop 제거, token 의미 변경, 활성 asset ID 제거

업데이트 PR에서는 changelog, 실제 화면의 visual QA, keyboard·focus, package version을 함께 확인한다.