Developer

JunDS

레고처럼 조합하는 프로덕션 레디 React 디자인 프레임워크

2026.04 ~

TypeScriptReactDesign SystemTailwind v4MCPa11y

190개컴포넌트

29개훅

476개 통과테스트

무엇을 만들었나

JunDS는 토큰 기반으로 화면을 레고처럼 조합하는 프로덕션 레디 React 디자인 시스템입니다. Box·Flex·Page·Heading·Text 프레임워크 코어 위에 190개 컴포넌트(38 Primitives · 117 Composites · 24 Patterns · 11 Layout)와 29개 커스텀 훅을 얹었습니다. 접근성이 내장되어 있고(a11y 위반 0건), 476개 테스트로 검증되며, AI 에디터가 컴포넌트를 정확히 조회하도록 MCP 서버를 내장합니다.

라이브 컴포넌트 갤러리

설명이 아니라 실물입니다. 첫 화면 카탈로그 탭에는 JunDS에 존재하는 모든 컴포넌트(190개)와 훅(29개)이 하나도 빠짐없이 나열되며, ● 표시된 항목은 이 페이지에서 곧바로 조작할 수 있습니다. 전체 탭이나 카테고리 탭에서는 버튼을 눌러 토스트를 띄우고, 스위치·슬라이더·별점을 조작하고, 모달·드로어·바텀시트를 열고, 테이블을 정렬하고, ⌘K로 커맨드 팔레트를 띄워 보세요. 상단 테마 바에서 액센트·라이트/다크·밀도·모서리 반경을 바꾸면 갤러리 전체가 실시간으로 반응합니다 — 이것이 JunDS 토큰 시스템의 실제 동작입니다.

설치

# JunDS는 Tailwind CSS v4를 peer로 사용합니다.
npm install @junds/ui tailwindcss @tailwindcss/postcss
npm install --save-dev react react-dom   # 18+복사

또는 npx create-junds my-app 한 줄로 아래 설정이 모두 적용된 starter를 즉시 생성합니다.

5분 시작

1) 글로벌 스타일 import

/* app/globals.css */
@import "tailwindcss";
@import "@junds/ui/styles.css";복사

2) Provider로 앱 감싸기

JunDSProvider는 라이선스 키를 받아 테마·밀도·반경 등 디자인 토큰을 트리에 주입합니다.

// app/providers.tsx
"use client";
import { JunDSProvider } from "@junds/ui";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <JunDSProvider licenseKey={process.env.NEXT_PUBLIC_JUNDS_LICENSE_KEY ?? ""}>
      {children}
    </JunDSProvider>
  );
}복사

3) 첫 컴포넌트 사용

import { Button, Card } from "@junds/ui";

export default function Home() {
  return (
    <Card hoverable>
      <Card.Header>환영합니다</Card.Header>
      <Card.Body>
        <Button variant="primary">시작하기</Button>
      </Card.Body>
    </Card>
  );
}복사

asChild 합성 (Slot 패턴)

Radix-style asChild prop으로 root 엘리먼트를 원하는 element(<Link>, <a> 등)로 위임합니다. 디자인 시스템 스타일은 그대로 유지됩니다.

import Link from "next/link";
import { Button, Card } from "@junds/ui";

// 카드 전체를 링크로 위임 — 영역 전체가 클릭 가능
<Card asChild hoverable>
  <Link href="/profile"><Card.Body>프로필로 이동</Card.Body></Link>
</Card>

// 버튼을 a 태그로 위임 — leftIcon/loading은 자동 합쳐집니다
<Button asChild variant="primary" leftIcon={<PlusIcon />}>
  <a href="/new">새로 만들기</a>
</Button>복사

반응형 Props

브레이크포인트별 값을 객체로 넘겨 반응형을 제어합니다.

<Box
  p={{ base: 2, md: 4, lg: 6 }}
  display={{ base: "block", md: "flex" }}
  fontSize={{ base: "sm", md: "md" }}
>
  Responsive content
</Box>

<SimpleGrid cols={{ base: 1, md: 2, lg: 3 }} gap="lg">
  <Card>...</Card>
</SimpleGrid>복사

테마 시스템

18개 빌트인 프리셋과 커스텀 색상, 다크 모드, 밀도/반경/간격 전역 제어를 제공합니다.

// 18개 프리셋 중 선택 또는 커스텀 HEX
<JunDSProvider theme="purple" />
<JunDSProvider theme="#e11d48" />

// 전역 제어
<JunDSProvider
  theme="purple"
  colorMode="system"   // light | dark | system
  density="normal"     // compact | normal | comfortable
  radius="md"
/>복사

아키텍처

토큰·테마 위에 프레임워크 코어를 두고, 그 위로 Primitives → Composites → Patterns가 쌓이는 5층 구조입니다.

Patterns (24)         DataTable, FormWizard, Calendar, Kanban...
Composites (117)      Modal, Tabs, Select, Toast, Drawer...
Primitives (38)       Button, Input, Badge, Avatar, Toggle...
Framework Core (15)   Box, Flex, Page, Heading, Text...
Tokens & Theme        Colors, Spacing, Typography...복사

컴포넌트 카탈로그

Primitives (38)

Button, Input, Textarea, Badge, Avatar, Spinner, Toggle, Checkbox, Radio, Switch, Slider, Tag, IconButton, NumberInput, FileUpload, CopyButton, PasswordInput, PinInput, OTPInput, CurrencyInput, PhoneInput, RangeSlider, StarRating, StatusDot, Divider, Portal, ScrollArea, ErrorBoundary, VisuallyHidden 등.

Composites (117)

Modal, Tabs, Select, Toast, Drawer, Card, Alert, Accordion, Breadcrumb, Pagination, Tooltip, Popover, Dropdown, Combobox, MultiSelect, Timeline, Stepper, Table, Carousel, TreeView, DataGrid, MetricCard, JSONViewer, CodeEditor, TagInput, SearchInput, SignaturePad, Marquee, Confetti, InlineEdit, Globe, GaugeChart, MarkdownViewer, EmojiPicker, QRCode, ImageCropper, VideoPlayer, ChatBubble, BottomSheet 등.

Patterns (24)

DataTable(25기능), FormWizard, FormArray, Form, FilterBar, CommandPalette, Sidebar, Calendar, Kanban, StatsGrid, FormBuilder, InfiniteList, VirtualList, RichTextEditor, Tour, FlowDiagram, MasonryGrid, LoginForm, SecurityChecklist 등.

Hooks (29)

useForm, useClickOutside, useKeyboard, useMediaQuery, useLocalStorage, useDebounce, useCopyToClipboard, useDisclosure, useBreakpoint, useReducedMotion, useScrollSpy, useIntersectionObserver, useCountUp, useIdle, useNetworkStatus, useLongPress, useElementSize, useSteps, useInterval 등.

품질 · 접근성

• 접근성 내장 — ARIA·키보드 네비게이션·Focus Trap·Reduced Motion, a11y 위반 0건
• 476개 테스트 — Vitest + Testing Library (415 unit + 61 a11y audit)
• Tree-shaking — ESM/CJS 듀얼 빌드, sideEffects: false
• 18개 테마 프리셋 — 다크 모드 + 밀도/반경/간격 전역 토큰

AI 에디터 연동 (MCP)

저장소를 AI 에디터로 열면 루트의 .mcp.json이 자동 픽업되어, 14개 도구로 컴포넌트 prop 시그니처·접근성 보고서·레시피를 AI가 직접 조회해 hallucination 없이 코드를 만듭니다.

{
  "mcpServers": {
    "junds": { "command": "node", "args": ["mcp/server.mjs"] }
  }
}복사

주요 도구: locate(자연어 컴포넌트 랭킹), get_component_props(한국어 JSDoc prop), list_recipes·read_recipe(앱 레벨 조합 템플릿), scaffold(컴포넌트·훅·레시피 자동 생성), get_a11y·get_bundle_info 등.

링크

• RepositoryGitHub