@ubittz/native-design-system

React Native 디자인 시스템 (NativeWind 기반)

설치

yarn add @ubittz/native-design-system

Peer Dependencies

yarn add react react-native nativewind tailwindcss

프로젝트 초기 세팅

1. Tailwind 설정

프로젝트 루트의 tailwind.config.ts에서 디자인 시스템의 preset을 확장합니다.

// tailwind.config.ts
import type { Config } from "tailwindcss";
import designSystemConfig from "@ubittz/native-design-system/tailwind.config";

const config: Config = {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  presets: [designSystemConfig],
  theme: {
    extend: {
      // 프로젝트별 커스텀 토큰 추가 가능
    },
  },
};

export default config;

2. Provider 설정

앱 최상위에 DesignSystemProvider를 감싸줍니다. locale에 따라 Typography 토큰이 자동 전환됩니다.

import { DesignSystemProvider } from "@ubittz/native-design-system";

export default function App() {
  return (
    <DesignSystemProvider locale="ko">
      {/* 앱 콘텐츠 */}
    </DesignSystemProvider>
  );
}

| locale | 설명 | | ------ | --------------- | | ko | 한국어 (기본값) | | en | 영어 |

토큰 오버라이드

DesignSystemProvider의 tokens prop을 통해 모든 디자인 토큰을 프로젝트별로 오버라이드할 수 있습니다. 오버라이드하지 않은 값은 기본값이 유지됩니다.

import { DesignSystemProvider, colorTokens } from "@ubittz/native-design-system";

export default function App() {
  return (
    <DesignSystemProvider
      locale="ko"
      tokens={{
        colors: {
          semanticColors: {
            brand: { primary: colorTokens.baseColors.apple },
          },
        },
        spacing: { md: "20px" },
        height: { "button-md": "44px" },
        borderRadius: { "button-default": "8px" },
        fontWeight: { bold: "800" },
      }}
    >
      {/* 앱 콘텐츠 */}
    </DesignSystemProvider>
  );
}

색상 토큰 오버라이드

색상 토큰은 baseColors → semanticColors → componentColors 순으로 파생됩니다. 상위 레벨을 오버라이드하면 하위 파생값이 자동으로 갱신됩니다.

baseColors 오버라이드

가장 상위 레벨입니다. 기본 팔레트를 변경하면 이를 참조하는 semantic, component 색상이 모두 재계산됩니다.

tokens={{
  colors: {
    baseColors: { sky: colorTokens.baseColors.apple },
  },
}}

semanticColors 오버라이드

brand를 오버라이드하면 surface.brandPrimary, text.brand, border.brand 등 brand에서 파생되는 semantic 값이 자동으로 갱신되고, 이를 참조하는 componentColors(버튼, 인풋 등)도 함께 반영됩니다.

tokens={{
  colors: {
    semanticColors: {
      brand: { primary: colorTokens.baseColors.coral },
    },
  },
}}

개별 semantic 값을 직접 오버라이드할 수도 있습니다.

tokens={{
  colors: {
    semanticColors: {
      text: { default: { primary: "#111111" } },
      surface: { default: { brandPrimary: "#FF0000" } },
    },
  },
}}

componentColors 오버라이드

특정 컴포넌트의 색상만 변경하고 싶을 때 사용합니다.

tokens={{
  colors: {
    componentColors: {
      button: {
        primary: { background: "#FF0000", label: "#FFFFFF" },
      },
    },
  },
}}

팩토리 함수

각 토큰 모듈은 createXxxTokens 팩토리 함수를 제공합니다. Provider 외부에서 직접 사용할 수도 있습니다.

import {
  createColorTokens,
  createSpacingTokens,
  createHeightTokens,
  createBorderRadiusTokens,
  createFontWeightTokens,
} from "@ubittz/native-design-system";

const customColors = createColorTokens({
  semanticColors: { brand: { primary: colorTokens.baseColors.apple } },
});

const customSpacing = createSpacingTokens({ md: "20px" });

Tokens

디자인 토큰을 직접 import하여 사용할 수 있습니다.

import {
  colorTokens,
  spacing,
  height,
  borderRadius,
  fontWeight,
  typography,
} from "@ubittz/native-design-system";

색상 토큰 구조

| 레벨 | 토큰 | 설명 | | --- | --- | --- | | Base | colorTokens.baseColors | 기본 컬러 팔레트 (gray, coral, apple, sky 등) | | Semantic | colorTokens.semanticColors.brand | 브랜드 컬러 (primary, secondary) | | | colorTokens.semanticColors.text | 텍스트 컬러 (default, inverse 모드별) | | | colorTokens.semanticColors.surface | 면/배경 컬러 | | | colorTokens.semanticColors.border | 선/구분선 컬러 | | | colorTokens.semanticColors.icon | 아이콘 컬러 | | | colorTokens.semanticColors.systemState | 시스템 상태 컬러 (success, info, warning, error) | | Component | colorTokens.componentColors.button | 버튼 컬러 | | | colorTokens.componentColors.input | 인풋 컬러 | | | colorTokens.componentColors.navigation | 네비게이션 컬러 | | | colorTokens.componentColors.modal | 모달 컬러 | | | colorTokens.componentColors.filter | 필터 컬러 | | | colorTokens.componentColors.toggle | 토글 컬러 |

기타 토큰

| 토큰 | 설명 | | --- | --- | | spacing | 간격 (xs~3xl) | | height | 높이 (버튼, 인풋 등 컴포넌트별) | | borderRadius | 모서리 라운딩 (버튼, 인풋, 모달 등 컴포넌트별) | | fontWeight | 폰트 두께 (regular, medium, semibold, bold) | | typography | 언어별 타이포그래피 스타일 (ko, en) |

아이콘

SVG 파일에서 React Native 아이콘 컴포넌트를 자동 생성합니다.

아이콘 생성

yarn generate:icons

src/assets/icons/ 하위에 SVG 파일을 배치하면 자동으로 react-native-svg 기반 컴포넌트가 생성됩니다. 폴더 구조가 그대로 namespace export에 반영됩니다.

사용법

import { Default, Round } from "@ubittz/native-design-system";

<Default.Solid.Heart size={24} color="red" />
<Default.Stroke.Search size={20} color="#333" />
<Round.Solid.Home size={28} color="blue" />

폴더 구조 → Export 매핑

| assets 경로 | 사용법 | |---|---| | icons/Default/Solid/Heart.svg | Default.Solid.Heart | | icons/Default/Stroke/Search.svg | Default.Stroke.Search | | icons/Round/Solid/Home.svg | Round.Solid.Home | | icons/Logo.svg (루트) | Root.Logo |

폴더를 추가/삭제/이름변경 후 yarn generate:icons만 실행하면 전체 export 체인이 자동 반영됩니다.

소비 프로젝트에서 아이콘 생성

이 패키지를 설치한 프로젝트에서도 동일한 아이콘 생성 파이프라인을 사용할 수 있습니다:

# 기본 경로 (src/assets/icons → src/components/Icons)
npx ubittz-icons

# 커스텀 경로
npx ubittz-icons --input src/icons --output src/components/Icons

# components/index.ts 자동 동기화
npx ubittz-icons --input src/icons --output src/components/Icons --components-index src/components/index.ts

| 옵션 | 설명 | 기본값 | |---|---|---| | --input <dir> | SVG 소스 디렉토리 | src/assets/icons | | --output <dir> | 출력 Icons 디렉토리 | src/components/Icons | | --components-index <file> | export 자동 동기화할 index.ts | (없음) |

첫 실행 시 types.ts와 Icon.tsx가 자동 생성됩니다.

IconProps

| prop | 타입 | 기본값 | 설명 | |---|---|---|---| | size | number | 24 | 아이콘 크기 (px) | | color | string | "currentColor" | 아이콘 색상 | | style | StyleProp<ViewStyle> | - | 추가 스타일 |

컴포넌트

Typography

import { Typography } from "@ubittz/native-design-system";

<Typography variant="Body1">본문 텍스트</Typography>
<Typography.Heading1>제목</Typography.Heading1>
<Typography.Body2 color="#333">본문</Typography.Body2>

Button

import { Button } from "@ubittz/native-design-system";

<Button variant="primary" size="Medium">확인</Button>
<Button variant="ghost" size="Small" shape="round">취소</Button>
<Button variant="secondary" fullWidth>전체 너비</Button>

| prop | 타입 | 기본값 | 설명 | | --- | --- | --- | --- | | variant | "primary" | "secondary" | "ghost" | "gray" | "outline" | "success" | "info" | "warning" | "error" | "primary" | 버튼 스타일 | | size | "ExtraSmall" | "Small" | "Medium" | "Large" | "XLarge" | "Medium" | 버튼 크기 | | shape | "default" | "square" | "semiRound" | "round" | "default" | 모서리 형태 | | fullWidth | boolean | false | 전체 너비 사용 | | disabled | boolean | false | 비활성화 | | iconFront | ReactNode | - | 앞쪽 아이콘 | | iconBack | ReactNode | - | 뒤쪽 아이콘 |

TextField

import { TextField } from "@ubittz/native-design-system";

<TextField placeholder="입력" />
<TextField shape="line" isError />
<TextField button={{ children: "인증", variant: "primary" }} />

| prop | 타입 | 기본값 | 설명 | | --- | --- | --- | --- | | shape | "default" | "line" | "default" | 인풋 형태 | | isError | boolean | false | 에러 상태 | | disabled | boolean | false | 비활성화 | | rightElement | ReactNode | - | 우측 요소 | | button | ButtonProps | - | 부착 버튼 |

유틸리티

import { cn } from "@ubittz/native-design-system";

// tailwind-merge 기반 클래스 병합
<View className={cn("p-4", isActive && "bg-primary-500")} />;

폴더 구조

src/
├── assets/
│   └── icons/                    ← SVG 소스 (자유 구조)
│       ├── Default/
│       │   ├── Solid/*.svg
│       │   └── Stroke/*.svg
│       └── Round/
│           ├── Solid/*.svg
│           └── Stroke/*.svg
├── components/
│   ├── Icons/
│   │   ├── Icon.tsx              ← createIcon 헬퍼 (수동 관리)
│   │   ├── types.ts              ← IconProps (수동 관리)
│   │   ├── index.ts              ← 자동 생성
│   │   └── generated/            ← 전부 자동 생성 (수동 편집 금지)
│   ├── Typography/
│   ├── Buttons/
│   ├── TextField/
│   ├── Checkbox/
│   └── Popup/
├── providers/
│   └── DesignSystemProvider.tsx
├── tokens/
│   ├── colors/
│   │   ├── constants/
│   │   │   ├── base.ts
│   │   │   ├── semantic.ts
│   │   │   ├── components.ts
│   │   │   └── index.ts
│   │   └── index.ts
│   ├── spacing/
│   ├── height/
│   ├── borderRadius/
│   ├── fontWeight/
│   ├── typography/
│   └── index.ts
├── utils/
│   └── cn.ts
└── index.ts

스크립트

yarn build           # 빌드
yarn dev             # 워치 모드 빌드
yarn typecheck       # 타입 체크
yarn lint            # ESLint 검사
yarn clean           # dist 폴더 삭제
yarn generate:icons  # SVG → RN 아이콘 컴포넌트 자동 생성