토큰 쓰는 자리 — 면 · 선 · 글자 · 강조 · 상태색

이 문서는 CoUI 로 그리는 모든 서비스 화면에서 어느 CoUI 색 토큰을 어느 자리에 쓰는지를 정합니다. 아래는 CoUI 기본 매핑 예시이며, 제품은 브랜드 테마에서 모드별 값과 역할 매핑을 조정할 수 있습니다. 전체 테마와 특정 컴포넌트 스타일의 절차는 brand-theme-workflow.md를 따릅니다. 간격 · 모서리 · 그림자 · 글자 크기는 layout.md, 알림 · 상태 화면은 patterns.md, 피그마에서 Dark 로 바꿔 확인하는 절차는 figma-file.md 가 맡습니다. 토큰의 정의와 값의 정본은 cc-designer:design-system 이고, 앱 테마를 잇는 코드는 cc-coui:coui-theme 입니다.

• 표기 — 피그마 변수 이름을 먼저, 괄호 안에 Dart 이름을 적습니다. 예: color/surface-container (CoreColors.surfaceContainer). 피그마 변수는 Semantic/ Color · CoUI 컬렉션(또는 서비스가 고른 브랜드 컬렉션 — 이름은 같습니다)에 있고, 모드는 Light · Dark · HCLight · HCDark 입니다.
• 브랜드는 모든 속성을 설계합니다 — 색·타이포·치수·곡률·선·효과·재질·모션·컴포넌트 내부 스타일을 테마와 override로 제어합니다. 아래 자리도 제품의 의미 역할에 맞게 재정의할 수 있습니다.
• hex 를 쓰지 않습니다 — 이 문서에도, 화면에도. 「현재값 참고」로 적은 것은 원시 단계 이름이나 대비 비율뿐이고, 판단은 그 값이 아니라 역할 이름으로 합니다.
• 한 단계 — 면의 층 사이에 눈에 보이는 밝기 차이 하나를 말합니다. 원시 사다리의 칸 수가 아닙니다. 패널 안 행은 Light 에서 패널보다 어둡게, Dark 에서 패널보다 밝게 보이도록 고른 짝입니다(사다리 칸 수는 2절).
• CoUI 에 없는 것 — 「CoUI 에 없음 → 지금 가능한 대체 → CoUI 후보」 세 칸으로 적습니다. 대체는 늘 CoUI 에 있는 토큰이고, 새 색을 만들지 않습니다(8절).
• 라이트가 기본입니다. 모든 자리는 변수 모드를 Dark 로 바꿔도 그대로 성립해야 합니다. 다크에서 채도나 밝기를 손으로 고치지 않습니다.

「Light 에서 · Dark 에서」 칸은 값이 아니라 지금 CoUI 브랜드에서 보이는 관계입니다. 브랜드 컬렉션을 바꾸면 색은 달라져도 관계는 같아야 합니다.

면은 화면이 칠하지 않습니다. 페이지 · 크롬 · 카드 · 떠 있는 판의 면은 CoUI 부품의 기본값이 정하고, 피그마 라이브러리 인스턴스도 같은 값을 그립니다 — CoUI 색상 가이드 「surface 계층」(카드 · 팝오버의 표면은 각 컴포넌트 기본값이 정한다). 이 절이 면 규칙의 정본이고, 다른 스킬 · 규칙은 이 절을 인용합니다. 구분은 선이 아니라 면의 밝기로 합니다 — 카드는 페이지 위에서 자기 면의 톤으로 드러나고, 선으로 두르는 것은 그 톤이 바탕과 같아지는 자리뿐입니다.

• 제품이 다른 면을 고르면 앱 테마 한 곳에서. 제품 시안의 화면 프레임 채움이 color/surface 가 아닌 변수(예: color/surface-dim)에 묶여 있거나 제품의 디자인 결정 기록이 다른 층을 정했으면, 코드는 앱 테마(CoreScaffoldTheme · CoreCardTheme 류) 한 곳에서 바꾸고 화면 · 위젯은 면을 칠하지 않습니다. 그 결정은 디자이너의 것이고 결정 기록에 남습니다.
• 카드 안에서 면이 달라지는 것은 부품의 상태뿐입니다 — 표의 선택 · 호버 행, 메뉴 항목의 선택처럼 그 상태를 그리는 부품(Table · MenuItem · NavigationBarItem)에 맡깁니다. 선택 · 호버 면을 그리지 않는 부품(Listing 의 행)만 그 행에 표의 선택 행과 같은 color/surface-container-high 를 깝니다(layout.md 2-3). 평상시 목록 행은 카드 면 그대로 두고 여백으로 나눕니다. 카드 안에 또 경계 있는 면(카드 안 카드)을 두지 않습니다(cc-blueprint/rules/figma-slop-tells.md §S1).
• 선으로 두르는 카드(outlined)는 카드 면의 톤이 바탕과 같아지는 자리뿐입니다 — 제품이 바탕을 회색으로 고른 화면(Light 에서 color/surface-dim 과 카드 면은 같은 값입니다, 10절), 회색 면 위에 놓이는 묶음. 이미지가 카드 폭을 채우는 카드도 filled 입니다 — 이미지가 위쪽 경계이고 본문은 카드 면의 톤이 묶습니다. 그 밖의 카드에 선을 더하지 않습니다(3절).
• 표의 토큰 이름은 지금 CoUI 판의 기본값을 적은 참고입니다. CoUI 가 기본값을 바꾸면 부품이 따라가고, 화면은 바뀔 것이 없습니다 — 화면이 고르는 것은 토큰이 아니라 부품이기 때문입니다.

아래는 부품이 자기 몫으로 쓰는 토큰입니다. 화면 쪽 면으로 직접 깔지 않습니다.

화면은 위 표의 부품 면을 다시 칠하지 않습니다.

면 대비로 충분하면 선을 긋지 않습니다. 선이 남는 자리는 셋입니다.

• 패널 · Card · Stat 같은 정적 컨테이너에는 선을 두지 않습니다 — 기본값(filled)이 이미 면의 톤으로 드러납니다. 선으로 두르는 카드(outlined)는 2절의 자리뿐입니다. 선과 면 대비를 한 자리에 겹쳐 쓰지 않습니다(사이드바는 부품 기본값을 그대로 두는 예외, 2-2).
• 패널 안 묶음 사이는 간격(space/*)으로 나눕니다. Divider 는 간격으로 안 될 때만 기본값으로 둡니다.
• color/outline-variant 는 장식 선 대비(현재값 참고 Light 흰 면 위 약 1.5:1)라서 컨트롤의 경계로 쓰지 않습니다.
• color/outline-subtle 은 부품 안쪽(키캡) 몫입니다. 화면 쪽 선으로 쓰지 않습니다.
• 포커스 링은 color/focus-ring 이고 부품이 그립니다.
• 상태색 테두리(success-outline 같은 이름)는 CoUI 에 없음 입니다(7절).

• 한 화면에 글자 색은 이 셋을 넘기지 않습니다.
• 메타 단계의 대비 — Light 에서 color/on-surface-subtle 은 흰 면(color/surface) 위 4.5:1 을 넘지만, 카드 기본 면(color/surface-container) 위에서는 약 4.3:1 입니다(현재값 참고). CoUI 가 「세 번째 단계는 두 번째보다 흐리다」는 위계를 지키려고 기록한 예외이고, 부품 기본값(카드 부제 · Stat 설명 · 표 머리 행)도 그 자리에 씁니다. 화면은 그 결정을 따르되, 읽지 않으면 일이 막히는 정보(금액 · 마감 · 오류 사유)는 메타 단계에 두지 않고 본문 · 보조 단계로 올립니다.
• 코드에서 메타 글자 — Text 체인에 .onSurfaceSubtle getter 가 없어 두 플랫폼이 다르게 씁니다. Flutter Text('12분 전').bodySmall.color(const CoreColor.token(CoreColors.onSurfaceSubtle)), Web Text('12분 전', style: const TextStyle(color: 'on-surface-subtle')).bodySmall. 강조 글자(color/primary-text)도 같은 꼴입니다. .onSurfaceVariant 로 대신하지 않습니다 — CoUI 이슈 — Text 체인으로 세 번째 글자 단계를 고를 수 없다.
• 화면이 글자로 고르지 않는 토큰: color/placeholder 는 입력 칸의 미입력 안내 전용이라 부품이 씁니다(Light 회색 면 위에서는 대비 4.5:1 에 모자랍니다). color/disabled-content 는 꺼진 상태를 그리는 부품의 몫입니다 — 꺼진 라벨 · 체크 표시는 부품이 그리므로 화면에서 손대지 않습니다. color/outline 은 선 토큰입니다.
• 면과 글자는 짝으로 씁니다. color/surface · color/surface-dim · color/surface-container 위는 color/on-surface · color/on-surface-variant, color/primary 위는 color/on-primary, color/primary-container 위는 color/on-primary-container, color/success-container 위는 color/on-success-container, color/inverse-surface 위는 color/inverse-on-surface 입니다. 짝이 아닌 조합은 한 모드에서만 읽힙니다.

강조색은 선택 상태 · 링크 · 진행 · 정보 표시에만 씁니다. 넓은 면에 칠하지 않습니다.

• 상단 바 · 사이드바 · 패널 바탕 · 표 머리를 강조색으로 칠하지 않습니다.
• 「옅은 강조 면」을 primarySubtle, 「진한 강조」를 primaryStrong 이라는 이름으로 찾는 경우가 있습니다. 둘 다 CoUI 에 없음 입니다(ThemeExtension 도 없습니다). 옅은 면은 color/primary-container 로 대체하고, 이름만 다른 같은 역할이라 CoUI 후보는 두지 않습니다. 진한 강조는 필요하지 않습니다 — 가장 높은 대비는 주 행동 버튼(color/primary 채움)이 이미 가집니다. 더 진한 단계가 필요해 보이면 그 화면이 강조색을 너무 많은 자리에 쓰고 있다는 신호입니다.
• 화면에서 고르지 않는 강조 토큰: color/primary-hover · color/primary-pressed(상태 전용, 부품 몫), color/primary-fixed 계열, color/tertiary · color/accent(CoUI 에서는 color/primary 를 그대로 따라갑니다 — 두 번째 강조색으로 쓰지 않습니다), color/inverse-primary.
• 강조색이 무슨 색인지는 CoUI 가 정합니다. 「파란 버튼」처럼 값에 기대는 판단을 적지 않습니다. CoUI 브랜드의 Dark 는 주 행동 · 선택 · 진행 · 포커스(color/primary 계열 · color/focus-ring)를 밝은 중립으로 그리고, 강조 글자(color/primary-text) · 링크만 강조색으로 남깁니다 — 피그마 라이브러리와 코드가 같은 값입니다. 강조색도 두 모드의 스크린샷으로 판단합니다(figma-file.md 7절).

버튼의 채움 · 글자 · 테두리 색은 CoUI Button 변형이 정합니다. 화면은 변형만 고릅니다.

• secondary 는 옅은 면입니다(coui_core 0.160 부터). 예전 secondary 는 진한 무채 채움이라 primary 와 밝기가 거의 같아(채움끼리 약 1.02:1) 보조 행동에 쓰지 않았습니다. 지금은 color/secondary-container 를 채우고, 올리거나 눌러도 채움은 그대로 두고 글자색 상태층만 얹습니다. 「취소」 「수정하기」 같은 보조 행동에 쓰되 놓이는 면으로 고릅니다 — 흰 면이면 secondary, 회색 카드면 outline.
• 한 줄에 보조 행동이 여럿이고 그중 하나가 「이 카드에서 가장 먼저 누를 행동」이면 피그마 라이브러리의 Button tonal(옅은 강조 면)이 그 자리입니다. 다만 tonal 은 코드에 아직 없습니다 — 코드에 들어오기 전까지는 다른 보조 행동과 같은 변형으로 두고 구현 gap 으로 기록합니다.
• 중립 고대비 주 버튼 — 브랜드 색 없이 무채 고대비 주 버튼이 필요한 서비스가 있습니다. 반전(inverse) 변형은 CoUI 에 없음 입니다. 예전에는 진한 secondary 를 주 행동으로 빌려 썼지만 secondary 가 옅은 면이 되어 그 대체는 사라졌습니다. 지금은 브랜드 테마에서 color/primary 를 무채로 두는 것이 가장 가까운 방법입니다. CoUI 후보: Button inverse 변형(color/inverse-surface 채움). 이 선택은 서비스 전체에서 하나로 정하고 DDR 에 남깁니다.
• 반투명 버튼 변형은 CoUI 에 없음 입니다. 알림 안에서는 ghost 로 대체하고, ghost 가 같은 역할을 하므로 CoUI 후보는 두지 않습니다.

CoUI 에 네 상태가 모두 있고, 상태마다 네 칸입니다.

• 진한 채움 위 글자 짝(color/on-success 등)은 부품(진한 Banner 등)이 씁니다. color/error-strong · color/error-pressed 는 파괴 버튼의 상태 전용입니다.

상태색을 쓰는 자리

• 면적 대부분을 상태색으로 칠하지 않습니다. 행 · 패널 · 표 전체를 -container 로 깔지 않고, 한 행에서 상태색 자리는 하나(점 또는 칩)입니다.
• 분류는 상태가 아닙니다. 진료과 · 과목 · 상품 카테고리 · 역할처럼 뜻 없이 구분만 하는 색은 분류색 color/category-<색> 계열(CoreColors.categoryBlue · categoryBlueContainer · onCategoryBlueContainer · categoryBlueOutline 꼴, 9색)에서 고릅니다. 코드와 피그마 라이브러리(Semantic/ Color · <브랜드>)에 같은 이름으로 있습니다. 상태색을 빌려 쓰지 않습니다.
• CoUI 에 없음: 상태색 테두리(success-outline 같은 이름 — 테두리 칸은 분류색에만 있습니다), 진한 상태 단계(success-strong 같은 이름 — color/error-strong 하나뿐입니다), 알림 표면의 사선 그라디언트 세기. 대체는 -container + on-…-container 짝입니다. 알림 표면 후보는 patterns.md 1절에 있습니다.

1. 이 문서의 표에서 가장 가까운 CoUI 토큰으로 대체합니다.
2. 대체로 부족한 이유를 DDR 에 적습니다(cc-designer:design-decision).
3. 여러 서비스에 필요하면 DDR 로 확정한 뒤 CoUI 토큰 후보로 제안합니다(cc-blueprint/rules/coui-library-consumption.md §2. 올리는 절차와 draft 모드는 같은 문서 §6).

하지 않는 것

• hex 를 화면에 직접 넣지 않습니다(L0 리터럴 색). 예외는 cc-blueprint 표준 표지 Cover 의 고정값 하나입니다.
• 서비스 확장 토큰은 실제 로컬 변수·컬렉션으로 정의합니다. alias·mode·코드 대응을 기록하고 재바인딩을 확인합니다.
• 불투명도와 합성색도 제어할 수 있습니다. 배경과 모드별 최종 대비, exporter의 composed color 지원을 확인합니다.
• 코드 확장은 실제 CoUI theme/style 통로부터 확인합니다. 없는 속성은 제품 adapter 또는 API 확장으로 구현하고 렌더까지 연결합니다.

CoUI 브랜드의 지금 값에서는 이름이 다른데 값이 같은 슬롯이 많습니다. 자리는 늘 이름으로 고르고, 지금 같아 보인다고 바꿔 쓰지 않습니다. 값은 브랜드와 CoUI 판마다 달라집니다.

• Light: color/surface · color/surface-bright · color/surface-container-lowest 가 같은 흰색이고, color/surface-dim · color/surface-container 가 같은 회색입니다.
• Dark: color/surface-dim · color/surface-container-lowest 가 같고, color/surface-bright · color/surface-container 가 같습니다.
• color/placeholder 와 color/outline 이 두 모드에서 같은 값입니다. 하나는 글자, 하나는 선입니다.
• Light 의 color/primary 와 color/secondary 가 같은 밝기입니다. Button secondary 는 이 슬롯이 아니라 color/secondary-container 를 채우므로 버튼끼리는 구분됩니다(6절). 대신 color/secondary-container 는 Light 에서 color/surface-container 와 같은 값입니다.
• Dark 그림자는 코드가 세기를 키워 그리고(색은 두 모드 모두 검정) 피그마는 라이트 세기로 그립니다. CoUI 몫이므로 화면 쪽에서 손대지 않습니다(layout.md 8절).

• cc-flutter:card-surface-tokens — 코드 쪽에서 카드 · 컨테이너를 고르는 법(Card 기본 · outlined · OutlinedContainer), 테두리가 자식을 잠식하는 문제, 테마 토큰 값 자체를 바꾸지 않는 규칙, 검출 명령. 면의 층은 그 스킬이 이 문서 2절을 인용합니다.
• cc-blueprint/rules/figma-composition-patterns.md §C9 — ①(정적 컨테이너의 선)과 ③(화면 바탕과 구분 신호)은 이 문서 2절을 인용합니다 — 정적 컨테이너는 부품 기본값(filled, 선 없음), 화면 바탕은 Scaffold 기본값입니다. ②(컨트롤 경계는 기본값)는 그대로 맞물립니다. ④(정적 컨테이너 반경은 Card 값 하나)는 Card · Stat · 패널 컨테이너에서 맞물리고, 카드 안 Table 은 부품 기본 반경 그대로입니다(layout.md 7절). §C4 콘솔 셸의 상단 바 아래 선과 사이드바의 면 · 선도 부품 기본값 그대로입니다(2-2). ⑤ 는 cc-blueprint 브리프(cc-blueprint/rules/figma-brand-selection.md §1)의 '카드 깊이' 칸을 늘 평면 으로 적어 맞물리게 합니다(이유: 떠 있는 것만 그림자, mood.md 2-7). 그 칸을 카드까지 로 두면 ⑤ 가 카드 · 표에 shadow/* 를 얹으라고 해서 이 문서와 부딪힙니다.
• cc-blueprint/rules/figma-slop-tells.md §S1 · §S4 — 카드 안에서 면이 달라지는 것을 부품의 상태(선택 · 호버)로 좁혀 §S1 과 함께 섭니다. §S4 강조색 과다는 5절과 같은 방향입니다.
• cc-designer:critique-color — 대비 · 팔레트 검사. 이 문서의 자리를 기준으로 봅니다.
• cc-designer:design-system — 토큰의 정의와 값. 이 문서는 목록을 다시 적지 않습니다. 앱 테마를 잇는 코드는 cc-coui:coui-theme.