색상

Figma Foundation · 01. Color · 값은 coui_core 가 정본입니다. 정본 파일은 Figma 라이브러리.

이 페이지는 역할을 고르고, 지금 테마의 실제 값을 스와치로 확인하는 곳입니다. 값은 coui_core 의 CoreColors 가 정하고, Flutter ColorScheme 과 Web --coui-* 변수가 같은 이름을 읽습니다.

팔레트 hex 를 앱에 복사하지 마세요. 라이트/다크와 서페이스 스타일이 토큰 값은 바꾸고, 이름은 그대로 둡니다. 토큰 축 전체는 디자인 토큰 을 보세요.

언제 쓰나#

시맨틱 토큰을 고르세요

• 배경 · 글자 · 보더 · 상태 색을 줄 때 — primary, onSurface, error 처럼 역할을 고릅니다
• 컴포넌트 Style (backgroundColor: CoreColor.token(CoreColors.surface)) 이나 Text('…').onSurface

쓰지 마세요

• #RRGGBB / Color(0xFF…) 를 위젯에 박기 — 다크 모드와 서페이스 스타일이 비껴갑니다
• "이 버튼은 파랑"처럼 원시 색을 고르기 — 채움은 역할(primary, accent)을 고릅니다

primary 와 accent#

CoUI 기본 테마에서 primary / onPrimary 는 라이트에서 블루그레이입니다 — neutral 보다 채도가 높은 청회색 계열(OKLCH hue 266)이라 자기 색으로 읽히지만, 채움 단계는 콘텐츠와 경쟁하지 않을 만큼 어둡습니다. 라이트는 진한 채움(primary/800)에 흰 글자입니다. 다크는 거의 흰 neutral 채움(neutral/100)에 거의 검은 글자(neutral/1000)입니다 — 파스텔 파랑(primary/200)은 편집기가 선택 영역 · 링크 · 정보에 이미 쓰는 파랑과 섞여 "선택된 것"처럼 읽혔기 때문에, 다크의 주 액션만 neutral 램프에서 고릅니다. 포커스 링 · hover · pressed 도 같은 neutral 단계를 따라가고, 컨테이너 · fixed · inverse · 글자(primaryText) 슬롯은 다크에서도 블루그레이를 유지해 브랜드 색조는 그 면과 글자에 남습니다. CoUI 는 모든 서비스의 기본 UI 라서 primary 가 콘텐츠와 경쟁하지 않게 두고, 브랜드 테마가 primary 슬롯을 자기 색으로 덮어씁니다 — 이 다크 예외는 CoUI 기본 테마만의 것이고 브랜드 매핑은 그대로 "밝은 단계 + 어두운 글자"입니다.

secondary 는 중성 강조입니다 — 일반 모드에서 primary 와 같은 단계를 neutral 램프에서 고른 채움입니다.

CoreColors.accent / CoreColors.onAccent 는 tertiary / onTertiary 와 같은 스킴 슬롯입니다. CoUI 기본 테마에서 tertiary 계열은 primary 와 같은 값이므로 accent 도 primary 와 같은 색입니다(라이트는 블루그레이, 다크는 거의 흰 neutral) — CoUI 에는 두 번째 강조색이 없습니다. 컨테이너·fixed 단계는 그대로 tertiaryContainer 이름을 씁니다.

색이 있는 강조 채움이 필요한 제품은 자기 브랜드(CoreBrand)의 tertiary 로 그 색을 정하고, 채움은 accent 에 묶습니다. Cocode 홈 센드 디스크의 민트는 CoUI 의 값이 아니고, 레포 안 브랜드(Unibook h312)에도 없습니다 — 제품 캔버스 hex 는 여기 정본이 아니므로, 홈은 그 민트를 CoreBrand 팔레트의 tertiaryHSL 에 심습니다.

final cocode = CoreBrand(
  id: 'cocode',
  displayName: 'Cocode',
  palette: PrimitiveColors.generate(
    primaryHSL: (h: 220.0, s: 0.65, l: 0.535),
    secondaryHSL: (h: 260.0, s: 0.60, l: 0.50),
    // 예시 시드 — 흰 아이콘(onAccent)이 accent 채움 위에서 4.5:1 을 넘는
    // 보라다. 홈 센드 디스크에서 실측한 민트로 바꿀 때도 라이트의
    // onAccent × accent 대비가 4.5:1 인지 확인한다 — 밝은 민트는 흰
    // 아이콘과 그 대비에 못 미친다.
    tertiaryHSL: (h: 272.0, s: 0.75, l: 0.46),
    successHSL: (h: 140.0, s: 0.70, l: 0.30),
    infoHSL: (h: 200.0, s: 0.75, l: 0.38),
    warningHSL: (h: 45.0, s: 0.85, l: 0.50),
    errorHSL: (h: 0.0, s: 0.75, l: 0.50),
    neutralHue: 220,
  ),
);

// 히어로 센드 디스크 — 채움 accent, 아이콘 onAccent.
// primary variant 의 기본 hover 채움은 background 를 덮어쓰면 빠진다.
Button(
  variant: CoreButtonVariant.primary,
  shape: CoreButtonShape.circle,
  buttonStyle: const CoreButtonStyle(
    backgroundColor: CoreColor.token(CoreColors.accent),
    foregroundColor: CoreColor.token(CoreColors.onAccent),
  ),
  onPressed: send,
  child: Icon(LucideIcons.arrowUp),
)

primary 는 주 액션 채움에, accent 는 브랜드가 따로 고른 강조 채움(센드 디스크 같은)에 씁니다. CoUI 기본 테마에서는 둘이 같은 색으로 칠해지고, 브랜드 테마가 tertiary 를 따로 고르면 둘이 갈라집니다. 상태 색(success, error)은 악센트가 아닙니다.

onX 는 그 위 글자/아이콘 색입니다. primary 배경에는 onPrimary, surface 위 본문에는 onSurface 를 짝지으세요.

링크 색 — link#

링크는 전용 슬롯 link 로 알아봅니다. primary 도 info 도 아닙니다 — CoUI 에서 primary 는 본문 글자와 거의 같은 톤(라이트 블루그레이, 다크 거의 흰 neutral)이라 링크로 읽히지 않고, info 는 상태색이라 "이동한다"가 아니라 "안내"를 뜻합니다. 슬롯을 따로 두면 브랜드가 링크 색만 바꿀 수 있습니다.

CoUI 에서는 새 프리미티브 없이 info 램프의 단계입니다: 라이트 info/700 · 다크 info/400 · 고대비 라이트 info/800 · 고대비 다크 info/200. 링크는 글자로 읽히므로 surface 8톤 전부에서 4.5:1 을 넘어야 하고, 그래서 상태 채움 단계(info/600)가 아니라 한 단계 어두운 700 입니다 — 600 은 회색 컨테이너 톤 위에서 4.5:1 아래로 떨어집니다. 브랜드가 링크 색을 바꾸려면 surface ~ surfaceContainerHighest 위에서 4.5:1 을 넘겨야 합니다.

링크의 밑줄은 색이 아니라 Link 컴포넌트가 정합니다 — Link.

세 번째 글자 단계 — onSurfaceSubtle#

글자는 세 단계입니다: 본문 onSurface, 보조 onSurfaceVariant, 메타 onSurfaceSubtle. 메타는 줄 번호 · 타임스탬프 · 도움말처럼 읽혀야 하지만 눈에 덜 띄어야 하는 글자입니다.

CoUI 에서는 새 프리미티브 없이 placeholder 와 같은 단계입니다(라이트 neutral/600 · 다크 neutral/500 · 고대비 라이트 neutral/700 · 고대비 다크 neutral/400) — neutral 램프에서 onSurfaceVariant 바로 아래 단계가 그것뿐입니다. 그래서 대비 약속도 placeholder 와 같습니다: 페이지(surface · surfaceContainerLowest) 위에서 4.5:1 을 넘고(라이트 4.65 · 다크 5.96), 회색 컨테이너 톤 위는 약속하지 않습니다(라이트 surfaceContainer 위 4.26).

placeholder 로 대신하지 마세요 — 값이 같아도 그건 "아직 값이 없다"는 뜻이라, 브랜드가 둘을 따로 바꿀 수 있어야 합니다. disabledContent 도 아닙니다 — 비활성은 대비 의무가 없어서, 메타 글자를 거기에 두면 4.5:1 을 놓쳐도 아무도 모릅니다. 회색 컨테이너 위나 hover · pressed 상태층이 덮이는 행 안의 보조 글자는 onSurfaceVariant 를 쓰세요.

솟은 면 — surfaceRaised#

surfaceRaised 는 트랙 위로 솟은 선택 면입니다 — 분할 컨트롤에서 선택된 칸, 알약 탭에서 선택된 탭. 라이트는 흰색, 다크는 컨테이너 사다리의 맨 위(neutral/800)입니다. 다크에서는 surfaceContainerHighest 와 같은 값이어도 뜻이 다릅니다 — 가장 높은 컨테이너 톤이 아니라 "아래 트랙에서 떠오른 면"이라서, 두 모드 모두 트랙(surfaceContainer)보다 밝습니다. 대비 게이트의 surface 톤 목록에 들어 있어, 본문 · 보조 글자와 링크가 그 위에서도 다른 톤과 같은 기준을 넘는지 잽니다.

상태 표시 — errorIcon · successIcon · warningIcon · infoIcon#

글자가 아닌 상태 표시 — 아이콘, 상태 점, 진행 막대, 차트 표시 — 는 상태 채움(error …)이 아니라 이 슬롯 넷을 씁니다. 글자는 4.5:1 을 넘어야 하지만 글자가 아닌 표시는 3:1(WCAG 1.4.11)이면 되어서, 채움보다 한 단계 밝게 둘 수 있습니다.

CoUI 에서는 새 프리미티브 없이 상태 램프의 단계입니다: 라이트 500 · 다크 400 · 고대비 라이트 700 · 고대비 다크 300. 대비 게이트가 페이지 톤(surface · surfaceBright · surfaceContainerLowest) 위에서 일반 모드 3:1, 고대비 4.5:1 을 잽니다(라이트 3.06 ~ 3.21 · 다크 8.25 ~ 9.10 · 고대비 라이트 6.30 ~ 6.92 · 고대비 다크 11.03 ~ 11.76). 라이트의 500 은 회색 컨테이너 톤 위에서 3:1 아래로 떨어지므로(2.45 ~ 3.07), 회색 컨테이너 위의 표시는 상태 채움(error …)을 쓰세요. 생성 팔레트 브랜드(표준 매핑)는 상태 채움과 같은 단계이고, 라이트 warning 만 채움이 밝아 한 단계 어두운 dark 입니다.

글자에는 쓰지 마세요 — 상태 색 글자는 onXContainer 입니다.

구문 색 — syntaxKeyword · syntaxType · syntaxFunction · syntaxString#

코드 강조 색은 슬롯 넷입니다 — 키워드(keyword · storage · control), 타입 · 클래스 · 숫자, 함수 · 메서드, 문자열. 평문 · 변수는 onSurface, 구두점 · 연산자는 onSurfaceVariant, 주석은 onSurfaceSubtle 을 씁니다.

구문 색은 브랜드가 정하는 색이 아니라 모든 브랜드에서 같은 값입니다. 보라 · 노랑 · 연두의 어두운 판용 값과 밝은 판용 값 여섯이 브랜드 밖의 syntax 그룹에 한 번만 있고, 브랜드의 시맨틱 매핑이 그 값을 모드에 맞게 이름으로 가리킵니다(분류색과 같은 방식). 함수 색만 브랜드 info 램프의 단계이고, CoUI 는 링크와 같은 단계입니다(라이트 info/700 · 다크 info/400). 고대비는 같은 밝기의 일반 값을 그대로 씁니다. 코드가 놓이는 바탕 여덟 곳(surface · surfaceContainerLow · surfaceContainer · surfaceContainerHigh · 네 상태의 XContainer 띠)에서 4.5:1 을 넘어야 하고, 레포의 대비 게이트가 CoUI 에서 그것을 잽니다(가장 낮은 곳이 라이트 surfaceContainerHigh 위 4.55).

coui_core 맵#

아래 스와치는 --coui-<token> 을 그대로 칠하므로, 헤더의 테마·서페이스 스위처를 바꾸면 같이 움직입니다.

사용법#

// Flutter — colorScheme 경유 또는 Style 토큰
theme.colorScheme.primary
theme.colorScheme.onSurfaceVariant
CoreColor.token(CoreColors.primary)

// Web — 토큰 class / CSS 변수
'bg-primary'                      // Tailwind class
'rgb(var(--coui-on-surface))'     // inline

무엇을 고르나 — 입력은 8개다#

CoUI 자신의 팔레트는 계산하지 않습니다 — 디자이너가 정한 고정 hex 를 CouiColorPresets.palette 에 숫자 단계로 적어 둡니다(neutral/50…1050, primary·상태 색 100…1000, base/white·base/black). Web 은 같은 이름을 --coui-neutral-100 처럼, Figma 는 color/coui/neutral/100 처럼 씁니다. 컴포넌트는 이 프리미티브를 직접 읽지 않고 시맨틱 슬롯만 읽습니다.

브랜드 팔레트의 출발점은 8개 입력입니다 — 7개 역할의 HSL (primary · secondary · tertiary · success · info · warning · error)과 중립 hue 하나를 PrimitiveColors.generate 에 넘깁니다. 슬롯을 하나씩 고르는 게 아니라 이 입력과 시맨틱 매핑을 정하면 컨테이너·전경·상태 슬롯이 따라옵니다. 모드와 서페이스 스타일도 최종 값에 참여하므로, 특정 팔레트의 hex 나 슬롯 개수를 고정된 보장으로 쓰지 마세요.

커스텀 팔레트를 만드는 법과 그것이 Tailwind config·CSS 변수로 구워지는 경로는 테마 가이드에 있습니다.

역할 — primary 가 기본이고, 나머지 둘은 갈래다#

셋은 파생 위계가 아니라 각각 따로 고르는 입력입니다. tertiary 가 secondary 에서 나오지 않습니다.

primary 는 기본 인터랙션 역할이고, secondary·tertiary 는 같은 컴포넌트를 색으로 갈래내야 할 때 고르는 다른 역할입니다. 실제 채움은 시맨틱 매핑이 정합니다 — CoUI 기본 테마에서는 primary 가 라이트에서 블루그레이(다크에서는 거의 흰 neutral), secondary 가 중성 강조이고, tertiary(= accent)는 primary 와 같은 값이라 갈래가 생기지 않습니다. 갈래는 브랜드 팔레트가 tertiary 를 따로 고를 때 생깁니다.

그 이상의 의미론("secondary 는 보조 동작")은 이 킷이 주장하지 않습니다. 앱이 정하세요.

채움의 밝기는 전경과 함께 결정하세요. onX 가 흰색인지 검정인지는 매핑이 정합니다. 채움만 밝히거나 어둡게 하면 그 위 전경과의 대비가 깨질 수 있으므로, 커스텀 팔레트도 실제 스킴에서 X / onX 를 한 쌍으로 검증해야 합니다.

surface 계층 — 이름은 밝기가 아니라 "페이지에서 떨어진 거리"다#

이건 이름만으로 맞힐 수 없어서 반드시 알아야 합니다.

surfaceContainerLowest → surfaceContainerLow → surfaceContainer → surfaceContainerHigh → surfaceContainerHighest 가 컨테이너 톤 사다리입니다. 실제 값은 아래 스와치에서 현재 테마로 확인하세요.

라이트에서는 level 이 오를수록 어두워지고, 다크에서는 밝아집니다. 방향이 뒤집히지만 뜻은 같습니다 — "페이지에서 멀어진다". 더 밝은 색이라는 이유로 역할을 고르지 마세요. 카드·팝오버의 표면은 각 컴포넌트 기본값이 정하고, 별도 위계가 필요할 때만 컨테이너 level 을 명시적으로 선택합니다.

다른 슬롯이 같은 값이 될 수 있습니다. 매핑·모드에 따라 surface 와 일부 컨테이너 톤이 겹칩니다. 이름이 다르다는 이유만으로 시각 차이가 보장되지는 않습니다.

onSurface 와 onSurfaceVariant 는 기본 스킴에서 surface 8톤 모두에 대해 4.5:1 기준으로 검증됩니다. 앱이 값을 덮으면 그 앱의 최종 조합도 다시 재야 합니다.

on* 페어링 — 이 표는 CI 가 매 PR 검증한다#

추측이 아닙니다. check_contrast.dart 가 실제 스킴을 빌드해 재고, CI 가 그것을 돌립니다. 검사 범위와 결과의 정본은 packages/coui_core/tool/check_contrast.dart 와 그 실행 출력입니다. 슬롯이 확장되어도 오래된 쌍 개수를 보장으로 남기지 않습니다.

규칙 세 줄#

1. onX 는 X 위에서만 보장됩니다. onPrimary 를 surface 위에 놓는 조합은 검증 대상이 아닙니다.
2. 역할색 텍스트가 필요하면 fill 이 아니라 onXContainer 또는 텍스트 전용 primaryText 를 쓰세요. fill 은 그 위의 onX 와 짝지은 채움이고 본문 색이 아닙니다. primaryTextLarge 는 큰 글자 기준이므로 일반 본문에 쓰지 않습니다.
3. outline 은 텍스트가 아니라 경계라 3:1 기준입니다.

일부러 검증하지 않는 것#

적어두지 않으면 없는 보장을 믿게 됩니다.

• outlineVariant — 장식 구분선이라 3:1 을 요구하면 hairline 이 아니게 됩니다. 컨트롤을 구획하는 경계를 이것만으로 그리지 마세요 — 그 용도는 outline 입니다.
• outlineSubtle — 떠 있는 패널의 테두리 슬롯입니다. 일반 모드에서는 outlineVariant 보다도 옅게 두는 값(라이트 neutral/150 · 다크 neutral/900)이라 같은 이유로 비율을 요구하지 않습니다. 다크의 neutral/900 은 패널 채움 (surfaceBright)과 같은 톤이라 선이 보이지 않고, 가장자리는 채움의 명도 차로 읽힙니다. 그림자를 믿을 수 없는 CoUI 고대비 두 모드만 surface · surfaceBright 위에서 4.5:1 로 잽니다. 브랜드가 따로 정하지 않은 표준 매핑에서는 이 슬롯이 outlineVariant 와 같은 값이라 그 기준을 지지 않습니다.
• disabled 슬롯 — WCAG 가 비활성 컨트롤을 면제합니다. 대신 별도 테스트가 다른 기준으로 값을 고정합니다(surface 대비 3:1 이상이면서 onSurface 보다는 낮을 것 — 읽히되 명백히 비활성).
• 컨테이너 톤 위의 placeholder — 입력 필드는 surface 바탕이라 이 조합은 그려지지 않습니다. CoUI 기본 테마에서 placeholder 는 라이트의 surfaceContainerLow 부터 위 컨테이너 톤과 surfaceDim, 다크의 surfaceContainerHigh·surfaceContainerHighest·surfaceBright 위에서 4.5:1 에 못 미칩니다. 컨테이너 톤으로 채운 입력을 만들면 그 톤을 검사 대상에 넣고 다시 재야 합니다.
• 임의 전경·배경 조합 — onX 가 있다는 사실만으로 모든 배경과의 대비를 보장하지 않습니다. primaryTextLarge 의 3:1 검사도 일반 본문 보장이 아닙니다.
• 페이지 위의 분류색 채움 — 칩 · 차트 · 범례 점이 페이지에서 보이는 정도 (categoryX × surface)입니다. 디자인은 UI 기준 3:1 을 참고로만 적습니다 — 분류의 이름은 칩이나 범례의 라벨이 말하고, 그 라벨 짝은 위 표에서 잽니다.
• 라이트 · 다크의 분류색 outline — 라이트에서는 컨테이너 톤을 읽어 옅은 칩에 일부러 테두리가 보이지 않습니다. 다크의 outline 은 칩 가장자리를 정리하는 색조이지 컨트롤을 구획하는 경계가 아니라 약 2:1 입니다. 보이는 경계를 약속하는 고대비 두 모드에서만 잽니다.
• 카드 · 컨테이너 톤 위의 분류색 짝 — 기준은 칩이 기본으로 놓이는 페이지에서 정했습니다. 고대비 다크의 outline 은 surfaceContainer 같은 컨테이너 톤 위에서 4.5:1 에 못 미칩니다. 그 모드에서 컨테이너 톤 위에 칩을 그리면 그 톤을 검사 대상에 넣고 다시 재야 합니다.
• 중립 톤이 다른 브랜드의 고대비 다크 페이지 — 분류색 값은 모든 브랜드에서 같지만 페이지(surface)는 브랜드의 중립 톤을 따릅니다. 게이트는 표준 매핑을 대표 팔레트 한 벌의 페이지에서만 재고, 고대비 다크의 outline 은 그 페이지에서 4.5:1 에 겨우 닿습니다(yellow 가 가장 빠듯합니다). 그래서 중립 톤이 더 밝거나 색조가 다른 브랜드의 고대비 다크 페이지에서는 outline 이 4.5:1 에 못 미칠 수 있습니다 — 그런 브랜드는 자기 페이지에서 outline 을 직접 재야 합니다. 글자 짝은 여유가 커서 같은 문제가 없습니다.

고대비 모드에서도 같은 역할 쌍을 같은 기준으로 검증하고, 그 위에 고대비에서만 더하는 기준이 있습니다 — 위 표에서 고대비를 따로 적은 행입니다. 고대비가 무엇을 바꾸고 무엇을 일부러 하지 않는지는 접근성 페이지에 있습니다.

분류색 (category) — 의미 없이 구분만 하는 색#

태그 · 아바타 · 라벨 · 일정 · 차트 범례처럼 이것과 저것이 다르다만 말하는 곳에 씁니다. 분류색은 성공 · 오류 · 경고 같은 의미를 나르지 않습니다 — 의미는 상태 색이 맡습니다.

색은 9가지입니다: red · orange · yellow · green · blue · purple · pink · brown · gray. 코드에서는 CoreCategoryColor 의 값이고, CSS 변수 · Figma 변수 · 아래 스와치가 모두 이 순서로 나열됩니다.

모드마다 칩이 다르게 보인다#

슬롯 이름은 네 모드가 같고 값만 다릅니다 — 컴포넌트는 슬롯만 고릅니다.

슬롯 — 색마다 다섯 개#

// 정해 둔 색
CoreColor.token(CoreColors.categoryRedContainer)

// 실행 중에 고른 색 — hue 는 CoreCategoryColor
CoreColor.token(hue.container)

// Web — 같은 이름의 class / CSS 변수
'bg-category-red-container'
'rgb(var(--coui-on-category-red-container))'

쓰는 규칙#

• 의미를 나르지 않습니다. 성공 · 오류 · 경고 · 정보에는 상태 색을 씁니다.
• 9가지 중에서 고릅니다. 사용자가 고른 임의의 hex 는 받지 않습니다.
• 색 글자는 모든 모드에서 onCategoryXContainer 입니다 — 분류명을 색으로 쓰는 글자, 범례 글자 모두. categoryX 는 글자색이 아닙니다. 흰 바탕 위에서 3.5:1 언저리까지 내려갑니다.
• 기본은 옅은 칩입니다. 진한 칩은 강조나 시간 배지 같은 짧은 라벨에만 씁니다.

대비 예외 — 라이트의 진한 칩 라벨 하나#

라이트 모드의 진한 칩 라벨(onCategoryX on categoryX)에 한해 3.5:1 을 허용합니다. 조건: SemiBold 이상 · 12px 이상 · 단어 하나나 시간 같은 짧은 라벨. 문장에는 쓰지 않습니다.

흰 글자로 4.5:1 을 지키면 라이트의 채움이 어둡고 탁해집니다. 짧은 라벨은 3.5:1 에서도 읽힙니다. 다크는 4.5:1, 고대비 두 모드는 7:1 을 예외 없이 지킵니다. 대비 게이트는 이 예외를 3:1 큰 글자 기준이 아닌 3.5:1 그대로 재므로, 채움이 3.5:1 아래로 내려가면 실패합니다.

값은 브랜드와 무관하다#

분류색은 브랜드 색이 아니라 모든 브랜드에서 같은 값입니다. 브랜드 팔레트 (CoreBrand)가 바꾸지 않고, PrimitiveColors.generate 의 입력도 아닙니다. 값은 coui_core 의 CoreCategoryPalette 한 곳에 있고, 각 매핑이 일반 스킴과 고대비 스킴에 그 표를 그대로 씁니다. 진한 칩 글자(onCategoryX)만 표의 색이 아니라 매핑의 흰색이고, 고대비 다크에서만 검정입니다. Figma 에서는 원시값이 브랜드 밖의 color/category/<색>/<역할> 그룹에 한 번 있고, 브랜드마다 시맨틱 슬롯이 그것을 가리킵니다.

CoreSchemeSource 를 직접 구현한다면 네 빌더(light · dark · highContrastLight · highContrastDark)와 raiseContrast 안에서 CoreCategoryPalette.applyTo 를 부르세요. 고대비 쪽에서 빠뜨리면 고대비 모드가 분류색의 일반 값을 그대로 그립니다 — 비어 있는 슬롯은 CoUI 의 일반 값으로 채워지기 때문입니다.

대비는 레포 게이트가 잰다#

레포의 대비 게이트(check_contrast.dart)가 위 on* 표의 분류색 짝을 9색 × 4모드, CoUI · 표준 매핑에서 잽니다. 표준 매핑은 대표 팔레트 한 벌의 페이지에서 재므로, 중립 톤이 다른 브랜드의 고대비 다크 outline 은 일부러 검증하지 않는 것 에 적었습니다. CoreContrast.auditScheme 은 분류색을 보지 않습니다 — 기준이 모드마다 다르고 라이트의 3.5:1 은 어떤 CoreContrastLevel 에도 없어서, 대표 쌍 한 벌로 적을 수 없습니다. 앱이 직접 그리는 분류색 짝은 CoreContrast.ratio 로 고정하세요.

스와치는 아래 전체 토큰 의 Category 묶음에 있습니다.

상태색을 장식으로 써도 되나 — 대가가 둘 있다#

시스템은 이 색들을 장식 variant 로 실제 제공합니다. 다만:

warning fill 은 텍스트 색으로 쓸 수 없습니다#

warning fill 을 본문 색으로 쓰지 않습니다. 밝은 팔레트에서 대비가 낮아지는 것은 튜닝 미스가 아니라 구조적입니다 — warning 은 onWarning 이 흰색이 아니라 검정인 유일한 역할이고, 그건 fill 이 설계상 밝다는 뜻입니다(경고는 노랑이니까). 텍스트로 읽히게 어둡게 하면 그 검정 전경이 깨집니다.

그래서 텍스트 체인의 fill getter 를 제공하지 않습니다 — Web 에서는 일곱 역할의 fill getter 가 삭제되었고 Flutter 에서는 deprecated 입니다. 가드가 그 경로의 재도입을 막습니다. 경고색 텍스트의 대체는 **onWarningContainer**입니다.

톤은 스크린 리더가 끼어드는 정도를 바꿉니다#

Alert 의 통보 방식은 variant 가 결정하고, 양 플랫폼이 같은 결정을 읽습니다:

Flutter 에는 통보 축이 하나뿐이라 polite/assertive 구분이 없습니다 — 그 구분만 Web 전용이고, 매핑 자체는 공유됩니다.

색을 장식으로 고르면 페이지가 말을 끊습니다. 배너 세 개를 destructive 로 두면 사용자가 아무것도 하기 전에 세 번 말이 끊깁니다.

대비 검증#

브랜드 팔레트를 세웠다면 라이트·다크 시맨틱 쌍의 대비를 테스트로 고정하세요. coui_core 의 CoreContrast 가 WCAG 2.x 상대 휘도와 대비 비율을 순수 Dart 로 계산하므로, Flutter 앱·Web 앱·골든 테스트가 같은 숫자를 봅니다. 앱에서 휘도 공식을 다시 짜지 마세요.

final brand = PrimitiveColors.generate(/* 브랜드 시드 */);
final light = CoreSemanticMapping.light(brand).resolved(.light);
final dark = CoreSemanticMapping.dark(brand).resolved(.dark);

// 대표 쌍 한 번에 — 실패한 쌍이 reason 맨 위에 찍힙니다
for (final scheme in [light, dark]) {
  final report = CoreContrast.auditScheme(scheme);
  expect(report.failures, isEmpty, reason: report.toString());
}

// 앱이 직접 칠하는 쌍
expect(
  CoreContrast.meets(light.onPrimaryContainer, light.surface, .aaNormalText),
  isTrue,
);
CoreContrast.ratio(const CoreColor(0xFF777777), const CoreColor(0xFFFFFFFF)); // 4.48

auditScheme 의 대표 쌍은 스킴이 그리라고 만든 조합입니다 — 역할마다 onX / X 와 onXContainer / XContainer, 페이지 위 onSurface · onSurfaceVariant · onSurfaceSubtle · placeholder · error, 이름이 기준을 말하는 primaryText(4.5:1) · primaryTextLarge(3:1), inverseOnSurface / inverseSurface, 컴포넌트 경계 outline(3:1). 모든 컨테이너 톤·hover 채움·컴포넌트 변형까지 훑지는 않으니, 앱이 따로 칠하는 쌍은 ratio / meets 로 직접 고정하세요. 장식용 outlineVariant · outlineSubtle 과 비활성 톤은 WCAG 가 비율을 요구하지 않아 넣지 않습니다. 분류색도 넣지 않습니다 — 기준이 모드마다 다르기 때문입니다(분류색).

• 입력은 해석된 색입니다 — ResolvedColorScheme 의 슬롯이나 Flutter scheme.resolve(token) 결과. 해석 전 CoreColor.token(...) 은 채널이 없어 StateError 를 던집니다.
• 반투명 — 대비는 불투명한 두 색 사이에서만 정의됩니다. 반투명한 전경은 배경 위에 합성(source-over)한 색으로 잽니다. 반투명한 배경은 그 뒤에 무엇이 있느냐에 달려 판정할 수 없으므로 ArgumentError 입니다 — 화면에 실제로 보이는 불투명 색을 넘기세요(CoreContrast.compositeOver).
• 반올림하지 않습니다 — 4.48:1 은 화면에 "4.5" 로 보여도 aaNormalText 를 통과하지 못합니다.

CoUI 기본 색(CouiColorPresets.source)의 라이트·다크·고대비 스킴은 대표 쌍을 모두 통과하고, 그 사실은 coui_core 테스트가 고정합니다.

전체 토큰#

이 표는 glass* 네 슬롯을 보여주지 않습니다 — 기본 팔레트가 그 슬롯을 채우지 않아 --coui-glass-* CSS 변수가 나가지 않기 때문입니다. 값을 명시하면 Liquid Glass 디자인 시스템 어댑터(Flutter)가 그것을 사용하고, 명시하지 않으면 surface·primary 에서 파생합니다.