OpenClaw shadcn/ui 스킬 가이드

OpenClaw shadcn/ui 스킬 개요

shadcn/ui 스킬은 OpenClaw를 shadcn/ui 컴포넌트 라이브러리에 연결하여, 에이전트가 프로젝트에서 접근성 높은 React 컴포넌트를 추가, 구성, 조합할 수 있게 합니다. 설치 후에는 일반 영어 설명만으로 폼, 데이터 테이블, 내비게이션, 다이얼로그 등 완전한 UI 기능을 스캐폴딩할 수 있습니다.

npm 패키지로 제공되는 기존 컴포넌트 라이브러리와 달리, shadcn/ui는 컴포넌트 소스 코드를 프로젝트에 직접 복사합니다. 이는 모든 코드를 직접 소유하며 라이브러리 추상화와 싸우지 않고 컴포넌트를 커스터마이징할 수 있다는 의미입니다. OpenClaw shadcn/ui 스킬은 대화를 통해 컴포넌트 선택, 설치, 조합, 스타일링을 처리하여 이 워크플로우를 더욱 빠르게 만듭니다.

일반적인 워크플로우:

1. OpenClaw에 정렬 및 페이지네이션이 포함된 데이터 테이블을 추가해 달라고 요청합니다.
2. 에이전트가 npx shadcn@latest add table 및 관련 컴포넌트를 실행한 후, 지정한 열로 테이블 구현을 생성합니다.
3. 완전히 작동하는 접근성 높은 데이터 테이블이 프로젝트에 나타나며 — 바로 커스터마이징할 수 있습니다.

이 스킬은 Tailwind CSS를 사용하는 React 및 Next.js 프로젝트용으로 설계되었습니다. 레이아웃 및 UX 가이드를 위한 Frontend Design 스킬과 자연스럽게 연동되며, 모든 디자인 시스템 워크플로우와 함께 잘 작동합니다.

shadcn/ui 스킬 사전 요구 사항

shadcn/ui 스킬을 설치하기 전에 다음을 확인하세요:

• OpenClaw 설치 및 실행 중 (v1.0+)
• Tailwind CSS가 구성된 React 또는 Next.js 프로젝트
• Node.js v18+ 및 패키지 매니저 (npm, pnpm 또는 bun)
• 스킬 관리를 위한 clawhub CLI 설치

설정을 확인하세요:

# OpenClaw 버전 확인
openclaw --version

# Node.js 버전 확인
node --version

# Tailwind CSS 구성 확인
npx tailwindcss --help

새 프로젝트를 시작하는 경우, 에이전트가 npx shadcn@latest init을 사용하여 shadcn/ui가 사전 구성된 Next.js 프로젝트를 초기화하는 것을 도와줄 수 있습니다.

shadcn/ui 스킬 설치 방법

단일 명령으로 shadcn/ui 스킬을 설치하세요:

npx clawhub@latest install shadcn-ui

설치를 확인하려면:

clawhub list

설치된 스킬 목록에 shadcn-ui가 표시되어야 합니다.

shadcn/ui 스킬 구성

shadcn/ui 스킬은 API 키나 외부 인증이 필요하지 않습니다. 로컬 프로젝트 파일과 shadcn CLI로 작동합니다.

프로젝트 초기화

프로젝트에 shadcn/ui가 아직 구성되지 않은 경우, 에이전트가 초기화할 수 있습니다:

# 프로젝트에 shadcn/ui 초기화
npx shadcn@latest init

이렇게 하면 프로젝트 루트에 다음 설정이 포함된 components.json 구성 파일이 생성됩니다:

| 설정 | 설명 | |------|------| | style | 컴포넌트 스타일 변형 (default 또는 new-york) | | tailwind.baseColor | 테마의 기본 색상 (slate, gray, zinc 등) | | tailwind.cssVariables | 테마에 CSS 변수 사용 여부 | | aliases.components | 컴포넌트의 임포트 경로 별칭 | | aliases.utils | 유틸리티 함수의 임포트 경로 별칭 |

테마 커스터마이징

CSS 변수를 편집하거나 에이전트에 색상 조정을 요청하여 기본 테마를 커스터마이징하세요:

/* 예시: globals.css의 커스텀 테마 변수 */
@layer base {
  :root {
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
  }
}

중요: shadcn/ui 컴포넌트는 프로젝트의 소스 코드로 복사됩니다. 모든 컴포넌트를 완전히 제어할 수 있으며 — 숨겨진 의존성이나 잠긴 추상화가 없습니다.

shadcn/ui 스킬 사용 예시

1. 완전한 폼 추가

사용자: "이름, 이메일, 비밀번호, 약관 동의 체크박스가 포함된 사용자 등록 폼을 만들어주세요. zod를 사용한 유효성 검사를 추가해주세요."

에이전트가 npx shadcn@latest add를 사용하여 필요한 컴포넌트(form, input, checkbox, button, label)를 설치한 후, zod 스키마 유효성 검사, 오류 메시지, 접근성 높은 레이블이 포함된 완전한 폼 컴포넌트를 생성합니다. 이 폼은 React Hook Form 패턴을 따르며 API에 연결할 준비가 되어 있습니다.

2. 데이터 테이블 구축

사용자: "이름, 이메일, 역할, 상태 열이 포함된 사용자 표시용 데이터 테이블을 추가해주세요. 정렬, 필터링, 페이지네이션을 포함해주세요."

에이전트가 table 컴포넌트를 추가하고 @tanstack/react-table을 사용하여 전체 기능을 갖춘 데이터 테이블을 구축합니다. 열 정의, 필터 컨트롤, 정렬 핸들러, 페이지네이션을 생성하며 — 모두 적절한 TypeScript 타입과 접근성 속성이 포함됩니다.

3. 대시보드 레이아웃 생성

사용자: "접을 수 있는 사이드바, 상단 내비게이션 바, 브레드크럼, 메인 콘텐츠 영역이 있는 대시보드 레이아웃을 설정해주세요."

에이전트가 sidebar, navigation-menu, breadcrumb, separator 컴포넌트를 설치한 후, 모바일 친화적인 사이드바 토글과 적절한 시맨틱 HTML 구조를 갖춘 반응형 레이아웃으로 조합합니다.

4. 명령 팔레트 추가

사용자: "Ctrl+K 단축키로 페이지와 액션을 검색할 수 있는 VS Code 같은 명령 팔레트를 추가해주세요."

에이전트가 command와 dialog 컴포넌트를 설치하고, 키보드 단축키 리스너를 설정한 후, 그룹화된 항목, 아이콘, 내비게이션 핸들러가 포함된 검색 가능한 명령 메뉴를 생성합니다.

5. 설정 페이지 구성

사용자: "프로필, 계정, 알림, 외관에 대한 탭이 있는 설정 페이지를 만들어주세요. 각 탭 내에서 관련 옵션을 그룹화하기 위해 카드를 사용해주세요."

에이전트가 tabs, card, switch, select, separator 컴포넌트를 설치한 후, 폼 필드, 토글, 드롭다운 선택기가 논리적인 탭 그룹으로 구성된 완전한 설정 인터페이스를 구축합니다.

보안 및 모범 사례

shadcn/ui 스킬 사용 시 다음 지침을 따르세요:

• 생성된 코드를 검토하세요. 에이전트는 프로젝트에 직접 컴포넌트 코드를 생성합니다. 커밋하기 전에 항상 새 파일과 변경 사항을 검토하세요, 특히 폼 핸들러와 API 통합 부분을 주의하세요.
• 사용자 입력을 검증하세요. shadcn/ui는 UI 컴포넌트를 제공하지만 입력 유효성 검사는 제공하지 않습니다. 항상 zod나 yup 같은 라이브러리를 사용한 서버 측 유효성 검사와 폼을 함께 사용하고, 처리 전에 입력을 살균하세요.
• 의존성을 최신 상태로 유지하세요. shadcn/ui 컴포넌트는 Radix UI 프리미티브 및 기타 패키지에 의존합니다. 주기적으로 npm audit을 실행하고 취약한 의존성을 업데이트하세요.
• 시맨틱 HTML을 사용하세요. 에이전트는 기본적으로 접근성 높은 마크업을 생성하지만, 커스텀 수정 사항이 ARIA 속성과 키보드 내비게이션을 유지하는지 확인하세요.
• 컴포넌트 패턴을 따르세요. shadcn/ui 컴포넌트를 지정된 컴포넌트 디렉토리(예: components/ui/)에 유지하세요. 인라인으로 수정하지 말고 — 대신 컴포지션을 통해 확장하세요. 일반적인 OpenClaw 지침은 안전 체크리스트를 검토하세요.

일반적인 오류 해결

"components.json not found"

프로젝트가 아직 shadcn/ui로 초기화되지 않았습니다.

# 프로젝트에 shadcn/ui 초기화
npx shadcn@latest init

프롬프트에 따라 스타일, 기본 색상, 임포트 별칭을 선택하세요. 에이전트도 이를 대신 실행할 수 있습니다.

"Module not found: Can't resolve '@/components/ui/button'"

임포트 경로 별칭이 프로젝트 구성과 일치하지 않습니다.

1. components.json에서 구성된 별칭 경로를 확인하세요.
2. tsconfig.json에 일치하는 경로 별칭이 있는지 확인하세요:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. Next.js를 사용하는 경우, tsconfig.json을 변경한 후 개발 서버를 재시작하세요.

"Tailwind CSS classes not applying"

Tailwind가 컴포넌트 파일 디렉토리를 처리하지 않고 있습니다.

1. tailwind.config.js에 컴포넌트 경로가 포함되어 있는지 확인하세요:

module.exports = {
  content: [
    "./src/components/**/*.{js,ts,jsx,tsx}",
  ],
}

2. globals.css에 Tailwind 디렉티브가 임포트되어 있는지 확인하세요 (@tailwind base; @tailwind components; @tailwind utilities;).
3. 개발 서버를 재시작하세요.