토큰 체계
oe는 ooee가 확정한 semantic decision의 이름이다. 실제 색상 값과 Light/Dark 매핑은 foundations/color.md, 실행 가능한 생성 규칙의 원본은 packages/tokens/src/index.ts다.
패키지 구성
packages/tokens의 styles.css가 :root·.dark에 실제 --oe-* 값과 @custom-variant dark를 함께 소유한다. 소비자는 @import "@ooee/tokens/styles.css" 한 줄로 Brand를 뺀 색을 받는다. 값의 단일 원본은 packages/tokens/src/index.ts의 CORE_SEMANTIC_TOKENS이며 packages/tokens/src/index.test.ts가 CSS와의 불일치를 검사한다.
Brand만 예외다. --brand-*·--brand-alpha-*와 mode별 --oe-brand-light-*·--oe-brand-dark-*는 packages/tokens의 brandVariables(seed)가 seed에서 만들고 쓰는 쪽이 런타임에 주입한다. Studio는 BrandThemeProvider, sandbox는 BrandVariables가 그 일을 한다. --oe-brand-*와 --oe-focus-ring은 두 앱의 globals.css가 그 mode별 주입값에 --color-blue-* 기본값을 붙여 정의한다. packages/tokens는 DEFAULT_BRAND_SEED와 생성 함수, @theme inline이 --oe-brand-*·--oe-focus-ring을 Tailwind 색으로 잇는 별칭만 갖고 :root·.dark의 Brand 실제 값은 갖지 않는다. 쓰는 쪽이 할 일은 아래 「앱에 들이는 법」이 갖는다.
Studio는 만든 Brand palette와 semantic CSS 변수를 ooee-brand-theme-css에 캐시하고, Root Layout의 선행 script가 첫 paint 전에 복원해 저장된 Brand 색과 기본값 사이의 전환을 막는다. 이 선행 style 주입이 내는 hydration 경고는 <html suppressHydrationWarning>으로 억제한다.
앱에 들이는 법
@import 둘만으로는 Brand 색이 서지 않는다. 아래 두 줄을 함께 해야 @ooee/ui의 Brand button·badge·focus ring에 색이 생긴다. 빠뜨리면 TypeScript도 lint도 빌드도 통과하고 화면에서만 그 자리가 색 없이 그려지므로, 새 앱을 세울 때 먼저 확인한다.
전역 CSS를 이 순서로 import한다.
@ooee/tokens/styles.css의@theme inline이 Tailwind의--color-*를 참조하므로tailwindcss가 먼저 와야 한다.@import "@ooee/fonts/styles.css"; @import "tailwindcss"; @import "@ooee/tokens/styles.css"; @import "@ooee/ui/styles.css";Brand 변수를 런타임에 주입한다.
@ooee/tokens의brandVariables(seed)가 seed 하나에서--brand-*·--brand-alpha-*·--brand-source와 mode별--oe-brand-light-*·--oe-brand-dark-*전부를 만든다. 앱은 그 결과를document.documentElement에 얹는다. seed를 바꿀 일이 없으면 인수를 비워DEFAULT_BRAND_SEED를 쓴다.useEffect(() => { const root = document.documentElement; Object.entries(brandVariables()).forEach(([property, value]) => root.style.setProperty(property, value)); }, []);mode별 주입값을
--oe-brand-*로 잇는다.packages/tokens의styles.css는--oe-brand-*와--oe-focus-ring에 값을 갖지 않고 Tailwind 색 별칭만 갖는다. 아래 여덟을 앱의:root·.dark가 정의한다. 대체값은 첫 paint와 주입 실패 때 쓰이며--color-blue-*로 둔다.--oe-brand-foreground-primary --oe-brand-foreground-secondary --oe-brand-background-primary --oe-brand-background-secondary --oe-brand-background-bold-primary --oe-brand-border-primary --oe-brand-border-secondary --oe-focus-ring실제 블록은
apps/studio/src/app/globals.css와apps/sandbox/src/app/globals.css에 있다. 두 파일이 같은 블록을 갖는 까닭과 이 기본값의 자리를 공용 package로 옮길지는 아직 정해지지 않았다.
Side Navigation의 아홉 색은 이 목록에 들어가지 않는다. --oe-side-navigation-*도 값 없이 이름만 packages/ui의 styles.css에 있지만, 그것은 SideNavigationProvider가 palette prop으로 받은 값을 얹는 구조이고, 주지 않은 칸은 컴포넌트의 DEFAULT_PALETTE가 oe 토큰으로 채우므로 앱이 아무것도 넣지 않아도 레일이 그려진다. 까닭은 components/side-navigation.md의 「색을 값으로 받는다」가 갖는다. --oe-message-*도 같은 꼴이지만 대체값을 갖고 있어 주입하지 않아도 그려진다.
packages/tokens/src/index.test.ts의 「styles.css 가 값을 갖지 않고 앱에 넘기는 이름은 brand 여덟뿐이다」가 위 목록을 CSS와 맞춘다. 값 없이 이름만 잇는 --oe-*가 새로 생기면 그 시험이 먼저 잡는다 — 그러지 않으면 쓰는 쪽이 「색이 없는 요소」로 발견한다.
기본 원칙
Primitive color는 별도의 oe scale로 복제하지 않고 Tailwind 기본 팔레트를 사용한다.
neutral-*
red-*
amber-*
green-*
blue-*
pink-*
sky-*
orange-*
cyan-*
violet-*
purple-*
teal-*
emerald-*
fuchsia-*
indigo-*
Tailwind에 없는 브랜드 팔레트가 필요하면 brand-* scale을 추가할 수 있다.
- Primitive는 semantic token을 정의할 때만 사용한다. 정식 컴포넌트에서
text-red-700,bg-neutral-50같은 primitive class를 직접 사용하지 않는다. oeprefix는 semantic token에만 사용한다. Tailwind 및 생성된 색상 palette는 primitive이며oeprefix를 붙이지 않는다.- Neutral role은 이름에서 생략한다. 일반 surface는 Neutral이며 Brand와 status는 명시된 role에서만 사용한다.
primary,secondary는 색상 이름이 아니라 같은 property/role 안의 강조 위계다.tertiary는 실제 용례가 확인된 Neutral foreground에만 사용하며 다른 property/role로 자동 확장하지 않는다. 그보다 약한 단계가 필요하면 위계 번호를 늘리지 않고subtle처럼 뜻을 담은 이름을 쓴다.
Neutral semantic token
oe-foreground-primary
oe-foreground-secondary
oe-foreground-tertiary
oe-foreground-subtle
oe-foreground-placeholder
oe-foreground-disabled
oe-foreground-inverse
oe-foreground-inverse-secondary
oe-background-canvas-primary
oe-background-canvas-secondary
oe-background-primary
oe-background-secondary
oe-background-alternate
oe-background-bold-primary
oe-background-control-off
oe-background-control-disabled
oe-background-disabled
oe-background-disabled-selected
oe-border-primary
oe-border-bold-primary
oe-border-secondary
oe-border-tertiary
oe-border-disabled
oe-border-visual
oe-border-overlay-subtle
oe-focus-ring
oe-interaction-hover-subtle
oe-interaction-hover
의미는 다음과 같다.
foreground: 텍스트, 아이콘과 전경 SVGbackground: canvas와 surfaceborder: outline과 divider의 색상primary: 해당 property 안에서 높은 기본 위계secondary: 해당 property 안에서 한 단계 낮은 위계tertiary:secondary보다 한 단계 더 낮은 위계. 중립 위계는 여기서 끝나며 그 아래 칸을 번호로 잇지 않는다alternate: 줄이 번갈아 오는 것을 알리는 면. 위계가 아니라 구실 이름이다bold: background와 border에서 가장 진한 solid 단계. 강한 solid fill과 작은 면의 선택은background-bold-primary로, 큰 면의 선택은border-bold-primary선으로 알린다disabled: 사용할 수 없는 상태inverse: 진한 표면 위의 범용 반전 foregroundvisual: 이미지와 색상 값처럼 콘텐츠 자체 위에 얹는 내부 경계. border에만 쓰며 테마 surface 색으로 바꾸지 않는다overlay: 바탕 색을 투과하며 합성되는 값. 아래 「Opaque와 Overlay」가 이름 규칙을 갖는다
Canvas와 컴포넌트 surface는 독립적으로 테마를 바꿀 수 있도록 분리한다. Light Neutral background는 primary에서 secondary 순으로 어두워지며, Dark에서는 이름보다 동일한 UI 역할과 계층을 유지한다. 두 경계선은 선이 무엇을 하는지로 갈린다. border-primary는 선 자체가 컨트롤의 모양을 만드는 자리에 쓴다. Checkbox의 네모와 Radio의 원이 그것이며, 16px 안에서 그 선이 사라지면 고를 것이 있다는 사실 자체가 보이지 않는다. border-secondary는 이미 면으로 서 있는 것의 테두리와 면을 가르는 divider에 쓴다. Input과 Textarea의 상자, Select·Combobox·Select Box의 트리거, 떠 있는 Popup, 그 사이의 divider가 여기에 해당한다.
2026-09-15에 뒤쪽을 한 단계 옅은 border-secondary로 옮겼다. 폼 요소의 테두리가 한 단계 진해 보인다는 판단이었고, 그때 Checkbox와 Radio는 border-primary에 남겼다. 상자는 안쪽의 글자와 바탕이 이미 그것이 입력란임을 말하지만, 선택 컨트롤은 선 말고 말해 줄 것이 없기 때문이다.
foreground-tertiary는 leading icon, timestamp와 더 약한 메타 정보의 실제 용례가 확인되어 사용한다.
중립 foreground의 위계는 tertiary에서 끝난다. subtle은 그 줄을 잇는 네 번째 칸이 아니라, tertiary보다 약한 단계가 국소적으로 필요한 자리에만 쓰는 이름이다. 번호를 이어 붙이면 다른 property와 role에도 같은 칸을 만들려는 압력이 생기므로 위계 이름을 늘리지 않는다. 현재 매핑은 Light neutral-400, Dark neutral-600이며 BottomNavigation이 선택되지 않은 항목의 아이콘을 라벨보다 낮출 때 쓴다.
oe-background-alternate는 위계가 아니라 구실 이름이다. primary보다 아래라는 뜻이 아니라 「번갈아 오는 면」을 뜻하며, background-control-off와 background-disabled-selected처럼 구실로 지은 이름과 같은 결이다. 값은 Light neutral-50, Dark neutral-850으로 두 테마에서 background-primary와 background-secondary 사이에 선다. 표의 짝수 줄이 쓰며, 그 자리에 background-secondary를 다시 쓰면 머리줄·TableFooter·골라 둔 줄이 이미 쓰는 값과 같아져 짝수 줄이 모두 골라 둔 줄로 읽힌다. Dark의 neutral-850은 Tailwind 팔레트에 없는 사이 단계이며 styles.css가 color-mix로 만들어 oe-border-tertiary와 함께 쓴다. 줄무늬를 어느 표에 켜는지는 components/table.md의 Guidelines가 정한다.
oe-border-overlay-subtle은 바탕 위에 아주 옅게 긋는 선이다. 값은 Light black 8%, Dark white 12%로 Neutral 가운데 유일하게 Dark에서 흰색을 얹는 경계다. 고정 단계가 아니라 alpha인 것이 이 토큰의 뜻이다 — 이 선이 서는 바탕이 하나가 아니라서, 고정 중립으로 그리면 같은 선이 Dark background-canvas-primary 위에서 바탕과 채널 차 54로 무겁고 Dark background-secondary 위에서는 26으로 옅어 두 배 넘게 흔들린다. alpha는 어느 바탕에서나 그 차를 Light 20, Dark 2629로 묶는다. 값은 19)의 1.5배다. 1px 점선은 면보다 좁아 같은 알파로는 선으로 읽히지 않으므로 겹보다 한 단계 진하게 두었다. 첫 용례는 Chart의 격자·기준선이며(components/chart.md), 경계가 무엇을 두르는 자리는 그대로 oe-interaction-hover가 내는 겹의 차(Light 13, Dark 17border-primary·secondary·tertiary가 갖는다. 포인터가 가리키는 자리를 말하는 Chart의 커서도 격자보다 진해야 하므로 border-primary에 남는다.
subtle은 oe-foreground-disabled와 값이 같지만 합치지 않는다. disabled는 꺼져서 조작할 수 없는 요소를 뜻하고 subtle은 켜져 있으나 위계가 낮은 요소를 뜻한다. 값이 같아도 역할이 다르면 하나로 묶지 않는다.
Placeholder는 실제 입력값과 명확히 구분하기 위해 전용 oe-foreground-placeholder를 사용한다. 현재 매핑은 Light neutral-400, Dark neutral-500이며 실제 입력값은 oe-foreground-primary를 유지한다.
Semantic status token
danger
warning
success
info
up
down
각 상태는 foreground, background, border와 primary/secondary 위계를 조합한다.
oe-danger-foreground-primary
oe-danger-foreground-secondary
oe-danger-background-primary
oe-danger-background-secondary
oe-danger-background-bold-primary
oe-danger-border-primary
oe-danger-border-secondary
up·down은 상태가 아니라 값의 방향이다. 같은 문법을 공유하므로 이 절에 함께 적지만, danger·warning·success·info와 달리 좋고 나쁨을 뜻하지 않는다. 오르내림이 좋은 일인지 나쁜 일인지는 화면이 정한다 — 비용이 오르는 것은 나쁜 일이고 이탈이 줄어드는 것은 좋은 일이다. 그래서 이름이 positive·negative가 아니다. 상태 색을 증감에 빌려 쓰지 않는다. 매출이 는 것은 success가 아니고 준 것은 danger가 아니다. 값은 국내 관례를 따라 상승이 붉은 계열, 하락이 파란 계열이며 서양과 뒤집혀 있다. Light up-foreground-secondary가 pink-600, down-foreground-secondary가 sky-600이다. danger가 이미 red를, info가 blue를 쓰므로 그 둘과 눈으로 갈리는 팔레트를 재어 골랐고, 그 근거는 foundations/color.md가 갖는다.
warning, success, info도 같은 문법을 따른다. Semantic status에서 primary는 같은 role/property 안에서 더 높은 강조와 대비, secondary는 한 단계 낮은 강조와 대비를 뜻하며 특정 Tailwind 숫자를 뜻하지 않는다. Light theme에서 danger-foreground-primary가 red-800, Dark theme에서 red-200에 연결된다. 이름은 역할을 나타내고 primitive 값은 테마별 구현이다.
범주 색 token
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
범주 색은 뜻이 없는 유일한 family다. 다른 모든 token은 「이 색은 무엇을 뜻한다」를 지고 있지만(danger는 위험, up은 상승, brand는 자사), 범주 색은 서로 다르다는 것만 말한다. 그래서 위 목록처럼 이름에 색도 뜻도 담지 않고 차례만 담는다. oe-categorical-1이 「첫째 범주」이지 「주 범주」가 아니다.
위계와 property를 갖지 않는다. status 문법(oe-{role}-{property}-{hierarchy})을 따르지 않는 첫 family이며, 색 하나가 token 하나다. 글자로 쓸 때는 text-oe-categorical-1, 면으로 쓸 때는 bg-oe-categorical-1을 같은 값으로 쓴다 — 지도 핀은 글자색이고 범례의 점은 면이지만 같은 색이어야 범례와 핀이 이어진다.
차례가 곧 쓰는 순서다. 1부터 차례로 집어 쓰고 중간을 건너뛰거나 섞지 않는다. 앞쪽일수록 서로 멀게 재어 두었으므로(계열이 둘셋뿐인 그래프가 가장 흔하다) 차례를 섞으면 그 배치가 깨진다.
아홉에서 멈춘다. 열을 같은 조건으로 찾으면 가장 가까운 쌍이 변별 문턱에 닿아 8px 점에서 갈리지 않는다. 아홉 넘게 필요하면 색이 아니라 다른 축(모양·무늬·라벨)을 쓰거나 그래프를 나눈다. 값과 그 근거는 foundations/color.md가 갖고, 쌍마다의 거리를 재는 단정은 packages/tokens/src/index.test.ts에 있다. 쓰는 자리는 components/chart.md의 「계열 색 정하기」다.
Opaque와 Overlay
불투명 색상을 기본값으로 보고 이름에서 별도 modifier를 생략한다. 다른 surface의 색을 투과하며 합성해야 하는 경우에만 overlay를 명시한다.
Neutral opaque
oe-{property}-{hierarchy}
Neutral overlay
oe-{property}-overlay-{hierarchy}
Semantic opaque
oe-{role}-{property}-{hierarchy}
Semantic overlay
oe-{role}-{property}-overlay-{hierarchy}
alpha는 구현 방식이고 overlay는 사용 목적이므로 이름에는 overlay를 사용한다. 모든 토큰에 overlay variant를 미리 만들지 않고 실제로 surface 합성이 필요한 사용 사례가 확인될 때만 추가한다.
이미지나 영상 위 UI처럼 일반 surface와 본질적으로 다른 맥락이 반복되면 media context token을 별도로 검토한다.
oe-media-foreground-primary
oe-media-background-primary
oe-media-border-secondary
이미지 위의 alpha border는 이미지 내용에 따라 대비가 달라질 수 있으므로 scrim, shadow 또는 이중 대비가 함께 필요할 수 있다.
Brand primitive
- 입력한 HEX는
brand-source로 보존한다. @material/material-color-utilities의 HCT tonal palette를 사용한다.- HCT tone을
brand-50~950에 연결한다. - Alpha primitive는 seed RGB 기준으로 다음 값만 생성한다:
05, 08, 10, 16, 20, 30, 40, 50, 60, 70, 80, 90. - Alpha primitive를 컴포넌트에 남발하지 않는다.
- Primitive는 모드에 독립적이고 semantic mapping은 Light/Dark에서 달라질 수 있다.
- HCT의 Material semantic roles를 oe semantic roles로 자동 채택하지 않는다.
- Sidebar와 Chart token은 특수 목적의 shadcn token으로 유지하고 oe 공용 semantic에 흡수하지 않는다. 둘은 Studio 화면 안에만 남은 token이며
@ooee/ui의 Chart는 쓰지 않는다 — 계열 색은 components/chart.md의 「계열 색 정하기」가 정한다.
사용 규칙
- 어두운 solid brand/status 배경 위에는 공통
oe-foreground-inverse를 먼저 검토한다. 밝은 배경에는 대비가 확보되는 Neutral foreground를 사용한다. 반복되는 실제 예외가 생기기 전에는on-*token을 만들지 않는다. - Bold fill 위의 약한 정보에는
oe-foreground-inverse-secondary를 사용한다.oe-foreground-inverse에 opacity를 중첩해 위계를 만들지 않는다. - semantic token에 이미 alpha나 강조 위계가 포함되어 있으면 컴포넌트에서 임의 opacity를 중첩해 위계를 다시 바꾸지 않는다. 추가 감쇠가 필요하면 기존 token 선택이 맞는지 먼저 확인한다.
- 폼에서 직접 조작하는 Input, Checkbox 같은 control의 식별 보더는
oe-border-primary를 사용한다. 여러 폼 요소나 Label을 하나의 선택·입력 영역으로 감싸는 낮은 위계의 form container는oe-border-secondary를 사용한다. - 이미지와 Color swatch처럼 콘텐츠 자체가 배경색을 갖는 값은 고정 Neutral border를 바깥에 두지 않고 내부 Black alpha layer를 중첩해 경계를 만든다.