img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(4)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-container *:[img:last-child]:rounded-b-container", className )} {...props} /> ) } function CardHeader({ className, ...props }: React.ComponentProps<"div">) { return (

) } function CardTitle({ className, ...props }: React.ComponentProps<"div">) { return (

) } function CardDescription({ className, ...props }: React.ComponentProps<"div">) { return (

) } function CardAction({ className, ...props }: React.ComponentProps<"div">) { return (

) } function CardContent({ className, ...props }: React.ComponentProps<"div">) { return (

) } function CardFooter({ className, ...props }: React.ComponentProps<"div">) { return (

) } export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent, } ``` ## Source: components/ui/dialog.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Dialog as DialogPrimitive } from "radix-ui" import { Button } from "@/components/ui/button" import { X } from "lucide-react" function Dialog({ ...props }: React.ComponentProps) { return } function DialogTrigger({ ...props }: React.ComponentProps) { return } function DialogPortal({ ...props }: React.ComponentProps) { return } function DialogClose({ ...props }: React.ComponentProps) { return } function DialogOverlay({ className, ...props }: React.ComponentProps) { return ( ) } function DialogContent({ className, children, showCloseButton = true, ...props }: React.ComponentProps & { showCloseButton?: boolean }) { return ( {children} {showCloseButton && ( )} ) } function DialogHeader({ className, ...props }: React.ComponentProps<"div">) { return (

) } function DialogFooter({ className, showCloseButton = false, children, ...props }: React.ComponentProps<"div"> & { showCloseButton?: boolean }) { return (

{children} {showCloseButton && ( )}

) } function DialogTitle({ className, ...props }: React.ComponentProps) { return ( ) } function DialogDescription({ className, ...props }: React.ComponentProps) { return ( ) } export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, } ``` ## Source: components/ui/alert-dialog.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { AlertDialog as AlertDialogPrimitive } from "radix-ui" import { Button } from "@/components/ui/button" function AlertDialog({ ...props }: React.ComponentProps) { return } function AlertDialogTrigger({ ...props }: React.ComponentProps) { return ( ) } function AlertDialogPortal({ ...props }: React.ComponentProps) { return ( ) } function AlertDialogOverlay({ className, ...props }: React.ComponentProps) { return ( ) } function AlertDialogContent({ className, size = "default", ...props }: React.ComponentProps & { size?: "default" | "sm" }) { return ( ) } function AlertDialogHeader({ className, ...props }: React.ComponentProps<"div">) { return (

) } function AlertDialogFooter({ className, ...props }: React.ComponentProps<"div">) { return (

) } function AlertDialogMedia({ className, ...props }: React.ComponentProps<"div">) { return (

) } function AlertDialogTitle({ className, ...props }: React.ComponentProps) { return ( ) } function AlertDialogDescription({ className, ...props }: React.ComponentProps) { return ( ) } function AlertDialogAction({ className, variant = "default", size = "default", ...props }: React.ComponentProps & Pick, "variant" | "size">) { return ( ) } function AlertDialogCancel({ className, variant = "outline", size = "default", ...props }: React.ComponentProps & Pick, "variant" | "size">) { return ( ) } export { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, } ``` ## Source: components/ui/tabs.tsx ```tsx "use client" import * as React from "react" import { cva, type VariantProps } from "class-variance-authority" import { cn } from "cn" import { Tabs as TabsPrimitive } from "radix-ui" function Tabs({ className, orientation = "horizontal", ...props }: React.ComponentProps) { return ( ) } const tabsListVariants = cva( "group/tabs-list items-center justify-center rounded-full [--nested-radius:calc(var(--radius)*0.2)] [--nested-gap:3px] p-1 text-muted-foreground group-data-horizontal/tabs:h-10 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none", { variants: { variant: { default: "grid w-68 max-w-full grid-cols-3 bg-tab-muted [--nested-gap:6px] p-1.5 group-data-horizontal/tabs:h-12", line: "inline-flex w-fit gap-1 bg-transparent", pills: "inline-flex w-fit max-w-full flex-wrap gap-2 bg-transparent p-0 group-data-horizontal/tabs:h-auto", }, }, defaultVariants: { variant: "default", }, } ) function TabsList({ className, variant = "default", children, ...props }: React.ComponentProps & VariantProps) { const listRef = React.useRef(null) const [indicator, setIndicator] = React.useState<{ left: number top: number width: number height: number } | null>(null) React.useLayoutEffect(() => { const list = listRef.current if (!list || variant !== "default") return const updateIndicator = () => { const active = list.querySelector( '[data-slot="tabs-trigger"][data-state="active"]' ) if (!active) return const listRect = list.getBoundingClientRect() const activeRect = active.getBoundingClientRect() setIndicator({ left: activeRect.left - listRect.left, top: activeRect.top - listRect.top, width: activeRect.width, height: activeRect.height, }) } updateIndicator() const observer = new MutationObserver(updateIndicator) observer.observe(list, { subtree: true, attributes: true, attributeFilter: ["data-state"] }) const resizeObserver = new ResizeObserver(updateIndicator) resizeObserver.observe(list) return () => { observer.disconnect() resizeObserver.disconnect() } }, [variant]) return ( {variant === "default" && indicator && ( ) } function TabsTrigger({ className, ...props }: React.ComponentProps) { return ( ) } function TabsContent({ className, ...props }: React.ComponentProps) { return ( ) } export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants } ``` ## Source: components/ui/input.tsx ```tsx import * as React from "react" import { cn } from "cn" function Input({ className, type, ...props }: React.ComponentProps<"input">) { return ( ) } export { Input } ``` ## Source: components/ui/select.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Select as SelectPrimitive } from "radix-ui" import { ChevronsUpDown, Check, ChevronUp, ChevronDown } from "lucide-react" function Select({ ...props }: React.ComponentProps) { return } function SelectGroup({ className, ...props }: React.ComponentProps) { return ( ) } function SelectValue({ ...props }: React.ComponentProps) { return } function SelectTrigger({ className, size = "default", children, ...props }: React.ComponentProps & { size?: "sm" | "default" }) { return ( {children} ) } function SelectContent({ className, children, position = "popper", align = "start", side = "bottom", sideOffset = 4, ...props }: React.ComponentProps) { return ( {children} ) } function SelectLabel({ className, ...props }: React.ComponentProps) { return ( ) } function SelectItem({ className, children, ...props }: React.ComponentProps) { return ( {children} ) } function SelectSeparator({ className, ...props }: React.ComponentProps) { return ( ) } function SelectScrollUpButton({ className, ...props }: React.ComponentProps) { return ( ) } function SelectScrollDownButton({ className, ...props }: React.ComponentProps) { return ( ) } export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, } ``` ## Source: components/ui/slider.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Slider as SliderPrimitive } from "radix-ui" function Slider({ className, defaultValue, value, min = 0, max = 100, ...props }: React.ComponentProps) { const _values = React.useMemo( () => Array.isArray(value) ? value : Array.isArray(defaultValue) ? defaultValue : [min, max], [value, defaultValue, min, max] ) return ( {Array.from({ length: _values.length }, (_, index) => ( ))} ) } export { Slider } ``` ## Source: components/ui/switch.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Switch as SwitchPrimitive } from "radix-ui" function Switch({ className, size = "default", ...props }: React.ComponentProps & { size?: "sm" | "default" }) { return ( ) } export { Switch } ``` ## Source: components/ui/checkbox.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Checkbox as CheckboxPrimitive } from "radix-ui" import { CheckIcon } from "lucide-react" function Checkbox({ className, ...props }: React.ComponentProps) { return ( ) } export { Checkbox } ``` ## Source: components/ui/radio-group.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { RadioGroup as RadioGroupPrimitive } from "radix-ui" function RadioGroup({ className, ...props }: React.ComponentProps) { return ( ) } function RadioGroupItem({ className, ...props }: React.ComponentProps) { return ( ) } export { RadioGroup, RadioGroupItem } ``` ## Source: components/ui/sheet.tsx ```tsx "use client" import * as React from "react" import { cn } from "cn" import { Dialog as SheetPrimitive } from "radix-ui" import { Button } from "@/components/ui/button" import { X } from "lucide-react" function Sheet({ ...props }: React.ComponentProps) { return } function SheetTrigger({ ...props }: React.ComponentProps) { return } function SheetClose({ ...props }: React.ComponentProps) { return } function SheetPortal({ ...props }: React.ComponentProps) { return } function SheetOverlay({ className, ...props }: React.ComponentProps) { return ( ) } function SheetContent({ className, children, side = "right", showCloseButton = true, ...props }: React.ComponentProps & { side?: "top" | "right" | "bottom" | "left" showCloseButton?: boolean }) { return ( {children} {showCloseButton && ( )} ) } function SheetHeader({ className, ...props }: React.ComponentProps<"div">) { return (

) } function SheetFooter({ className, ...props }: React.ComponentProps<"div">) { return (

) } function SheetTitle({ className, ...props }: React.ComponentProps) { return ( ) } function SheetDescription({ className, ...props }: React.ComponentProps) { return ( ) } export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, } ``` ## Source: components/ui/pagination.tsx ```tsx import * as React from "react" import { cn } from "cn" import { Button } from "@/components/ui/button" import { ArrowLeft, ArrowRight, Ellipsis } from "lucide-react" function Pagination({ className, ...props }: React.ComponentProps<"nav">) { return (

) } function PaginationContent({ className, ...props }: React.ComponentProps<"ul">) { return (

} type PaginationLinkProps = { isActive?: boolean } & Pick, "size"> & React.ComponentProps<"a"> function PaginationLink({ className, isActive, size = "icon", ...props }: PaginationLinkProps) { return ( ) } function PaginationPrevious({ className, text = "Previous", ...props }: React.ComponentProps & { text?: string }) { return ( {text} ) } function PaginationNext({ className, text = "Next", ...props }: React.ComponentProps & { text?: string }) { return ( {text} ) } function PaginationEllipsis({ className, ...props }: React.ComponentProps<"span">) { return ( More pages ) } export { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, } ``` ## Source: components/ui/dot-pagination.tsx ```tsx "use client" import type { ComponentProps } from "react" import { Button } from "@/components/ui/button" import { Pagination, PaginationContent, PaginationItem } from "@/components/ui/pagination" type DotPaginationProps = Omit, "children"> & { pageCount: number page: number onPageChange: (page: number) => void getPageLabel?: (page: number) => string } function DotPagination({ pageCount, page, onPageChange, getPageLabel = (value) => `Image ${value} of ${pageCount}`, ...props }: DotPaginationProps) { const count = Math.max(0, Math.floor(pageCount)) const currentPage = Math.min(count, Math.max(1, page)) const visibleCount = Math.min(6, count) const dotStep = 12 const windowStart = Math.min(Math.max(0, currentPage - 1 - Math.floor((visibleCount - 1) / 2)), count - visibleCount) return (

{Array.from({ length: count }, (_, index) => { const value = index + 1 const active = value === currentPage const visible = index >= windowStart && index < windowStart + visibleCount const dotSize = count <= 5 ? 8 : Math.max(2, 8 - Math.abs(value - currentPage) * 2) return ( ) })}

) } function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">) { return (

) } function ButtonPreview({ compact = false }: { compact?: boolean } = {}) { const [selected, setSelected] = useState("") const buttonClass = `${compact ? "h-10" : "h-12"} w-full min-w-0 px-4 text-base` return (

{([ { variant: "default", label: "Primary" }, { variant: "secondary", label: "Secondary" }, { variant: "tertiary", label: "Tertiary" }, { variant: "outline", label: "Outline" }, { variant: "link", label: "Link" }, ] as const).map(({ variant, label }) => ( ))}

) } function CardPreview({ compact = false }: { compact?: boolean } = {}) { const { locale } = useLocale() return (

{locale === "ko" ? "새로운 소식" : "What's new"} {locale === "ko" ? "이번 주 업데이트를 확인해 보세요." : "Catch up on this week's updates."}

) } function TabsPreview() { const { t } = useLocale() return (

{t("자동차")} {t("버스")} {t("지하철")}

) } function DialogPreview() { const { t } = useLocale() const [open, setOpen] = useState(false) const [name, setName] = useState("Compass") const [draft, setDraft] = useState(name) return (

{t("현재 이름")}: {name}

) } function AlertDialogPreview() { const { locale } = useLocale() const [open, setOpen] = useState(false) const [decision, setDecision] = useState<"allowed" | "necessary" | null>(null) function choose(value: "allowed" | "necessary") { setDecision(value) setOpen(false) } return (

{open && createPortal(

{locale === "ko" ? "쿠키를 허용할까요?" : "Allow cookies?"}

{locale === "ko" ? "필수 쿠키는 서비스 운영에 사용해요. 선택 쿠키를 허용하면 이용 경험을 개선하는 데 도움이 돼요." : "Essential cookies keep the service running. Optional cookies help us improve your experience."}

, document.body )}

{decision && (locale === "ko" ? decision === "allowed" ? "모든 쿠키를 허용했어요." : "필수 쿠키만 허용했어요." : decision === "allowed" ? "All cookies allowed." : "Only essential cookies allowed.")}

) } export { ButtonPreview, GalleryButtonPreview, CardPreview, TabsPreview, DialogPreview, AlertDialogPreview } ``` ## Source: components/component-preview.tsx ```tsx "use client" import { DocPreviewActions } from "@/components/doc-preview-actions" import { LayoutThumbnail } from "@/components/layout-thumbnail" import { ImageCardPreview, ListLayoutPreview, TableLayoutPreview, GridLayoutPreview, FluidLayoutPreview, WrapLayoutPreview, InlineExpansionPreview, PushPanelPreview, NavigationBarPreview, ToolbarPreview, PopoverLayoutPreview, SidePanelPreview, ToastLayoutPreview } from "@/components/layout-previews" import { ButtonPreview, GalleryButtonPreview, CardPreview, TabsPreview, DialogPreview, AlertDialogPreview, } from "@/components/component-previews" import { InputPreview, SelectPreview, SliderPreview, SwitchPreview, CheckboxPreview, RadioButtonPreview, BottomSheetPreview, PaginationPreview, DotPaginationPreview, ChipPreview, BadgePreview, GalleryBadgePreview, TagPreview, AvatarPreview, ProgressPreview, } from "@/components/catalog-previews" import { PasswordInputPreview, PhoneInputPreview, CodeInputPreview, NumberStepperPreview, DatePickerPreview, TimePickerPreview, FileDropPreview, VoiceRecorderPreview, SignatureInputPreview, TreeViewPreview, AccordionPreview, CarouselPreview, ClassicTabsPreview, BackToTopPreview, BreadcrumbPreview, SearchPreview, AvatarGroupPreview, GoalRingPreview, ChallengePreview, ContributionPreview, VideoPlaybackPreview, ProgressBarPreview, StepProgressPreview, SkeletonPreview, ImageGalleryPreview, CalendarPreview, MapPreview, TablePreview, TimelinePreview, TableOfContentsPreview, } from "@/components/extended-previews" const previews = { "password-input": PasswordInputPreview, "phone-input": PhoneInputPreview, "code-input": CodeInputPreview, "number-stepper": NumberStepperPreview, "date-picker": DatePickerPreview, "time-picker": TimePickerPreview, "file-drop": FileDropPreview, "voice-recorder": VoiceRecorderPreview, "signature-input": SignatureInputPreview, "tree-view": TreeViewPreview, accordion: AccordionPreview, carousel: CarouselPreview, "video-playback": VideoPlaybackPreview, "image-gallery": ImageGalleryPreview, calendar: CalendarPreview, map: MapPreview, timeline: TimelinePreview, "table-of-contents": TableOfContentsPreview, "classic-tabs": ClassicTabsPreview, "back-to-top": BackToTopPreview, breadcrumb: BreadcrumbPreview, search: SearchPreview, "avatar-group": AvatarGroupPreview, "goal-ring": GoalRingPreview, challenge: ChallengePreview, contributions: ContributionPreview, "progress-bar": ProgressBarPreview, list: ListLayoutPreview, table: TableLayoutPreview, grid: GridLayoutPreview, "fluid-layout": FluidLayoutPreview, "inline-expansion": InlineExpansionPreview, "push-panel": PushPanelPreview, "image-card": ImageCardPreview, "navigation-bar": NavigationBarPreview, toolbar: ToolbarPreview, popover: PopoverLayoutPreview, "side-panel": SidePanelPreview, toast: ToastLayoutPreview, skeleton: SkeletonPreview, "step-progress": StepProgressPreview, button: ButtonPreview, input: InputPreview, select: SelectPreview, slider: SliderPreview, switch: SwitchPreview, checkbox: CheckboxPreview, "radio-group": RadioButtonPreview, card: CardPreview, "bottom-sheet": BottomSheetPreview, tabs: TabsPreview, pagination: PaginationPreview, "dot-pagination": DotPaginationPreview, filter: ChipPreview, badge: BadgePreview, tag: TagPreview, avatar: AvatarPreview, progress: ProgressPreview, dialog: DialogPreview, "alert-dialog": AlertDialogPreview, } const galleryPreviews = { ...previews, button: GalleryButtonPreview, badge: GalleryBadgePreview, } function ComponentPreview({ slug, compact = false, }: { slug: string compact?: boolean }) { const activePreviews = compact ? galleryPreviews : previews const Preview = Object.hasOwn(activePreviews, slug) ? activePreviews[slug as keyof typeof activePreviews] : undefined if (!Preview) return null const desktopLayout = ["grid", "image-gallery", "carousel", "fluid-layout", "inline-expansion", "push-panel"].includes(slug) const thumbnailLayout = ["dialog", "bottom-sheet", "side-panel", "popover", "toast", "alert-dialog"].includes(slug) return compact ? (

) : ( {thumbnailLayout ? <>

} ) } export { ComponentPreview } ``` ## Source: components/button-guidelines.tsx ```tsx import type { ReactNode } from "react" import { ButtonGuidelinePreview } from "@/components/button-guideline-preview" import { LocaleText } from "@/components/locale-provider" import { buttonGuidelineSectionId } from "@/lib/button-guideline-navigation" const groups = [ { id: "button-graphic", title: "그래픽", sections: [ { title: "모양", previews: ["shape"], paragraphs: [ "부드러운 인상으로 텍스트에 집중하게 돕는 둥근 네모형이 많이 쓰입니다. 직사각형은 뾰족한 영역의 자극에 시선이 모이는 현상이 있고 둥근 네모는 중앙으로 시선이 부드럽게 모이는 현상이 있습니다.", "경우에 따라 양 끝이 완전히 둥근 버튼을 쓰기도 합니다. 곡률이 같은데 크기가 작아지면 선분이 찌그러져 보이는 현상도 있어 크기가 작으면 곡률을 높이는 것이 자연스럽습니다.", ], }, { title: "크기", previews: ["size"], paragraphs: [ "버튼의 크기는 다른 요소와의 관계에 따라 다르게 정의합니다. 버튼 단독으로 크기를 정할 때는 주로 서비스에서 정한 최소 단위 간격을 중심으로 정합니다. 작음, 중간, 큼으로 단순하게 정하는 것이 쓰기 좋습니다.", "작은 버튼은 높이 32px로 대시보드와 밀도가 높은 화면에 사용합니다. 중간 버튼은 높이 40px로 일반적인 액션에 사용하고, 큰 버튼은 높이 56px로 모바일 하단의 주요 액션에 사용합니다.", ], }, { title: "곡률", previews: ["radius"], paragraphs: ["편의를 위해 버튼 및 레이어의 꼭지점의 곡률을 동일하게 적용하는 경우가 많습니다. 절대 수치로 곡률 값을 지정하면 크기가 작아져도 원 크기가 고정됩니다. 버튼의 크기가 작으면 꼭지점이 더 둥글어 보입니다. 자연스러운 표현을 위해서는 버튼의 크기 변화를 규격화하고 각 크기에 알맞은 곡률을 적용하는 것이 좋습니다."], }, { title: "연속형 모서리", previews: ["corners"], paragraphs: [ "모든 둥근 모서리가 같은 방식으로 그려지는 것은 아닙니다. 원형 모서리는 단순한 호를 따르기 때문에 직선 가장자리에서 곡선으로 넘어가는 변화가 더 눈에 띄게 느껴질 수 있습니다. 반면 연속형 모서리는 곡선이 가장자리와 더 부드럽게 이어지도록 만들어, 같은 반경이라도 더 부드럽고 덜 갑작스럽게 느껴지게 합니다.", "두 예시는 같은 크기의 완전히 둥근 버튼입니다. 원형은 일정한 곡률의 원호를 사용하고, 연속형은 직선으로 이어지는 구간의 곡률을 점진적으로 변화시킵니다. 아래 확대 비교도 버튼과 동일한 곡선을 사용합니다. 이 웹 표현은 iOS 네이티브 곡선과 완전히 동일한 구현은 아닙니다.", ], }, { title: "여백", previews: ["padding"], paragraphs: ["버튼을 설명하는 텍스트를 중심으로 가로 세로 여백을 정합니다. 사람의 눈은 수평 탐색에 더 익숙하기 때문에 좌우로 넓은 것이 더 익숙합니다. 세로 여백보다 가로 여백이 긴 것이 자연스럽습니다."], }, { title: "색", previews: ["color"], paragraphs: ["버튼의 색은 자유롭게 선택합니다. 주로 브랜드나 서비스의 정체성을 표현하는 색을 선택합니다. 사용성을 위해 텍스트는 식별이 쉽도록 흰색 혹은 같은 색조의 어두운 색을 사용합니다. 검정색을 사용할 수도 있습니다. 배경색은 내부에 담기는 텍스트가 잘 보일 수 있게 최소한의 명도 대비를 유지합니다."], }, { title: "색 위계", previews: ["color-hierarchy"], paragraphs: ["가장 중요도가 높은 요소에 주색을 사용합니다. 순서대로 보조색, 무채색 등을 이용해 버튼의 중요도와 상태를 표현합니다. 그라데이션을 이용해 누르는 요소라는 것을 더 강조하기도 합니다. 스마트폰에서는 단색으로도 충분히 버튼임이 이해되어 많이 사용하지는 않습니다."], }, { title: "글 쓰기", previews: ["word"], paragraphs: [ "버튼을 누르면 무슨 일이 생길지 알려 줍니다. 버튼을 누르면 페이지가 이동하는지, 정보를 제출하는지, 지금 하던 행동을 취소하는지 등 가능한 구체적으로 알려줍니다.", "버튼은 주로 동사를 표현하게 되는데 주어와 목적어를 명확하게 해석할 수 있는 독립적이고 구체적인 단어를 쓰는 것이 좋습니다. ‘예’라고만 표현할 경우 무엇에 대한 긍정인지, 긍정하면 무슨 일이 생기는지 알 수 없습니다.", "만약 사람이라면 사용자에게 무어라 말할지를 가정해 평소에 쓰는 언어로 말을 거는 것이 자연스럽습니다.", ], }, { title: "스타일", previews: ["style"], paragraphs: [ "용도에 따라 다양한 시각 기법을 조합해 스타일을 만듭니다. 중요한 정보를 자극 정도에 따라 사용합니다. 가장 많이 쓰이는 스타일은 주색으로 배경을 칠한 filled 스타일입니다. 배경의 색과 테두리를 변형해 여러 변주를 만듭니다. 배경이 없는 텍스트 버튼도 있습니다.", "버튼 스타일에 가장 중요한 것은 ‘누를 수 있다’를 알려주는 장치를 꼭 포함하는 것입니다. 예를 들어 텍스트 버튼에 밑줄이나 아이콘이 없다면 누를 수 있는 요소인지 단순히 색이 들어간 글자인지 구분할 수 없게 됩니다.", ], }, ], }, { id: "button-composition", title: "컴포지션", sections: [ { title: "레이어", previews: ["layer"], paragraphs: [ "버튼은 전체를 담는 바탕 레이어와 내부에 포함되는 레이어로 구분됩니다. 텍스트 레이어가 사용자에게 전달되어야 하는 핵심 콘텐츠입니다. 아이콘은 텍스트의 의미 전달을 강화합니다. 공간을 절약하면서 의미를 직관적으로 전달하기 위해 텍스트 대신 단독으로 쓰기도 합니다.", "바탕 레이어는 누를 수 있는 영역을 알립니다. 내부를 채우는 Fill과 테두리 선 Stroke를 정의합니다. 다양한 스타일로 표면과 테두리 성격을 설정합니다.", "주로 단색으로 표현하는 편이며 데스크탑 환경에서는 버튼을 튀어나오게 그라데이션으로 표현하기도 합니다. 다른 요소와 구분하기 위해 상황에 따라 그림자를 이용해 버튼이 공중에 뜬 것처럼 표현하기도 합니다.", ], }, { title: "조직화", previews: ["icon"], paragraphs: [ "텍스트 단독으로 쓰이는 경우가 많지만 식별을 돕기 위해 아이콘과 결합해서도 많이 씁니다.", "앞에 아이콘이 붙을 때는 텍스트의 의미를 동일하게 표현하는 경우가 많습니다. 텍스트와 비슷한 두께와 무게로 글자와 아이콘이 하나의 서체인 것처럼 표현하는 편입니다.", "텍스트 뒤에 아이콘이 쓰일 때는 주로 페이지를 이동하거나 레이아웃에 변화가 있을 때 많이 쓰이는 편입니다. 새로운 페이지가 열리거나 아코디언이 열릴 때 쓰입니다.", ], }, { title: "위계", previews: ["hierarchy"], paragraphs: [ "여러 버튼을 쓸 때는 위계를 명확히 합니다. 주색을 가득 채운 Primary를 1순위로 쓰고 같은 색조의 옅은 배경과 주색 텍스트를 가진 Secondary를 2순위로 사용합니다. 3순위인 Tertiary는 무채색 배경과 중립색 텍스트로 중요도를 낮춰 구분합니다.", "면으로 된 1순위 버튼과 테두리로 구성된 2순위 버튼을 사용하기도 합니다. 면과 선으로 확실하게 구분할 수 있는 장점이 있습니다. 다만 1순위 버튼과 2순위 버튼의 대비 정도가 심해 2순위 버튼의 힘이 과하게 약해지는 경향이 있습니다.", ], }, ], }, ] function ButtonGuidelines({ children }: { children?: ReactNode }) { return ( <>

가이드

{children &&

{children}

}

위키

버튼은 UI의 가장 기본적인 인터랙션입니다. 모든 UI는 버튼에서 출발한다고 해도 과언이 아닙니다. 사용자가 기계에게 의사를 전달하는 가장 단순하고 직접적인 요소이기 때문입니다.

화면 속 버튼은 단순한 그래픽 요소가 아닙니다. 사용자가 무언가를 결정하고, 실행하고, 이동하고, 취소하고, 저장하는 순간마다 버튼은 행동의 접점이 됩니다. 좋은 버튼은 사용자가 “무엇을 할 수 있는지”를 분명하게 알려주고, 그 행동의 결과를 예측할 수 있게 돕습니다.

버튼 디자인에서 중요한 것은 예쁘게 보이는 것만이 아닙니다. 버튼은 눌러야 할 것처럼 보여야 하고, 어떤 행동을 수행하는지 명확해야 하며, 현재 상태와 우선순위를 시각적으로 전달해야 합니다. 같은 버튼이라도 색상, 크기, 위치, 문구, 아이콘, 여백에 따라 사용자가 느끼는 중요도와 행동 가능성은 크게 달라집니다.

{groups.map((group) => (

{group.title}

{group.sections.map((section) => (

{section.title}

{section.previews.map((example) => )}

{section.paragraphs.map((paragraph) =>

{paragraph}

)}

))}

) } export { ButtonGuidelines } ``` ## Source: components/button-guideline-preview.tsx ```tsx "use client" import { useId, useState, type CSSProperties, type ReactNode, type ComponentProps } from "react" import { Plus } from "lucide-react" import { Button } from "@/components/ui/button" import { Slider } from "@/components/ui/slider" import { CornerComparison } from "@/components/corner-comparison" import { useLocale } from "@/components/locale-provider" function ExampleButton({ children = "저장", className = "", ...props }: ComponentProps) { const { t } = useLocale() const [pressed, setPressed] = useState(false) return } function Comparison({ items }: { items: { label: string; preview: ReactNode }[] }) { const { t } = useLocale() return

} function ButtonGuidelinePreview({ example }: { example: string }) { const { t } = useLocale() const id = useId() const [amount, setAmount] = useState(example === "radius" ? 22 : 12) const [clicked, setClicked] = useState(false) function range(label: string, min: number, max: number) { return

{t(label)}{amount}px

setAmount(value)} />

} function sample(style?: CSSProperties, label = "저장") { return {label} } let content switch (example) { case "shape": content = ({ label, preview: }))} /> break case "size": content = ({ label, preview: }))} /> break case "radius": content = <>{sample({ width: 160, height: 64, borderRadius: amount })}{range("곡률", 0, 32)} break case "corners": content = break case "padding": content = 저장 }, { label: "자연스러운 여백", preview: 저장 }, { label: "과한 여백", preview: 저장 }, ]} /> break case "color": content = ({ label, preview: sample({ background: ["var(--primary)", "var(--foreground)", "var(--destructive)"][index], color: index === 1 ? "var(--background)" : "white" }, index === 2 ? "삭제" : "저장") }))} /> break case "color-hierarchy": case "hierarchy": content = ({ label, preview: {example === "hierarchy" && }))} /> break case "word": content = break case "style": content = ({ label, preview: }))} /> break case "layer": content = ({ label, preview: {t("추가")}{index === 1 && } }))} /> break case "icon": content = }, { label: "뒤", preview: {t("추가")} }, { label: "아이콘만", preview: }, ]} /> break } return

{content}

} export { ButtonGuidelinePreview } ``` ## Source: components/corner-comparison.tsx ```tsx "use client" import { useId } from "react" import { Button } from "@/components/ui/button" import { useLocale } from "@/components/locale-provider" const width = 160 const height = 64 const shapes = [ { label: "원형 모서리", corner: "round" }, { label: "연속형 모서리", corner: "continuous" }, ] as const function CornerComparison() { const { t } = useLocale() const id = useId() return (

{shapes.map((shape) => (

{t(shape.label)}

))}

{t("원형과 연속형 모서리의 위쪽 접합부 확대 비교")} {t("위의 완전히 둥근 두 버튼과 동일한 모서리를 같은 배율로 확대해 겹쳐 표시합니다. 원형은 중립색 점선, 연속형은 파란 실선입니다.")} {shapes.map((shape, index) => (

{t("원형 모서리")} {t("연속형 모서리")}

{sections.map(({ id, title, items }) => (

{title[language]}

{text[language]}

))}

{t("이메일")}

updateValue(event.target.value)} onCompositionEnd={(event) => updateValue(event.currentTarget.value)} /> {value.length > 0 && ( )}

{t(message)}

) } function SwitchPreview() { const { t } = useLocale() const [checked, setChecked] = useState(true) return (

) } function CheckboxPreview() { const { t } = useLocale() const groupId = useId() const [selected, setSelected] = useState([]) const options = [ { value: "email", label: "이메일" }, { value: "sms", label: "문자 메시지" }, { value: "push", label: "앱 알림" }, ] return (

{t("알림 수단")} {options.map((option) => ( setSelected((current) => checked === true ? [...current.filter((value) => value !== option.value), option.value] : current.filter((value) => value !== option.value) )} /> {t(option.label)} ))}

) } function RadioButtonPreview() { const { t } = useLocale() const groupId = useId() const [value, setValue] = useState("delivery") const options = [ { value: "delivery", label: "배달" }, { value: "pickup", label: "픽업" }, { value: "visit", label: "방문" }, ] return (

{options.map((option) => ( {t(option.label)} ))}

) } function SelectPreview() { const { t } = useLocale() const [value, setValue] = useState("design") const choices = { design: "디자인", development: "개발", research: "리서치" } return (

{t(choices[value as keyof typeof choices])}

) } function SliderPreview() { const { t } = useLocale() const [value, setValue] = useState([50]) return (

) } function BottomSheetPreview() { const { locale } = useLocale() const [selected, setSelected] = useState("recommended") const options = locale === "ko" ? [["recommended", "추천순"], ["newest", "최신순"], ["price", "가격 낮은순"]] : [["recommended", "Recommended"], ["newest", "Newest"], ["price", "Price: low to high"]] return (

{locale === "ko" ? "어떤 순서로 볼까요?" : "How would you like to sort?"} {locale === "ko" ? "상품을 보여줄 순서를 선택해 주세요." : "Choose the order for your products."}

{options.map(([value, label]) => {label})}

{options.find(([value]) => value === selected)?.[1]}

) } function PaginationPreview({ compact = false }: { compact?: boolean } = {}) { const { t } = useLocale() const [page, setPage] = useState(1) const totalPages = 30 const photos = [ { id: "photo-1500534623283-312aade485b7", alt: "Sunrise over mountain ridges" }, { id: "photo-1470770841072-f978cf4d019e", alt: "A lake surrounded by mountains" }, { id: "photo-1464822759023-fed622ff2c3b", alt: "A mountain summit" }, { id: "photo-1441974231531-c6227db76b6e", alt: "Sunlight in a forest" }, ] const photo = photos[(page - 1) % photos.length] const paginationRef = useRef(null) const [visibleSlots, setVisibleSlots] = useState(3) useEffect(() => { const container = paginationRef.current if (!container) return const updateSlots = () => { const controls = container.querySelectorAll("[data-pagination-direction]") const controlWidth = Array.from(controls).reduce( (width, control) => width + control.getBoundingClientRect().width, 0 ) const available = container.clientWidth - controlWidth - 16 setVisibleSlots(available >= 7 * 42 ? 7 : available >= 5 * 42 ? 5 : 3) } const observer = new ResizeObserver(updateSlots) observer.observe(container) return () => observer.disconnect() }, [compact, t]) const getPages = (): (number | "start-ellipsis" | "end-ellipsis")[] => { if (visibleSlots === 3) { return page < totalPages / 2 ? [page, "end-ellipsis", totalPages] : [1, "start-ellipsis", page] } if (page <= visibleSlots - 2) { return [...Array.from({ length: visibleSlots - 2 }, (_, index) => index + 1), "end-ellipsis", totalPages] } if (page >= totalPages - visibleSlots + 3) { return [1, "start-ellipsis", ...Array.from({ length: visibleSlots - 2 }, (_, index) => totalPages - visibleSlots + 3 + index)] } const neighbors = (visibleSlots - 5) / 2 return [1, "start-ellipsis", ...Array.from({ length: visibleSlots - 4 }, (_, index) => page - neighbors + index), "end-ellipsis", totalPages] } return (

{ event.preventDefault() if (page === 1) return setPage(Math.max(1, page - 1)) }} /> {getPages().map((value) => ( {typeof value === "string" ? ( ) : ( { event.preventDefault() setPage(value) }} > {value} )} ))} { event.preventDefault() if (page === totalPages) return setPage(Math.min(totalPages, page + 1)) }} />

) } function DotPaginationPreview() { const { t } = useLocale() const [page, setPage] = useState(1) const [carouselRef, carouselApi] = useEmblaCarousel({ loop: false, duration: 22 }) const images = [ { photo: "photo-1500534623283-312aade485b7", alt: "Sunrise over layers of mountain ridges" }, { photo: "photo-1470770841072-f978cf4d019e", alt: "Mountains reflected in a calm lake" }, { photo: "photo-1464822759023-fed622ff2c3b", alt: "A rugged mountain summit" }, { photo: "photo-1519681393784-d120267933ba", alt: "A snowy mountain beneath a starry sky" }, { photo: "photo-1441974231531-c6227db76b6e", alt: "Sunlight falling through a forest" }, { photo: "photo-1507525428034-b723cf961d3e", alt: "Turquoise water along a sandy beach" }, { photo: "photo-1470252649378-9c29740c9fa8", alt: "A misty landscape in warm morning light" }, { photo: "photo-1469474968028-56623f02e42e", alt: "A sunlit mountain valley" }, ] const pageCount = images.length useEffect(() => { if (!carouselApi) return const syncPage = () => setPage(carouselApi.selectedScrollSnap() + 1) carouselApi.on("select", syncPage).on("reInit", syncPage) return () => { carouselApi.off("select", syncPage).off("reInit", syncPage) } }, [carouselApi]) const goToPage = (value: number) => { carouselApi?.scrollTo(value - 1, window.matchMedia("(prefers-reduced-motion: reduce)").matches) } return (

{ if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return event.preventDefault() goToPage(Math.min(pageCount, Math.max(1, page + (event.key === "ArrowRight" ? 1 : -1)))) }} >

{images.map((image, index) => (

))}

`${t("이미지")} ${value} / ${pageCount}`} />

) } function ChipPreview() { const { t } = useLocale() return (

{t("전체")} {t("Input")} {t("Navigation")} {t("Status")} {t("Layout")}

) } function FilterPreview({ compact = false }: { compact?: boolean } = {}) { const { t } = useLocale() const [filter, setFilter] = useState("all") const items = [ { name: "Button", type: "input" }, { name: "Slider", type: "input" }, { name: "Tabs", type: "navigation" }, { name: "Card", type: "navigation" }, ] const visible = items.filter( (item) => filter === "all" || item.type === filter ) return (

setFilter(value || "all")} variant="outline" aria-label={t("필터")} className={compact ? "max-w-full flex-wrap justify-center" : undefined} > {t("전체")} Input Navigation {!compact && <>

{item.name}

{t("결과")}: {visible.length}

}

) } function GalleryBadgePreview() { const { t } = useLocale() const [visible, setVisible] = useState(true) const [animated, setAnimated] = useState(false) return (

) } function BadgePreview() { const { locale } = useLocale() const [visible, setVisible] = useState(["1", "7", "24", "99+"]) const [animated, setAnimated] = useState([]) return (

{["1", "7", "24", "99+"].map((count) => ( ))}

) } function TagPreview({ showReset = true }: { showReset?: boolean } = {}) { const { t } = useLocale() return (

{["진행 중", "완료", "취소"].map((tag) => ( {tag === "취소" ? (t("취소") === "Cancel" ? "Cancelled" : "취소") : t(tag)} ))}

) } function AvatarPreview({ compact = false }: { compact?: boolean } = {}) { return (

) } function ProgressPreview() { const { t } = useLocale() return (

{locale === "ko" ? "콘텐츠를 불러오는 중" : "Loading content"}

) } function ProgressBarPreview({ progress = 45, onComplete }: { progress?: number; onComplete?: () => void } = {}) { const { locale } = useLocale() const complete = progress >= 100 const value = Math.min(99, Math.max(0, progress)) useEffect(() => { if (complete) onComplete?.() }, [complete, onComplete]) if (complete) return null return (

) } function StepProgressPreview() { const { locale } = useLocale() const [step, setStep] = useState(1) const labels = locale === "ko" ? ["정보 입력", "확인", "완료"] : ["Details", "Review", "Complete"] return (

) } function VideoPlaybackPreview() { const { locale } = useLocale() const [playing, setPlaying] = useState(false) const [position, setPosition] = useState(24) const duration = 180 useEffect(() => { if (!playing) return const timer = window.setInterval(() => { setPosition((current) => Math.min(current + 1, duration)) }, 1000) return () => window.clearInterval(timer) }, [playing]) useEffect(() => { if (position === duration) setPlaying(false) }, [position]) const formatTime = (seconds: number) => `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}` const label = locale === "ko" ? (playing ? "일시정지" : "재생") : (playing ? "Pause" : "Play") return (

setPosition(value[0])} />

{formatTime(position)}{formatTime(duration)}

) } function PasswordInputPreview() { const { t } = useLocale() const id = useId() const [value, setValue] = useState("") const [visible, setVisible] = useState(false) const [caps, setCaps] = useState(false) return (

{t("비밀번호")}

setValue(e.target.value)} onKeyUp={(e) => setCaps(e.getModifierState("CapsLock"))} onBlur={() => setCaps(false)} className="pr-11" />

{caps && (

Caps Lock

)}

) } function PhoneInputPreview() { const { t, locale } = useLocale() const id = useId() const [value, setValue] = useState("") const [checked, setChecked] = useState(false) const [country, setCountry] = useState("KR") const [open, setOpen] = useState(false) const [search, setSearch] = useState("") const names = new Intl.DisplayNames([locale], { type: "region" }) const englishNames = new Intl.DisplayNames(["en"], { type: "region" }) const countries = getCountries().filter((code) => `${names.of(code)} ${englishNames.of(code)} ${code} +${getCountryCallingCode(code)}`.toLowerCase().includes(search.trim().toLowerCase()) ) const invalid = checked && value.length > 0 && !isValidPhoneNumber(value, country) return (

{t("전화번호")}

{ setOpen(next); if (!next) setSearch("") }}> setSearch(event.target.value)} placeholder={locale === "ko" ? "대한민국, Korea, +82" : "South Korea, +82"} />

{countries.map((code) => )} {!countries.length &&

{locale === "ko" ? "검색 결과가 없습니다." : "No countries found."}

}

{ const input = e.target.value const international = input.trim().startsWith("+") ? parsePhoneNumberFromString(input) : undefined if (international?.country) { setCountry(international.country) setValue(international.formatNational()) } else { setValue(new AsYouType(country).input(input)) } setChecked(false) }} onBlur={() => setChecked(true)} />

) } function CodeInputPreview() { const { t } = useLocale() const [value, setValue] = useState("") return (

( <> {slots.map((slot, i) => ( ))} )} /> {value.length === 6 ? t("코드 입력 완료") : ""}

) } function NumberStepperPreview() { const { t } = useLocale() const [value, setValue] = useState("1") const number = Number(value) const commit = (next: number) => setValue(String(Math.min(99, Math.max(1, next || 1)))) return (

setValue(e.target.value)} onBlur={() => commit(number)} className="w-16 [appearance:textfield] px-1 text-center [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none" />

) } function DatePickerPreview() { const { locale } = useLocale() const [range, setRange] = useState({ from: new Date(2026, 9, 9), to: new Date(2026, 9, 11) }) const [month, setMonth] = useState(new Date(2026, 9, 1)) const [preset, setPreset] = useState(3) const presets = [1, 0, 3, 7, 14, 30, 90] const format = (date: Date) => new Intl.DateTimeFormat(locale === "ko" ? "ko-KR" : "en-US", { month: "short", day: "numeric" }).format(date) function choosePreset(days: number) { const end = new Date() end.setHours(0, 0, 0, 0) if (days === 0) end.setDate(end.getDate() - 1) const start = new Date(end) start.setDate(start.getDate() - Math.max(0, days - 1)) setRange({ from: start, to: end }) setMonth(end) setPreset(days) } return (

{presets.map((days) => )}

{ setRange(value); setPreset(null) }} month={month} onMonthChange={setMonth} locale={locale === "ko" ? ko : enUS} showOutsideDays fixedWeeks classNames={{ root: "relative min-w-0 flex-1 p-4 text-base", months: "relative", month: "w-full", month_caption: "flex h-10 items-center justify-center", caption_label: "font-medium", nav: "absolute inset-x-0 top-0 flex justify-between", button_previous: "grid size-10 place-items-center rounded-xl hover:bg-tab-muted", button_next: "grid size-10 place-items-center rounded-xl hover:bg-tab-muted", month_grid: "w-full table-fixed border-collapse", weekday: "h-7 text-xs font-normal text-muted-foreground", day: "h-10 p-0 text-center", day_button: "mx-auto grid size-10 place-items-center rounded-xl hover:bg-tab-muted focus-visible:outline-2 focus-visible:outline-ring", range_start: "[&>button]:bg-foreground [&>button]:text-background", range_end: "[&>button]:bg-foreground [&>button]:text-background", range_middle: "bg-tab-muted [&>button]:rounded-none", outside: "text-muted-foreground/50", today: "font-semibold", hidden: "invisible", }} components={{ Chevron: ({ orientation }) => orientation === "left" ? : }} />

) } function TimePickerPreview() { const { t } = useLocale() const [time, setTime] = useState("10:00") return (

) } function FileDropPreview() { const { t } = useLocale() const picker = useRef(null) const [file, setFile] = useState(null) const [dragging, setDragging] = useState(false) const [error, setError] = useState("") const accept = (value?: File) => { setDragging(false) if (!value) return if ( (!value.type.startsWith("image/") && value.type !== "application/pdf") || value.size > 10 * 1024 * 1024 ) { setError(t("이미지 또는 PDF, 최대 10 MB까지 가능합니다.")) return } setFile(value) setError("") } return (

accept(e.target.files?.[0])} /> {file && (

{file.name}

)} {error && (

{error}

)}

) } function VoiceRecorderPreview() { const { t } = useLocale() const [recording, setRecording] = useState(false) const [pending, setPending] = useState(false) const [level, setLevel] = useState(0) const [error, setError] = useState("") const stream = useRef(null) const mounted = useRef(true) useEffect(() => { mounted.current = true return () => { mounted.current = false stream.current?.getTracks().forEach((track) => track.stop()) } }, []) useEffect(() => { if (!recording) return const input = stream.current if (!input) return const context = new AudioContext() const analyser = context.createAnalyser() analyser.fftSize = 512 const source = context.createMediaStreamSource(input) source.connect(analyser) const samples = new Float32Array(analyser.fftSize) void context.resume().catch(() => {}) const timer = setInterval(() => { analyser.getFloatTimeDomainData(samples) const rms = Math.sqrt(samples.reduce((sum, sample) => sum + sample * sample, 0) / samples.length) setLevel(rms < 0.015 ? 0 : Math.min(1, rms * 8)) }, 33) return () => { clearInterval(timer) source.disconnect() analyser.disconnect() void context.close() } }, [recording]) const start = async () => { setPending(true) setError("") try { if ( !navigator.mediaDevices?.getUserMedia ) throw new Error("unsupported") const input = await navigator.mediaDevices.getUserMedia({ audio: true }) if (!mounted.current) { input.getTracks().forEach((track) => track.stop()) return } stream.current = input setLevel(0) setRecording(true) } catch { stream.current?.getTracks().forEach((track) => track.stop()) if (mounted.current) setError(t("마이크 사용 권한과 브라우저 지원을 확인하세요.")) } finally { if (mounted.current) setPending(false) } } return (

{error && (

{error}

)}

) } function SignatureInputPreview() { const { t } = useLocale() const canvas = useRef(null) useEffect(() => { const element = canvas.current if (!element) return const signature = new SignaturePad(element, { penColor: "rgba(23, 27, 34, 0.9)", minWidth: 0.8, maxWidth: 2, }) const resize = new ResizeObserver(() => { const data = signature.toData() const ratio = Math.max(window.devicePixelRatio || 1, 1) element.width = element.clientWidth * ratio element.height = element.clientHeight * ratio element.getContext("2d")?.scale(ratio, ratio) signature.clear() signature.fromData(data) }) resize.observe(element) return () => { resize.disconnect() signature.off() } }, []) return (

) } function TreeViewPreview() { const { t } = useLocale() const [selected, setSelected] = useState("Button.tsx") return (

{t("컴포넌트")}

{t("Input")}

{t("텍스트 필드")}

{["Email.tsx", "Password.tsx"].map((name) => )}

{["Button.tsx", "Input.tsx", "Dropdown.tsx"].map((name) => ( ))}

) } function AccordionPreview() { const { t } = useLocale() const items = [ ["배송", "배송은 영업일 기준 2~3일 소요됩니다."], ["교환·반품", "수령 후 7일 이내에 요청할 수 있습니다."], ["결제", "카드와 간편 결제를 사용할 수 있습니다."], ] return (

{items.map(([title, content]) => ( {t(title)} {t(content)} ))}

) } function CarouselPreview() { const { t } = useLocale() const [page, setPage] = useState(1) const [ref, api] = useEmblaCarousel({ loop: false, align: "center", containScroll: false, duration: 22 }) useEffect(() => { if (!api) return const select = () => setPage(api.selectedScrollSnap() + 1) api.on("select", select).on("reInit", select) return () => { api.off("select", select).off("reInit", select) } }, [api]) const move = (index: number) => api?.scrollTo( index, window.matchMedia("(prefers-reduced-motion: reduce)").matches ) return (

{ if (e.key === "ArrowLeft" || e.key === "ArrowRight") { e.preventDefault() move( Math.max( 0, Math.min( galleryPhotos.length - 1, page - 1 + (e.key === "ArrowRight" ? 1 : -1) ) ) ) } }} className="layout-screen-surface h-36 cursor-grab overflow-hidden active:cursor-grabbing" >

{galleryPhotos.map((photo) => (

{t("콘텐츠")}

))}

) } function ImageGalleryPreview() { const { t } = useLocale() return (

{galleryPhotos.map((photo, index) => ( ))}

) } function AvatarGroupPreview() { const { locale } = useLocale() return (

{["0% 0%", "100% 0%", "0% 100%"].map((position, index) => ( ))} +3

) } function GoalRingPreview() { const { locale } = useLocale() const [goal, setGoal] = useState(65) return

} function ChallengePreview() { const { locale } = useLocale() const [days, setDays] = useState(4) return

{Array.from({length:7},(_,i)=>)}

} function ContributionPreview() { const { locale } = useLocale() const [selected, setSelected] = useState(null) const colors = ["bg-tab-muted", "bg-blue-200", "bg-blue-400", "bg-blue-600", "bg-blue-800"] return

{Array.from({length:84},(_,i)=>{const count=(i*17+i%5)%5;return

} function SearchPreview() { const { locale } = useLocale() const [query, setQuery] = useState("") const input = useRef(null) return (

) } function BreadcrumbPreview() { const { locale } = useLocale() return (

) } function BackToTopPreview() { const { locale } = useLocale() const viewport = useRef(null) useEffect(() => { if (viewport.current) viewport.current.scrollTop = 120 }, []) return (

{locale === "ko" ? "문서" : "Document"}

{Array.from({ length: 5 }, (_, index) =>

{locale === "ko" ? "섹션" : "Section"} {index + 1}

)}

) } function ClassicTabsPreview() { const { locale } = useLocale() const [value, setValue] = useState("overview") return (

{[["overview", "개요", "Overview"], ["activity", "활동", "Activity"], ["settings", "설정", "Settings"]].map(([id, ko, en]) => ( {locale === "ko" ? ko : en} ))}

) } function TableOfContentsPreview() { const { t } = useLocale() const prefix = useId() const [activeId, setActiveId] = useState(`${prefix}-intro`) const sections = [ { id: `${prefix}-intro`, label: t("Introduction"), depth: 0 }, { id: `${prefix}-principles`, label: t("기본 원칙"), depth: 0 }, { id: `${prefix}-example`, label: t("예시"), depth: 1 }, { id: `${prefix}-accessibility`, label: t("접근성"), depth: 0 }, ] return (

{ setActiveId(id) }} />

) } function CalendarPreview() { const { locale } = useLocale() const [date, setDate] = useState(new Date(2026, 9, 10)) return (

) } function MapPreview() { const { t } = useLocale() const [city, setCity] = useState("seoul") const positions: Record = { seoul: [37.5665, 126.978], busan: [35.1796, 129.0756], jeju: [33.4996, 126.5312], } return (

) } function TablePreview() { const { t } = useLocale() const [ascending, setAscending] = useState(true) const rows = [ { name: "Compass", count: 24 }, { name: "Atlas", count: 12 }, { name: "North", count: 36 }, ].sort((a, b) => (ascending ? a.count - b.count : b.count - a.count)) return (

{rows.map((row) => ( ))}

{t("프로젝트 목록")}
{t("프로젝트")}
{row.name}	{row.count}

) } function TimelinePreview() { const { t } = useLocale() const events = [ ["09:00", "주문 접수"], ["10:30", "준비 중"], ["", "배송 시작"], ] return (

{index < events.length - 1 && (

) } export { SkeletonPreview, ProgressBarPreview, StepProgressPreview, VideoPlaybackPreview, AvatarGroupPreview, GoalRingPreview, ChallengePreview, ContributionPreview, SearchPreview, BreadcrumbPreview, BackToTopPreview, ClassicTabsPreview, PasswordInputPreview, PhoneInputPreview, CodeInputPreview, NumberStepperPreview, DatePickerPreview, TimePickerPreview, FileDropPreview, VoiceRecorderPreview, SignatureInputPreview, TreeViewPreview, AccordionPreview, CarouselPreview, ImageGalleryPreview, CalendarPreview, TableOfContentsPreview, MapPreview, TablePreview, TimelinePreview, } ``` ## Source: components/map-canvas.tsx ```tsx "use client" import { useEffect, useRef, useState } from "react" import type { Map as LeafletMap, CircleMarker } from "leaflet" import { useLocale } from "@/components/locale-provider" function MapCanvas({ value, onChange, }: { value: [number, number] onChange?: (value: [number, number]) => void }) { const { t } = useLocale() const element = useRef(null) const map = useRef(null) const marker = useRef(null) const change = useRef(onChange) const initialValue = useRef(value) const [failed, setFailed] = useState(false) useEffect(() => { change.current = onChange }, [onChange]) useEffect(() => { let disposed = false let resize: ResizeObserver | undefined import("leaflet") .then((L) => { if (disposed || !element.current) return const instance = L.map(element.current, { scrollWheelZoom: false, }).setView(initialValue.current, 13) map.current = instance const tiles = L.tileLayer( "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", { attribution: '© OpenStreetMap', maxZoom: 19, } ).addTo(instance) tiles.on("tileerror", () => { if (!disposed) setFailed(true) }) marker.current = L.circleMarker(initialValue.current, { radius: 8, color: "#ffffff", weight: 2, fillColor: "#007AFF", fillOpacity: 1, }).addTo(instance) instance.on("click", (event) => change.current?.([event.latlng.lat, event.latlng.lng]) ) resize = new ResizeObserver(() => instance.invalidateSize()) resize.observe(element.current) }) .catch(() => { if (!disposed) setFailed(true) }) return () => { disposed = true resize?.disconnect() map.current?.remove() map.current = null marker.current = null } }, []) useEffect(() => { initialValue.current = value marker.current?.setLatLng(value) map.current?.panTo(value) }, [value]) return (

{failed && (

{t("지도를 불러오지 못했습니다.")}

)}

) } export { MapCanvas } ``` ## Source: components/ui/calendar.tsx ```tsx "use client" import { DayPicker } from "react-day-picker" import { ko, enUS } from "react-day-picker/locale" import { ChevronLeft, ChevronRight } from "lucide-react" function Calendar({ selected, onSelect, language = "ko", today, }: { selected?: Date onSelect: (date: Date | undefined) => void language?: "ko" | "en" today?: Date }) { return ( button]:bg-primary [&>button]:text-primary-foreground", today: "font-bold", outside: "text-muted-foreground/50", disabled: "opacity-30", hidden: "invisible", }} components={{ Chevron: ({ orientation }) => orientation === "left" ? ( ) : ( ), }} /> ) } export { Calendar } ``` ## Source: components/ui/table-of-contents.tsx ```tsx "use client" import { type ComponentProps } from "react" import { cn } from "cn" type TocItem = { id: string; label: string; depth?: number } type TableOfContentsProps = Omit, "children"> & { items: TocItem[] activeId?: string onNavigate?: (id: string) => void } function TableOfContents({ items, activeId, onNavigate, className, ...props }: TableOfContentsProps) { return ( ) } export { TableOfContents } export type { TocItem, TableOfContentsProps } ``` ## Source: components/ui/time-picker.tsx ```tsx "use client" import { WheelPicker, WheelPickerWrapper } from "@ncdai/react-wheel-picker" type TimePickerProps = { value: string onValueChange: (value: string) => void label?: string periodLabel?: string hourLabel?: string minuteLabel?: string amLabel?: string pmLabel?: string minuteStep?: 1 | 5 | 10 | 15 | 30 } function TimePicker({ value, onValueChange, label = "Time", periodLabel = "AM or PM", hourLabel = "Hour", minuteLabel = "Minute", amLabel = "AM", pmLabel = "PM", minuteStep = 5, }: TimePickerProps) { const valid = /^(?:[01]\d|2[0-3]):[0-5]\d$/.test(value) ? value : "10:00" const [hour24, minute] = valid.split(":").map(Number) const period = hour24 >= 12 ? "pm" : "am" const hour = hour24 % 12 || 12 const hours = Array.from({ length: 12 }, (_, index) => ({ value: index + 1, label: String(index + 1), })) const minutes = [ ...new Set([ ...Array.from( { length: 60 / minuteStep }, (_, index) => index * minuteStep ), minute, ]), ] .sort((a, b) => a - b) .map((value) => ({ value, label: String(value).padStart(2, "0") })) const classNames = { optionItem: "text-xl! font-medium text-muted-foreground/30", highlightWrapper: "bg-transparent", highlightItem: "text-xl font-medium text-foreground", } function update(nextPeriod: string, nextHour: number, nextMinute: number) { const nextHour24 = (nextHour % 12) + (nextPeriod === "pm" ? 12 : 0) onValueChange( `${String(nextHour24).padStart(2, "0")}:${String(nextMinute).padStart(2, "0")}` ) } return (

update(next, hour, minute)} visibleCount={12} optionItemHeight={40} classNames={classNames} />

update(period, next, minute)} infinite visibleCount={12} optionItemHeight={40} classNames={classNames} />

update(period, hour, next)} infinite visibleCount={12} optionItemHeight={40} classNames={classNames} />

{period === "am" ? amLabel : pmLabel} {hour}: {String(minute).padStart(2, "0")}

) } export { TimePicker } export type { TimePickerProps } ``` ## Source: lib/extended-catalog.ts ```ts const inputItems = [ [ "password-input", "비밀번호 입력", "Password input", "비밀번호를 입력하고 필요할 때 표시 여부를 바꿉니다.", "Enter a password and reveal it when needed.", "입력 내용을 기본적으로 가리고, 표시 전환 버튼에 명확한 이름을 제공합니다.", "Mask the value by default and clearly label the visibility control.", ], [ "phone-input", "전화번호 입력", "Phone input", "전화번호를 읽기 쉬운 형식으로 입력합니다.", "Enter a phone number in a readable format.", "숫자 키보드를 제공하고 국가별 형식을 고려합니다. 입력 중에는 오류 안내를 서두르지 않습니다.", "Offer a numeric keyboard and account for country formats. Avoid premature errors while typing.", ], [ "code-input", "6자리 코드 입력", "6-digit code input", "인증을 위한 일회용 숫자 코드를 입력합니다.", "Enter a one-time numeric verification code.", "코드 전체를 붙여넣을 수 있게 하고, 입력칸 이동과 삭제를 자연스럽게 지원합니다.", "Allow pasting the complete code and support natural navigation and deletion.", ], [ "number-stepper", "숫자 스테퍼", "Number stepper", "정해진 범위 안에서 수량을 늘리거나 줄입니다.", "Increase or decrease a quantity within a range.", "최솟값과 최댓값에서 해당 버튼을 비활성화하고 직접 입력도 허용합니다.", "Disable controls at the limits and allow direct entry.", ], [ "date-picker", "날짜 선택기", "Date picker", "일정을 위해 날짜를 선택합니다.", "Choose a date for an event.", "날짜 형식을 명확히 표시하고 선택한 날짜를 편집하거나 지울 수 있게 합니다.", "Show the date format clearly and allow editing or clearing the selection.", ], [ "time-picker", "시간 선택기", "Time picker", "오전·오후, 시, 분을 각각 조절해 시간을 선택합니다.", "Choose a time by adjusting the period, hour and minute separately.", "선택된 시간을 중앙에 표시하고 터치·마우스·키보드로 같은 선택을 할 수 있게 합니다.", "Center the selected time and support equivalent touch, mouse and keyboard interaction.", ], [ "file-drop", "드래그 앤 드롭", "Drag & drop", "파일을 끌어 놓거나 찾아 선택합니다.", "Drop a file or browse to select it.", "끌기 외에도 키보드로 파일을 선택할 수 있게 하고, 허용 형식과 용량 초과를 안내합니다.", "Provide a keyboard-accessible alternative and explain unsupported formats or size limits.", ], [ "voice-recorder", "음성 녹음", "Voice recorder", "음성을 녹음하고 다시 듣습니다.", "Record audio and listen back.", "시작·중지 상태를 구분하고 권한 거부 시 복구 방법을 안내합니다. 녹음은 명시적인 동작으로만 시작합니다.", "Distinguish start and stop states and handle denied permission. Start recording only after an explicit action.", ], [ "signature-input", "서명 입력", "Signature input", "손가락이나 마우스로 서명을 작성합니다.", "Draw a signature with a finger or mouse.", "충분한 작성 영역과 지우기 기능을 제공합니다. 서명 없이 진행할 수 없는 상황은 명확히 알립니다.", "Provide ample drawing space and a clear action. Explain when a signature is required.", ], ] as const const additionalItems = [ [ "tree-view", "트리뷰", "Tree view", "폴더와 하위 항목의 계층을 탐색합니다.", "Explore a hierarchy of folders and items.", "펼침 상태와 선택 상태를 구분하고 키보드로도 항목에 접근할 수 있게 합니다.", "Distinguish expansion from selection and make items keyboard accessible.", ], [ "accordion", "아코디언", "Accordion", "관련 내용을 필요한 때 펼쳐 확인합니다.", "Expand related information when needed.", "제목만으로 내용을 예측할 수 있게 하고, 열린 상태를 명확하게 표시합니다.", "Use descriptive headings and clearly show expanded states.", ], [ "carousel", "캐러셀", "Carousel", "여러 이미지를 한 영역에서 순서대로 탐색합니다.", "Browse a sequence of images in one area.", "자동 이동을 강제하지 않고 버튼·드래그·키보드로 이동할 수 있게 합니다.", "Avoid forced autoplay and support buttons, dragging, and keyboard navigation.", ], [ "table-of-contents", "목차", "Table of Contents", "문서의 제목 위계를 보여주고 원하는 섹션으로 이동합니다.", "Show a document's heading hierarchy and navigate to a section.", "본문의 제목과 같은 이름을 사용하고 현재 위치와 하위 제목의 깊이를 명확히 구분합니다.", "Match document headings and clearly distinguish the current location and nested levels.", ], [ "image-gallery", "갤러리", "Gallery", "이미지 모음을 비교하고 크게 확인합니다.", "Compare a collection of images and open a larger view.", "동일한 비율로 썸네일을 배치하고, 확대한 이미지를 쉽게 닫을 수 있게 합니다.", "Keep thumbnails consistent and make enlarged images easy to dismiss.", ], [ "calendar", "캘린더", "Calendar", "월 단위로 날짜를 탐색하고 선택합니다.", "Browse and select dates by month.", "현재 날짜와 선택 날짜를 구분하고 월 이동을 키보드로도 지원합니다.", "Distinguish today from the selected date and support keyboard navigation.", ], [ "map", "지도", "Map", "장소와 주변 지리를 탐색합니다.", "Explore places and their surroundings.", "확대·축소와 이동을 제공하되 페이지 스크롤을 방해하지 않도록 합니다.", "Offer zoom and pan without trapping page scrolling.", ], [ "table", "테이블", "Table", "여러 항목의 정보를 같은 기준으로 비교합니다.", "Compare records using consistent columns.", "열 제목과 정렬 방향을 명확히 표시하고, 숫자는 비교하기 쉽게 정렬합니다.", "Label columns and sort direction clearly and align numbers for comparison.", ], [ "timeline", "단계 진행 세로형", "Vertical Step Progress", "시간 순서에 따라 사건과 진행 상황을 살펴봅니다.", "Explore events and progress in chronological order.", "시간과 상태를 함께 표시하고, 색상 외에도 텍스트로 진행 상황을 구분합니다.", "Show time and status together and communicate progress beyond color alone.", ], ] as const export const extendedInputItems = [...inputItems.filter(([slug]) => slug !== "file-drop"), ...inputItems.filter(([slug]) => slug === "file-drop")].map(([slug, label]) => ({ slug, label, })) const additionalCatalogItems = additionalItems.map(([slug, label]) => ({ slug, label, })) export const extendedNavigationItems = additionalCatalogItems.filter( ({ slug }) => ["tree-view", "accordion", "carousel"].includes(slug) ) export const extendedLayoutItems = additionalCatalogItems.filter( ({ slug }) => slug === "image-gallery" ) export const extendedModuleItems = additionalCatalogItems.filter(({ slug }) => ["calendar", "map", "table"].includes(slug) ) export const extendedStatusItems = additionalCatalogItems.filter( ({ slug }) => slug === "timeline" ) export const extendedComponentDetails = Object.fromEntries( [...inputItems, ...additionalItems].map( ([slug, , , description, descriptionEn, usage, usageEn]) => [ slug, { description, descriptionEn, usage, usageEn }, ] ) ) export const extendedCatalogTranslations = Object.fromEntries( [...inputItems, ...additionalItems].map(([, ko, en]) => [ko, en]) ) ``` ## Source: components/foundation-preview.tsx ```tsx "use client" import Link from "next/link" import { useState } from "react" import { useLocale } from "@/components/locale-provider" import { Button } from "@/components/ui/button" import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group" import { DialogPreview } from "@/components/component-previews" import { InputPreview } from "@/components/catalog-previews" function FoundationPreview({ slug }: { slug: string }) { const { t } = useLocale() const [columns, setColumns] = useState("2") const [saved, setSaved] = useState(false) if (slug === "layers") return if (slug === "input-output") return if (slug === "writing") return (

{t("변경 사항을 저장합니다.")}

{saved ? t("설정이 저장되었습니다.") : null}

) if (slug === "layout") return (

{ if (value) setColumns(value) }} variant="outline" aria-label={t("레이아웃")} > 1 2 3

{["Input", "Layout", "Navigation", "Status"].map((name) => (

{name}

))}

) if (slug === "information-architecture") return ( ) return (

{["Input", "Layout", "Navigation", "Status"].map((name) => (

{name}

{name === "Input" ? t("버튼") + " · " + t("텍스트 필드") + " · " + t("드롭다운") : name === "Layout" ? t("카드") + " · " + t("바텀 시트") + " · " + t("다이얼로그") : name === "Navigation" ? t("세그멘티드 컨트롤") + " · " + t("페이지네이션") + " · " + t("칩") : t("뱃지") + " · " + t("아바타") + " · " + t("확인 다이얼로그")}

))}

) } export { FoundationPreview } ``` ## Source: lib/docs-catalog.ts ```ts import { extendedInputItems, extendedNavigationItems, extendedLayoutItems, extendedStatusItems, extendedComponentDetails, extendedCatalogTranslations } from "@/lib/extended-catalog" export const componentGroups = [ { title: "Input", items: [ { label: "버튼", slug: "button" }, { label: "토글", slug: "switch" }, { label: "슬라이더", slug: "slider" }, { label: "Single Selection", slug: "radio-group" }, { label: "Multiple Selection", slug: "checkbox" }, { label: "드롭다운", slug: "select" }, { label: "툴 바", slug: "toolbar" }, { label: "텍스트 필드", slug: "input" }, { label: "검색", slug: "search" }, ...extendedInputItems, ], }, { title: "Layout", items: [ { label: "카드", slug: "card" }, { label: "이미지 카드", slug: "image-card" }, { label: "리스트", slug: "list" }, { label: "테이블", slug: "table" }, { label: "그리드", slug: "grid" }, ...extendedLayoutItems, ...extendedNavigationItems.filter((item) => item.slug === "carousel"), { label: "유동형 레이아웃", slug: "fluid-layout" }, { label: "인라인 확장", slug: "inline-expansion" }, { label: "밀어내는 패널", slug: "push-panel" }, { label: "팝오버", slug: "popover" }, { label: "모달", slug: "dialog" }, { label: "바텀 시트", slug: "bottom-sheet" }, { label: "사이드 패널", slug: "side-panel" }, { label: "토스트", slug: "toast" }, { label: "플로팅 카드", slug: "alert-dialog" }, ], }, { title: "Navigation", items: [ { label: "탭", slug: "classic-tabs" }, { label: "세그멘티드 컨트롤", slug: "tabs" }, { label: "칩 필터", slug: "filter" }, { label: "네비게이션 바", slug: "navigation-bar" }, { label: "브레드크럼", slug: "breadcrumb" }, { label: "목차", slug: "table-of-contents" }, ...["accordion", "tree-view"].flatMap((slug) => extendedNavigationItems.filter((item) => item.slug === slug)), { label: "점 페이지네이션", slug: "dot-pagination" }, { label: "페이지네이션", slug: "pagination" }, ], }, { title: "Status", items: [ { label: "태그", slug: "tag" }, { label: "뱃지", slug: "badge" }, { label: "과정 표시", slug: "progress" }, { label: "스켈레톤", slug: "skeleton" }, { label: "프로그레스 바", slug: "progress-bar" }, { label: "아바타", slug: "avatar" }, { label: "아바타 모음", slug: "avatar-group" }, { label: "원형 게이지", slug: "goal-ring" }, { label: "습관 추적", slug: "challenge" }, { label: "활동 히트맵", slug: "contributions" }, { label: "단계 진행 가로형", slug: "step-progress" }, ...extendedStatusItems, ], }, ] export const componentDetails: Record< string, { description: string; descriptionEn: string; usage: string; usageEn: string } > = { ...extendedComponentDetails, "image-card": { description: "이미지를 배경으로 사용하고 하단에 제목과 태그를 배치합니다.", descriptionEn: "Place a title and tag over a full-background image.", usage: "하단으로 갈수록 블러를 높여 이미지의 분위기를 유지하면서 텍스트를 읽기 쉽게 합니다.", usageEn: "Increase blur toward the bottom to preserve the image while keeping text readable.", }, ...Object.fromEntries([ ["list", "관련 항목을 세로 목록으로 정리합니다.", "Arrange related items in a vertical list."], ["table", "같은 속성을 가진 데이터를 행과 열로 비교합니다.", "Compare data with shared attributes in rows and columns."], ["grid", "콘텐츠를 일정한 열과 간격으로 배치합니다.", "Arrange content in consistent columns with even spacing."], ["inline-expansion", "현재 흐름 안에서 상세 영역을 펼쳐 아래 콘텐츠를 밀어냅니다. 아코디언이나 추가 입력 영역에 사용합니다.", "Expand details in the document flow, pushing following content down. Use for accordions or additional form fields."], ["push-panel", "패널이 공간을 차지하면 기존 콘텐츠의 폭이 줄어듭니다. 화면을 덮지 않고 메뉴나 보조 작업을 함께 보여줍니다.", "A panel takes layout space and resizes the main content. Show navigation or supporting tasks without covering the page."], ["fluid-layout", "영역의 너비가 변하면 콘텐츠도 같은 비율로 늘어나거나 줄어듭니다.", "Content expands or contracts with the available width."], ["navigation-bar", "주요 화면 사이의 이동을 제공합니다.", "Navigate between main destinations."], ["toolbar", "현재 작업에 필요한 도구를 모읍니다.", "Group tools for the current task."], ["popover", "선택한 요소 가까이에 보조 정보를 엽니다.", "Open contextual information beside a trigger."], ["side-panel", "화면 옆에서 상세 정보와 보조 작업을 제공합니다.", "Show details and supporting tasks beside the page."], ["toast", "방금 수행한 작업의 결과를 잠시 알려줍니다.", "Briefly announce the result of an action."], ].map(([slug, description, descriptionEn]) => [slug, { description, descriptionEn, usage: description, usageEn: descriptionEn }])), skeleton: { description: "콘텐츠를 불러오는 동안 실제 요소의 형태와 위치를 미리 보여줍니다.", descriptionEn: "Preview the shape and position of content while it loads.", usage: "콘텐츠와 비슷한 크기로 자리를 확보해 로딩 전후의 화면 이동을 줄입니다. 움직임은 은은하게 유지합니다.", usageEn: "Reserve space matching the content to reduce layout shifts. Keep the animation subtle.", }, "progress-bar": { description: "작업이 얼마나 진행되었는지 비율로 표시합니다.", descriptionEn: "Show how much of a task has been completed.", usage: "전체 작업량을 알 수 있는 업로드나 처리 과정에 사용합니다. 처리 중에는 최대 99%까지만 표시하고, 완료되면 100%를 보여주지 않고 다음 단계로 전환합니다. 진행률을 계산할 수 없다면 로딩 표시를 사용합니다.", usageEn: "Use for uploads or tasks with a known total. Display at most 99% while processing, and move to the next step on completion without showing 100%. Use a loading indicator when progress cannot be measured.", }, "step-progress": { description: "여러 단계로 이루어진 과정의 현재 위치를 표시합니다.", descriptionEn: "Show the current position in a multi-step process.", usage: "현재 단계, 완료한 단계, 남은 단계를 구분합니다. 각 단계의 이름은 짧고 명확하게 표시합니다.", usageEn: "Distinguish current, completed, and upcoming steps. Keep step labels short and clear.", }, "video-playback": { description: "동영상의 재생 상태와 현재 위치를 확인하고 제어합니다.", descriptionEn: "View and control video playback and its current position.", usage: "재생과 일시정지를 명확히 구분하고, 현재 시간과 전체 길이를 함께 표시합니다. 재생바로 원하는 구간을 탐색할 수 있게 합니다.", usageEn: "Clearly distinguish play and pause, show elapsed and total time, and allow seeking to a specific position.", }, "avatar-group": { description: "여러 참여자를 묶어 보여줍니다.", descriptionEn: "Show a group of participants.", usage: "참여자 수를 간결하게 표현합니다.", usageEn: "Show participants compactly." }, "goal-ring": { description: "목표 달성 비율을 원형으로 표시합니다.", descriptionEn: "Show goal progress in a ring.", usage: "달성률을 숫자와 함께 표시합니다.", usageEn: "Include a numeric progress value." }, challenge: { description: "일별 진행과 챌린지 달성을 표시합니다.", descriptionEn: "Show daily progress and challenge completion.", usage: "완료한 단계와 남은 단계를 구분합니다.", usageEn: "Distinguish completed and remaining steps." }, contributions: { description: "날짜별 활동량을 작은 칸으로 표시합니다.", descriptionEn: "Show daily activity as a contribution grid.", usage: "색상 농도로 활동량을 표현하고 각 날짜에 수치를 제공합니다.", usageEn: "Use color intensity and accessible daily counts." }, search: { description: "키워드로 원하는 항목을 찾습니다.", descriptionEn: "Find items using a keyword.", usage: "입력에 따라 결과를 갱신하고 검색어 지우기와 결과 없음 상태를 제공합니다.", usageEn: "Update results as people type and provide clearing and empty states.", }, breadcrumb: { description: "현재 위치와 상위 경로를 보여줍니다.", descriptionEn: "Show the current location and its parent pages.", usage: "상위 경로에는 링크를 제공하고, 현재 페이지는 링크 없이 구분합니다.", usageEn: "Link to parent pages and distinguish the current page without a link.", }, "back-to-top": { description: "스크롤한 콘텐츠의 시작으로 돌아갑니다.", descriptionEn: "Return to the beginning of scrolled content.", usage: "위쪽 화살표로 이동 방향을 알리고 스크롤할 때 접근하기 쉽게 배치합니다.", usageEn: "Use an upward arrow and keep the control accessible while scrolling.", }, "classic-tabs": { description: "같은 맥락의 화면을 탭으로 전환합니다.", descriptionEn: "Switch between related views using tabs.", usage: "현재 선택된 탭을 하단 막대로 구분합니다.", usageEn: "Mark the selected tab with a bottom indicator.", }, button: { description: "명령을 실행하거나 다음 단계로 이동하는 기본 액션입니다.", descriptionEn: "A basic action for running commands or moving to the next step.", usage: "주요 액션은 기본 버튼, 보조 액션은 Outline이나 Secondary로 구분합니다. 실행할 수 없는 액션은 비활성 상태로 표시합니다.", usageEn: "Use default for primary actions and Outline or Secondary for supporting actions. Disable unavailable actions.", }, input: { description: "사용자가 텍스트를 입력하고 수정하는 필드입니다.", descriptionEn: "A field for entering and editing text.", usage: "항상 명확한 라벨을 제공하고, 입력 형식과 오류를 설명합니다. 플레이스홀더는 라벨을 대신하지 않습니다.", usageEn: "Provide a clear label and explain input formats and errors. A placeholder does not replace a label.", }, select: { description: "미리 정의된 선택지 중 하나를 선택합니다.", descriptionEn: "Choose one option from a predefined list.", usage: "선택지가 제한되어 있을 때 사용합니다. 현재 선택을 표시하고, 키보드로 열기·이동·선택할 수 있게 합니다.", usageEn: "Use for a finite list of choices. Show the selection and support keyboard navigation.", }, checkbox: { description: "여러 선택지에서 원하는 항목을 각각 선택하거나 해제합니다.", descriptionEn: "Select or deselect independent options from a list.", usage: "여러 항목을 동시에 선택할 수 있을 때 사용합니다. 각 항목에 명확한 라벨을 제공하고, 선택 여부를 체크 표시로 구분합니다.", usageEn: "Use when multiple options can be selected. Provide a clear label for each option and distinguish selection with a checkmark.", }, "radio-group": { description: "서로 배타적인 선택지 중 하나를 선택합니다.", descriptionEn: "Choose one option from a mutually exclusive set.", usage: "한 번에 하나만 선택해야 할 때 사용합니다. 관련 선택지를 묶고, 모든 선택지를 보여주어 바로 비교할 수 있게 합니다.", usageEn: "Use when exactly one option should be selected. Group related options and show all choices for immediate comparison.", }, slider: { description: "연속적인 범위에서 값을 조절합니다.", descriptionEn: "Adjust a value within a continuous range.", usage: "볼륨이나 밝기처럼 상대적인 값 조절에 사용합니다. 현재 값을 표시하고, 정밀한 입력이 필요하면 입력 필드를 함께 제공합니다.", usageEn: "Use for relative values like volume. Show the current value and provide an input when precision is needed.", }, switch: { description: "설정을 켜거나 끄는 두 가지 상태의 입력 요소입니다.", descriptionEn: "A binary control for turning a setting on or off.", usage: "알림처럼 변경이 즉시 적용되는 설정에 사용합니다. 라벨은 설정 이름으로 유지하고, 켜짐과 꺼짐은 위치와 색으로 함께 구분합니다.", usageEn: "Use for settings that take effect immediately, such as notifications. Keep the setting name as the label and distinguish on and off through both position and color.", }, card: { description: "관련 정보와 액션을 하나의 주제로 묶습니다.", descriptionEn: "Group related information and actions around one topic.", usage: "제목·설명·내용·액션의 위계를 유지합니다. 서로 다른 주제는 나누고 카드 안에 카드를 중첩하지 않습니다.", usageEn: "Maintain a clear hierarchy of title, description, content, and actions. Avoid nesting cards.", }, "bottom-sheet": { description: "화면 아래에서 보조 작업이나 선택지를 엽니다.", descriptionEn: "Open supporting tasks or choices from the bottom of the screen.", usage: "짧은 선택이나 보조 작업에 사용합니다. 제목과 닫기 수단을 제공하고, 긴 내용은 시트 안에서 스크롤합니다.", usageEn: "Use for short choices or supporting tasks. Provide a title, dismissal controls, and scrolling for long content.", }, tabs: { description: "같은 맥락의 콘텐츠 패널을 전환합니다.", descriptionEn: "Switch between related content panels.", usage: "세그먼트 이름을 짧고 명확하게 유지합니다. 독립된 문서 페이지로 이동하는 용도에는 링크를 사용합니다.", usageEn: "Keep tab labels concise. Use links to navigate to independent document pages.", }, pagination: { description: "여러 페이지로 나뉜 결과를 탐색합니다.", descriptionEn: "Navigate through results split across pages.", usage: "현재 페이지와 이전·다음 이동을 명확하게 표시합니다. 첫 페이지와 마지막 페이지에서는 해당 이동을 비활성화합니다.", usageEn: "Show the current page and previous/next controls. Disable controls at the first and last pages.", }, "dot-pagination": { description: "이미지 캐러셀에서 현재 위치와 전체 이미지 수를 점으로 표시합니다.", descriptionEn: "Show the current position and image count in an image carousel using dots.", usage: "이미지가 적을 때 사용합니다. 선택된 점을 명확하게 구분하고, 점을 누르면 해당 이미지로 이동합니다.", usageEn: "Use for a small set of images. Clearly distinguish the active dot and let each dot navigate to its image.", }, filter: { description: "조건을 선택해 표시할 결과를 좁힙니다.", descriptionEn: "Narrow visible results by selecting conditions.", usage: "선택 상태와 결과 수를 함께 표시합니다. 조건을 해제하거나 전체 결과로 돌아갈 수 있어야 합니다.", usageEn: "Show selected conditions and the result count. Allow conditions to be cleared.", }, badge: { description: "상태나 짧은 보조 정보를 표시합니다.", descriptionEn: "Display a status or short supporting information.", usage: "상태 이름은 짧게 작성합니다. 색상만으로 의미를 전달하지 말고 텍스트를 함께 사용합니다.", usageEn: "Keep status labels concise. Pair color with text rather than relying on color alone.", }, tag: { description: "콘텐츠의 주제나 적용된 조건을 표시합니다.", descriptionEn: "Label content topics or applied conditions.", usage: "뱃지는 상태, 태그는 분류나 조건에 사용합니다. 제거할 수 있는 태그에는 이름이 있는 삭제 버튼을 제공합니다.", usageEn: "Use badges for status and tags for categories or conditions. Give removable tags a named removal button.", }, avatar: { description: "사람이나 팀을 작은 시각 요소로 식별합니다.", descriptionEn: "Identify a person or team with a compact visual.", usage: "이미지를 사용할 수 없을 때 이니셜을 표시합니다. 이름을 함께 제공해 이미지에만 의존하지 않습니다.", usageEn: "Show initials when an image is unavailable. Provide a name alongside the avatar.", }, progress: { description: "시스템 응답을 기다리는 동안 로딩 상태를 표시합니다.", descriptionEn: "Show a loading state while waiting for the system to respond.", usage: "진행률을 알 수 없는 대기 상태에는 반복 애니메이션을 사용합니다. 응답이 도착하면 로딩 표시를 제거합니다.", usageEn: "Use a looping animation when progress is unknown. Remove the loading indicator when the response arrives.", }, dialog: { description: "현재 페이지에서 짧은 편집 작업을 처리합니다.", descriptionEn: "Handle a focused editing task on the current page.", usage: "저장은 변경을 반영하고, 취소나 Escape는 변경 없이 닫습니다. 명확한 제목과 설명을 제공합니다.", usageEn: "Save applies changes. Cancel and Escape close without changes. Provide a clear title and description.", }, "alert-dialog": { description: "현재 작업을 막지 않고 화면 한쪽에서 사용자의 판단을 요청합니다.", descriptionEn: "Ask for a decision alongside the current task without blocking it.", usage: "쿠키 권한처럼 즉시 응답하지 않아도 되는 선택에 사용합니다. 배경 작업을 유지하고 선택지는 명확하게 구분합니다.", usageEn: "Use for non-urgent decisions such as cookie preferences. Keep background tasks available and distinguish choices clearly.", }, } export const foundationDocs = [ { category: "elements", slug: "writing", title: "글", titleEn: "Writing", group: "Elements", description: "사용자가 상태와 다음 행동을 이해할 수 있는 문장을 작성합니다.", descriptionEn: "Write content that helps people understand the current state and next action.", rules: [ "버튼은 실행할 행동을 구체적으로 설명합니다.", "오류는 문제와 해결 방법을 함께 안내합니다.", "같은 기능은 같은 단어로 표현합니다.", ], rulesEn: [ "Button labels describe the action.", "Errors explain the problem and recovery.", "Use consistent words for the same function.", ], }, { category: "composition", slug: "layers", title: "레이어", titleEn: "Layers", group: "Composition", description: "배경, 콘텐츠, 오버레이의 깊이를 구분합니다.", descriptionEn: "Distinguish the depth of backgrounds, content, and overlays.", rules: [ "기본 콘텐츠보다 팝오버와 다이얼로그를 위에 배치합니다.", "오버레이는 배경 작업과 현재 작업을 구분합니다.", "레이어가 닫히면 원래 컨트롤로 포커스를 돌려줍니다.", ], rulesEn: [ "Place popovers and dialogs above base content.", "Use overlays to separate the current task.", "Restore focus when a layer closes.", ], }, { category: "composition", slug: "organization", title: "조직화", titleEn: "Organization", group: "Composition", description: "관련 정보를 묶고 중요도에 따라 순서를 정합니다.", descriptionEn: "Group related information and order it by importance.", rules: [ "관련된 항목은 가까이 배치합니다.", "제목, 설명, 액션의 위계를 유지합니다.", "반복되는 그룹은 동일한 구조로 구성합니다.", ], rulesEn: [ "Keep related items close together.", "Maintain a hierarchy of title, description, and actions.", "Give repeated groups the same structure.", ], }, { category: "composition", slug: "layout", title: "레이아웃", titleEn: "Layout", group: "Composition", description: "화면 크기에 맞춰 콘텐츠의 정렬과 간격을 조절합니다.", descriptionEn: "Adapt content alignment and spacing to the screen size.", rules: [ "간격은 4px 기준의 일관된 단계로 사용합니다.", "좁은 화면에서는 읽는 순서를 유지하며 세로로 배치합니다.", "긴 텍스트가 컨트롤을 밀어내거나 겹치지 않게 합니다.", ], rulesEn: [ "Use consistent spacing based on a 4px grid.", "Stack content on narrow screens without changing reading order.", "Prevent long text from overlapping controls.", ], }, { category: "interaction", slug: "information-architecture", title: "정보 구조", titleEn: "Information architecture", group: "Interaction", description: "사용자가 원하는 내용을 찾을 수 있도록 탐색 경로를 설계합니다.", descriptionEn: "Design navigation paths that help people find what they need.", rules: [ "왼쪽 메뉴는 독립된 페이지 이동에 사용합니다.", "오른쪽 목차는 현재 페이지 안의 섹션 이동에 사용합니다.", "현재 위치와 선택 상태를 명확히 표시합니다.", ], rulesEn: [ "Use left navigation for independent pages.", "Use the right table of contents for sections on the current page.", "Show the current location and selection.", ], }, { category: "interaction", slug: "input-output", title: "입력과 출력", titleEn: "Input and output", group: "Interaction", description: "사용자의 입력에 명확한 상태와 결과로 응답합니다.", descriptionEn: "Respond to user input with clear states and outcomes.", rules: [ "입력 필드에 라벨과 필요한 형식을 제공합니다.", "저장, 오류, 완료 상태를 즉시 안내합니다.", "키보드와 보조 기술로 같은 작업을 수행할 수 있게 합니다.", ], rulesEn: [ "Provide labels and input formats.", "Communicate saving, errors, and completion promptly.", "Support the same tasks with keyboard and assistive technology.", ], }, ] export const catalogTranslations = Object.fromEntries([ ...Object.entries(extendedCatalogTranslations), ...Object.values(componentDetails).flatMap((item) => [ [item.description, item.descriptionEn], [item.usage, item.usageEn], ]), ...foundationDocs.flatMap((item) => [ [item.title, item.titleEn], [item.description, item.descriptionEn], ...item.rules.map((rule, index) => [rule, item.rulesEn[index]]), ]), ]) ```