7onicDESIGN SYSTEM

Installation

7onic UI 컴포넌트를 프로젝트에 설치하고 사용하는 방법

Install

@7onic-ui/react

Terminal
# npm
npm install @7onic-ui/react @7onic-ui/tokens

# yarn
yarn add @7onic-ui/react @7onic-ui/tokens

# pnpm
pnpm add @7onic-ui/react @7onic-ui/tokens
Tailwind 필수: Tailwind v3 또는 v4가 필요합니다. 설치 후 아래 Import 설정을 진행하세요. Get Tailwind

Import

Tailwind v4

설정 파일 불필요
your-styles.css
@import "tailwindcss";

@import '@7onic-ui/tokens/tailwind/v4.css';

@source "../node_modules/@7onic-ui/react/dist";
개별 임포트
@import "tailwindcss";

@import '@7onic-ui/tokens/css/variables.css';
@import '@7onic-ui/tokens/css/themes/light.css';
@import '@7onic-ui/tokens/css/themes/dark.css';
@import '@7onic-ui/tokens/tailwind/v4-theme.css';

@source "../node_modules/@7onic-ui/react/dist";

@source 디렉티브로 컴포넌트 내 Tailwind 클래스를 스캔 대상에 추가합니다. 프로젝트 구조에 맞게 경로를 조정하세요.

Tailwind v3

CSS + 프리셋
your-styles.css
@tailwind base;
@tailwind components;
@tailwind utilities;

@import '@7onic-ui/tokens/css/all.css';
개별 임포트
@tailwind base;
@tailwind components;
@tailwind utilities;

@import '@7onic-ui/tokens/css/variables.css';
@import '@7onic-ui/tokens/css/themes/light.css';
@import '@7onic-ui/tokens/css/themes/dark.css';
tailwind.config.js
module.exports = {
  presets: [
    require('@7onic-ui/tokens/tailwind/v3-preset')
  ],
  content: [
    './node_modules/@7onic-ui/react/dist/**/*.{js,mjs}',
  ],
}

프리셋은 theme.extend를 사용하므로 기존 Tailwind 클래스가 그대로 유지됩니다. v3에서도 시맨틱 컬러의 opacity modifier(bg-primary/50 등)를 완전히 지원합니다. RGB 채널 변수로 알파값을 적용합니다.

Body StyleRecommended
body 요소에 추가하세요. 라이트/다크 모드 모두에서 배경색과 텍스트색이 올바르게 적용됩니다.
layout.html
<body class="bg-background text-foreground">
Next.js App Router: 클라이언트 컴포넌트로 사용할 경우 파일 상단에 'use client'를 추가하세요.

Fonts

Aa

Fonts Setup Guide

폰트 설치 및 다국어 설정

컴포넌트는 토큰의 font-sans를 사용합니다. Design Tokens > Installation > Fonts에서 설정하세요.

Usage

컴포넌트의 임포트 및 사용 방법. Namespace와 Named 두 가지 방식을 지원합니다.

Namespace (권장)

권장
namespace.tsx
import { Card, Button } from '@7onic-ui/react'

<Card>
  <Card.Header>
    <Card.Title>Project Settings</Card.Title>
    <Card.Description>Manage your project configuration.</Card.Description>
  </Card.Header>
  <Card.Content>
    <p>Content here</p>
  </Card.Content>
  <Card.Footer>
    <Button variant="outline">Cancel</Button>
    <Button>Save</Button>
  </Card.Footer>
</Card>

루트 컴포넌트만 임포트하고 서브 컴포넌트는 점 표기법으로 접근합니다.

Named Export (호환)

named.tsx
import {
  Card, CardHeader, CardTitle, CardDescription,
  CardContent, CardFooter, Button,
} from '@7onic-ui/react'

<Card>
  <CardHeader>
    <CardTitle>Project Settings</CardTitle>
    <CardDescription>Manage your project configuration.</CardDescription>
  </CardHeader>
  <CardContent>
    <p>Content here</p>
  </CardContent>
  <CardFooter>
    <Button variant="outline">Cancel</Button>
    <Button>Save</Button>
  </CardFooter>
</Card>

기존 Named Export도 계속 지원됩니다. 기존 코드가 그대로 동작합니다.

Standalone 컴포넌트(Button, Input, Badge 등)는 단독 임포트만으로 충분하며 Namespace가 필요 없습니다.

Requirements

패키지버전
react≥ 18.0.0
react-dom≥ 18.0.0
tailwindcssv3 or v4
@7onic-ui/tokens필수 (동시 설치)

Package Contents

두 개의 패키지로 구성됩니다. 컴포넌트와 토큰을 별도로 관리할 수 있습니다.

@7onic-ui/react

UI 컴포넌트 라이브러리 (dist/ 배포)

index.js
CJS
index.mjs
ESM
index.d.ts
Types
import { Button, Card, Modal } from '@7onic-ui/react'
@7onic-ui/tokens

디자인 토큰: CSS 변수, Tailwind 프리셋, JS, CLI

CSS

4

variables, light, dark, all

Tailwind

3

v3-preset, v4-theme, v4

JS / Types

4

CJS, ESM, .d.ts, JSON

CLI

1

sync-tokens

figma-tokens.jsonSSOT→ npx sync-tokens로 전체 파일 자동 생성

figma-tokens.json → → npx sync-tokens로 전체 파일 자동 생성

Package Contents

Token Sync

디자인 커스터마이즈

토큰을 변경하면 컴포넌트 스타일에 자동 반영

FigmaJSONsync-tokensCSS + Components
$ npx sync-tokensToken Sync