@olundot/tokens

OLUN의 CSS custom properties, Tailwind v3/v4 매핑과 브랜드 assets를 제공하는 패키지입니다. 현재 버전은 0.15.0입니다.

설치

pnpm add @olundot/tokens

브랜드 React 컴포넌트에는 React 18 이상, Tailwind export에는 Tailwind CSS 3.4 이상이 필요합니다. 두 peer dependency는 패키지에서 optional로 선언됩니다.

기본 설정

토큰만 사용할 때는 CSS entry를 불러옵니다.

import "@olundot/tokens/css";

data-theme이 없으면 OS prefers-color-scheme을 따릅니다. 명시적으로 고정하려면 root element에 data-theme="light" 또는 data-theme="dark"를 설정합니다.

저장된 테마를 첫 paint 전에 적용하는 예시는 다음과 같습니다.

<script
  dangerouslySetInnerHTML={{
    __html: `(function(){try{var s=localStorage.getItem('olun-theme');if(s==='light'||s==='dark'){document.documentElement.setAttribute('data-theme',s);}}catch(e){}})();`,
  }}
/>

토큰 레이어

| 레이어 | 예시 | 용도 | |---|---|---| | Semantic | --accent, --bg-base, --focus-ring, --error | 일반 UI. color-scheme에 따라 light/dark 값이 바뀜 | | Palette | --n-0…--n-1000, --lime, --lime-50…--lime-800 | 인쇄나 브랜드 asset처럼 모드에 고정된 값이 필요한 경우 |

일반 UI는 semantic 토큰을 사용합니다. v0.14에서 이전의 mode별 palette split은 제거됐습니다. 전체 목록은 docs/TOKEN-LAYERS.md에 있습니다.

Surface 모델

Light는 #FAFAFA desk 아래에 흰 종이를 놓는 두 값 모델입니다. --bg-inset은 종이 단계가 아니라 표면 안쪽의 well입니다.

| 토큰 | Light | Dark | 역할 | |---|---|---|---| | --bg-base | #FAFAFA | #08090A | page floor, app chrome | | --bg-canvas | #FFFFFF | #0C0D0F | main content | | --bg-surface | #FFFFFF | #111317 | card, section, overlay panel | | --bg-raised | #FFFFFF | #16181D | reserved dark-ramp step; 기존 elevated consumer 유지 | | --bg-overlay | #FFFFFF | #1C1F26 | reserved top step; 현재 컴포넌트 consumer 없음 | | --bg-inset | #F1F2F4 | #16181D | element well, pressed fill |

Dialog, Sheet, Popover, DropdownMenu, Select와 Toast의 비-error variant는 panel에 --bg-surface를 사용합니다. Toast error variant만 --error-bg를 사용하며, --bg-raised와 --bg-overlay는 overlay panel 단계로 사용하지 않습니다.

Shadow와 scrim

0.15.0에서 light shadow 알파가 다음 값으로 조정됐습니다. Dark shadow 값은 바뀌지 않았습니다.

| 토큰 | Light alpha | |---|---| | --shadow-1 | 0.08 | | --shadow-2 | 0.09, 0.06 | | --shadow-4 | 0.11, 0.07 | | --shadow-8 | 0.11, 0.06 | | --shadow-16 | 0.15, 0.09 |

Light --scrim은 rgba(16,18,23,0.45)입니다. Dialog와 Sheet는 이 토큰을 backdrop에 사용합니다.

Tailwind

Tailwind v4

@import "tailwindcss";
@import "@olundot/tokens/css";
@import "@olundot/tokens/tailwind/v4";

Tailwind v3

import preset from "@olundot/tokens/tailwind";

export default {
  presets: [preset],
  content: ["./src/**/*.{ts,tsx}"],
};

Export

| 경로 | 내용 | |---|---| | @olundot/tokens/css | light/dark CSS custom properties | | @olundot/tokens/preflight | opt-in preflight CSS | | @olundot/tokens/tailwind | Tailwind v3 preset | | @olundot/tokens/tailwind/v4 | Tailwind v4 @theme inline 매핑 | | @olundot/tokens/brand | Logo, Wordmark, Favicon, faviconSvgString |

전체 설정은 integration guide, 릴리스 변경은 CHANGELOG에 있습니다.

라이선스

MIT