Getting started

Theming

제품별 강조색, 배경, elevation, 모서리 값을 재정의하고 컴포넌트 래퍼에서 관리하는 방법을 설명합니다.

Setup

앱 진입점에서 완성 CSS를 한 번 불러옵니다. 테마를 지정하지 않으면 :root의 light 값을 사용합니다. data-theme="dark" 또는 .dark는 dark 값을 적용합니다. 테마 상태는 앱에서 관리하며 시스템 설정을 자동으로 따르지 않습니다.

app/layout.tsx

import '@amineslab/ui/styles'

import type { ReactNode } from 'react'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ko" data-theme="light" data-brand="product">
      <body>{children}</body>
    </html>
  )
}

next-themes와 연결

@amineslab/ui/theme/next는 next-themes의 ThemeProvider와 useTheme를 다시 내보냅니다. attribute는 data-theme로 설정합니다. color-scheme은 패키지 CSS가 적용하므로 비활성화합니다. hydration 전에 attribute가 바뀌므로 html에 suppressHydrationWarning을 붙입니다.

app/providers.tsx

'use client'

import { ThemeProvider } from '@amineslab/ui/theme/next'
import type { ReactNode } from 'react'

export function Providers({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider
      attribute="data-theme"
      defaultTheme="light"
      enableColorScheme={false}
      enableSystem={false}
    >
      {children}
    </ThemeProvider>
  )
}

일부 영역에 다른 테마 적용

ThemeScope는 영역과 그 안에서 여는 Select, Dialog, Tooltip 등의 포털 표면에 같은 light 또는 dark 테마를 전달합니다. theme을 생략하면 상위 scope를 따르고, scope 밖에서는 기존 문서 테마를 사용합니다. asChild는 별도 div 없이 자식 요소를 경계로 사용합니다. 임의의 CSS 변수나 브랜드 속성은 복사하지 않습니다.

import { ThemeScope } from '@amineslab/ui'

<ThemeScope theme="dark" asChild>
  <section>{children}</section>
</ThemeScope>

Token 계층

색상 토큰은 원시 값, 서비스별 원시 alias, 의미별 palette, 배경에 얹는 elevation, 컴포넌트 역할별 토큰 순서로 참조합니다. 제품 테마에서는 필요한 alias, 역할별 토큰, radius만 재정의합니다.

계층	예시	제품에서
Primitive literal	`--color-neutral-950--color-coral-500`	light와 dark에서 바뀌지 않습니다. 원시 palette는 재정의하지 않습니다.
Primitive alias	`--color-gray-300--color-accent-500`	서비스별 gray와 accent를 50~950 전체 ramp로 선택합니다.
Semantic palette	`--color-brand-300--color-success-500`	원시 색에 brand, success 등 의미를 붙입니다. dark에서는 패키지가 단계를 역순으로 매핑합니다.
Elevation	`--color-elevation-700--color-elevation-accent-300`	중성 ramp는 배경·테두리 강도에, colored ramp는 선택·상태 배경과 아이콘에 씁니다.
Semantic role	`--color-background-primary--radius-section`	화면 코드에서 우선 사용합니다. 색상 역할 토큰은 81개이며 radius도 역할별 토큰으로 제공합니다.
Component alias	`--component-control-height-md`	컨트롤 높이와 터치 영역 등 공통 치수를 조정합니다.
Motion, density, layer	`--motion-duration-normal--layer-overlay`	레이아웃과 동작 정책이 필요할 때만 조정합니다.

원시 palette와 alias의 전체 목록, 의미별 palette와 역할별 토큰의 light·dark 값은 Color 페이지에 있습니다.

단계 숫자와 OKLCH

기본 palette는 Tailwind CSS v4와 동일한 11단계(50~950)이며 숫자는 색의 강도입니다. 50이 가장 옅고 950이 가장 짙습니다. 원시 값은 light/dark에서 변하지 않는 Tailwind oklch(...) 값입니다. 중성·colored elevation은 합성식을 사용할 수 있고, 역할별 토큰은 이미 정의된 palette나 elevation을 참조해야 합니다. 예를 들어 success-300은 light에서 green-300, dark에서 green-700입니다. 전체 원시 값은 Color 페이지와 Tailwind 색상 문서에 있습니다.

제품 색상 override

제품 식별자는 테마 상태를 나타내는 data-theme와 분리해 data-brand="product"처럼 지정합니다. 원시 값은 유지하고, gray/accent alias는 50~950 전체 ramp를 선택합니다. 화면에서는 의미별 palette, elevation, 역할별 토큰을 사용합니다. 역할별 토큰에도 OKLCH 값을 직접 넣지 말고 기존 palette나 elevation을 참조합니다. 컴포넌트 CSS는 주로 역할별 토큰을 참조합니다. scrim과 tooltip의 내부 대비 색은 이름이 있는 원시 값을 직접 사용하므로 내부 클래스를 재정의하지 않습니다.

src/styles/theme.css

/* 제품의 역할별 토큰은 원시 값, palette, elevation만 참조합니다. */
[data-brand='product'] {
  --color-background-primary: var(--color-gray-50);
  --color-background-secondary: var(--color-elevation-50);
  --color-background-tertiary: var(--color-elevation-100);

  --color-section-primary: var(--color-elevation-50);
  --color-section-secondary: var(--color-elevation-100);
  --color-section-tertiary: var(--color-elevation-200);
  --color-section-overlay: var(--color-gray-50);

  --color-text-primary: var(--color-gray-950);
  --color-text-secondary: var(--color-gray-700);

  --color-focus: var(--color-brand-600);
  --color-link: var(--color-brand-700);
  --color-link-hover: var(--color-brand-800);
}

Gray family 선택

기본 gray는 Neutral입니다. 서비스 색조에 맞춰 Neutral, Slate, Stone, Zinc 중 하나를 고른 뒤 50부터 950까지 해당 계열로 연결합니다. 네 계열 모두 Tailwind의 OKLCH 값을 사용합니다. alias는 원시 값이므로 dark selector에서 다시 정의하지 않습니다.

src/styles/theme.css

[data-brand='product'] {
  /* gray 기본값은 neutral. 서비스 색조에 맞는 원시 계열 하나를 고릅니다. */
  --color-gray-50: var(--color-slate-50);
  --color-gray-100: var(--color-slate-100);
  --color-gray-200: var(--color-slate-200);
  --color-gray-300: var(--color-slate-300);
  --color-gray-400: var(--color-slate-400);
  --color-gray-500: var(--color-slate-500);
  --color-gray-600: var(--color-slate-600);
  --color-gray-700: var(--color-slate-700);
  --color-gray-800: var(--color-slate-800);
  --color-gray-900: var(--color-slate-900);
  --color-gray-950: var(--color-slate-950);
}

Accent palette 지정

기본 accent는 Amineslab Coral입니다. 아래 예시는 서비스 accent를 Violet 원시 ramp에 연결합니다. 자체 ramp가 있다면 --color-violet-* 위치에 서비스 토큰을 넣고 data-brand 범위에서 전체 alias를 연결합니다. brand palette의 light/dark 단계와 단일 brand 역할은 패키지 매핑을 따릅니다. Button은 이 brand palette와 colored·neutral elevation을 내부에서 조합합니다. 제품은 전체 accent ramp만 바꾸고 Button을 그대로 사용합니다.

src/styles/theme.css

[data-brand='product'] {
  /* accent 원시 값은 light/dark 공통입니다. 전체 ramp를 함께 지정합니다. */
  --color-accent-50: var(--color-violet-50);
  --color-accent-100: var(--color-violet-100);
  --color-accent-200: var(--color-violet-200);
  --color-accent-300: var(--color-violet-300);
  --color-accent-400: var(--color-violet-400);
  --color-accent-500: var(--color-violet-500);
  --color-accent-600: var(--color-violet-600);
  --color-accent-700: var(--color-violet-700);
  --color-accent-800: var(--color-violet-800);
  --color-accent-900: var(--color-violet-900);
  --color-accent-950: var(--color-violet-950);
}

테마별 브랜드 역할

--color-brand와 채움 위의 글자·아이콘 색인 --color-brand-foreground를 테마별로 지정할 수 있습니다. 기본값은 500과 흰색입니다. 브랜드 채움의 hover·active는 지정한 brand에서 파생되며, palette와 elevation은 기존 accent ramp를 따릅니다.

src/styles/theme.css

/* 패키지 CSS 다음에 로드합니다. 중첩 테마도 같은 경계에 적용합니다. */
[data-brand='product'][data-theme='light'] {
  --color-brand: var(--color-violet-700);
  --color-brand-foreground: var(--color-white);
}

[data-brand='product'][data-theme='dark'] {
  --color-brand: var(--color-violet-300);
  --color-brand-foreground: var(--color-black);
}

함께 확인할 role

background primary·secondary·tertiary와 그 위의 text 위계
section, form field, interactive item 각각의 기본·상호작용·disabled 상태
success, warning, danger, info의 palette와 colored elevation ramp
border에 사용하는 neutral elevation 강도
링크와 포커스 표시

Button과 IconButton의 solid·subtle·hover·disabled 상태는 brand palette와 colored·neutral elevation으로 컴포넌트 내부에서 처리합니다. 화면에서 원시 색상 utility를 조합하지 말고 컴포넌트를 사용합니다.

Light와 dark를 함께 정의하기

gray/accent 원시 alias와 palette·elevation에는 패키지의 dark 매핑이 자동으로 적용됩니다. background, section, form field, interactive item 등 역할별 값을 바꿀 때만 dark 범위에 해당 값을 추가합니다. alias나 scale은 dark에서 다시 선언하지 않습니다.

src/styles/theme.css

/* palette와 elevation은 패키지가 모드별로 매핑합니다. */
/* gray/accent 원시 alias는 dark에서 다시 선언하지 않습니다. */
html[data-theme='dark'][data-brand='product'] {
  color-scheme: dark;
  /* 역할별 토큰을 조정할 때만 dark 값을 추가합니다. */
  --color-background-primary: var(--color-gray-800);
  --color-background-secondary: var(--color-gray-900);
  --color-background-tertiary: var(--color-gray-950);
}

Elevation

Elevation은 중성 색의 opacity를 50~950의 11단계 배경 tint로 구성합니다. 자식 콘텐츠의 opacity는 바뀌지 않으며 숫자는 배경의 강도를 나타냅니다. light와 dark 값은 각 단계가 비슷한 시각적 무게를 갖도록 조정되어 있습니다.

Primitive	Light	Dark
`--color-elevation-50`	1%	2%
`--color-elevation-100`	2%	4%
`--color-elevation-200`	3%	6%
`--color-elevation-300`	4%	7%
`--color-elevation-400`	5%	9%
`--color-elevation-500`	6%	10%
`--color-elevation-600`	8%	12%
`--color-elevation-700`	9%	14%
`--color-elevation-800`	13%	19%
`--color-elevation-900`	18%	25%
`--color-elevation-950`	22%	30%

밝은 색은 어두운 배경에서 동일한 opacity여도 약하게 보입니다. 이를 보정하기 위해 dark 값은 낮은 단계에서 더 크게 높이고, 단계가 올라갈수록 보정 폭을 줄입니다.

Colored elevation

accent, success, warning, danger, info에는 각각 50~950 colored elevation ramp가 있습니다. light 50은 원색 4% tint, dark 50은 8% tint에서 시작하고 950은 불투명합니다. 선택한 항목의 배경, 상태 강조, 아이콘처럼 기존 배경 위에 의미색을 더할 때 사용합니다. 모드별 색은 Color에서 비교할 수 있습니다.

Border

별도 border alias는 없습니다. 주변 배경과 구분할 강도에 맞춰 border-elevation-50부터 border-elevation-950까지 neutral elevation을 직접 선택합니다. 기본 구분선은 700, 강조된 컨트롤은 800, 강한 상호작용 상태의 테두리는 950부터 조정합니다.

Radius와 geometry override

Radius는 컴포넌트 이름이 아니라 역할별 토큰으로 조정합니다. action과 form field는 기본값이 모두 md여도 별도 토큰이므로 각각 재정의할 수 있습니다. 컨트롤 높이와 터치 영역 등 공통 치수는 component alias를 사용합니다.

src/styles/theme.css

[data-brand='product'] {
  --component-control-height-md: 2.75rem;
  --component-touch-target: 2.75rem;

  /* 역할은 독립적으로 바꿉니다. */
  --radius-action: var(--radius-lg);
  --radius-form-field: var(--radius-md);
  --radius-section: var(--radius-xl);
  --radius-overlay: var(--radius-2xl);
}

원·pill의 full, 직각의 none, 자식 요소의 inherit, 연결된 컨트롤의 안쪽 모서리 0처럼 구조가 모양을 정하면 원시 값을 사용합니다. 역할별 선택과 시각 샘플은 Radius에 있습니다. size prop은 한 컨트롤의 크기, data-density는 화면의 정보 밀도를 정합니다. 모바일 전용 컴포넌트나 토큰 이름은 만들지 않습니다.

Design tokens

색상을 제외한 토큰 228개의 light 기본값입니다. 이 값은 @amineslab/ui/tokens의 generatedTokens에서 가져옵니다.

Component alias

컨트롤 높이와 터치 영역 등 컴포넌트 공통 치수. radius는 역할별 토큰을 사용

`--component-overlay-scrim-opacity`	`0.52`
`--component-control-border-width`	`1px`
`--component-focus-ring-width`	`2px`
`--component-focus-ring-offset`	`2px`
`--component-field-gap`	`var(--space-2)`
`--component-field-stack-gap`	`var(--space-4)`
`--component-card-padding`	`var(--space-10)`
`--component-overlay-padding`	`var(--space-10)`
`--component-overlay-max-width`	`32rem`
`--component-control-height-xs`	`1.5rem`
`--component-control-padding-inline-xs`	`0.25rem`
`--component-control-height-sm`	`1.75rem`
`--component-control-padding-inline-sm`	`0.375rem`
`--component-control-height-md`	`2rem`
`--component-control-padding-inline-md`	`0.5rem`
`--component-control-height-lg`	`2.5rem`
`--component-control-padding-inline-lg`	`0.625rem`
`--component-control-height-xl`	`3rem`
`--component-control-padding-inline-xl`	`0.75rem`
`--component-touch-target`	`2.75rem`
`--component-switch-border-width`	`2px`
`--component-avatar-size-xs`	`1.5rem`
`--component-avatar-size-sm`	`2rem`
`--component-avatar-size-md`	`2.5rem`
`--component-avatar-size-lg`	`3rem`
`--component-avatar-size-xl`	`4rem`
`--component-avatar-group-spacing`	`0.5rem`
`--component-overlay-viewport-inset`	`1rem`
`--component-dialog-width-sm`	`24rem`
`--component-dialog-width-md`	`28rem`
`--component-dialog-width-lg`	`var(--component-overlay-max-width)`
`--component-dialog-width-xl`	`42rem`
`--component-sheet-width`	`75%`
`--component-sheet-max-width`	`var(--component-dialog-width-sm)`
`--component-popover-max-width`	`20rem`
`--component-tooltip-width-sm`	`10rem`
`--component-tooltip-width-md`	`15rem`
`--component-tooltip-width-lg`	`20rem`
`--component-tooltip-width-xl`	`25rem`

Radius

원시 단계와 action, form field, section, overlay 역할별 토큰

`--radius-none`	`0`
`--radius-xs`	`0.125rem`
`--radius-sm`	`0.25rem`
`--radius-md`	`0.375rem`
`--radius-lg`	`0.5rem`
`--radius-xl`	`0.75rem`
`--radius-2xl`	`1rem`
`--radius-full`	`9999px`
`--radius-action`	`var(--radius-md)`
`--radius-form-field`	`var(--radius-md)`
`--radius-section`	`var(--radius-lg)`
`--radius-overlay`	`var(--radius-xl)`

Shadow

11단계 원시 값과 raised, floating, modal 역할별 토큰. dark에서 원시 값이 바뀜

`--shadow-50`	`0 1px 2px rgb(22 24 43 / 0.03)`
`--shadow-100`	`0 1px 3px rgb(22 24 43 / 0.04)`
`--shadow-200`	`0 2px 5px rgb(22 24 43 / 0.05)`
`--shadow-300`	`0 3px 8px rgb(22 24 43 / 0.06), 0 1px 2px rgb(22 24 43 / 0.03)`
`--shadow-400`	`0 5px 12px rgb(22 24 43 / 0.08), 0 1px 3px rgb(22 24 43 / 0.04)`
`--shadow-500`	`0 8px 16px rgb(22 24 43 / 0.1), 0 2px 6px rgb(22 24 43 / 0.05)`
`--shadow-600`	`0 12px 24px rgb(22 24 43 / 0.12), 0 3px 8px rgb(22 24 43 / 0.06)`
`--shadow-700`	`0 16px 32px rgb(22 24 43 / 0.14), 0 4px 12px rgb(22 24 43 / 0.07)`
`--shadow-800`	`0 24px 48px rgb(22 24 43 / 0.16), 0 6px 16px rgb(22 24 43 / 0.08)`
`--shadow-900`	`0 32px 64px rgb(22 24 43 / 0.18), 0 8px 20px rgb(22 24 43 / 0.09)`
`--shadow-950`	`0 48px 96px rgb(22 24 43 / 0.22), 0 12px 32px rgb(22 24 43 / 0.11)`
`--shadow-raised`	`var(--shadow-300)`
`--shadow-floating`	`var(--shadow-500)`
`--shadow-modal`	`var(--shadow-700)`

Spacing

2px 단위. 레이아웃 간격의 기준

`--space-0`	`0`
`--space-1`	`0.125rem`
`--space-2`	`0.25rem`
`--space-3`	`0.375rem`
`--space-4`	`0.5rem`
`--space-5`	`0.625rem`
`--space-6`	`0.75rem`
`--space-7`	`0.875rem`
`--space-8`	`1rem`
`--space-9`	`1.125rem`
`--space-10`	`1.25rem`
`--space-11`	`1.5rem`
`--space-12`	`1.75rem`
`--space-13`	`2rem`
`--space-14`	`2.5rem`
`--space-15`	`3rem`
`--space-16`	`4rem`

Typography recipes

용도별 글꼴, 크기, 줄 높이, 두께, 자간을 한 번에 적용

`--typography-display-1-font-family`	`var(--font-family-sans)`
`--typography-display-1-font-size`	`var(--font-size-5xl)`
`--typography-display-1-font-weight`	`var(--font-weight-bold)`
`--typography-display-1-line-height`	`var(--line-height-115)`
`--typography-display-1-letter-spacing`	`var(--letter-spacing-n040)`
`--typography-display-2-font-family`	`var(--font-family-sans)`
`--typography-display-2-font-size`	`var(--font-size-4xl)`
`--typography-display-2-font-weight`	`var(--font-weight-bold)`
`--typography-display-2-line-height`	`var(--line-height-115)`
`--typography-display-2-letter-spacing`	`var(--letter-spacing-n040)`
`--typography-heading-1-font-family`	`var(--font-family-sans)`
`--typography-heading-1-font-size`	`var(--font-size-3xl)`
`--typography-heading-1-font-weight`	`var(--font-weight-bold)`
`--typography-heading-1-line-height`	`var(--line-height-115)`
`--typography-heading-1-letter-spacing`	`var(--letter-spacing-n020)`
`--typography-heading-2-font-family`	`var(--font-family-sans)`
`--typography-heading-2-font-size`	`var(--font-size-2xl)`
`--typography-heading-2-font-weight`	`var(--font-weight-bold)`
`--typography-heading-2-line-height`	`var(--line-height-130)`
`--typography-heading-2-letter-spacing`	`var(--letter-spacing-n020)`
`--typography-heading-3-font-family`	`var(--font-family-sans)`
`--typography-heading-3-font-size`	`var(--font-size-xl)`
`--typography-heading-3-font-weight`	`var(--font-weight-bold)`
`--typography-heading-3-line-height`	`var(--line-height-130)`
`--typography-heading-3-letter-spacing`	`var(--letter-spacing-n010)`
`--typography-title-1-font-family`	`var(--font-family-sans)`
`--typography-title-1-font-size`	`var(--font-size-xl)`
`--typography-title-1-font-weight`	`var(--font-weight-semibold)`
`--typography-title-1-line-height`	`var(--line-height-140)`
`--typography-title-1-letter-spacing`	`var(--letter-spacing-n010)`
`--typography-title-2-font-family`	`var(--font-family-sans)`
`--typography-title-2-font-size`	`var(--font-size-lg)`
`--typography-title-2-font-weight`	`var(--font-weight-semibold)`
`--typography-title-2-line-height`	`var(--line-height-140)`
`--typography-title-2-letter-spacing`	`var(--letter-spacing-n010)`
`--typography-title-3-font-family`	`var(--font-family-sans)`
`--typography-title-3-font-size`	`var(--font-size-md)`
`--typography-title-3-font-weight`	`var(--font-weight-semibold)`
`--typography-title-3-line-height`	`var(--line-height-140)`
`--typography-title-3-letter-spacing`	`var(--letter-spacing-000)`
`--typography-body-1-font-family`	`var(--font-family-sans)`
`--typography-body-1-font-size`	`var(--font-size-md)`
`--typography-body-1-font-weight`	`var(--font-weight-regular)`
`--typography-body-1-line-height`	`var(--line-height-160)`
`--typography-body-1-letter-spacing`	`var(--letter-spacing-000)`
`--typography-body-2-font-family`	`var(--font-family-sans)`
`--typography-body-2-font-size`	`var(--font-size-sm)`
`--typography-body-2-font-weight`	`var(--font-weight-regular)`
`--typography-body-2-line-height`	`var(--line-height-150)`
`--typography-body-2-letter-spacing`	`var(--letter-spacing-000)`
`--typography-body-3-font-family`	`var(--font-family-sans)`
`--typography-body-3-font-size`	`var(--font-size-xs)`
`--typography-body-3-font-weight`	`var(--font-weight-regular)`
`--typography-body-3-line-height`	`var(--line-height-150)`
`--typography-body-3-letter-spacing`	`var(--letter-spacing-000)`
`--typography-label-1-font-family`	`var(--font-family-sans)`
`--typography-label-1-font-size`	`var(--font-size-md)`
`--typography-label-1-font-weight`	`var(--font-weight-medium)`
`--typography-label-1-line-height`	`var(--line-height-140)`
`--typography-label-1-letter-spacing`	`var(--letter-spacing-000)`
`--typography-label-2-font-family`	`var(--font-family-sans)`
`--typography-label-2-font-size`	`var(--font-size-sm)`
`--typography-label-2-font-weight`	`var(--font-weight-medium)`
`--typography-label-2-line-height`	`var(--line-height-140)`
`--typography-label-2-letter-spacing`	`var(--letter-spacing-000)`
`--typography-label-3-font-family`	`var(--font-family-sans)`
`--typography-label-3-font-size`	`var(--font-size-xs)`
`--typography-label-3-font-weight`	`var(--font-weight-semibold)`
`--typography-label-3-line-height`	`var(--line-height-140)`
`--typography-label-3-letter-spacing`	`var(--letter-spacing-p010)`
`--typography-caption-1-font-family`	`var(--font-family-sans)`
`--typography-caption-1-font-size`	`var(--font-size-xs)`
`--typography-caption-1-font-weight`	`var(--font-weight-regular)`
`--typography-caption-1-line-height`	`var(--line-height-140)`
`--typography-caption-1-letter-spacing`	`var(--letter-spacing-000)`
`--typography-caption-2-font-family`	`var(--font-family-sans)`
`--typography-caption-2-font-size`	`var(--font-size-2xs)`
`--typography-caption-2-font-weight`	`var(--font-weight-regular)`
`--typography-caption-2-line-height`	`var(--line-height-140)`
`--typography-caption-2-letter-spacing`	`var(--letter-spacing-p010)`
`--typography-overline-1-font-family`	`var(--font-family-sans)`
`--typography-overline-1-font-size`	`var(--font-size-2xs)`
`--typography-overline-1-font-weight`	`var(--font-weight-bold)`
`--typography-overline-1-line-height`	`var(--line-height-140)`
`--typography-overline-1-letter-spacing`	`var(--letter-spacing-p080)`
`--typography-code-1-font-family`	`var(--font-family-mono)`
`--typography-code-1-font-size`	`var(--font-size-md)`
`--typography-code-1-font-weight`	`var(--font-weight-regular)`
`--typography-code-1-line-height`	`var(--line-height-160)`
`--typography-code-1-letter-spacing`	`var(--letter-spacing-000)`
`--typography-code-2-font-family`	`var(--font-family-mono)`
`--typography-code-2-font-size`	`var(--font-size-sm)`
`--typography-code-2-font-weight`	`var(--font-weight-regular)`
`--typography-code-2-line-height`	`var(--line-height-150)`
`--typography-code-2-letter-spacing`	`var(--letter-spacing-000)`
`--typography-code-3-font-family`	`var(--font-family-mono)`
`--typography-code-3-font-size`	`var(--font-size-xs)`
`--typography-code-3-font-weight`	`var(--font-weight-regular)`
`--typography-code-3-line-height`	`var(--line-height-150)`
`--typography-code-3-letter-spacing`	`var(--letter-spacing-000)`

Font family

`--font-family-sans`	`Pretendard, "Apple SD Gothic Neo", "Noto Sans KR", sans-serif`
`--font-family-mono`	`"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace`

Font weight

`--font-weight-regular`	`400`
`--font-weight-medium`	`500`
`--font-weight-semibold`	`600`
`--font-weight-bold`	`700`

Line height

`--line-height-100`	`1`
`--line-height-115`	`1.15`
`--line-height-130`	`1.3`
`--line-height-140`	`1.4`
`--line-height-150`	`1.5`
`--line-height-160`	`1.6`

Letter spacing

`--letter-spacing-n040`	`-0.04em`
`--letter-spacing-n020`	`-0.02em`
`--letter-spacing-n010`	`-0.01em`
`--letter-spacing-000`	`0`
`--letter-spacing-p010`	`0.01em`
`--letter-spacing-p080`	`0.08em`

Motion

reduced motion에서 재생 시간이 0ms

`--motion-duration-instant`	`0ms`
`--motion-duration-fast`	`120ms`
`--motion-duration-normal`	`180ms`
`--motion-duration-slow`	`280ms`
`--motion-ease-standard`	`cubic-bezier(0.2, 0, 0, 1)`
`--motion-ease-emphasized`	`cubic-bezier(0.2, 0, 0, 1.2)`
`--motion-ease-exit`	`cubic-bezier(0.4, 0, 1, 1)`

Density

data-density="compact"에서 바뀜

`--density-control-gap`	`var(--space-3)`
`--density-section-gap`	`var(--space-8)`

Layer

z-index 순서

`--layer-dropdown`	`1000`
`--layer-sticky`	`1100`
`--layer-overlay`	`1200`
`--layer-toast`	`1300`
`--layer-tooltip`	`1400`

Safe area

env() 값을 그대로 전달

`--safe-area-top`	`env(safe-area-inset-top, 0px)`
`--safe-area-right`	`env(safe-area-inset-right, 0px)`
`--safe-area-bottom`	`env(safe-area-inset-bottom, 0px)`
`--safe-area-left`	`env(safe-area-inset-left, 0px)`

Tailwind CSS v4 bridge

패키지가 제공하는 완성 CSS만 사용하는 앱에는 이 bridge가 필요 없습니다. 역할별 토큰을 Tailwind utility에서 사용할 때 추가합니다. 색상은 Tailwind의 표준 --color-* namespace를 공유하므로 bg-info-300처럼 쓰고, radius는 rounded-action, rounded-form-field, rounded-section, rounded-overlay처럼 역할로 고릅니다. Typography는 text-body-2와 text-code-2처럼 글꼴 계열을 포함한 recipe로 선택합니다.

app/globals.css

@import 'tailwindcss';
@import '@amineslab/ui/styles/tailwind';

SettingsPanel.tsx

import { Button } from '@/ui'

<div className="bg-background-primary text-body-2 text-text-primary">
  <p className="text-heading-2 text-brand">제품 제목</p>
  <aside className="rounded-section bg-background-secondary">탐색</aside>
  <input className="rounded-form-field bg-form-field text-body-1 text-text-primary" aria-label="이름" />
  <button className="bg-interactive-item hover:bg-interactive-item-hover">메뉴 항목</button>
  <Button>저장</Button>
</div>

프로젝트에서 쓰는 구조

제품의 UI 폴더에는 재내보내기 진입점, 테마 파일, 필요한 컴포넌트 래퍼만 둡니다. 화면 코드에서는 패키지 이름 대신 제품의 UI 진입점에서 컴포넌트를 가져옵니다.

권장 구조

src/
  ui/
    index.ts        # @amineslab/ui를 다시 내보내는 유일한 진입점
    icons.ts        # 제품이 승인한 아이콘만 다시 내보냄
    providers.tsx   # 앱 전체에 적용할 ThemeProvider, TooltipProvider
    theme.css       # [data-brand='product'] 색상 재정의
    button.tsx      # 제품 기본값을 고정한 얇은 래퍼 (필요한 것만)
  app/
    layout.tsx      # '@amineslab/ui/styles' 와 './ui/theme.css' 를 여기서 한 번 import

src/ui/index.ts

// src/ui/index.ts
// 화면 코드는 '@amineslab/ui'가 아니라 '@/ui'에서 가져온다.
// 패키지를 올리거나 래퍼로 바꿀 때 이 파일 하나만 고치면 된다.
export * from '@amineslab/ui'
export { ProductButton as Button } from './button'

// src/ui/icons.ts
export { ArrowRight, Check, Plus, Search, Settings, Trash2 } from '@amineslab/ui/icons'

app/layout.tsx

import '@amineslab/ui/styles'
import './ui/theme.css'

import type { ReactNode } from 'react'
import { Providers } from '@/ui/providers'

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ko" data-theme="light" data-brand="product" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

얇은 래퍼

제품 기본값을 바꿀 때만 래퍼를 만듭니다. 래퍼는 props와 ref를 전달하며 패키지의 클래스나 DOM 구조에 의존하지 않습니다. 새 variant가 필요하면 패키지 API로 제안합니다.

src/ui/button.tsx

// src/ui/button.tsx
import { Button, type ButtonProps } from '@amineslab/ui'
import { forwardRef } from 'react'

/** 제품 기본값만 고정한다. props와 접근성 동작은 패키지 구현을 따른다. */
export const ProductButton = forwardRef<HTMLButtonElement, ButtonProps>(
  function ProductButton({ size = 'lg', ...props }, ref) {
    return <Button {...props} ref={ref} size={size} />
  },
)

이렇게 합니다

기본 size, 기본 variant, 제품 아이콘 등 제품 공통값만 고정합니다.
prop 이름은 패키지와 동일하게 유지합니다.

피합니다

내부 클래스를 selector로 선택해 덮어쓰지 않습니다.
컴포넌트 소스를 복사하거나 패키지에 없는 prop을 추가하지 않습니다.

유지보수

패키지 버전을 정확히 고정하고 CHANGELOG를 읽은 뒤 typecheck, lint, build를 실행합니다. 업그레이드할 때는 UI 진입점, 테마 파일, 컴포넌트 래퍼의 변경을 먼저 검사합니다.

upgrade.sh

# 1. 변경 내용 읽기
cat node_modules/@amineslab/ui/CHANGELOG.md

# 2. 올리기
pnpm add @amineslab/ui@0.2.0

# 3. 게이트
pnpm typecheck && pnpm lint && pnpm build

역할별 토큰 이름이 바뀌면 theme.css의 참조를 고치고 Color 페이지의 목록과 비교합니다.
컴포넌트 props가 바뀌면 래퍼를 먼저 수정합니다. 화면 코드는 @/ui에서 컴포넌트를 가져옵니다.
동일한 props로 이 문서의 Playground와 제품 화면을 나란히 비교합니다.
tarball은 Versioning 절차에 따라 독립 fixture에 설치합니다.

대비 확인

기본 토큰은 핵심 색상 조합의 대비 테스트를 통과합니다. 역할별 색상을 바꿨다면 브라우저에 계산된 색상값으로 다음 대비를 다시 검사합니다.

background와 section 위의 일반 텍스트 4.5:1, 큰 텍스트 3:1
Button variant와 colored elevation 위의 텍스트·아이콘 대비
포커스 표시와 인접 배경의 대비 3:1
색상 외에 텍스트나 아이콘으로도 상태 전달

contrast.test.ts

import { semanticColorValues } from '@amineslab/ui/tokens'

// 패키지 기본값. 제품 재정의가 반영된 값은 getComputedStyle로 읽는다.
semanticColorValues.light['--color-text-primary']   // 'oklch(20.5% 0 none)'
semanticColorValues.dark['--color-background-primary']  // theme-aware role

사용 기준

권장하는 사용

원시 색을 바로 쓰지 말고 background, section, form field, interactive item 토큰을 palette와 elevation에 연결합니다.
Button의 상태 색은 brand palette와 elevation으로 처리합니다.

피해야 할 사용

고정된 coral이나 orange를 작은 글자에 쓰지 마세요.
대비를 검사한 역할별 색을 사용합니다.

확인 기준

공개 import 경로와 타입 선언에 맞춰 사용했는지 확인합니다.
라이트·다크 모드에서 정보와 포커스를 구분할 수 있어야 합니다.
390px 화면, 200% 확대, 키보드 탐색에서도 작업을 마칠 수 있어야 합니다.

`--font-size-2xs`	`0.6875rem`
`--font-size-xs`	`0.75rem`
`--font-size-sm`	`0.875rem`
`--font-size-md`	`1rem`
`--font-size-lg`	`1.125rem`
`--font-size-xl`	`1.25rem`
`--font-size-2xl`	`1.5rem`
`--font-size-3xl`	`1.875rem`
`--font-size-4xl`	`2.25rem`
`--font-size-5xl`	`3rem`

Setup

next-themes와 연결

일부 영역에 다른 테마 적용

Token 계층

단계 숫자와 OKLCH

제품 색상 override

Gray family 선택

Accent palette 지정

테마별 브랜드 역할

함께 확인할 role

Light와 dark를 함께 정의하기

Elevation

Colored elevation

Border

Radius와 geometry override

Design tokens

Component alias

Radius

Shadow

Spacing

Typography recipes

Font family

Font size

Font weight

Line height

Letter spacing

Motion

Density

Layer

Safe area

Tailwind CSS v4 bridge

프로젝트에서 쓰는 구조

얇은 래퍼

유지보수

대비 확인

사용 기준

확인 기준