Foundation

Color

원시 팔레트, neutral·colored elevation, 컴포넌트 역할별 색을 구분합니다.

Primitive

테마와 관계없이 고정된 색상 재료입니다. Raw palette는 값이 고정되고, Gray와 Accent alias는 서비스가 고른 raw family를 가리킵니다. 숫자가 낮을수록 밝고 높을수록 어둡습니다.

Black & White

Gray

Gray는 alias입니다. 서비스는 Neutral, Slate, Stone, Zinc 중 하나를 골라 50~950 전체를 한 번에 교체합니다. 기본값은 Neutral입니다.

Neutral

색 기운이 없는 중성 회색. gray의 기본값입니다.

Slate

은은한 청색 기운의 차가운 회색입니다.

Stone

은은한 웜 기운의 회색입니다.

Zinc

미세한 보랏빛이 도는 무채색입니다.

Chromatic

상태 의미가 아니라 제품 그래픽과 semantic palette의 재료로 쓰는 고정 원색입니다.

Coral

Sage

Steel

Red

Orange

Amber

Yellow

Lime

Green

Emerald

Teal

Cyan

Sky

Blue

Indigo

Violet

Purple

Fuchsia

Pink

Rose

Accent

Accent는 Amineslab Coral을 기본값으로 가리키는 primitive alias입니다. light/dark selector에서 서로 다른 값을 주지 않고 서비스 범위에서 전체 ramp를 한 번 override하면 brand semantic이 mode별 위계를 적용합니다.

Elevation

부모 배경 위에 중성 잉크를 합성하는 11단계 primitive입니다. 자식의 opacity나 box-shadow가 아니며, 숫자가 높을수록 구분이 강해집니다. light와 dark는 같은 단계가 비슷한 시각적 무게를 갖도록 서로 다른 잉크 비율을 사용합니다.

light

dark

Border

테두리에는 neutral elevation 50~950을 사용합니다. 기본 구분선은 700, 강조할 컨트롤은 800, 선택·포커스 구분선은 950부터 조정하세요.

border-elevation-700border-elevation-800border-elevation-950

Semantic

Palette dark

Elevation light

Elevation dark

Component roles

컴포넌트와 제품 화면이 우선 사용하는 role입니다. dark mode와 제품 override가 이 계층에 반영됩니다.

Background

앱 shell의 세 영역을 main content, 보조 navigation, 그 사이의 gutter로 구분합니다.

TokenLightDarkUse

background-primary

white

gray-800

본문과 주요 content가 올라가는 app의 기본 배경

background-secondary

gray-50

gray-900

LNB, sidebar, TOC처럼 본문을 보조하는 영역의 배경

background-tertiary

gray-100

gray-950

main content와 보조 영역 사이를 구분하는 gutter 배경

Section

content 안에서 카드·패널·중첩 영역과 떠 있는 section의 깊이를 구분합니다.

TokenLightDarkUse

section-primary

elevation-100

content 안의 기본 카드·패널·그룹 배경

section-secondary

elevation-200

section header나 한 단계 들어간 보조 영역

section-tertiary

elevation-300

section 안에서 다시 구분되는 가장 깊은 영역

section-overlay

white

gray-800

제품에서 직접 조합하는, 문서 흐름 위에 떠 있는 section

Form field

입력·선택 control의 기본, hover, disabled 배경을 한 묶음으로 관리합니다.

TokenLightDarkUse

form-field

elevation-300

입력·선택 control의 기본 배경

form-field-hover

elevation-500

입력·선택 control을 가리킨 상태의 배경

form-field-disabled

elevation-100

수정할 수 없는 입력·선택 control의 배경

form-field-disabled-foreground

gray-600

gray-300

비활성 field 안에서도 읽어야 하는 값과 icon

Interactive item

메뉴·목록·option처럼 반복되는 항목의 기본과 상호작용 상태입니다.

TokenLightDarkUse

interactive-item

white

gray-800

메뉴·목록·option의 기본 항목 배경

interactive-item-hover

elevation-200

항목을 가리키거나 keyboard로 탐색하는 상태

interactive-item-disabled

elevation-100

선택하거나 실행할 수 없는 항목

interactive-item-disabled-foreground

gray-500

gray-400

비활성 항목의 text와 icon

interactive-item-selected

elevation-accent-200

현재 선택된 항목의 accent 배경

interactive-item-selected-foreground

accent-900

accent-100

선택된 accent 배경 위의 text와 icon

Text

typography 크기와 독립적으로 본문 강조도와 반전 배경 위 text·icon의 위계를 정합니다.

TokenLightDarkUse

text-primary

gray-900

gray-50

제목, 본문, label처럼 가장 먼저 읽어야 하는 content

text-secondary

gray-600

gray-300

설명, metadata, field 값처럼 충분한 가독성이 필요한 보조 content

text-tertiary

gray-500

gray-400

장식적 hint, placeholder, 구분자처럼 가장 낮은 강조의 content

text-inverse

white

gray-900

짙은 단색 배경 위의 반전 text와 icon

Brand

accent 500을 사용하는 단일 브랜드 색상입니다.

TokenLightDarkUse

brand

accent-500

브랜드 원색을 사용하는 text와 icon

brand-foreground

white

브랜드 채움 위의 text와 icon

Focus and Link

keyboard focus ring과 문장 안 링크입니다.

TokenLightDarkUse

focus

accent-600

accent-400

keyboard focus indicator

link

accent-700

accent-300

본문 안에서 이동을 나타내는 기본 link

link-hover

accent-800

accent-200

본문 link의 hover 상태

Usage

완성 CSS를 import하면 모든 token이 CSS 변수로 존재합니다. Tailwind utility가 필요한 앱만 bridge를 추가합니다. Primitive는 그래픽과 palette 정의에, Semantic은 실제 UI에 씁니다.

Semantic role · CSS

color: var(--color-text-primary);

var(--color-{role})

Semantic elevation · Tailwind

<p className="bg-elevation-accent-300 text-brand">Brand</p>

{utility}-{elevation-family-step}

Opacity modifier

<div className="bg-elevation-accent-300/50">

{utility}-{name}/{opacity}

Inline style

<div style={{ borderColor: token('--color-elevation-700') }} />

token('--color-{name}')

Resolved semantic value

semanticColorValues.dark['--color-brand-300']

semanticColorValues.{light|dark}[token]

Primitive step

background: var(--color-coral-500);

var(--color-{family}-{step})

Primitive vs Semantic

Primitive는 색의 원본 값이고, Semantic은 배경·텍스트·상태에 맞춰 연결한 토큰입니다. 컴포넌트와 제품 화면에는 Semantic을 우선 사용합니다.

Semantic 토큰 사용

dark mode 자동 대응과 제품별 테마 재정의를 위해 semantic token을 우선 사용합니다.

text-text-primary기본 본문 텍스트
bg-background-primarymain content 배경
bg-section-primary카드와 패널 면
bg-interactive-item-selected선택된 item의 accent 배경
text-brandtheme-aware brand text

Primitive 토큰 사용

테마와 무관하게 고정되어야 하는 브랜드 그래픽, 일러스트, palette 정의에 사용합니다.

var(--color-accent-500)서비스 accent 원색
var(--color-coral-500)Amineslab 고정 원색
var(--color-neutral-950)고정 어두운 배경

Dark mode

<html data-theme="dark"> 또는 .dark가 있으면 semantic token이 참조하는 primitive가 바뀝니다. raw primitive 자체의 값은 두 테마에서 같습니다.

<html lang="ko" data-theme="dark" data-brand="product">
  {/* --color-background-primary: gray-800, --color-text-primary: gray-50 */}
</html>

Gray family selection

제품의 온도에 맞춰 gray alias 전체를 Neutral, Slate, Stone, Zinc 중 하나로 선택합니다. 모든 단계를 같은 family로 매핑해야 light와 dark의 위계가 어긋나지 않습니다.

src/styles/theme.css

[data-brand='product'] {
  /* gray는 서비스에 맞는 raw gray family를 고릅니다. 기본값은 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 override

서비스가 accent를 바꾸려면 raw accent의 50부터 950까지 전체 ramp를 제품 범위에서 지정합니다. 이 primitive는 light/dark에서 동일하게 유지하고, brand role이 mode별로 적절한 단계를 선택하게 합니다.

src/styles/theme.css

[data-brand='product'] {
  /* accent primitive은 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);
}

Setup

완성 CSS 한 번, Tailwind bridge는 선택입니다.

app/layout.tsx

import '@amineslab/ui/styles'

app/globals.css

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

tokens.ts

import {
  primitiveColorNames,
  primitiveColorValues,
  neutralElevationColorNames,
  semanticElevationColorNames,
  elevationColorValues,
  semanticPaletteColorNames,
  semanticRoleColorNames,
  semanticColorNames,
  semanticColorValues,
  token,
} from '@amineslab/ui/tokens'

primitiveColorNames.length
primitiveColorValues['--color-accent-500']
token('--color-background-primary')
semanticColorValues.dark['--color-brand-300']
elevationColorValues.dark['--color-elevation-accent-300']
neutralElevationColorNames.length + semanticElevationColorNames.length
semanticPaletteColorNames.length + semanticRoleColorNames.length

사용 기준

권장하는 사용

화면에서는 `--color-background-primary`, `--color-form-field`, `--color-interactive-item`, `--color-text-primary` 같은 역할별 토큰과 Button 같은 공개 컴포넌트를 사용합니다.

피해야 할 사용

palette 단계 번호를 제품 상태 의미로 고정하지 마세요.

검증 기준

라이트·다크 모드에서 각 토큰의 역할과 정보 구분이 유지되는지 확인합니다.
토큰을 재정의한 뒤에도 텍스트, 포커스, 경계가 선명하게 구분되어야 합니다.
브랜드 원색은 표현에, 의미 토큰은 화면의 역할과 상태에 맞춰 사용합니다.

Primitive

Black & White

Gray

Neutral

Slate

Stone

Zinc

Chromatic

Accent

Elevation

Border

Semantic

Palette & elevation semantics

Brand / Accent

Success

Warning

Danger

Info

Component roles

Background

Section

Form field

Interactive item

Text

Brand

Focus and Link

Usage

Primitive vs Semantic

Dark mode

Gray family selection

Categories

Accent override

Setup

사용 기준

검증 기준