Installation

색상, 간격, 타이포그래피 등 디자인 값을 어떤 환경에서도 동일하게 사용할 수 있는 토큰 패키지입니다.

Install

@7onic-ui/tokens

Terminal

# npm
npm install @7onic-ui/tokens

# yarn
yarn add @7onic-ui/tokens

# pnpm
pnpm add @7onic-ui/tokens

Import

CSS

CSS 변수만

your-styles.css

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

개별 임포트

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

<html class="dark">를 추가하면 시맨틱 색상이 자동으로 다크 테마로 전환됩니다.

Tailwind v4

설정 파일 불필요

your-styles.css

@import "tailwindcss";

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

개별 임포트

@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';

v4-theme.css가 없으면 bg-primary나 duration-fast 등의 클래스를 사용할 수 없습니다.

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')
  ],
}

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

JavaScript / TypeScript

정적 값

your-file.ts

import { colors, spacing, typography } from '@7onic-ui/tokens'

ESM(.mjs)과 CJS(.js) 모두 지원합니다. TypeScript 타입 정의도 포함되어 있습니다.

Usage Reference

사용 가능한 토큰과 형식을 확인하세요.

Colors

CSS--color-primary

TWbg-primary

JScolors.primary[600]

CSS--color-secondary

TWbg-secondary

JScolors.secondary[600]

CSS--color-success

TWbg-success

JScolors.green[600]

CSS--color-warning

TWbg-warning

JScolors.yellow[500]

CSS--color-error

TWbg-error

JScolors.red[600]

CSS--color-background-muted

TWbg-background-muted

JSCSS only ※

CSS--color-text

TWtext-foreground

JSCSS only ※

CSS--color-text-muted

TWtext-text-muted

JSCSS only ※

CSS--color-primary-text

TWtext-primary-foreground

JSCSS only ※

CSS--color-border

TWborder-border

JSCSS only ※

CSS Variable	Tailwind	JS / TS
--color-primary	bg-primary	colors.primary[600]
--color-secondary	bg-secondary	colors.secondary[600]
--color-success	bg-success	colors.green[600]
--color-warning	bg-warning	colors.yellow[500]
--color-error	bg-error	colors.red[600]
--color-background-muted	bg-background-muted	CSS only ※
--color-text	text-foreground	CSS only ※
--color-text-muted	text-text-muted	CSS only ※
--color-primary-text	text-primary-foreground	CSS only ※
--color-border	border-border	CSS only ※

Typography

CSS--font-size-2xs (11px)

TWtext-2xs

JSfontSize["2xs"]

CSS--font-size-xs (12px)

TWtext-xs

JSfontSize.xs

CSS--font-size-sm (13px)

TWtext-sm

JSfontSize.sm

CSS--font-size-md (14px)

TWtext-md

JSfontSize.md

CSS--font-size-base (16px)

TWtext-base

JSfontSize.base

CSS--font-size-lg (18px)

TWtext-lg

JSfontSize.lg

CSS--font-size-xl (20px)

TWtext-xl

JSfontSize.xl

CSS--font-size-2xl (24px)

TWtext-2xl

JSfontSize["2xl"]

CSS Variable	Tailwind	JS / TS
--font-size-2xs (11px)	text-2xs	fontSize["2xs"]
--font-size-xs (12px)	text-xs	fontSize.xs
--font-size-sm (13px)	text-sm	fontSize.sm
--font-size-md (14px)	text-md	fontSize.md
--font-size-base (16px)	text-base	fontSize.base
--font-size-lg (18px)	text-lg	fontSize.lg
--font-size-xl (20px)	text-xl	fontSize.xl
--font-size-2xl (24px)	text-2xl	fontSize["2xl"]

Spacing

CSS--spacing-1 (4px)

TWp-1 m-1 gap-1

JSspacing[1]

CSS--spacing-2 (8px)

TWp-2 m-2 gap-2

JSspacing[2]

CSS--spacing-4 (16px)

TWp-4 m-4 gap-4

JSspacing[4]

CSS--spacing-6 (24px)

TWp-6 m-6 gap-6

JSspacing[6]

CSS--spacing-8 (32px)

TWp-8 m-8 gap-8

JSspacing[8]

CSS Variable	Tailwind	JS / TS
--spacing-1 (4px)	p-1 m-1 gap-1	spacing[1]
--spacing-2 (8px)	p-2 m-2 gap-2	spacing[2]
--spacing-4 (16px)	p-4 m-4 gap-4	spacing[4]
--spacing-6 (24px)	p-6 m-6 gap-6	spacing[6]
--spacing-8 (32px)	p-8 m-8 gap-8	spacing[8]

Duration

CSS--duration-fast (100ms)

TWduration-fast

JSduration.fast

CSS--duration-micro (150ms)

TWduration-micro

JSduration.micro

CSS--duration-normal (200ms)

TWduration-normal

JSduration.normal

CSS--duration-slow (300ms)

TWduration-slow

JSduration.slow

CSS--duration-slower (400ms)

TWduration-slower

JSduration.slower

CSS Variable	Tailwind	JS / TS
--duration-fast (100ms)	duration-fast	duration.fast
--duration-micro (150ms)	duration-micro	duration.micro
--duration-normal (200ms)	duration-normal	duration.normal
--duration-slow (300ms)	duration-slow	duration.slow
--duration-slower (400ms)	duration-slower	duration.slower

Radius / Shadow / Z-Index

CSS--radius-{sm|md|lg|...}

TWrounded-{sm|md|lg|...}

JSborderRadius.*

CSS--shadow-{xs|sm|md|lg|xl}

TWshadow-{xs|sm|md|lg|xl}

JSshadow.*

CSS--z-index-{modal|tooltip|...}

TWz-{modal|tooltip|...}

JSzIndex.*

CSS Variable	Tailwind	JS / TS
--radius-{sm\|md\|lg\|...}	rounded-{sm\|md\|lg\|...}	borderRadius.*
--shadow-{xs\|sm\|md\|lg\|xl}	shadow-{xs\|sm\|md\|lg\|xl}	shadow.*
--z-index-{modal\|tooltip\|...}	z-{modal\|tooltip\|...}	zIndex.*

Custom Utilities

CSS--icon-size-{xs|sm|md|lg|xl}

TWicon-{xs|sm|md|lg|xl}

JSiconSize.*

CSS--scale-{50|75|pressed}

TWscale-{50|75|pressed}

JSscale.*

CSS--opacity-{0~100}

TWopacity-{0~100}

JSopacity.*

CSS--easing-{ease|ease-in|...}

TWease-{in|out|in-out}

JSeasing.*

CSS--color-focus-ring

TWfocus-ring

JSCSS only ※

CSS@keyframes {name}

TWanimate-{name}

JSCSS only ※

CSS Variable	Tailwind	JS / TS
--icon-size-{xs\|sm\|md\|lg\|xl}	icon-{xs\|sm\|md\|lg\|xl}	iconSize.*
--scale-{50\|75\|pressed}	scale-{50\|75\|pressed}	scale.*
--opacity-{0~100}	opacity-{0~100}	opacity.*
--easing-{ease\|ease-in\|...}	ease-{in\|out\|in-out}	easing.*
--color-focus-ring	focus-ring	CSS only ※
@keyframes {name}	animate-{name}	CSS only ※

시맨틱 vs 프리미티브: 프리미티브(--spacing-4 등)는 고정값입니다. 시맨틱(--color-primary 등)은 라이트/다크 테마에 따라 전환됩니다.

JS export: 프리미티브 값(정적)만 export합니다. CSS only ※ 값은 테마에 따라 변경되므로 JS에서는 사용 불가합니다. CSS 변수를 사용하세요. TypeScript 타입 정의(18종) 포함.

Package Contents

필요한 파일을 가져다 쓰세요. 모두 npx sync-tokens로 자동 생성됩니다.

@7onic-ui/tokens

9개 배포 파일 + CLI + 소스

{}

CSS Variables

css/all.css추천

css/variables.css전체 프리미티브 변수

css/themes/light.css라이트 테마

css/themes/dark.css다크 테마

Tailwind Presets

tailwind/v4.css추천

tailwind/v3-preset.jsv3 프리셋

tailwind/v4-theme.cssv4 테마 정의

JavaScript / Types

js/index.jsCJS

js/index.mjsESM

types/index.d.tsTypeScript 타입

json/tokens.json플랫 JSON

CLI / Source

cli/sync.jsnpx sync-tokens

llms.txtAI Integration

figma-tokens.jsonSSOT

유일한 편집 대상 파일

figma-tokens.json를 편집하고 npx sync-tokens를 실행하면 9개 파일이 모두 자동 재생성됩니다.

Token Sync

Figma에서 디자인 업데이트 → CLI 하나로 전체 파일에 반영

Figma

디자인 편집

JSON

익스포트

CLI

sync-tokens

Output

9개 파일

Figma

디자인 편집

JSON

토큰 익스포트

CLI

npx sync-tokens 실행

Output

9개 파일 자동 생성

Terminal

$ npx sync-tokens

CLI Options

Option	Description
--dry-run	파일을 실제로 쓰지 않고 변경 사항을 미리 확인
--force	브레이킹 체인지 확인 프롬프트 건너뛰기
--input <path>	figma-tokens.json 경로 (기본값: ./figma-tokens.json)
--output <dir>	출력 디렉토리 (기본값: ./)

Generated Files

CSS

variables.css

light.css

dark.css

Tailwind

v3-preset.js

v4-theme.css

JavaScript

index.js

index.mjs

Types + JSON

index.d.ts

tokens.json

Breaking Change Detection

기존 variables.css가 있으면 sync-tokens가 자동으로 변경 사항을 감지하고 diff를 표시합니다.

Diff 표시 — 추가, 변경, 삭제, 리네임을 색상으로 시각화

확인 프롬프트 — 브레이킹 체인지(삭제, 리네임)가 있을 경우 실행 전 확인 요청

하위 호환 alias — 리네임 감지 시 css/deprecated.css를 자동 생성해 기존 참조를 보호합니다.

--dry-run로 먼저 diff를 확인하거나, --force로 확인 프롬프트를 건너뛸 수 있습니다.

Tokens Studio 설정

Figma 커뮤니티에서 Tokens Studio 플러그인을 설치하세요

리포지토리의 figma-tokens.json을 플러그인에 가져오세요

GitHub 동기화를 설정하면 디자인과 코드 토큰이 자동 동기화됩니다 (선택사항)