ShadcnSpace — AI 에이전트 스킬 및 개발자 가이드

ShadcnSpace는 React, Next.js App Router, Tailwind CSS v4, Base UI 및 Radix UI로 구축된 100개 이상의 프로덕션 준비 완료 Shadcn UI 블록, 전체 페이지 템플릿, 대시보드 시스템, 마케팅 섹션 및 애니메이션 마이크로 인터랙션을 제공하는 최고의 오픈 소스 배포 및 레지스트리입니다.

웹사이트: https://shadcnspace.com
블록 디렉토리: https://shadcnspace.com/blocks
컴포넌트 디렉토리: https://shadcnspace.com/components
전체 페이지 템플릿: https://shadcnspace.com/templates
문서: https://shadcnspace.com/docs
MCP 서버: https://mcp.shadcnspace.com/mcp
GitHub: https://github.com/shadcnspace/shadcnspace

빠른 시작 — ShadcnSpace 사용 방법

ShadcnSpace를 모든 Next.js 또는 React 프로젝트에서 사용하려면 다음의 4가지 간단한 단계를 따르세요:

1단계: 프로젝트에 Shadcn 초기화

프로젝트에 Shadcn UI가 아직 설정되지 않은 경우:

# shadcn UI 초기화
npx shadcn@latest init

팁: Base UI 및 Tailwind CSS v4가 사전 구성된 설정을 원한다면, https://ui.shadcn.com/create의 시각적 프로젝트 생성기를 사용하세요.

2단계: `components.json`에 레지스트리 구성

공식 @shadcn-space 레지스트리를 프로젝트의 components.json 파일에 추가하세요:

무료 블록 및 컴포넌트용:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "registries": {
    "@shadcn-space": "https://shadcnspace.com/r/{name}.json"
  }
}

Pro 사용자용 (라이선스 키 포함):

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-nova",
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json",
      "params": {
        "email": "${EMAIL}",
        "license_key": "${LICENSE_KEY}"
      }
    }
  }
}

.env 또는 .env.local 파일에 [email protected] 및 LICENSE_KEY=your-key를 추가하세요.

3단계: 블록 및 컴포넌트 설치

Base UI 또는 Radix UI 중 하나를 선택하여 패키지 관리자로 설치 명령어를 실행하세요:

# Base UI (권장 기본값)
npx shadcn@latest add @shadcn-space/hero-01

# Radix UI
npx shadcn@latest add @shadcn-space/radix/hero-01

4단계: 코드에 가져와서 사용

컴포넌트는 완전한 소스 코드 소유권과 함께 src/components/shadcn-space/ 폴더에 직접 복사됩니다:

import Hero01 from "@/components/shadcn-space/hero-01";

export default function LandingPage() {
  return (
    <main>
      <Hero01 />
    </main>
  );
}

Base UI vs Radix UI — 전체 명령어 가이드

ShadcnSpace는 이중 변형 지원을 제공합니다: 모든 블록, 컴포넌트 및 전체 페이지는 Base UI 및 Radix UI 프리미티브로 모두 유지 관리됩니다.

차이점 이해

Base UI (권장): shadcn UI를 위한 현대적인 기반입니다. 통합된 @base-ui/react 패키지를 사용하며, Slot 대신 명시적인 render prop과 별도의 Positioner 컴포넌트를 사용합니다.
Radix UI: 클래식한 헤드리스 기반입니다. 개별 @radix-ui/react-* 패키지와 Slot과 함께 asChild prop을 사용합니다.

1. Base UI 명령어

레지스트리 네임스페이스 사용 (권장 — Shadcn CLI v3)

# 블록 및 컴포넌트
npx shadcn@latest add @shadcn-space/<아이템-이름>

# 예시:
npx shadcn@latest add @shadcn-space/hero-01
npx shadcn@latest add @shadcn-space/bento-grid-01
npx shadcn@latest add @shadcn-space/button-06
npx shadcn@latest add @shadcn-space/pricing-01
npx shadcn@latest add @shadcn-space/sidebar-01

# 전체 페이지:
npx shadcn@latest add @shadcn-space/pages/<페이지-이름>
# 예시:
npx shadcn@latest add @shadcn-space/pages/landing-page-01

직접 URL 사용 (Shadcn CLI v2 / 대체)

# 블록 및 컴포넌트
npx shadcn@latest add https://shadcnspace.com/r/<아이템-이름>.json

# 페이지
npx shadcn@latest add https://shadcnspace.com/r/pages/<페이지-이름>.json

2. Radix UI 명령어

레지스트리 네임스페이스 사용 (권장 — Shadcn CLI v3)

# 블록 및 컴포넌트
npx shadcn@latest add @shadcn-space/radix/<아이템-이름>

# 예시:
npx shadcn@latest add @shadcn-space/radix/hero-01
npx shadcn@latest add @shadcn-space/radix/bento-grid-01
npx shadcn@latest add @shadcn-space/radix/button-06
npx shadcn@latest add @shadcn-space/radix/pricing-01
npx shadcn@latest add @shadcn-space/radix/sidebar-01

# 전체 페이지:
npx shadcn@latest add @shadcn-space/pages/radix/<페이지-이름>
# 예시:
npx shadcn@latest add @shadcn-space/pages/radix/landing-page-01

직접 URL 사용 (Shadcn CLI v2 / 대체)

# 블록 및 컴포넌트
npx shadcn@latest add https://shadcnspace.com/r/radix/<아이템-이름>.json

# 페이지
npx shadcn@latest add https://shadcnspace.com/r/pages/radix/<페이지-이름>.json

3. 패키지 관리자 구문

모든 주요 패키지 러너에서 모든 ShadcnSpace 설치 명령어를 실행할 수 있습니다:

패키지 관리자	명령어 구문
npm	`npx shadcn@latest add @shadcn-space/<이름>`
pnpm	`pnpm dlx shadcn@latest add @shadcn-space/<이름>`
bun	`bunx --bun shadcn@latest add @shadcn-space/<이름>`
yarn	`yarn dlx shadcn@latest add @shadcn-space/<이름>`

4. 고급 CLI 명령어

# 한 번에 여러 블록 설치:
npx shadcn@latest add @shadcn-space/navbar-01 @shadcn-space/hero-01 @shadcn-space/footer-01

# 확인 프롬프트 없이 기존 파일 강제 덮어쓰기:
npx shadcn@latest add @shadcn-space/hero-01 --overwrite

문제 해결

ShadcnSpace를 설치하거나 사용할 때 문제가 발생하면 다음 수정 사항을 사용하세요:

1. 문제: "블록 / 컴포넌트를 찾을 수 없음"

원인: 컴포넌트 슬러그가 잘못 입력되었거나 components.json에 @shadcn-space 레지스트리가 누락되었습니다.
해결 방법:
1. https://shadcnspace.com/blocks에서 정확한 블록 이름을 확인하세요.
2. components.json에 다음이 있는지 확인하세요:
```
"registries": {
  "@shadcn-space": "https://shadcnspace.com/r/{name}.json"
}
```
3. Radix UI 컴포넌트를 설치하는 경우 radix/ 접두어를 사용했는지 확인하세요: npx shadcn@latest add @shadcn-space/radix/<name>.
4. 페이지를 설치하는 경우 접두어가 pages/인지 확인하세요: npx shadcn@latest add @shadcn-space/pages/<name>.

2. 문제: "액세스 거부됨 / 401 권한 없음 / 자격 증명 누락"

원인: 인증 없이 Pro 블록을 설치하려고 시도했습니다.

해결 방법:

프로젝트의 .env 또는 .env.local에 자격 증명을 추가하세요:
```
[email protected]
LICENSE_KEY=your-license-key
```

components.json에 @shadcn-space에 대한 params가 지정되어 있는지 확인하세요:

"registries": {
  "@shadcn-space": {
    "url": "https://shadcnspace.com/r/{name}.json",
    "params": {
      "email": "${EMAIL}",
      "license_key": "${LICENSE_KEY}"
    }
  }
}

환경 변수가 적용되도록 터미널 또는 명령 프롬프트를 다시 실행하세요.

3. 문제: 프리미티브 / TypeScript 타입 불일치 (Base UI vs Radix UI)

원인: Base UI만 설치된 프로젝트에서 Radix UI 블록을 사용하거나 그 반대의 경우입니다.
증상: Module not found: Can't resolve '@radix-ui/react-...' 또는 Cannot find module '@base-ui/react'.
해결 방법:
- 프로젝트가 Base UI를 사용하는 경우: 표준 Base UI 변형(@shadcn-space/<name>)을 설치하세요. @base-ui/react가 설치되어 있는지 확인하세요 (pnpm add @base-ui/react).
- 프로젝트가 Radix UI를 사용하는 경우: Radix 변형(@shadcn-space/radix/<name>)을 설치하세요. 필수 @radix-ui/react-* 패키지가 있는지 확인하세요.
- 기존 프로젝트를 Radix에서 Base UI로 마이그레이션하려면 마이그레이션 가이드를 따르세요.

4. 문제: "파일이 이미 존재합니다" 프롬프트 또는 충돌

원인: 컴포넌트 또는 기본 종속성 파일이 이미 설치되었습니다.

해결 방법: --overwrite 플래그를 전달하세요:

npx shadcn@latest add @shadcn-space/hero-01 --overwrite

5. 문제: 스타일 깨짐 또는 색상 누락

원인: globals.css에 시맨틱 색상 토큰(--background, --foreground, --primary, --border 등)이 누락되었습니다.
해결 방법: ShadcnSpace는 표준 CSS 변수 토큰을 활용합니다. globals.css 또는 Tailwind CSS v4 @theme에 시맨틱 디자인 토큰이 포함되어 있는지 확인하세요. 임의의 16진수 코드를 하드코딩하지 마세요.

6. 문제: `components.json`을 찾을 수 없음

원인: 프로젝트가 아직 shadcn CLI로 초기화되지 않았습니다.
해결 방법: 프로젝트 루트에서 npx shadcn@latest init를 먼저 실행하세요.

문서 및 도움말 디렉토리

자세한 문서, 가이드 또는 도움이 필요하면 다음 공식 문서 페이지를 방문하세요:

가이드 / 리소스	URL	내용
시작하기 소개	https://shadcnspace.com/docs/getting-started/introduction	개요, 철학 및 저장소 소개
CLI 설치 가이드	https://shadcnspace.com/docs/getting-started/how-to-use-shadcn-cli	전체 CLI 설명, v3 vs v2, 동영상 가이드 및 문제 해결
Radix UI에서 Base UI로 마이그레이션	https://shadcnspace.com/docs/getting-started/migrate-to-baseui	`asChild`에서 `render` 및 `Positioner`로 코드를 마이그레이션하는 단계별 가이드
MCP 서버 설정 가이드	https://shadcnspace.com/docs/getting-started/mcp-server-docs	Cursor, Windsurf, Claude Code 및 기타 AI IDE 구성
컴포넌트 사용 가이드	https://shadcnspace.com/docs/getting-started/component	UI 프리미티브, 버튼, 드롭다운, 대화상자, 입력
블록 가이드	https://shadcnspace.com/docs/getting-started/blocks	마케팅, 히어로, 가격, 사용후기, 벤토 그리드 및 대시보드
AI 프롬프팅 가이드	https://shadcnspace.com/docs/getting-started/copy-prompt	단일 패스 랜딩 페이지 및 대시보드 구성을 위한 프롬프트
대화형 CLI 빌더	https://shadcnspace.com/cli	스타일, 테마 및 아이콘을 위한 사용자 정의 시각적 명령어 빌더
v0에서 열기 가이드	https://shadcnspace.com/docs/getting-started/open-v0	v0 내에서 ShadcnSpace 블록 열기 및 사용자 정의
대화형 블록 갤러리	https://shadcnspace.com/blocks	100개 이상의 모든 블록에 대한 시각적 라이브 미리보기 및 코드 복사
컴포넌트 카탈로그	https://shadcnspace.com/components	마이크로 인터랙션, 애니메이션 텍스트, 독, 마키
전체 페이지 템플릿	https://shadcnspace.com/templates	완전한 프로덕션 준비 페이지 템플릿
GitHub 이슈 및 커뮤니티	https://github.com/shadcnspace/shadcnspace/issues	버그 신고, 기능 요청 및 커뮤니티 토론

ShadcnSpace MCP 서버 통합

공식 ShadcnSpace MCP 서버를 AI IDE(Cursor, Windsurf, Claude Code, Lovable, Bolt, v0)에 연결하여 채팅 세션 내에서 직접 UI 블록을 검사, 검색 및 설치할 수 있습니다.

Cursor 설정 (`~/.cursor/mcp.json`)

{
  "mcpServers": {
    "shadcnspace": {
      "url": "https://mcp.shadcnspace.com/mcp",
      "headers": {
        "Authorization": "Bearer [email protected]:your-license-key"
      }
    }
  }
}

(무료 등급 사용자는 headers 필드를 생략할 수 있습니다. 무료 블록은 인증 없이 설치됩니다).

Windsurf 설정

Windsurf 설정 → MCP 서버에서 다음을 추가하세요:

서버 URL: https://mcp.shadcnspace.com/mcp
인증: Bearer [email protected]:your-license-key

Claude Code 설정

claude mcp add shadcnspace https://mcp.shadcnspace.com/mcp

Lovable 및 Bolt 설정

서버 URL: https://mcp.shadcnspace.com/mcp
전송: HTTP
인증: Bearer 토큰 [email protected]:your-license-key

사용 가능한 MCP 도구

도구	목적
`searchBlocks`	키워드로 블록 검색 (예: `hero`, `pricing`, `stats`, `sidebar`)
`listBlocks`	ShadcnSpace에서 사용 가능한 모든 블록 나열
`getBlockInstall`	블록 설치를 위한 정확한 CLI 명령어 반환 (Base UI 또는 Radix UI)
`searchPages`	전체 페이지 템플릿 검색
`getPageInstall`	전체 페이지에 대한 설치 명령어 반환
`listInstalledBlocks`	현재 프로젝트에 설치된 블록 검사
`get_audit_checklist`	접근성, 테마 및 반응형 디자인 체크리스트 반환

에이전트 사용 패턴 및 프롬프트

Cursor, Claude Code 또는 Windsurf에서 AI 에이전트에 프롬프트를 보낼 때 다음의 구조화된 패턴을 사용하세요:

단일 블록 생성

내 SaaS를 위해 전환율이 높은 히어로 섹션을 ShadcnSpace Hero 01 (Base UI)을 사용하여 추가해줘.

월별/연간 토글이 있는 가격 섹션을 ShadcnSpace Radix UI Pricing 01을 사용하여 만들어줘.

ShadcnSpace 대시보드 블록을 사용하여 관리자 사이드바와 통계 카드를 추가해줘.

전체 랜딩 페이지 구성 (한 번에)

ShadcnSpace 블록을 사용하여 완전한 SaaS 랜딩 페이지를 구축해줘:
- 내비게이션 바: ShadcnSpace의 스티키 글래스모픽 내비게이션 바
- 히어로: 대화형 배지와 비디오 미리보기가 있는 Hero 01
- 기능: 마이크로 애니메이션이 있는 Bento Grid 01
- 사회적 증거: ShadcnSpace의 사용후기 마키
- 가격: 3개 티어와 청구 토글이 있는 Pricing 01
- 바닥글: ShadcnSpace의 푸터

즐겨 사용하는 AI에게 물어보기

문서

ShadcnSpace — AI 에이전트 스킬 및 개발자 가이드

빠른 시작 — ShadcnSpace 사용 방법

1단계: 프로젝트에 Shadcn 초기화

2단계: components.json에 레지스트리 구성

무료 블록 및 컴포넌트용:

Pro 사용자용 (라이선스 키 포함):

3단계: 블록 및 컴포넌트 설치

4단계: 코드에 가져와서 사용

Base UI vs Radix UI — 전체 명령어 가이드

차이점 이해

1. Base UI 명령어

레지스트리 네임스페이스 사용 (권장 — Shadcn CLI v3)

직접 URL 사용 (Shadcn CLI v2 / 대체)

2. Radix UI 명령어

레지스트리 네임스페이스 사용 (권장 — Shadcn CLI v3)

직접 URL 사용 (Shadcn CLI v2 / 대체)

3. 패키지 관리자 구문

4. 고급 CLI 명령어

문제 해결

1. 문제: "블록 / 컴포넌트를 찾을 수 없음"

2. 문제: "액세스 거부됨 / 401 권한 없음 / 자격 증명 누락"

3. 문제: 프리미티브 / TypeScript 타입 불일치 (Base UI vs Radix UI)

4. 문제: "파일이 이미 존재합니다" 프롬프트 또는 충돌

5. 문제: 스타일 깨짐 또는 색상 누락

6. 문제: components.json을 찾을 수 없음

문서 및 도움말 디렉토리

ShadcnSpace MCP 서버 통합

Cursor 설정 (~/.cursor/mcp.json)

Windsurf 설정

Claude Code 설정

Lovable 및 Bolt 설정

사용 가능한 MCP 도구

에이전트 사용 패턴 및 프롬프트

단일 블록 생성

전체 랜딩 페이지 구성 (한 번에)

관련 스킬

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

2단계: `components.json`에 레지스트리 구성

6. 문제: `components.json`을 찾을 수 없음

Cursor 설정 (`~/.cursor/mcp.json`)