Flatpack UI로 구축하기
Flatpack UI는 React 19 + Tailwind CSS 4 컴포넌트 라이브러리입니다. 인터랙티브 컴포넌트는 Base UI 기본 요소(스타일이 지정되지 않은, 접근성 있음) 위에 구축되었으며, 시각적 레이어는 단일 스타일시트입니다. 디자인 규칙은 정사각형, 흑백, 여백입니다. 라이브러리의 컴포넌트를 조합하여 화면을 구축하고, 컴포넌트가 존재하는 경우 스타일이 적용된 <div>를 직접 만들지 마십시오.
사용 시기
- 사용자가 Flatpack UI 또는 이 흑백 컴포넌트 라이브러리를 언급하면서 페이지/화면/대시보드/프로토타입 구축을 요청하는 경우
- 사용자가 이 프로젝트의 확립된 시각적 언어로 UI를 원하는 경우
- 사용자가 이 라이브러리를 언급하지 않거나 프로젝트에서 이미 사용하고 있지 않은 한, 일반적인 "웹사이트를 만들어 줘" 요청에는 사용하지 마십시오.
설정 (먼저 수행)
Flatpack UI에는 스타일시트와 컴포넌트 소스만 있으면 됩니다. 대상 프로젝트에서:
- 라이브러리 루트에서 테마와 컴포넌트를 복사합니다:
src/styles/flatpack.css→ 대상src/styles/flatpack.csssrc/components/ui/*.tsx→ 대상src/components/ui/src/lib/utils.ts→ 대상src/lib/utils.ts
- 누락된 종속성을 설치합니다:
react@19 react-dom@19 @base-ui/react clsx tailwind-merge lucide-react. Tailwind CSS 4와 TypeScript가 필요합니다. 인터랙티브 컴포넌트(Button, Checkbox, Switch, RadioGroup, Select, Dialog, Sheet, DropdownMenu, Tabs, Tooltip, Popover, Progress, Avatar, Collapse, Segmented)는 Base UI 기본 요소 위에 구축됩니다. 순수 시각적 컴포넌트는 독립적입니다. 배포는 shadcn 레지스트리 형식(registry.json+public/r/)을 사용합니다. - Tailwind 후에 테마를 가져옵니다:
@import "tailwindcss"; @import "./styles/flatpack.css"; - 기존 shadcn
:root/.dark색상 변수를 제거하십시오. Flatpack은 자체 변수를 정의합니다.
프로젝트에 이미 라이브러리가 연결되어 있으면 설정을 건너뛰고 바로 컴포넌트 조합으로 진행하십시오.
가장 중요한 한 가지 규칙
색상, 크기, 간격, 모서리 반경 또는 그림자를 하드코딩하지 마십시오. 모든 시각적 결정은 flatpack.css의 CSS 변수에서 비롯되며, tokens/flatpack.tokens.json에서 생성됩니다. 인라인 스타일은 토큰만 참조합니다: var(--fp-text-*)(글꼴 크기: 12/14/16/20/28/40/64/96), var(--fp-space-*)(간격: 4…128), 그리고 색상 토큰 --fp-bg, --fp-surface, --fp-line, --fp-line-strong, --fp-muted, --fp-ink, --fp-danger, --fp-success. npm run check:design은 다른 모든 경우에 실패합니다.
세 가지 규칙:
- 역할에 따른 형태: 클릭 가능한 단일 라인 부품(Button, ChipGroup, Input, Select, Segmented, Badge, Switch, Tooltip, 페이지네이션)은
--fp-radius-control(기본적으로 알약형)을 사용합니다. 콘텐츠를 담는 표면(Card, Image, Dialog, 메뉴, Table, Toast, 코드, Textarea)은--fp-radius-surface(0)을 사용합니다. 중간 모서리 반경은 없습니다. "모두 정사각형" 프리셋(data-fp-shape="square"또는 오버라이드에서 shape: square)은 컨트롤도 0으로 만듭니다. - 필터 및 검색: 별도의 필터 칩은
<ChipGroup options={[{ value, label, count? }]} />입니다. 검색 상자는<Input variant="filled" leading={<Search size={16} />} />입니다. 보조 링크 버튼은<Button variant="outline">(잉크 테두리)입니다. - 흑백: 테마당 하나의 악센트이며, 기본 테마에서는 잉크(
--fp-accent)입니다. 파란색 링크 없음(링크는 밑줄 친 잉크), 시안 없음, 그라데이션 없음. 빨간색과 녹색은 상태 텍스트와 아이콘에만 나타나며, 채움으로는 절대 사용되지 않습니다. - 여백: 공백으로 섹션을 구분합니다(페이지 섹션 사이에 최소 96px). 1px 테두리 하나. 카드에는 두 번째 테두리 상자가 절대 포함되지 않습니다. 오버레이 계층(Dialog, Popover, Select, Dropdown)만 그림자를 가집니다.
유형: 본문 16px, 1.6줄 간격, 제목 1.1줄 간격, 굵기 400/500/600. 모노스페이스는 숫자, ID 및 코드(.fp-num)에만 사용되며, 섹션 제목에는 절대 사용되지 않습니다. 대문자 레이블 없음. 아이콘은 16px의 lucide입니다. 상호 작용은 색상만 변경하고 위치는 변경하지 않습니다. 반복 애니메이션 없음.
반대 테마로 블록을 렌더링하려면(예: 기본 버튼이 계속 보여야 하는 잉크 배너) className="fp-invert"를 추가하십시오.
작은 회색 캡션에는 .fp-label 클래스를 사용하고, 제목 위의 일반 회색 줄에는 <Kicker>를 사용하십시오.
컴포넌트 인벤토리
모든 임포트는 @/components/ui/<name>에서 가져옵니다(대상 프로젝트에 맞게 별칭 조정).
| 필요 | 컴포넌트 |
|---|---|
| 액션 | Button, ButtonGroup / ToggleGroup / Toggle (toggle-group), Toolbar + ToolbarButton/ToolbarToggle/ToolbarGroup/ToolbarSeparator/ToolbarSpacer |
| 컨테이너 | Card + CardHeader/CardTitle/CardDescription/CardContent/CardFooter |
| 레이블 / 상태 | Badge, StatusDot (8px 정사각형: default / success / danger / idle), Kbd / KbdGroup, Kicker (primitives에서) |
| 텍스트 입력 | Input, Label, Textarea, NumberInput, Field / Fieldset / FieldControl (레이블 + 도움말 + 오류) |
| 선택 | Select, Combobox (타입어헤드), MultiSelect (칩), Checkbox, RadioGroup, Switch, Segmented, Slider (단일 또는 범위) |
| 날짜 / 파일 | Calendar, DatePicker, DateRangePicker, FileInput (파일만 수집) |
| 오버레이 | Dialog, AlertDialog (확인; 파괴적 작업은 danger), Sheet, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, CommandPalette (⌘K), Lightbox / LightboxGallery |
| 피드백 | Alert, Toast (<Toaster />를 한 번 마운트, toast({ title, type }) 호출), Spinner, Skeleton + SkeletonText, Progress, Steps |
| 내비게이션 | Tabs, Breadcrumb, Pagination, Sidebar + SidebarSection/SidebarItem |
| 데이터 표시 | Table (+ 파트), DescriptionList, Tree, Image, Carousel, Avatar, AvatarGroup, Statistic, Timestamp, Collapse, Empty, CodeBlock / Code |
| 레이아웃 / 유틸리티 | Divider, Separator (primitives에서), ScrollArea, Masonry (폭포수), VisuallyHidden, BorderBeam (선택적 장식 테두리선; 반복 애니메이션 규칙 때문에 기본적으로 사용되지 않음) |
총 63개의 컴포넌트. 테이블에 없는 요구사항이 있으면 새 소스를 추가하기 전에 이 컴포넌트들로 구성하십시오. 의도적으로 제공되지 않음: 리치 텍스트 에디터, Markdown 렌더러, Cascader, Transfer. AI 채팅 화면의 경우 src/blocks/BlockScreens.tsx의 assistant 블록을 복사하십시오.
밀도, 글꼴 및 선택적 따뜻한 회색은 토큰 수준입니다. 요소에 data-fp-density="compact"(또는 data-fp-font, data-fp-heading, data-fp-gray)를 설정하거나, 프리셋 코드를 tokens/overrides.json에 작성하고 npm run build:tokens를 실행하십시오. 테마(flatpack, catalog, sage)는 팔레트, 악센트, 표면 반경 및 글꼴 스택을 하나의 단위로 교체합니다. 요소에 data-fp-theme="sage"를 설정하십시오. 채움 및 선택된 상태는 --fp-accent / --fp-on-accent를 사용하고, 텍스트는 --fp-ink를 사용합니다. 테마 외부에 일회성 반경, 악센트 색상, 그림자 또는 블러를 절대 추가하지 마십시오.
복사-붙여넣기 패턴
다음은 정확한 props입니다. 그대로 사용하고 props 이름을 추측하지 마십시오.
import { Button } from '@/components/ui/button'
import { Input, Label } from '@/components/ui/input'
import { Badge } from '@/components/ui/badge'
import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card'
import { Kicker, Separator } from '@/components/ui/primitives'
// 버튼 — variant: default | secondary | outline | ghost | link; size: default | sm | lg | icon
<Button>기본</Button>
<Button variant="outline" size="sm">보조</Button>
<Button size="icon" aria-label="검색"><Search size={16}/></Button>
// 배지 — variant: default | outline | success | danger
<Badge>신규</Badge><Badge variant="success">재고 있음</Badge>
// 폼
<Label>이름</Label>
<Input placeholder="여기에 입력" />
// 카드
<Card>
<CardHeader><CardTitle>제목</CardTitle><CardDescription>부제목</CardDescription></CardHeader>
<CardContent>...</CardContent>
<CardFooter><Button size="sm">액션</Button></CardFooter>
</Card>
<Kicker>섹션 눈썹</Kicker>
<Separator />
import { Select } from '@/components/ui/select'
import { Checkbox } from '@/components/ui/checkbox'
import { RadioGroup } from '@/components/ui/radio'
import { Switch } from '@/components/ui/switch'
import { Segmented } from '@/components/ui/segmented'
<Select
options={[{ value: 'a', label: 'A' }, { value: 'b', label: 'B' }]}
defaultValue="a"
onValueChange={(v) => {}}
/>
<Checkbox defaultChecked label="활성화" />
<Checkbox indeterminate label="부분" />
<Checkbox disabled defaultChecked label="잠김" />
<RadioGroup defaultValue="a" options={[
{ value: 'a', label: '옵션 A' },
{ value: 'b', label: '옵션 B', disabled: true },
]} />
<Switch defaultChecked label="알림" />
<Segmented defaultValue="day" options={[
{ value: 'day', label: '일' },
{ value: 'week', label: '주' },
]} />
import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose } from '@/components/ui/dialog'
import { Sheet, SheetTrigger, SheetContent } from '@/components/ui/sheet'
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs'
import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbCurrent, BreadcrumbSeparator } from '@/components/ui/breadcrumb'
import { Pagination } from '@/components/ui/pagination'
import { Alert } from '@/components/ui/alert'
import { Progress } from '@/components/ui/progress'
import { Steps } from '@/components/ui/steps'
import { Empty } from '@/components/ui/empty'
import { Statistic } from '@/components/ui/statistic'
import { Collapse } from '@/components/ui/collapse'
import { Divider } from '@/components/ui/divider'
<Dialog>
<DialogTrigger>열기</DialogTrigger>
<DialogContent>
<DialogHeader><DialogTitle>제목</DialogTitle><DialogDescription>세부사항</DialogDescription></DialogHeader>
<DialogFooter><DialogClose>닫기</DialogClose></DialogFooter>
</DialogContent>
</Dialog>
<Sheet>
<SheetTrigger>장바구니 (2)</SheetTrigger>
<SheetContent title="장바구니">...</SheetContent>
</Sheet>
<Tabs defaultValue="a">
<TabsList><TabsTrigger value="a">A</TabsTrigger><TabsTrigger value="b">B</TabsTrigger></TabsList>
<TabsContent value="a">...</TabsContent>
<TabsContent value="b">...</TabsContent>
</Tabs>
<Breadcrumb>
<BreadcrumbItem><BreadcrumbLink>홈</BreadcrumbLink></BreadcrumbItem>
<BreadcrumbSeparator />
<BreadcrumbItem><BreadcrumbCurrent>현재</BreadcrumbCurrent></BreadcrumbItem>
</Breadcrumb>
<Pagination total={96} pageSize={10} defaultValue={1} onValueChange={(p) => {}} />
<Alert variant="success" title="저장됨">변경 사항이 적용되었습니다.</Alert>
<Progress value={64} label="진행률" showValue />
<Steps current={1} steps={[{ title: '시작' }, { title: '설정' }, { title: '완료' }]} />
<Empty title="항목 없음" action={<Button size="sm">생성</Button>} />
<Statistic label="주문" value="1,472" trend={{ value: 12.4 }} />
<Collapse items={[{ key: 'a', title: '질문', children: '답변' }]} />
<Divider label="또는" />
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell, TableCaption } from '@/components/ui/table'
import { Image } from '@/components/ui/image'
import { Avatar } from '@/components/ui/avatar'
import { Skeleton, SkeletonText } from '@/components/ui/skeleton'
<Table>
<TableCaption>항목</TableCaption>
<TableHeader><TableRow><TableHead>이름</TableHead><TableHead>수량</TableHead></TableRow></TableHeader>
<TableBody><TableRow><TableCell>위젯</TableCell><TableCell>1</TableCell></TableRow></TableBody>
</Table>
<Image ratio="4:3" alt="미리보기" src="/x.jpg" /> {/* 비율: square | 4:3 | 16:9 | 3:4 */}
<Avatar size="md" name="Alice" />
<Skeleton circle width={40} height={40} />
<SkeletonText lines={3} />
모든 컴포넌트의 전체 API 테이블은 라이브러리의 src/site/componentDocs.ts와 #/docs/components/:id의 렌더링된 문서에 있습니다. 위에 표시되지 않은 prop이 필요하면 해당 파일을 읽으십시오.
테마
테마는 기본적으로 시스템을 따릅니다. <html>에 data-theme을 설정하여 전환합니다(사이트는 선택 사항을 fp-theme으로 localStorage에 저장하고 첫 페인트 전에 index.html에 설정합니다):
document.documentElement.setAttribute('data-theme', 'dark') // 또는 'light'
컴포넌트에 테마별 CSS를 작성하지 마십시오. 전체적으로 모양을 변경해야 하는 경우 tokens/flatpack.tokens.json을 편집하고 npm run build:tokens를 실행하십시오.
안티 패턴 (하지 말아야 할 것)
- 새로운 색상의 기본 액션 발명(예: 파란색 또는 녹색 CTA). 기본은 검정/거의 흰색만 가능.
- 오버레이 계층 외부의 그림자, 그라데이션, 유리 효과, 색상 채움 또는 카드 내부의 두 번째 테두리 추가.
- 둥근 모서리, 알약 버튼, 대문자 모노스페이스 섹션 레이블.
var(--fp-*)대신 JSX에 16진수 값 하드코딩.Button/Card/Input을 스타일이 지정된<div>로 재구현 — 항상 컴포넌트를 임포트.- props 추측(
<Button color="red">,<Select items={...}>). 이 스킬의 정확한 props를 사용. - 기본 라이브러리에 전자상거래 관련 컴포넌트(가격 태그, 제품 타일) 추가. 시나리오별 UI는 Blocks에 속하며 컴포넌트 세트에 속하지 않음.
작업 흐름
- 대상 프로젝트에 Flatpack이 연결되어 있는지 확인하고(위 설정), 그렇지 않으면 연결합니다.
- props가 확실하지 않은 컴포넌트에 대해
src/site/componentDocs.ts를 읽습니다. 이것이 진리의 원천입니다. - 인벤토리에서 화면을 구성합니다. 레이아웃/간격에만 Tailwind를 사용합니다.
- 세 가지 규칙에 대해 결과를 확인하고
npm run check:design을 실행합니다. 도입한 하드코딩된 값, 그림자 또는 장식용 악센트를 제거합니다. - 빌드가 되는지 확인합니다. 인벤토리에 없는 컴포넌트를 추가한 경우 명시적으로 말하고 기본 세트에 추가하지 말고 시나리오 로컬로 유지합니다.