CLI

klic-design 통합 패키지

[email protected] · AI 지침·토큰·테마·폰트·CLI·컴포넌트·블록·모션 · npm 발행 전

KLIC 저장소에서 bun run pack:npm을 실행해 설치할 tarball을 만드세요.

bun add [email protected]
bunx --bun [email protected] klic version --json

npm install [email protected]
npx --yes [email protected] klic version --json

필요한 항목만 가져오기

import {createTokens} from 'klic-design/tokens';
import {getMotion} from 'klic-design/motions';
import button from 'klic-design/components/button';
import SupportTickets from 'klic-design/blocks/support-tickets';
import 'klic-design/blocks.css';
import 'klic-design/motions/fade-slide.css';

컴포넌트는 항목별 등록 HTML 형태, 블록은 React 19 실행 예제, 모션은 CSS/React 원본 예제입니다. 블록에는 React·React DOM이 필요합니다. 폰트·스타일은 필요한 경로를 명시적으로 가져오세요.

KLIC Design Agent Skill

동일한 klic-design 패키지에 포함됩니다. 별도 설치 없이, 필요한 에이전트에만 선택적으로 동기화하세요. 동기화 명령은 실험적 기능입니다.

klic-design 스킬 다운로드

bunx skills experimental_sync -y

npx skills experimental_sync -y

선택 사항 · CLI 파일 직접 다운로드

직접 다운로드하는 단일 ESM CLI는 Bun 1.4.2 실행을 기본으로 합니다. Node.js 22+도 npm/npx 호환 소비 경로로 지원합니다. 명령은 현재 디렉터리에서 실행합니다.

curl -fL https://design.klic.co.kr/integrations/klic.mjs -o klic.mjs
bun klic.mjs help
bun klic.mjs contract

shadcn으로 React 블록 추가

shadcn이 설정된 React 19 프로젝트에서 아래 명령으로 지원 블록의 소스, CSS, 토큰과 MIT 고지를 추가할 수 있습니다. 폰트는 시스템 대체 글꼴을 사용합니다.

bunx --bun shadcn@latest add https://design.klic.co.kr/r/affect-agent-review.json

지원 항목: affect-agent-review, affect-response-workspace, affect-logo-marquee, affect-testimonial-wall. 다른 항목은 아래 KLIC CLI의 독립 작업 폴더 전달을 사용하세요.

각 항목의 설치 내용은 https://design.klic.co.kr/r/<항목-ID>.json에서 확인할 수 있습니다.

전체 명령

항목 명령의 kind는 component 또는 block입니다. theme은 별도 명령 그룹이며 아래 하위 명령별 옵션을 사용합니다. 모든 데이터 명령에 --base 또는 --local을 사용할 수 있으며 두 옵션을 함께 쓰면 오류입니다. 중복 옵션, 알 수 없는 옵션과 명령에 맞지 않는 옵션도 오류입니다.

필터와 페이지 이동

curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs list --kind component --limit 5
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs search "button" --kind component --token klic.component --group actions
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs list --kind component --limit 5 --cursor 5
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs list --kind block --status planned --limit 5

페이지를 넘길 때 동일한 검색 조건과 release를 유지하세요. 다음 페이지가 없으면 nextCursor는 null입니다. 필터를 바꾸면 cursor를 0으로 되돌립니다.

소스 가져오기

curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs add block support-tickets --out ./klic-support-tickets

curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
node ./klic.mjs add block support-tickets --out ./klic-support-tickets

컴포넌트 상세의 variants에 등록된 형태의 ID·용도·출처·소스 경로가 있습니다. source의 --variant에는 그 ID를 사용하세요. add는 해당 컴포넌트의 모든 등록 형태와 공통 스타일·동작을 함께 가져옵니다.

curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs get component button
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs source component button --variant default
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs source block support-tickets
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs plan block support-tickets
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs add block support-tickets --out ./klic-support-demo --dry-run
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs add block support-tickets --out ./klic-support-demo

• dry-run: manifest를 읽어 파일 경로·용량·의존성을 출력하며 파일은 만들지 않습니다.
• add: 모든 파일의 크기와 SHA-256을 검증한 뒤 저장합니다. 기존 경로와 심볼릭 링크는 거부합니다. 상위 폴더는 미리 존재해야 합니다.
• 출력은 공용 런타임과 라이선스를 포함한 독립 작업 폴더입니다. bun install과 bun run dev는 README 확인 후 직접 실행합니다.
• source는 참조 코드 한 파일을 출력합니다. 의존성을 포함한 전체 전달은 add를 사용하세요.

테마 검색과 검증된 전달

curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs theme list --query paper
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs theme get paper
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs theme plan paper --profile studio --material glass --mode system
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs theme add paper --profile studio --material glass --mode system --out ./klic-theme-paper --dry-run
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs theme add paper --profile studio --material glass --mode system --out ./klic-theme-paper

theme list는 --query만, theme get은 선택 옵션 없이 실행합니다. theme plan과 theme add는 --profile, --material, --mode를 받으며 add만 새 폴더 --out과 선택 --dry-run을 받습니다. --base와 --local은 모든 theme 하위 명령에서 사용할 수 있습니다.

• theme add는 파일별 SHA-256과 크기를 검증한 뒤 새 폴더에만 씁니다. 기존 경로는 덮어쓰지 않으며 npm, shell 또는 설치 명령을 실행하지 않습니다.
• 묶음: theme.css, tokens.light.json, tokens.dark.json, theme.config.json, apply-theme.mjs, vanilla index.html, 표준 테마 엔진 JS, 등록된 실제 폰트 21개와 fonts/FONT-NOTICES.md.
• 초기 CSS는 선택한 테마·프로필의 Light/Dark와 공통 재질 선택자를 포함합니다. 런타임 helper는 같은 표준 엔진으로 테마·프로필·모드·재질 전환을 지원합니다. 토큰 JSON은 Component와 Semantic 재질 역할 및 그 참조를 보존한 4계층 형식입니다.

import './klic-theme-paper/theme.css';
import {applyTheme} from './klic-theme-paper/apply-theme.mjs';

const theme = applyTheme(document.documentElement);
theme.update({id:'paper', profile:'studio', mode:'dark', material:'glass'});
// For a portal outside the themed root, also call applyTheme(portalRoot).
// Keep each root's context in sync, then release its listeners when disposed.
theme.destroy();

테마를 적용할 앱 루트에 helper를 연결하세요. 루트 밖 포털은 자체 포털 루트에도 helper를 연결하고 컨텍스트를 함께 갱신합니다. system 모드는 운영체제 색상 설정을 따라가며 destroy()가 리스너를 해제합니다.

Paperlogy는 실제 400·600·700 파일을, Pretendard는 실제 400 파일만 제공합니다. 다른 Pretendard 굵기는 브라우저가 합성하며 별도 실제 파일이 아닙니다. fonts/FONT-NOTICES.md의 라이선스 고지를 보존하세요.

로컬 체크아웃과 다른 배포

# KLIC source repository root
bun dist/integrations/klic.mjs list --local --kind component
bun dist/integrations/klic.mjs get component button --local
curl --fail --location --output klic.mjs https://design.klic.co.kr/integrations/klic.mjs
bun ./klic.mjs list --base https://design.klic.co.kr

--local은 현재 작업 폴더의 dist/api/v1/registry.json과 dist 아래 소스를 읽습니다. 다운로드한 단일 파일만으로 로컬 스냅샷이 생기지는 않습니다. --base는 HTTPS만 허용하며 localhost 개발 환경에 한해 HTTP를 허용합니다.

출력과 오류 처리

성공 종료 코드는 0, 실패는 1입니다. JSON 결과는 stdout, 오류 JSON은 stderr로 출력합니다. source는 원본 텍스트를, mcp는 응답마다 한 줄 JSON을 출력합니다.

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "add requires --out with a new directory."
  }
}

테마 컨텍스트와 범위

전체 정의 인벤토리는 호환성을 위해 3,751개 토큰을 유지합니다. 외부 전달은 선택한 컨텍스트의 활성 참조를 따라 사용하지 않는 Primitive를 제외하며, 토큰 탐색기는 현재 컨텍스트와 전체 정의 범위를 구분합니다. Primitive 3,143개 중 2,496개(79.41%)는 재질 정의입니다.

형식은 프로젝트가 지원하는 타입과 4계층 참조 규칙을 검증합니다. 모든 DTCG 기능 지원이나 모든 화면의 WCAG 인증을 의미하지 않습니다.

요청 한도와 권한 키

초과 요청은 HTTP 429와 Retry-After를 반환합니다. API·MCP는 X-KLIC-API-Key 헤더, CLI는 KLIC_API_KEY 환경 변수를 지원합니다. 서버에 등록된 키만 한도에서 제외되며 관리 권한이나 MCP 인증을 부여하지 않습니다. 키를 URL·문서·브라우저 코드에 넣지 마세요.

이미 읽은 스냅샷의 stdio·WebMCP 호출과 --local 실행은 서버 요청을 만들지 않습니다. 초기 HTTP 레지스트리 조회와 소스 다운로드는 각각 서버 한도를 사용합니다.

수치의 집계 범위

제공 형태와 버전 읽기

KLIC은 7개 디자인 디멘션과 4계층 토큰을 공통 기반으로 씁니다. 적용 기준은 다릅니다. 컴포넌트는 개별 조작 요소, 블록은 업무 흐름, 모션은 시간에 따른 전환을 다룹니다. 공개 npm: [email protected]. 소스 후보 [email protected]는 미발행이며 [email protected]가 현재 발행본입니다.

컴포넌트 109개와 실행 블록 247개는 CLI plan/add로 독립 참고 작업 폴더 356개를 제공합니다. 모션 884개는 source id + pattern 출처와 보존된 고지를 포함한 KLIC 각색 패턴이며 상세 화면·API·CLI motion get에서 HTML/CSS/JavaScript/React 소스를 제공합니다(CSS/React 예제 포함). 미리보기와 JavaScript/React 구현은 같은 런타임을 사용하며 Canvas 재생은 CSS만으로 재현되지 않습니다. 패키지는 components/*·blocks/*·motions/*를 제공하고, 모션 수는 작업 폴더 수와 별도로 집계합니다. 소스 후보 [email protected]는 미발행이며 [email protected]가 현재 발행본입니다.

라이선스 안내는 파일별 출처와 보존 고지의 색인입니다. 사이트 전체에 새 단일 라이선스를 부여하지 않습니다. Figma는 manifest와 이관 가이드를 제공하며 자동 동기화 기능과 구분합니다. 공개 KLIC 소스 저장소 주소는 현재 제공 계약에 등록되어 있지 않습니다.

https://design.klic.co.kr/licenses/README.md
https://design.klic.co.kr/design-contract/materials/figma-manifest.json
https://design.klic.co.kr/design-contract/materials/figma-migration.md