@mondrianai/runyourai-design-system
v0.0.13
Published
RunyourAI Design System
Maintainers
mondrianaiReadme
@mondrianai/runyourai-design-system
RunYourAI Design System — React component library built on shadcn/ui components, Radix UI primitives, and Tailwind CSS v4.
Requirements
- React 18+
- Next.js 15+
- Tailwind CSS v4
Installation
npm install @mondrianai/runyourai-design-system
# or
yarn add @mondrianai/runyourai-design-systemLocal Development (yalc)
소비 앱에서 로컬 빌드를 테스트할 때는 yalc를 사용합니다.
# 최초 1회: 소비 앱에 yalc 연결
# (design system 레포에서)
yalc publish
# (소비 앱 레포에서)
yalc add @mondrianai/runyourai-design-system
# 이후 변경사항 반영 시 (design system 레포에서)
npm run build && yalc push
# 소비 앱 dev 서버 재시작 필요주의:
sidebar.tsx,button.tsx등 컴포넌트 소스를 수정한 경우, 반드시npm run build && yalc push를 실행해야 소비 앱에 변경사항이 반영됩니다. 소스 파일을 수정해도 소비 앱의 dev server hot-reload만으로는 dist가 갱신되지 않습니다.
Setup
1. 패키지 설치
npm install @mondrianai/runyourai-design-system tailwindcss
npm install --save-dev @tailwindcss/postcss
# or
yarn add @mondrianai/runyourai-design-system tailwindcss
yarn add --dev @tailwindcss/postcss2. PostCSS 설정
프로젝트 루트에 postcss.config.mjs를 생성합니다.
// postcss.config.mjs
const config = {
plugins: {
'@tailwindcss/postcss': {},
},
};
export default config;3. Next.js (Turbopack) 설정
Next.js 15+ / 16의 기본 번들러인 Turbopack은 CSS @import에서 package.json의 exports 서브패스를 해석하지 못합니다. next.config.ts에 아래 resolveAlias를 추가해야 합니다.
// next.config.ts
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
turbopack: {
resolveAlias: {
'@mondrianai/runyourai-design-system/styles':
'./node_modules/@mondrianai/runyourai-design-system/dist/styles/index.css',
'@mondrianai/runyourai-design-system/tailwind-theme':
'./node_modules/@mondrianai/runyourai-design-system/dist/styles/tailwind-theme.css',
},
},
};
export default nextConfig;Turbopack을 사용하지 않는 경우(webpack 기반 커스텀 설정 등)에는 이 단계를 건너뜁니다.
4. Tailwind CSS 설정
globals.css에 아래 내용을 추가합니다. 디자인 토큰, Tailwind 테마, 애니메이션, 다크모드 설정이 모두 적용됩니다.
/* globals.css */
@import 'tailwindcss';
@import '@mondrianai/runyourai-design-system/styles';
@import '@mondrianai/runyourai-design-system/tailwind-theme';
/* globals.css 위치 기준 node_modules 상대 경로 — 프로젝트 구조에 따라 조정하세요
* globals.css가 app/globals.css 에 있는 경우: ../node_modules/...
* globals.css가 src/app/globals.css 에 있는 경우: ../../node_modules/...
*/
@source "../node_modules/@mondrianai/runyourai-design-system/dist";
@import순서 주의
url(...)형태의 외부 폰트 import가 있다면@import 'tailwindcss'앞에 위치시킵니다.@mondrianai/runyourai-design-system/styles,@mondrianai/runyourai-design-system/tailwind-theme는@import 'tailwindcss'뒤에 위치시킵니다.
디자인 토큰 오버라이드 주의
:root에서 디자인 시스템 CSS 변수를 오버라이드할 때, 컴포넌트 표면색 토큰(--background,--card,--popover등)을 페이지 배경색 설정 목적으로 변경하면 안 됩니다. 이 변수들은Buttonoutline,Card,Popover등 컴포넌트의 배경색에 직접 사용됩니다.페이지 배경색은 CSS 토큰 오버라이드 대신
html/body에 직접 지정하세요./* ❌ 잘못된 예 — Button outline 등 컴포넌트 배경색까지 바뀜 */ :root { --background: #fdfdfd; } /* ✅ 올바른 예 — 페이지 배경만 변경, 컴포넌트 토큰 무영향 */ html, body { background-color: #fdfdfd; }
기존 CSS 리셋 주의 (Tailwind v4) 프로젝트에
* { margin: 0; padding: 0; }같은 전역 리셋이 있다면 반드시@layer base로 감싸야 합니다. Tailwind v4에서 레이어 밖의 스타일은@layer utilities보다 우선순위가 높아px-*,py-*등의 유틸리티 클래스가 무효화됩니다.@layer base { *, *::before, *::after { box-sizing: border-box; } * { margin: 0; padding: 0; } }
5. Provider 설정
Tooltip 등 Radix UI 기반 컴포넌트가 올바르게 동작하려면 앱 최상단에 Providers를 감싸야 합니다.
// app/layout.tsx
import { Providers } from '@mondrianai/runyourai-design-system';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang='ko'>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}Usage
import { Button, Badge, Card } from '@mondrianai/runyourai-design-system';
export default function Page() {
return (
<Card>
<Badge text='New' />
<Button onClick={() => console.log('clicked')}>시작하기</Button>
</Card>
);
}Utilities
import { cn } from '@mondrianai/runyourai-design-system/utils';
<div className={cn('base-class', isActive && 'active-class')} />;Components
| Component | Description |
| ------------------------------------- | ------------------------- |
| Accordion | 펼침/접힘 컨텐츠 영역 |
| AlertDialog | 확인/취소 모달 다이얼로그 |
| Alert | 인라인 알림 메시지 |
| Avatar / AvatarGroup | 유저 아바타 및 그룹 |
| Badge | 상태·카테고리 배지 |
| Breadcrumb | 페이지 경로 탐색 |
| Button | 버튼 |
| Card | 카드 컨테이너 |
| Checkbox / CheckboxCard | 체크박스 |
| ChoiceCardGroup / ChoiceCardItem | 선택형 카드 그룹 |
| Collapsible | 접을 수 있는 컨텐츠 |
| Combobox | 검색 가능한 선택 입력 |
| Field / FieldSection / FieldRow | 폼 필드 레이아웃 |
| GroupedSelect | 그룹 구분이 있는 셀렉트 |
| Header | 앱 상단 헤더 |
| Icon | Lucide 아이콘 래퍼 |
| MarkdownMessage | 마크다운 렌더링 메시지 |
| Menubar | 메뉴바 |
| MessageFooter | 메시지 하단 액션 영역 |
| NumberBadge | 숫자 배지 |
| SegmentedControl | 세그먼트 탭 컨트롤 |
| Select | 셀렉트 박스 |
| Sheet | 사이드 슬라이드 패널 |
| Sidebar | 앱 사이드바 |
| Slider | 슬라이더 |
| Stepper | 단계 진행 표시 |
| Switch / SwitchField | 토글 스위치 |
| Tooltip / TooltipWithIcon | 툴팁 |
| UserMessageBubble | 채팅 메시지 말풍선 |
Icons
Custom Icons
import {
SparklesIcon,
TrashIcon,
StarIcon,
} from '@mondrianai/runyourai-design-system';
<SparklesIcon className='size-4 text-primary' />;Brand Icons
import {
ClaudeIcon,
OpenAiIcon,
GeminiIcon,
} from '@mondrianai/runyourai-design-system';
<ClaudeIcon className='size-6' />;Logo
import { RyaiLogoIcon } from '@mondrianai/runyourai-design-system';
<RyaiLogoIcon />;