@reco-inc/upbox-ui

@reco-inc/upbox-ui

Upbox Design System - Vue 3 Component Library

Storybook

Live Storybook — 컴포넌트 데모와 props 문서.

로컬에서 띄우려면:

pnpm storybook   # localhost:6006

Installation

# npm
npm install @reco-inc/upbox-ui

# pnpm
pnpm add @reco-inc/upbox-ui

저장소는 private 이지만 패키지는 npm public 레지스트리에 배포되므로, 설치에 별도 인증이 필요 없다.

Setup (Tailwind v4)

1. CSS Import

/* style.css */
@import "tailwindcss";
@import "@reco-inc/upbox-ui/style.css";   /* 컴파일된 라이브러리 CSS */
@import "@reco-inc/upbox-ui/theme.css";   /* @theme 토큰 등록 */
@source "../node_modules/@reco-inc/upbox-ui/dist/**/*.mjs";

2. Vue Template Autocomplete (권장)

Consumer 프로젝트의 env.d.ts 또는 vite-env.d.ts에 추가:

/// <reference types="@reco-inc/upbox-ui/global" />

이렇게 하면 .vue 파일 <template>에서 컴포넌트 자동완성이 동작합니다.

3. Use Components

<script setup lang="ts">
import { Button, Card, CardHeader, CardTitle, CardContent } from '@reco-inc/upbox-ui'
</script>

<template>
  <Card>
    <CardHeader>
      <CardTitle>Title</CardTitle>
    </CardHeader>
    <CardContent>
      <Button variant="primary" size="regular">Click</Button>
    </CardContent>
  </Card>
</template>

4. i18n (필수)

일부 컴포넌트(DropdownFilter, FileUploader, TimePicker 등)는 소비 앱의 useI18n() 으로 문구를 찾습니다. 기본 문구는 DS 가 갖고 있으니, 앱 메시지 아래에 깔아 주세요.

import { createI18n } from 'vue-i18n'
// 컴포넌트를 물지 않는 i18n 전용 진입점. root barrel 로 받으면 문구 하나 때문에
// 컴포넌트 번들 전체가 딸려 온다
import { mergeMessages } from '@reco-inc/upbox-ui/i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'ko',
  // 같은 키가 양쪽에 있으면 앱 메시지가 이깁니다
  messages: mergeMessages({ ko: appKo, en: appEn }),
})

깔지 않으면 화면에 common.search 같은 키 문자열이 그대로 노출됩니다. DS 가 문구를 제공하지 않는 로케일(예: jp)은 앱 메시지를 그대로 둡니다.

문구를 바꾸고 싶으면 두 가지 방법이 있습니다.

• 한 곳만 바꿀 때는 컴포넌트 props (search-placeholder, select-all-text 등)
• 앱 전체에서 바꿀 때는 앱 메시지에 같은 키를 정의

Components

Flat vs Compound

일부 컴포넌트는 자주 쓰는 형태를 flat(props 중심) API로 제공하고, 같은 primitive 위에서 자유 조합이 필요할 땐 compound를 그대로 사용합니다 (escape hatch).

Design Tokens

CSS variables for colors, typography, spacing are included in style.css.

Color System

Figma 팔레트 이름을 그대로 사용:

• grey (10-100): Grayscale
• navy (20-100): Brand / primary CTA
• blue (20-100): Informative
• green (20-100): Positive
• red (20-100): Negative / destructive
• orange (20-100): Warning

Dark Mode

Add class="dark" to the root element. All color tokens automatically invert.

업데이트

pnpm install 은 lockfile 에 고정된 버전을 그대로 설치한다. 새 버전이 나와도 자동으로 올라가지 않으므로, 갱신하려면 update 를 실행하고 바뀐 lockfile 을 커밋한다.

pnpm update @reco-inc/upbox-ui

Contributing

개발·릴리스·배포 절차는 저장소의 CONTRIBUTING.md 를 참고한다.

Tech Stack

• Vue 3 + TypeScript
• Tailwind CSS + CSS Variables (Design Tokens)
• Reka UI (Headless components)
• Class Variance Authority (Variant system)
• Vite (Library mode build)
• vite-plugin-dts (Type declaration generation)
• Storybook (Component documentation & playground)