docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,292 @@
|
||||
---
|
||||
id: wiki-2026-0508-shadcn-ui
|
||||
title: shadcn/ui
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [shadcn, shadcn-ui, shadcn/ui, ui.shadcn.com]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.95
|
||||
verification_status: applied
|
||||
tags: [react, ui, components, tailwind, radix, design-system]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: TypeScript
|
||||
framework: React 19/Next.js 15/Tailwind 4/Radix UI
|
||||
---
|
||||
|
||||
# shadcn/ui
|
||||
|
||||
## 매 한 줄
|
||||
> **"매 install package 가 아니라 매 copy-paste component collection — 매 source code 매 own, 매 customize 자유"**. shadcn (Shaad Heuvel) 매 2023 출시, 매 React + Tailwind + Radix UI 위에 매 well-designed accessible primitive 를 매 CLI 로 가져다 쓰는 anti-library pattern. 2026 현재 매 React app 의 default UI starting kit — Vercel templates, AI SDK examples, Next.js docs 매 default.
|
||||
|
||||
## 매 핵심
|
||||
|
||||
### 매 differentiator
|
||||
- **Not a dependency**: 매 `npm install shadcn/ui` 가 아님. 매 `npx shadcn add button` → component code 매 your repo 에 copy.
|
||||
- **Owned source**: 매 매 component file 매 직접 modify. 매 lock-in 없음.
|
||||
- **Built on Radix UI**: accessibility primitives (focus management, ARIA, keyboard) 매 무료.
|
||||
- **Tailwind**: utility-first styling, theme via CSS variables.
|
||||
- **Composable**: 매 small primitive (Button, Input, Dialog) 매 large block 으로 조합.
|
||||
|
||||
### 매 stack
|
||||
- **Foundation**: Radix UI Primitives (unstyled accessible components).
|
||||
- **Styling**: Tailwind CSS v4 (2024+ JIT engine).
|
||||
- **Variants**: `class-variance-authority` (cva) — type-safe variant API.
|
||||
- **Class merge**: `tailwind-merge` + `clsx` (`cn()` helper).
|
||||
- **Forms**: `react-hook-form` + `zod` (resolver).
|
||||
- **Charts**: Recharts wrapper (shadcn/charts).
|
||||
- **Icons**: lucide-react.
|
||||
|
||||
### 매 CLI workflow
|
||||
```bash
|
||||
npx shadcn@latest init # one-time setup, creates components.json
|
||||
npx shadcn@latest add button input dialog
|
||||
npx shadcn@latest add https://ui.shadcn.com/r/styles/new-york/login-01.json
|
||||
```
|
||||
|
||||
### 매 응용
|
||||
1. SaaS dashboard / admin panel.
|
||||
2. AI chat UI (shadcn/ui + Vercel AI SDK).
|
||||
3. Marketing site sections.
|
||||
4. Internal tools (Retool 대체).
|
||||
5. Design system foundation (매 fork 후 brand 적용).
|
||||
|
||||
## 💻 패턴
|
||||
|
||||
### 1. Initial setup (Next.js 15)
|
||||
```bash
|
||||
pnpm create next-app@latest my-app --ts --tailwind --app
|
||||
cd my-app
|
||||
pnpm dlx shadcn@latest init
|
||||
# choose: New York style, Slate base, CSS variables
|
||||
pnpm dlx shadcn@latest add button card input form dialog dropdown-menu
|
||||
```
|
||||
|
||||
### 2. cn() utility (필수 helper)
|
||||
```typescript
|
||||
// lib/utils.ts
|
||||
import { clsx, type ClassValue } from "clsx";
|
||||
import { twMerge } from "tailwind-merge";
|
||||
|
||||
export function cn(...inputs: ClassValue[]) {
|
||||
return twMerge(clsx(inputs));
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Button with cva variants
|
||||
```tsx
|
||||
import * as React from "react";
|
||||
import { Slot } from "@radix-ui/react-slot";
|
||||
import { cva, type VariantProps } from "class-variance-authority";
|
||||
import { cn } from "@/lib/utils";
|
||||
|
||||
const buttonVariants = cva(
|
||||
"inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "bg-primary text-primary-foreground hover:bg-primary/90",
|
||||
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
|
||||
outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
|
||||
ghost: "hover:bg-accent hover:text-accent-foreground",
|
||||
},
|
||||
size: {
|
||||
default: "h-10 px-4 py-2",
|
||||
sm: "h-9 rounded-md px-3",
|
||||
lg: "h-11 rounded-md px-8",
|
||||
icon: "h-10 w-10",
|
||||
},
|
||||
},
|
||||
defaultVariants: { variant: "default", size: "default" },
|
||||
}
|
||||
);
|
||||
|
||||
export interface ButtonProps
|
||||
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
|
||||
VariantProps<typeof buttonVariants> {
|
||||
asChild?: boolean;
|
||||
}
|
||||
|
||||
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
|
||||
({ className, variant, size, asChild = false, ...props }, ref) => {
|
||||
const Comp = asChild ? Slot : "button";
|
||||
return <Comp className={cn(buttonVariants({ variant, size, className }))} ref={ref} {...props} />;
|
||||
}
|
||||
);
|
||||
Button.displayName = "Button";
|
||||
```
|
||||
|
||||
### 4. Form with react-hook-form + zod
|
||||
```tsx
|
||||
"use client";
|
||||
import { zodResolver } from "@hookform/resolvers/zod";
|
||||
import { useForm } from "react-hook-form";
|
||||
import { z } from "zod";
|
||||
import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form";
|
||||
import { Input } from "@/components/ui/input";
|
||||
import { Button } from "@/components/ui/button";
|
||||
|
||||
const schema = z.object({
|
||||
email: z.string().email(),
|
||||
password: z.string().min(8),
|
||||
});
|
||||
|
||||
export function LoginForm() {
|
||||
const form = useForm<z.infer<typeof schema>>({
|
||||
resolver: zodResolver(schema),
|
||||
defaultValues: { email: "", password: "" },
|
||||
});
|
||||
|
||||
function onSubmit(values: z.infer<typeof schema>) {
|
||||
// server action
|
||||
}
|
||||
|
||||
return (
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
|
||||
<FormField control={form.control} name="email" render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormLabel>Email</FormLabel>
|
||||
<FormControl><Input type="email" {...field} /></FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)} />
|
||||
<FormField control={form.control} name="password" render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormLabel>Password</FormLabel>
|
||||
<FormControl><Input type="password" {...field} /></FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)} />
|
||||
<Button type="submit" className="w-full">Sign in</Button>
|
||||
</form>
|
||||
</Form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Theming (CSS variables)
|
||||
```css
|
||||
/* app/globals.css */
|
||||
@import "tailwindcss";
|
||||
|
||||
@layer base {
|
||||
:root {
|
||||
--background: 0 0% 100%;
|
||||
--foreground: 222.2 84% 4.9%;
|
||||
--primary: 221.2 83.2% 53.3%;
|
||||
--primary-foreground: 210 40% 98%;
|
||||
--radius: 0.5rem;
|
||||
}
|
||||
.dark {
|
||||
--background: 222.2 84% 4.9%;
|
||||
--foreground: 210 40% 98%;
|
||||
--primary: 217.2 91.2% 59.8%;
|
||||
--primary-foreground: 222.2 47.4% 11.2%;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Data table (TanStack Table integration)
|
||||
```tsx
|
||||
import { ColumnDef, flexRender, getCoreRowModel, useReactTable } from "@tanstack/react-table";
|
||||
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
|
||||
|
||||
export function DataTable<T, V>({ columns, data }: { columns: ColumnDef<T, V>[]; data: T[] }) {
|
||||
const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
|
||||
return (
|
||||
<Table>
|
||||
<TableHeader>
|
||||
{table.getHeaderGroups().map((hg) => (
|
||||
<TableRow key={hg.id}>
|
||||
{hg.headers.map((h) => (
|
||||
<TableHead key={h.id}>{flexRender(h.column.columnDef.header, h.getContext())}</TableHead>
|
||||
))}
|
||||
</TableRow>
|
||||
))}
|
||||
</TableHeader>
|
||||
<TableBody>
|
||||
{table.getRowModel().rows.map((row) => (
|
||||
<TableRow key={row.id}>
|
||||
{row.getVisibleCells().map((c) => (
|
||||
<TableCell key={c.id}>{flexRender(c.column.columnDef.cell, c.getContext())}</TableCell>
|
||||
))}
|
||||
</TableRow>
|
||||
))}
|
||||
</TableBody>
|
||||
</Table>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 7. AI chat UI (Vercel AI SDK + shadcn)
|
||||
```tsx
|
||||
"use client";
|
||||
import { useChat } from "@ai-sdk/react";
|
||||
import { Card } from "@/components/ui/card";
|
||||
import { Input } from "@/components/ui/input";
|
||||
import { Button } from "@/components/ui/button";
|
||||
|
||||
export function Chat() {
|
||||
const { messages, input, handleInputChange, handleSubmit } = useChat();
|
||||
return (
|
||||
<div className="flex flex-col h-[600px] gap-2">
|
||||
<div className="flex-1 overflow-y-auto space-y-2 p-4">
|
||||
{messages.map((m) => (
|
||||
<Card key={m.id} className={cn("p-3", m.role === "user" && "bg-primary/10")}>
|
||||
<strong className="text-xs uppercase">{m.role}</strong>
|
||||
<p className="whitespace-pre-wrap">{m.content}</p>
|
||||
</Card>
|
||||
))}
|
||||
</div>
|
||||
<form onSubmit={handleSubmit} className="flex gap-2 p-2">
|
||||
<Input value={input} onChange={handleInputChange} placeholder="Say something..." />
|
||||
<Button type="submit">Send</Button>
|
||||
</form>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Approach |
|
||||
|---|---|
|
||||
| 빠른 SaaS prototype | shadcn/ui + Next.js + Vercel — 매 default 선택 |
|
||||
| 강한 brand identity | shadcn/ui fork → CSS variables 로 brand 적용 |
|
||||
| 매 component lock-in 싫음 | shadcn/ui (own source) |
|
||||
| 매 dependency 관리 single 파일 선호 | Material UI / Mantine (전통 lib) |
|
||||
| 매 enterprise tabular admin | shadcn/ui + TanStack Table + Recharts |
|
||||
| 매 native mobile (RN) | NativeBase / Tamagui / shadcn-react-native (community) |
|
||||
|
||||
**기본값**: Next.js 15 + shadcn/ui (New York style) + Tailwind 4 + lucide-react + react-hook-form + zod.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[React]] · [[Design Systems]]
|
||||
- 변형: [[Radix UI]]
|
||||
- 응용: [[Next.js]]
|
||||
- Adjacent: [[CSS_Architecture_and_Styling|Tailwind CSS]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: 매 modern React app 매 빠르게 launch — 매 LLM (Claude/GPT) 매 shadcn 패턴 매 well-trained, 매 generation quality 매 높음.
|
||||
**언제 X**: 매 design-from-scratch creative work — 매 too opinionated. 매 매 non-React framework (Vue/Svelte) — 매 community port 있지만 매 first-class 아님.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **shadcn 을 npm package 처럼 취급**: 매 update CLI 매 `npx shadcn diff` 로 검토 후 매 manually merge.
|
||||
- **cn() 무시**: 매 className concat 매 직접 — 매 conflict 매 발생.
|
||||
- **Tailwind v3 와 mix**: 매 v4 와 v3 매 incompatible API. 매 lock 명시.
|
||||
- **Radix unstyle 무시 직접 div**: 매 accessibility 손실.
|
||||
- **모든 Button 을 custom variant 로**: 매 base variant 4-5개 유지, 매 outlier 만 inline className.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (ui.shadcn.com docs, Next.js learn, Vercel templates 2025-2026).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — full setup + cva + form + AI chat patterns (2026 stack) |
|
||||
Reference in New Issue
Block a user