Color foundation v0
상태: Provisional
이 문서는 브랜드 seed color를 ooee의 primitive 및 semantic color token으로 변환하는 초기 규칙을 정의한다. 실제 컴포넌트와 여러 브랜드에서 검증되기 전까지 매핑값은 변경될 수 있다.
생성 과정
- 6자리 HEX 브랜드 seed를 입력한다.
- Material Color Utilities의 HCT로 동일한 hue/chroma의 tonal palette를 생성한다.
- HCT tone을 ooee의
brand-50~950명칭에 연결한다. - seed의 RGB 값을 기준으로 alpha primitive를 생성한다.
- Light/Dark 모드별 oe semantic token을 primitive에 연결한다.
- 컴포넌트에서는 semantic token을 우선 사용한다.
HCT는 palette 계산 도구로 사용한다. Material의 semantic role이나 컴포넌트 색상 체계를 그대로 채택하지 않는다.
Color Foundation 화면은 Tailwind Primitive, OE Semantic, Brand Color를 한 페이지의 분리된 탭으로 제공한다. Tailwind Primitive에는 Tailwind CSS v4의 white/black과 22개 기본 palette 전체를 표시한다. OE Semantic은 실제 컴포넌트가 우선 사용하는 의미 토큰을, Brand Color는 seed와 HCT로 생성한 ooee 전용 palette 및 semantic mapping 후보를 표시한다. Sidebar와 Chart는 특수 목적의 shadcn token으로 유지하며 oe 공용 semantic 목록에 포함하지 않는다. 세 탭은 주소 해시와 연결된다. #primitive·#semantic·#brand로 특정 탭을 바로 가리킬 수 있고, 탭을 누르면 주소도 따라 바뀐다.
Neutral, Accent, Warning, Danger, Success, Info의 이름과 Light/Dark primitive 매핑은 packages/tokens/src/index.ts의 CORE_SEMANTIC_TOKENS가 단일 실행 원본이다. Color Foundation 표와 Studio 전역 CSS 변수는 이 정의를 함께 사용하며 표시용 목록을 별도로 복제하지 않는다.
Solid primitive
| Token | HCT tone |
|---|---|
brand-50 |
98 |
brand-100 |
95 |
brand-200 |
90 |
brand-300 |
80 |
brand-400 |
70 |
brand-500 |
60 |
brand-600 |
50 |
brand-700 |
40 |
brand-800 |
30 |
brand-900 |
20 |
brand-950 |
10 |
brand-source는 입력한 브랜드 원색을 그대로 보존한다. HCT palette는 색역 보정으로 인해 source와 정확히 같은 값을 포함하지 않을 수 있다.
Alpha primitive
다음 단계만 생성한다.
brand-alpha-05
brand-alpha-08
brand-alpha-10
brand-alpha-16
brand-alpha-20
brand-alpha-30
brand-alpha-40
brand-alpha-50
brand-alpha-60
brand-alpha-70
brand-alpha-80
brand-alpha-90
Alpha primitive는 화면 예시에서 직접 사용할 수 있지만 컴포넌트에 임의로 반복 사용하지 않는다. 같은 의미와 맥락에서 반복되면 semantic token으로 승격할 필요가 있는지 검토한다.
Semantic mapping v0
Light
oe-brand-foreground-primary → brand-800
oe-brand-foreground-secondary → brand-600
oe-brand-background-primary → brand-50
oe-brand-background-secondary → brand-100
oe-brand-background-bold-primary → brand-700
oe-brand-border-primary → brand-500
oe-brand-border-secondary → brand-200
oe-focus-ring → brand-600
Dark
oe-brand-foreground-primary → brand-200
oe-brand-foreground-secondary → brand-400
oe-brand-background-primary → brand-950
oe-brand-background-secondary → brand-900
oe-brand-background-bold-primary → brand-400
oe-brand-border-primary → brand-500
oe-brand-border-secondary → brand-800
oe-focus-ring → brand-400
위 값은 모든 브랜드에 적용되는 확정 공식이 아니다. seed의 명도와 chroma, 실제 배경과 접근성 대비를 Color Lab에서 검수한 뒤 브랜드별로 override할 수 있다.
공통 사용 규칙
- Neutral surface는
oe-background-*, 브랜드 표현은oe-brand-background-*를 사용한다. - 직접 조작하는 form control의 식별 보더는
oe-border-primary, control과 Label 등을 하나의 영역으로 감싸는 form container 보더는oe-border-secondary를 사용한다. - 상태색은
oe-danger-*,oe-warning-*,oe-success-*,oe-info-*로 분리한다. - 상태 색을 증감에 빌려 쓰지 않는다. 값이 오르내린 것은 상태가 아니다. 매출이 는 것은
success가 아니고 준 것은danger가 아니므로 증감은oe-up-*,oe-down-*을 쓴다. 오르내림이 좋은 일인지 나쁜 일인지는 화면이 정한다. - brand와 겹치는 뜻은 색만으로 알리지 않는다. brand는 seed에서 뽑는 색이므로(
createBrandPalette) 어떤 semantic 색과 겹칠지는 고객이 고른 seed가 정한다. 기본 seed#2563EB에서는 Dark의oe-down-background-bold-primary가brand-400과 적록 색약에서 ΔEok 0.0013이고, 초록 seed는 적록 색약에서oe-danger-*와 만난다. 고정 palette를 다시 골라 없앨 수 있는 겹침이 아니므로, brand와 나란히 서는 뜻은 부호·화살표·글자 등 색 아닌 것으로도 알린다. - 증감은 색만으로 알리지 않는다.
oe-up-*,oe-down-*으로 칠한 값에는+/-부호나 화살표를 함께 둔다. 위 brand 규칙이 적용되는 첫 자리다. - 어두운 solid 배경 위의 텍스트와 아이콘은 공통
oe-foreground-inverse를 우선 검토한다. - 밝은 브랜드 배경에서는
oe-foreground-primary처럼 대비가 확보되는 중립 foreground를 사용한다. - Primitive 숫자는 컴포넌트 의미가 아니다. 공용 컴포넌트는 가능한 semantic token을 사용한다.
- Alpha 결과는 합성되는 배경에 따라 달라지므로 Light, Dark, 이미지 배경에서 각각 검수한다.
oe-focus-ring은 적용된 brand seed를 기반으로 Lightbrand-600, Darkbrand-400에 연결한다. 브랜드 기반이어도 식별 가능성과 대비 검증을 우선한다.
아직 확정하지 않은 항목
- 대표 solid action에 사용할 semantic token 이름
- 브랜드별 semantic override 저장 형식
- 대비 검증 기준과 자동 경고 수준
- Neutral 및 status palette 생성 규칙
다음 검토 체크포인트
현재 Studio의 OE Semantic 표와 위 Semantic mapping v0은 구조를 눈으로 확인하기 위한 임시안이다. 아래 질문에 답하기 전에는 실제 컴포넌트의 확정 기준이나 최종 매핑으로 간주하지 않는다.
제안하는 최소 역할
Neutral
oe-foreground-primary / secondary / tertiary / subtle / placeholder / disabled / inverse
oe-foreground-inverse-secondary
oe-background-canvas-primary / canvas-secondary
oe-background-primary / secondary / alternate / disabled / disabled-selected / bold-primary
oe-background-control-off / control-disabled
oe-border-primary / bold-primary / secondary / tertiary / disabled / visual / overlay-subtle
oe-focus-ring
oe-interaction-hover-subtle
oe-interaction-hover
Accent
oe-accent-background-bold-primary
Brand 및 danger / warning / success / info
oe-{role}-foreground-primary / secondary
oe-{role}-background-primary / secondary / bold-primary
oe-{role}-border-primary / secondary
증감 up / down
oe-{role}-foreground-primary / secondary
oe-{role}-background-primary / secondary / bold-primary
oe-{role}-border-primary / secondary
범주 색 (뜻 없음 · 차례만)
oe-categorical-1
oe-categorical-2
oe-categorical-3
oe-categorical-4
oe-categorical-5
oe-categorical-6
oe-categorical-7
oe-categorical-8
oe-categorical-9
primary/secondary는 사용 빈도가 아니라 같은 role/property 안의 시각적 위계를 나타낸다.- Light Neutral background는 primary에서 secondary 순으로 어두워진다. Dark에서는 이름보다 동일한 UI 역할과 계층을 유지한다.
- Canvas와 컴포넌트 surface는 독립적으로 테마를 바꿀 수 있도록 분리한다.
- Light와 Dark semantic token을 교체하는 동안에는 색상 transition을 일시 중지한다. 컴포넌트의 선택·Hover 같은 상태 transition은 유지하되, 서로 다른 테마 값 사이를 보간해 중간색이 노출되지 않게 한다.
background-bold-primary는 버튼, 배지, 강한 선택 상태처럼 채도가 높거나 어두운 solid fill의 후보 이름이다.bold는 background와 border에 쓰는 modifier로, 그 property 안에서 가장 진한 solid 단계를 가리킨다.oe-background-bold-primary는 채도가 높거나 어두운 solid fill과 작은 면의 선택에,oe-border-bold-primary는 Select Box 카드처럼 큰 면의 선택을 선으로 알릴 때 쓴다. 선으로 알릴지 면을 채워 알릴지는 interaction.md의 「선택 상태와 Hover·Pressed」가 정한다. foreground에는bold를 붙이지 않는다.interaction-hover는 기존 background를 교체하지 않고 위에 합성하는 state layer다. 초기값은 Lightblack / 5%, Darkwhite / 8%이며 화면 검증 후 조율한다.- 클릭 가능한 아이콘은 공통적으로 hover 시
interaction-hover회색조 state layer를 표시하고, keyboard focus 시oe-focus-ring을 표시한다. - Pointer 클릭으로 Control이 실제 DOM focus를 받을 수는 있지만 Focus 시각 표시는
:focus-visible을 기준으로 한다. 마우스 클릭만으로 Focus 선을 노출하지 않는다. Focus 경계는 기존 선 구조에 따라 세 방식 중 하나를 사용한다. 1px 경계는 기존 선의 색을oe-focus-ring으로 바꾸고 바깥에 간격 없는 1px을 더해 총 2px로 표시한다. 기존 선택선이 2px이면 위치와 두께를 유지한 채 색만 바꾼다. 분리된 Focus 표시가 필요한 경우에는 기본 2px 간격 뒤에 바깥 2px ring을 사용한다. 한 요소에 선택선과 분리 ring을 중첩하지 않는다. foreground-inverse-secondary는 bold fill 위의 약한 메타 정보에 사용한다.background-disabled-selected는 선택값을 유지한 채 조작만 제한된 control의 Neutral fill이다. Light/Dark 모두neutral-400을 사용한다.background-alternate는 줄이 번갈아 오는 것을 알리는 면이다. Lightneutral-50, Darkneutral-850으로 두 테마에서background-primary와background-secondary사이에 선다. 위계 이름이 아니라 구실 이름이며, 표의 짝수 줄이 쓴다. 그 자리에background-secondary를 다시 쓰면 머리줄·Footer·골라 둔 줄이 이미 쓰는 값과 같아져 짝수 줄이 골라 둔 줄로 읽힌다. Dark의neutral-850은border-tertiary가 이미 쓰는 사이 단계다.background-control-off는 조작 가능한 Boolean control의 Off Track이며 Lightneutral-400, Darkneutral-500을 사용한다.background-control-disabled는 조작할 수 없는 Boolean control의 Track이다. 이전 Off 색상인 Lightneutral-300, Darkneutral-600을 사용해 Enabled Off보다 한 단계 낮은 위계를 만든다.accent는 danger나 warning 같은 상태 의미 없이 시선을 끄는 교체 가능한 강조 role이다. shadcnaccent와 직접 매핑하지 않는다.oe-accent-background-bold-primary는 Lightred-600, Darkred-400으로 시작한다.- 경계는 세 단계다.
oe-border-primary가 컨트롤과 면의 경계,oe-border-secondary가 그보다 한 단계 물러난 구분,oe-border-tertiary가 가장 옅은 구분이다. Tertiary는 같은 묶음 안을 나누는 자리에 쓴다. 필터 패널에서 조건 축을 가르는 선이 그 자리이며, 그 선이 Secondary면 상자를 두르는 테두리와 같은 무게가 되어 패널 안이 격자로 보인다. 값은 Lightneutral-150, Darkneutral-850이다.oe-border-disabled(Lightneutral-100, Darkneutral-900)보다 배경과 조금 더 구별되며, 꺼진 상태를 뜻하는 그 이름과는 뜻이 다르므로 이름을 따로 둔다. border-overlay-subtle은 바탕 위에 아주 옅게 긋는 선이다. 경계가 무엇을 두르는 자리가 아니라, 바탕 자체에 얹히는 보조선이 쓴다 — Chart의 격자와 기준선이 첫 용례다. Lightblack 8%, Darkwhite 12%이며 Neutral 가운데 유일하게 Dark에서 흰색을 얹는다. 고정 단계가 아닌 까닭은 이 선이 서는 바탕이 하나가 아니기 때문이다. 고정 중립border-primary로 그리면 같은 선이 Darkbackground-canvas-primary위에서 바탕과 채널 차 54, Darkbackground-secondary위에서 26으로 두 배 넘게 흔들린다. alpha는 그 차를 Light 20, Dark 2629로 묶으며, 이 값은19)의 1.5배다. 1px 점선은 면보다 좁아 같은 알파로는 선으로 읽히지 않는다.interaction-hover겹이 내는 차(Light 13, Dark 17up·down은 값의 방향을 말하는 역할이며 상태가 아니다.danger·warning·success·info와 같은 문법(foreground/background/border × primary/secondary)을 쓰지만 좋고 나쁨을 뜻하지 않으므로positive·negative라 부르지 않는다. 값은 국내 관례를 따라 상승이pink, 하락이sky이며 서양과 뒤집혀 있다. 팔레트는 재어 골랐다(2026-10-07).danger가red를,info가blue를 이미 쓰므로 같은 팔레트를 다시 쓰면 두 뜻이 화면에서 하나가 된다. 토스증권의 상승색#F5445A에 가장 가까운rose는red와 갈리지 않았다 — Darkforeground-primary가 되는rose-200과red-200이 채널 차 10, Oklab 거리 0.0119로 변별 문턱(약 0.02) 아래다.pink는 짙은 네 자리에서 모두 갈린다(화면이 쓰는foreground-secondary가 Light 채널 차 107·0.115, Dark 79·0.111). 하락의sky는blue와 같은 자리에서 Light 43·0.120, Dark 80·0.073이다. 이웃한 색상끼리는background-primary·background-secondary처럼 흰색·검정에 거의 닿은 단계에서는 겹치며(pink-50과red-50이 채널 차 6), 그 자리는 이미 싣고 있는 네 상태 family도 서로 가장 가깝다(Oklab 0.021~0.039). 증감에 배경 용례가 생기면 그 자리를 다시 잰다.oe-categorical-1…-9는 뜻이 없는 유일한 역할이다. 서로 다르다는 것만 말하므로 위계도 property도 없고 이름이 차례뿐이며,oe-{role}-{property}-{hierarchy}문법을 따르지 않는다. 글자(text-)와 면(bg-)에 같은 값을 쓴다 — 범례의 점과 지도 핀이 이어져야 한다. 차례는 1부터 차례로 쓰고 섞지 않는다. 쓰는 자리는 지도·범례의 범주와 Chart의 셋째 계열부터다(components/chart.md).- 범주 색의 수와 값은 재어서 정했다(
2026-10-07). 자는 OKLab 거리 ΔEok, 문턱은 이 저장소가 이미 쓰는 0.02다. 네 조건을 두 테마에서 모두 넘겨야 하고, 넘기지 못한 쌍은 하나도 없다. ① 서로 갈린다 — 쌍 36개 × 두 테마 × 네 시야 288번을 재어 가장 가까운 쌍이 0.0426이다(categorical-3×categorical-9, Dark protanopia). ② 색약에서도 갈린다 — 변환은 Machado, Oliveira & Fernandes (2009)의 severity 1.0 행렬을 선형 sRGB에 곱한 것이며 protanopia·deuteranopia·tritanopia 셋을 모두 잰다. 붉은 쪽 팔레트가 여기서 떨어졌다. Dark의lime-400과warning의amber-400이 deuteranopia에서 0.0096, Light의yellow-700과amber-700이 0.0045,lime-600과danger의red-500이 0.0070으로 문턱 아래다. ③ brand·status·증감과 갈린다 — 같은 화면에 표식으로 설 수 있는 색 열여덟 자리(자사brand, 그래프 둘째 계열foreground-tertiary, 상태 넷과 증감 둘의 짙은 자리,accent)와 재어 가장 가까운 것이 0.0208이다(categorical-4×down-background-bold-primary, Dark protanopia). ④ 8px에서 보인다 — 범례의 점이 8px 원이므로 바탕background-primary와의 대비가 가장 낮은 것도 3.05:1로 quality.md의 「필수 UI 3:1」 위이고, OKLCh chroma가 모두 0.065 이상이어서 회색으로 읽히지 않는다(무채색이면 그래프 둘째 계열의foreground-tertiary와 뜻이 겹친다). - 범주 색은 아홉에서 멈춘다. 수요는 상권 메인의 범례 열 자리이고 그 가운데 자사 한 자리는
brand가 갖기로 이미 정해져 있어 범주 색이 덮을 자리가 아홉이다. 열을 같은 조건으로 찾으면 가장 가까운 쌍이 정확히 문턱 0.0200에 닿아 8px 점에서 갈리지 않고, 열하나는 조건을 넘기는 조합이 없다. 아홉 넘게 필요하면 색이 아니라 다른 축(모양·무늬·라벨)을 쓰거나 그래프를 나눈다. - 범주 색이 쓰는 팔레트는
orange·cyan·violet·purple·teal·emerald·fuchsia·indigo여덟이다. 뜻이 묶인 팔레트(red·amber·green·blue·pink·sky·neutral)를 다시 쓰지 않는다 — 같은 팔레트를 쓰면 두 구실이 화면에서 하나가 된다.rose는red와 갈리지 않아 증감에서 이미 떨어진 팔레트이므로 범주 색에도 쓰지 않고,gray·slate·zinc·stone은 무채색이라 위 ④의 chroma 밑값을 넘지 못한다. 두 색이 같은 팔레트의 두 단계를 쓰는 자리가 둘 있다(categorical-7·-9가fuchsia). 그 둘은 짙은 단계와 옅은 단계로 떨어져 있어 네 시야에서 모두 갈린다. - 이미지와 색상 값의 내부 경계는 일반 Neutral border 대신 공용
oe-border-visual을 사용한다. Light/Dark 모두 콘텐츠 자체 위에 중첩되는 1px insetblack 10%이며, 테마 surface 색상으로 바꾸지 않는다.
다음 작업에서 먼저 답할 질문
Neutral canvas와 component surface의 구조:canvas-primary/secondary와background-primary/secondary를 분리하는 안으로 현재 검토 화면에 반영했다.- Focus를 border 계열인
oe-border-focus로 둘 것인가, 독립 접근성 역할인oe-focus-ring으로 둘 것인가? 현재 추천은oe-focus-ring이다. 강한 solid fill의 modifier 이름:bold로 결정했다. 처음에는 background 전용이었으나2026-08-24에 큰 면의 선택을 선으로 알리는oe-border-bold-primary가 생겨 background와 border에 쓴다.- 지금 실제로 반복되는 overlay 용례는 무엇인가? 예: 이미지 위 border, 이미지 hover, 선택 행, brand tint, scrim. 확인 전에는 공통 overlay semantic을 늘리지 않는다.
Status role 명칭:danger,warning,success,info네 가지를 공용 명칭으로 사용하고 중복 용어는 만들지 않는다.
답변 후에는 다음을 함께 수정한다.
- 이 문서의 Light/Dark 매핑
packages/tokens/src/index.ts의 semantic reference- Studio의 OE Semantic catalog
- 필요한 경우 전역 CSS 변수와 shadcn compatibility mapping
현재 매핑은 전체 Color catalog에서 컨펌하기 위한 Provisional 후보이며, 접근성 대비와 실제 컴포넌트 검증 후 확정한다.
MessageBubble의 삭제 action hover에서 oe-danger-background-primary가 첫 실제 용례로 확인되었다. 초기 매핑은 Light red-50, Dark red-950이며 다른 danger surface와 함께 대비를 추가 검증한다.
컴포넌트 작업에서의 확장 방식
이 Color v0는 가능한 조합을 미리 모두 생성하는 닫힌 목록이 아니다. 이후 컴포넌트와 화면을 만들면서 기존 token으로 설명하기 어려운 패턴이 발견되면 다음 순서로 고도화한다.
새 색상 패턴 발견
→ 기존 semantic token이나 component recipe로 해결 가능한지 확인
→ 해결되지 않으면 사용자에게 알림
→ token candidate 등록
→ 다른 상태·모드·컴포넌트에서 재검증
→ 공용 semantic token / component token / 일회성 recipe 중 하나로 분류
→ 승인 후 Provisional 또는 확정 값에 반영
token candidate에는 최소한 다음을 기록한다.
- 발견한 화면과 컴포넌트
- 상태와 사용 맥락
- 해결하려는 의미와 시각적 역할
- 사용한 임시 primitive 또는 alpha 값
- 기존 token을 재사용하지 못한 이유
- Light/Dark 및 접근성 검수 여부
같은 의미로 세 번 반복되거나 두 개 이상의 독립 컴포넌트에서 필요하면 공용 semantic token 승격을 검토한다. 접근성, theme, 시스템 경계에 필수적인 값은 첫 용례에서도 등록할 수 있다. 특정 컴포넌트에만 의미가 있다면 공용 token을 늘리지 않고 component token 또는 recipe로 유지한다.
첫 적용
Color v0의 역할 매핑은 목록과 상세를 좌우로 나눈 Inbox 화면에서 처음 검증했다. 그 화면은 2026-09-14에 저장소에서 걷어냈으며 아래 연결은 Provisional로 남는다.
- Preview 바탕:
oe-background-canvas-secondary - Inbox와 reading pane surface:
oe-background-primary - 검색창, 선택 행, incoming bubble:
oe-background-secondary(Lightneutral-100, Darkneutral-800) - Outgoing bubble과 Send button:
oe-background-bold-primary - Unread count badge:
oe-accent-background-bold-primary - 본문, 보조 정보, timestamp와 leading icon:
oe-foreground-primary / secondary / tertiary - Bold fill 위 콘텐츠:
oe-foreground-inverse - 외곽과 내부 divider:
oe-border-primary / secondary - 키보드 focus:
oe-focus-ring
일반 Hover는 oe-interaction-hover layer를 기존 background 위에 합성한다. CheckboxField와 RadioField처럼 넓은 조작 영역에는 더 옅은 oe-interaction-hover-subtle(Light black 3%, Dark white 5%)을 사용하며 현재 Provisional이다. Outgoing message metadata의 낮은 강조는 oe-foreground-inverse-secondary를 사용한다. 이 token들은 다른 컴포넌트와 여러 배경에서 alpha 및 대비를 추가 검증한다.