@01.works/design-system

@01.works/design-system

Design Context foundation을 프로젝트 소유 소스로 생성하고 provenance, 진단, 안전한 upgrade를 관리하는 CLI다.

이 패키지는 두 영역을 의도적으로 분리한다.

• Foundation: Design Context 토큰, 상태 계약, primitive, 의존성, framework wiring. 결정론적으로 생성하고 digest를 추적한다.
• Composition: route, 콘텐츠, 정보 위계, reference를 해석한 화면 조합. 처음부터 프로젝트가 소유한다.

init은 화면이나 route를 만들지 않는다.

사용자 흐름

0.5.0은 immutable design-context@1.2.0 foundation을 사용합니다.

패키지 설치 자체는 프로젝트 파일을 변경하지 않습니다. 새 프로젝트는 init, 기존 프로젝트는 adopt를 실행해야 foundation, provenance와 agent skill이 저장소에 연결됩니다. foundation 없이 agent skill만 먼저 연결하려면 setup을 사용합니다. setup은 생성 digest를 skill 디렉터리에 기록하므로, 사용자가 수정하지 않은 이전 버전은 후속 실행에서 안전하게 갱신하고 프로젝트가 수정한 skill은 conflict로 보존합니다.

# CLI를 프로젝트의 반복 가능한 devDependency로 설치할 때
pnpm add -D @01.works/design-system@0.5.0

# 1. Design Context foundation 계획과 적용
pnpm dlx @01.works/design-system@0.5.0 init --profile minimal --dry-run --json
pnpm dlx @01.works/design-system@0.5.0 init --profile minimal --yes

# 2. context.01.works의 프롬프트 복사로 revision-pinned reference JSON을 전달
#    공개되지 않은 Design Context reference CLI 버전을 추측해 설치하지 않는다.

# 3. 에이전트가 reference evidence를 읽고 프로젝트 소유 화면을 작성
#    init은 이 단계의 route/content를 생성하지 않는다.

# 4. 상태와 provenance 검사. error는 중단하고 warning은 검토한다.
pnpm exec design-system doctor

# 5. 구현 검증 뒤, 프로젝트 정책상 warning도 실패시킬 때만 strict 사용
pnpm exec design-system doctor --strict

# 6. 의도적인 커스터마이징 승인과 이후 갱신 확인
pnpm exec design-system baseline --yes
pnpm exec design-system upgrade --check
# CI에서는 변경·수동 검토·unsupported 항목을 모두 실패 처리
pnpm exec design-system upgrade --check --fail-on-change
pnpm exec design-system upgrade --apply-safe

init과 adopt가 함께 설치하는 use-01works-design-system skill은 reference를 관찰 자료로 취급하고, 증거가 없는 column 수·gutter·breakpoint를 추론하지 않도록 안내한다. 시각 검증 도구의 설치와 수명주기는 foundation 계약에 포함하지 않는다.

# foundation을 적용하지 않고 agent skill만 연결
pnpm dlx @01.works/design-system@0.5.0 setup --dry-run --json
pnpm dlx @01.works/design-system@0.5.0 setup --yes

지원 범위

foundation profile은 --components로 portable primitive 또는 form, overlay, data, feedback group을 선택한다. minimal은 Button, Input, Badge를 설치하고 product는 portable primitive 8개를 설치한다. profile은 설치 범위의 단축 표현일 뿐 foundation 선택이 아니다. 실제 선택 결과는 design-system.json의 components에 기록된다.

pnpm exec design-system init --profile foundation --components button,dialog --catalog none --yes
pnpm exec design-system init --profile product --catalog storybook --yes
pnpm exec design-system init --framework vite --profile product --catalog storybook --yes
pnpm exec design-system init --profile monorepo --catalog storybook --yes

pnpm exec design-system add slider table --dry-run
pnpm exec design-system add form overlay --yes

Storybook은 현재 프로젝트에 설치된 Design Context component만 문서화한다. preset toolbar, dark-mode 비교, pattern route/story는 생성하지 않는다.

기존 프로젝트

adopt는 Design Context 일부를 기존 시스템과 공존시키는 명령이며 전체 Design Context 준수를 주장하지 않는다.

# 진단만 수행합니다. 옵션 없는 adopt는 파일을 변경하지 않습니다.
pnpm dlx @01.works/design-system@0.5.0 adopt --dry-run

# components.json이 이미 있는 shadcn 앱: UI 자산을 바꾸지 않고 등록
pnpm dlx @01.works/design-system@0.5.0 adopt --register --dry-run
pnpm dlx @01.works/design-system@0.5.0 adopt --register --yes

# components.json이 없는 앱: 보존형 coexist 제어면 등록
pnpm dlx @01.works/design-system@0.5.0 adopt --bootstrap --dry-run
pnpm dlx @01.works/design-system@0.5.0 adopt --bootstrap --yes

# 선택 자산까지 격리된 계층에 추가
pnpm dlx @01.works/design-system@0.5.0 adopt --bootstrap --tokens --icons tabler --components button --yes

--register는 기존 shadcn 앱 전용이며 토큰·아이콘·컴포넌트 옵션과 함께 사용할 수 없습니다. --bootstrap은 비-shadcn 앱 전용입니다. 두 경로 모두 실제 적용 전 --dry-run 결과를 검토합니다.

프로젝트 수준에는 integration.kind = generated | coexist | enrolled, 파일 수준에는 origin = generated | coexist | enrolled | tool을 기록한다. 기존 파일을 나중에 Design Context 계약에 등록하는 enroll은 별도 검증 명령으로 설계되어 있으며 이번 버전에는 아직 공개하지 않는다. coexist/enrolled 기존 파일은 generatedDigest: null이고 자동 upgrade 대상이 아니다.

설정과 provenance

• design-system.json: schema v2, immutable Design Context reference/digest, integration, 실제 component 목록과 경로 정책
• .design-system/manifest.json: foundation·registry·파일 digest, origin, migration과 검증 결과
• .design-system/backups/: adopt가 수정하는 기존 설정 백업

design-system.json, .design-system/manifest.json, 설치된 .agents/skills/, 생성·수정된 foundation 파일, package.json과 lockfile은 함께 commit해야 다른 작업자와 CI가 동일한 상태를 복원할 수 있습니다. .design-system/transaction.lock은 실행 중에만 사용하는 로컬 파일이며 commit하지 않습니다. 프로젝트 정책상 backup을 제외하려면 .design-system/backups/만 선택적으로 ignore합니다.

파일 transaction은 관리 파일과 명시된 lockfile을 rollback합니다. 설치·검증 명령이 만든 node_modules, package-manager cache, Storybook·build 산출물은 rollback 범위가 아니므로 명령 실패 후 필요하면 해당 로컬 산출물을 정리하고 다시 실행합니다.

화면 composition 작업을 시작하면 설치된 skill의 references/handoff-template.md를 바탕으로 프로젝트 소유 docs/design-context-handoff.md를 만듭니다. 이 문서는 사용한 reference revision과 digest, route별 진행 상태, guide-to-CSS mapping, 검증 결과와 다음 작업을 기록합니다. foundation provenance와 화면 구현 이력을 섞지 않기 위해 handoff 문서는 manifest에 포함하지 않습니다.

manifest가 없으면 doctor, add, baseline, catalog, upgrade의 안전한 digest 판단을 복원할 수 없습니다. design-system.json만 남은 상태를 새 foundation으로 간주해 자동 재생성하지 말고, 원래 manifest를 버전 관리나 artifact에서 복구해야 합니다.

Source of truth

registry/foundation/design-context/<version>의 immutable snapshot이 Design Context foundation의 정본이다. apps/web는 이 정본을 사용하는 제품 dogfood consumer이며 package source가 아니다.

immutable package snapshot --> generated project
                           └-> apps/web dogfood surface

package build, test와 release는 Catalogue를 읽지 않는다. 저장소 루트의 scripts/sync-design-context-dogfood.mjs --check가 package-owned token/component와 Catalogue의 portable surface가 같은지 별도로 검증합니다. 의도적인 foundation 변경은 새 version으로 promotion한 뒤 pnpm design-system:sync-web으로 앱에 단방향 적용합니다.

• registry/foundation/design-context/1.2.0: 현재 Design Context contract, tokens, states, component snapshots와 provenance
• registry/foundation/design-context/1.1.0: 기존 프로젝트 upgrade를 위한 immutable 이전 snapshot
• registry/vendor/shadcn-4.18.0/base-mira: 변환하지 않은 공식 shadcn 기준 snapshot
• registry/fragments/design-context-foundation/1.json: 브라우저 안전한 Design Context prompt fragment data

Design Context fragment는 이 패키지가 소유합니다. Reference/security/tooling prompt compiler는 현재 유일한 consumer인 Catalogue가 소유하고 제품 context를 orchestration합니다. 브라우저 번들에서 design-system의 Node CLI export를 import하지 않습니다.

개발 및 검증

pnpm --filter @01.works/design-system validate:registry
pnpm --filter @01.works/design-system check
pnpm --filter @01.works/design-system lint:package
pnpm --filter @01.works/design-system test:package
pnpm --filter @01.works/design-system verify:release

공식 shadcn 기준점을 바꿀 때만 vendor:upstream을 실행합니다. 이 명령은 upstream을 변환하지 않습니다.