콘텐츠로 이동

화면 부품과 키트

Webcraft 키트는 업무 앱에 자주 쓰는 화면 부품 모음이에요. 앱의 틀(사이드바, 휴대폰 하단 탭), 페이지 머리와 툴바, 필터, 빈 화면, 편집기 같은 것들이 들어 있어요. shadcn/ui 부품을 다듬은 것과 Webcraft가 따로 만든 부품이 함께 있어요.

Webcraft로 만든 프로젝트에는 처음부터 들어 있어요. 기존 프로젝트에서 쓰고 싶다면 에이전트에게 부탁하세요.

Webcraft 키트에서 필터 부품 받아 줘.

shadcn/ui를 쓰는 프로젝트라면 직접 받을 수도 있어요. components.json에 Webcraft 레지스트리를 더하세요.

{
"registries": {
"@webcraft": "https://goraebap.xyz/r/{name}.json"
}
}

테마를 먼저 받고, 필요한 부품을 받아요.

터미널 창
npx shadcn@latest add @webcraft/theme
npx shadcn@latest add @webcraft/filter

받은 부품은 src/shared/ui/kit/에 들어가요. 받은 코드는 프로젝트 것이니 마음대로 고쳐도 돼요.

키트 부품은 Webcraft의 폴더 별칭(@/shared/ui/kit, @/shared/lib)을 그대로 가져와요. shadcn이 다른 별칭으로 바꿔 주지 않으므로, components.json의 aliases를 아래처럼 맞춰요. cn은 cn 패키지에서 가져오고, shared/lib/utils.ts는 만들지 않아요.

web/components.json
{
"$schema": "https://ui.shadcn.com/schema.json",
// …
"aliases": {
"components": "@/shared/ui/kit",
"utils": "cn",
"ui": "@/shared/ui/kit",
"lib": "@/shared/lib",
"hooks": "@/shared/lib"
},
// …
"registries": {
"@webcraft": "https://goraebap.xyz/r/{name}.json"
}
}

키트에서 받은 부품은 shared/ui/kit/, 앱이 직접 만든 공용 부품은 shared/ui/ 바로 아래에 둬요. 받은 부품을 고쳐도 kit/에 두고, 앱이 만든 부품을 kit/에 넣지 않아요. 그래야 키트를 다시 받을 때 비교할 파일이 폴더로 구분돼요.

  • 디렉터리web/src/shared/ui/
    • 디렉터리kit/ Webcraft 키트에서 받은 부품
      • button.tsx
      • dialog.tsx
      • 디렉터리filter/
        • …
      • 디렉터리layout/
        • 디렉터리app-shell/
          • …
        • 디렉터리page/
          • …
        • 디렉터리split-view/
          • …
        • …
      • 디렉터리page-state/
        • …
      • …
    • 디렉터리activity/ cowork가 만든 부품
      • …
    • 디렉터리mark-picker/
      • …
    • 디렉터리rich-body/
      • …
    • tone-badge.tsx
    • …

cowork는 받은 키트 부품마다 고쳤는지를 web/kit.lock.json에 적어 둬요. npm run kit:check는 레지스트리의 원본과 지금 파일을 비교해서, 그 표시가 실제와 다르면 실패해요.

명령 하는 일
npm run kit:check 원본과 비교해 결과를 보여 줘요. 고쳤는데 표시가 없거나, 표시는 고침인데 원본과 같아졌으면 실패해요
npm run kit:check -- --write 비교 결과로 kit.lock.json의 고침 표시를 고쳐 써요

부품을 고쳤으면 고친 곳에 까닭을 주석으로 달고, npm run kit:check -- --write로 고친 것으로 표시해요. 키트 원본의 새 판과 비교하려면 npx shadcn@latest add @webcraft/<이름> --diff를 써요.

cowork web/DESIGN.md는 화면 모양을 바꿀 때 이 순서로 시도해요.

  1. 키트 부품의 props와 변형(예: Button의 view, Badge의 label)
  2. 테마 토큰(src/app/theme/tailwind.css)
  3. 키트 부품의 코드(src/shared/ui/kit)

어느 단계로도 안 되면 꼼수를 쓰지 않고 사용자에게 물어요. 부품을 고르고 배치하는 규칙은 규칙 목록의 디자인 시스템에 있어요.