onul-d

Toss-style design system. 토큰 + 컴포넌트.

설치

pnpm add onul-d

Consumer 셋업

Tailwind v4

/* app/globals.css */
@import "tailwindcss";
@import "onul-d/tokens.css";

/* onul-d 의 컴포넌트 클래스를 Tailwind 가 보게 명시 source 등록.
 * Tailwind v4 는 기본적으로 node_modules 를 스캔하지 않아요. */
@source "../../node_modules/onul-d/src/**/*.{ts,tsx}";

/* Pretendard 폰트 (선택) */
@import url("https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/variable/pretendardvariable-dynamic-subset.min.css");

Tailwind v3

// tailwind.config.ts
import type { Config } from "tailwindcss";
import { tailwindV3 as spikeDS } from "onul-d/tokens";

const config: Config = {
  content: [
    "./src/**/*.{ts,tsx}",
    // onul-d 컴포넌트 클래스 스캔
    "./node_modules/onul-d/src/**/*.{ts,tsx}",
  ],
  theme: {
    extend: {
      colors: spikeDS.colors,
      fontFamily: spikeDS.fontFamily,
    },
  },
};

export default config;

/* app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

(v3 에선 tokens.css import 안 해도 됩니다 — config 에서 색상이 흡수돼요.)

컴포넌트 사용

import { Button, cn } from "onul-d";

export default function Page() {
  return (
    <Button size="medium" color="primary">
      저장
    </Button>
  );
}

Next.js 전용 컴포넌트

next/link / next/navigation 에 의존하는 컴포넌트는 별도 entry 로 분리되어 있어요. 다른 프레임워크 consumer 가 next 를 끌어오지 않도록 하기 위함.

import { SideNav, BottomNav, BackHeader, Breadcrumb } from "onul-d/next";

<SideNav
  items={[
    { label: "홈", href: "/", icon: "M3 12l2-2..." },
    { label: "검색", href: "/search", icon: "M21 21l-6-6..." },
  ]}
  brand={<span className="font-bold">My App</span>}
/>

next 는 optional peer dep — Next.js consumer 만 이 entry 를 import 하세요.

권장 사용 패턴

semantic 클래스 우선:

<div className="bg-bg-subtle text-text-secondary border border-border">
  <button className="bg-primary text-text-inverse">저장</button>
</div>

어쩔 수 없을 때 raw scale (escape hatch):

<span className="bg-grey-100 text-blue-500">draft</span>

토큰 목록

| 카테고리 | 토큰 | |---------|------| | Surface | bg, bg-subtle, bg-muted, bg-overlay | | Text | text, text-secondary, text-tertiary, text-placeholder, text-disabled, text-inverse | | Border | border, border-strong | | Brand | primary, primary-hover, primary-subtle | | Status | danger, success, warning, info (+-subtle) | | Raw | grey-50..900, blue-50/100/400/500/600, red-50/500, yellow-50/500, green-50/500, teal-50/500, purple-50/500 |

컴포넌트 (60개)

전체 카탈로그는 showcase 페이지 에서 직접 클릭해보세요.

Action

Button IconButton TextButton

Display

Card Badge Tag Avatar AvatarGroup Bubble Border Highlight Loader Skeleton ProgressBar ProgressStepper Stepper EmptyState Result StatCard Paragraph Post

Form

TextField Checkbox Switch SearchField SegmentedControl Slider NumericSpinner Keypad Rating Agreement

Data

DataTable TableRow ListRow ListHeader ListFooter BoardRow Feed Chart Dropdown Menu

Layout

PageContainer PageHeader Top TopBar BottomCTA BottomInfo CardGrid GridList

Navigation

Tab Pagination

Overlay

BottomSheet Modal Dialog Toast Tooltip

Next.js 전용 (onul-d/next)

SideNav BottomNav BackHeader Breadcrumb

cn 헬퍼

clsx + tailwind-merge 조합. 커스텀 utility 그룹 (text-tds-* 폰트 사이즈, rounded-tds* radius) 을 알도록 extendTailwindMerge 로 등록되어 있어요. consumer 도 이걸 쓰면 같은 그룹에서 dedup 일관됨.

import { cn } from "onul-d";

<button className={cn("bg-primary", "text-text-inverse", className)} />

토큰 수정

src/tokens.ts 가 single source of truth. CSS 산출물(tokens.css)은 generator 가 만듦.

# 수정 후
pnpm --filter onul-d build:tokens

CI 에서 drift 자동 검사 (regenerate 후 git diff --exit-code).

Dogfood smoke test

repo 루트에서 pnpm dogfood 한 번이면 다음을 순차 검증:

1. tokens.css 가 SoT 와 일치 (drift 검사)
2. playground 빌드
3. yalc 로 모든 외부 consumer 에 onul-d 푸시
4. 각 외부 consumer 빌드

새 consumer 추가는 scripts/dogfood.sh 의 CONSUMERS 배열에 한 줄.

버전 정책

• 0.x: tokens / 컴포넌트 안정화 단계 (이름 변경 발생 가능)
• 1.0: tokens + 첫 컴포넌트 셋 동결 후 공개

Publish 절차 (maintainer)

# 1. npm 로그인 (한 번만)
npm login

# 2. 패키지 디렉토리로
cd packages/onul-d

# 3. publish
npm publish

# 4. 확인
npm view onul-d

prepublishOnly 후크가 자동으로 build:tokens 를 돌려서 SoT drift 가 없는 상태로 만들어요.

릴리즈 후 consumer 측 작업:

# yalc 떼고 진짜 npm 의존성으로
yalc remove onul-d
npm install onul-d@^0.1.0