레이어링 | CoUI
LogoCoUI

레이어링

CoUI Web 겹침 순서 — CoreZIndex 가 단일 출처입니다. Flutter 는 위젯 트리 순서입니다.

레이어링#

Figma Foundation · 07. Layering · 값은 coui_core 가 정본입니다.

이 페이지는 무엇이 무엇 위에 오는가를 고르는 곳입니다. Web 의 z-index 12단계는 coui_core 의 CoreZIndex 가 정합니다. Flutter 짝은 없습니다 — Flutter 는 위젯 트리 순서(그리고 Stacks)가 겹침을 결정합니다.

z-index 는 숫자 경쟁이 아니라 계약입니다. 목록에 없는 값을 쓰는 순간 다음 사람이 999999 를 쓰게 됩니다. 토큰 축 전체는 디자인 토큰 을 보세요.

언제 쓰나#

토큰을 고르세요

  • Web 오버레이·헤더·토스트의 z-index → CoreZIndex.z50 등
  • Flutter 에서 겹침이 필요하면 Stacks / Position — raw Stack/Positioned 대체

쓰지 마세요

  • z-[1234] / zIndex: 9999 리터럴 — 사다리 밖 값은 다음 오버레이와 충돌합니다
  • Flutter 위젯에 CoreZIndex 를 붙이기 — 그 상수는 Web CSS 용입니다
  • 부모에 transform / opacity / filter 가 걸린 채 자식 z-index 로 전역 레이어를 이기려 하기 — 스택 컨텍스트는 부모가 만듭니다

시맨틱 layer/modal 같은 별칭은 아직 없습니다. Figma 페이지의 "권장 매핑" 표는 캔버스에 미적용 제안으로 남아 있습니다. 지금은 원시 z0–z100 을 직접 고릅니다.

coui_core 맵#

쓰는 이름의미
CoreZIndex.z50Web z-index 정수 (여기선 1050)
CoreZIndex.scale.z50 CSS 키 '50' → var(--z-50)
CoreZIndex.zAuto'auto' — 새 스택 컨텍스트를 만들지 않음

기준값은 1000 부터입니다. 서드파티·레거시가 쓰는 1–999 와 안 부딪히게 하려는 여유입니다. 단계 사이는 10 이라 급한 중간값을 끼울 수는 있지만, 끼운 값은 토큰으로 승격해야 합니다.

근거 명세: design/design-tokens/z-index/CoUI_ZIndex_Token_Specification.md (1.0). 우선순위는 디자인 소스.

스케일#

역할 이름은 coui_core 주석이 정본입니다. 아래는 낮은 층 → 높은 층입니다.

토큰값역할
zAutoauto기본 흐름. 새 컨텍스트 없음
z01000기본 콘텐츠
z101010드롭다운 메뉴
z201020sticky / fixed 헤더
z301030사이드바
z401040오버레이 스크림
z501050모달 · 다이얼로그
z601060팝오버
z701070툴팁
z801080토스트 · 스낵바
z901090긴급 알림
z1001100최상위 (디버그 · 개발 도구)

모달은 스크림(z40) 위(z50)에 오고, 토스트는 그 위(z80)에 옵니다. 툴팁(z70)이 토스트를 가리지 않도록 순서를 뒤집지 마세요.

사용법#

// Web — CSS 변수 / Tailwind 키
'z-${CoreZIndex.scale.z50}'     // z-50 → var(--z-50) → 1050

// Flutter — 트리 순서. z-index 토큰 없음. 마지막 자식이 위
Stacks(
  children: [
    Position.fill(child: scrim),
    dialog,
  ],
)

함께 보기#