Skip to Content
디자인

카드와 표면 계층

콘텐츠 카드, 워크스페이스 셸, 플로팅 레이어, 그림자 및 배경 블러 사용 규칙.

실시간 컴포넌트카드 레이어

콘텐츠 카드는 평평하게 유지되며, 외부 쉘은 워크스페이스 그룹화를 전달합니다.

프로젝트 개요출시 준비 상태
콘텐츠12개 페이지 완료

표준 콘텐츠 카드는 외부 그림자를 사용하지 않습니다.

체크 목록모바일 대응 완료

선택 및 상태는 색상과 정보 계층을 통해 전달됩니다.

카드 재질 및 계층 규격

이 문서는 Qokit 작업 인터페이스가 어떤 상황에서 그림자, 투명도, 그라데이션 및 배경 블러를 사용하는지 공개적으로 설명합니다. 플랫폼 확장, Builder, CMS, Dashboard, Studio 및 Admin에 적용됩니다. 마케팅 페이지와 생성된 사이트는 더 표현력이 풍부할 수 있지만, 효과는 현재 테마에 귀속되어야 하며 콘텐츠 가독성을 보장해야 합니다.

핵심 원칙

시각 효과는 구조를 표현하는 데 사용되며, 모든 블록을 장식하는 데 사용되지 않습니다:

  • 콘텐츠는 배경 색상 차이로 구분됩니다.
  • 컨테이너는 투명도 또는 절제된 그라데이션으로 소속감을 표현합니다.
  • 플로팅 레이어는 그림자로 계층을 표현합니다.
  • 상호작용은 색상과 포커스 링으로 상태를 표현합니다.

독립적인 단색 카드와 입력 필드는 공유 1단계 가벼운 그림자를 사용하며, 목록, 중첩된 표면 및 투명 그룹은 평평하게 유지되고, 실제 플로팅 레이어만 뚜렷한 그림자를 사용합니다.

판단 순서

재질 효과를 추가하기 전에 표면의 역할을 먼저 판단합니다:

  1. 독립적인 단색 카드 또는 입력 필드인가? 공유 1단계 표면 또는 필드 그림자를 사용합니다.
  2. 목록 행, 중첩된 카드, 반복 옵션 또는 투명 그룹인가? 평평하게 유지합니다.
  3. 여러 내부 콘텐츠 카드를 하나의 워크스페이스로 구성하는가? 셸을 사용합니다.
  4. 페이지 콘텐츠를 덮거나 현재 평면 위에 나타나는가? 플로팅 레이어 그림자를 사용합니다.
  5. 드래그, 확대/축소 또는 임시 호버 상태인가? 임시 그림자를 사용합니다.
  6. 단순히 hover, 선택 또는 focus를 표현하기 위한 것인가? 공유 hover 역할, 상호작용 배경색 및 포커스 링을 사용합니다.

표면 역할이 정말로 필요하지 않는 한, 그림자, 투명도, 그라데이션 및 블러를 동시에 겹치지 마십시오.

시나리오 매트릭스

표면 역할그림자투명도 또는 그라데이션배경 블러
독립적인 단색 콘텐츠 카드, 지표 카드공유 1단계 가벼운 그림자약간의 배경 색상 차이 허용없음
목록 행, 중첩된 카드, 투명 그룹, 반복 옵션없음약간의 배경 색상 차이 허용없음
페이지 내 그룹 셸없음권장일반적으로 필요하지 않음
사이드바 또는 상주 워크스페이스 셸경량권장뒤에 보이는 콘텐츠가 있을 때 허용
Dialog, Popover, Dropdown, 컨텍스트 메뉴명확한 플로팅 레이어 그림자배경은 가독성을 보장할 만큼 충분히 단색이어야 함허용
드래그 미리보기, 확대/축소 상태, 호버 미리보기임시로 강하게선택 사항일반적으로 필요하지 않음
Hover1단계 그림자 유지 또는 약간 강화배경 변경 가능변화 없음
선택 또는 활성화 상태없음강조 색상 배경 또는 절제된 그라데이션변화 없음
입력 필드, 검색 필드매우 가벼운 필드 그림자컨트롤 표면 색상 사용일반적으로 필요하지 않음
독립적인 기본 작업, 독립적인 캡슐, 세그먼트 컨트롤 외피매우 가벼운 컨트롤 그림자컨트롤 표면 색상 사용일반적으로 필요 않음
도구 모음 및 투명 내부 컨트롤없음컨트롤 표면 색상 또는 투명 사용일반적으로 필요하지 않음
마케팅 페이지 또는 생성된 사이트 시각적 카드테마에 의해 결정허용절제하여 사용

컴포넌트 매핑

  • <Card>은 기본적으로 layer="content"을 사용합니다: 공유 1단계 가벼운 그림자, 테두리 없음, 기본 20px 모서리 반경; muted, 중첩, 목록 및 투명 변형은 평평하게 유지됩니다.
  • <Card layer="shell">: 페이지 내에서는 그룹화만 담당하며, 투명 또는 가벼운 그라데이션 표면을 사용하고 평평하게 유지합니다; 상주 워크스페이스 셸은 해당 모드에서 별도로 계층을 제공합니다.
  • <Card shape="pill">: 컴팩트한 단일 행 카드에 사용되며, 모서리 반경은 타원형 캡슐 형태입니다.
  • SidebarNavigation: 독립적인 워크스페이스 셸로, 명확한 그라데이션, 투명도, 블러 및 가벼운 그림자를 유지합니다.
  • Studio의 PromptPanel이 워크스페이스 컨테이너로 사용될 때: --workspace-shell-shadow을 사용합니다.
  • DialogPanel, 드롭다운 메뉴, Popover, 컨텍스트 메뉴 및 컨셉 탐색기: 플로팅 레이어 그림자를 사용합니다.
  • Builder 캔버스, 디바이스 미리보기, 생성된 사이트 미리보기, 드래그 미리보기 및 확대/축소 상태: 독립적인 미리보기 평면 또는 임시 상호작용 레이어를 나타내므로 전용 그림자를 유지할 수 있습니다.

여러 층의 플로팅 콘텐츠 카드를 생성하지 마십시오. 외부 그룹화가 정말로 필요하다면, 그것은 평평한 셸이어야 합니다. 실제 플로팅 레이어를 제외하고, 동일한 DOM 조상 체인에서 일반 콘텐츠 또는 컨트롤 그림자는 최대 하나만 나타날 수 있습니다.

디자인 변수(Token) 사용

공유 Token을 우선 사용하고, 효과를 하드코딩하지 마십시오:

  • 콘텐츠 카드 그림자: --card-shadow: var(--qk-shadow-surface)
  • 콘텐츠 카드 hover 그림자: --card-shadow-hover: var(--qk-shadow-surface-hover)
  • 필드 그림자: --input-shadow: var(--qk-shadow-field)
  • 필드 활성화 그림자: --input-state-shadow: var(--qk-shadow-field-active)
  • 컨트롤 그림자: --qk-shadow-control / --qk-shadow-control-hover
  • 기본 작업 컨트롤 그림자: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • 콘텐츠 카드 블러: --card-backdrop-filter: none
  • 셸 표면: --card-shell-surface
  • 셸 블러: --card-shell-backdrop-filter
  • 워크스페이스 셸 그림자: --workspace-shell-shadow
  • Dialog 표면: --dialog-surface, 절제된 테마 그라데이션 제공
  • Dialog 블러: --dialog-backdrop-filter
  • Dialog 플로팅 레이어 그림자: --dialog-shadow
  • Dialog 모서리 반경: --card-radius 재사용
  • 키보드 포커스: --focus-ring
  • 플로팅 레이어 그림자: 기존 Dialog, Dropdown, Menu 또는 페이지 수준 플로팅 레이어 Token 사용

일반 콘텐츠 카드와 워크스페이스 패널은 강한 범용 --shadow Token을 사용해서는 안 됩니다.

전역 그림자는 "짧은 변위, 낮은 투명도, 배치 계층에 따라 증가"하는 조용한 스케일을 채택합니다. 일반 Card, 필드 및 컨트롤은 라우트에서 공유 그림자를 깊게 하거나 확대해서는 안 됩니다; Popover와 Dialog는 더 큰 변위와 블러 범위로 페이지에서 벗어남을 표현하며, 짙은 회색 안개를 겹치지 않습니다.

상호작용 규칙

호버(Hover)

  • 콘텐츠 카드는 --qk-shadow-surface-hover 이상의 계층으로 상승해서는 안 됩니다.
  • translateY으로 콘텐츠 카드를 상승시키지 않습니다.
  • 약간의 배경 변화 또는 명확한 컨트롤 피드백을 사용합니다.
  • 형태를 변경하지 않아 모서리 반경이 일관되지 않거나 그림자가 잘리는 것을 방지합니다.

선택 및 활성화

  • 강조 색상 표면, 아이콘 상태, 시맨틱 상태 또는 절제된 그라데이션을 사용합니다.
  • 그림자로만 상태를 표현해서는 안 됩니다.

키보드 포커스

  • 공유 focus-visible 규칙 또는 --focus-ring을 사용합니다.
  • 일반 카드 그림자는 포커스 힌트를 대체할 수 없습니다.
  • 라이트 및 다크 테마 모두에서 명확하게 보여야 합니다.

드래그 및 확대/축소

  • 레이어가 이동하거나 크기가 조정될 때만 강한 그림자를 사용할 수 있습니다.
  • 상호작용 종료 후 임시 그림자를 제거해야 합니다.
  • 오버플로우 컨테이너는 이동 레이어의 피드백 효과를 잘라서는 안 됩니다.

투명도 및 배경 블러

투명도는 외부 표면과 워크스페이스의 소속 관계를 표현하는 데 사용됩니다. 배경 블러는 표면 뒤에 실제로 보이는 콘텐츠, 색상 또는 이미지가 있을 때만 의미가 있습니다.

  • 단색 배경에서 블러를 사용하지 마십시오. 렌더링 비용만 증가시키고 계층을 표현할 수 없습니다.
  • 뒤에 어떤 배경이 지나가든, 텍스트, 아이콘 및 컨트롤은 명확하게 읽을 수 있어야 합니다.
  • 브라우저가 배경 블러를 지원하지 않을 때, 불투명하거나 읽을 수 있는 대체 배경이 있어야 합니다.
  • 밀집된 작업 인터페이스에서는 블러 강도를 절제해야 합니다.
  • 라이트 및 다크 테마를 동시에 검증해야 합니다.

그림자 유지가 허용되는 예외

  • 워크스페이스 사이드바 셸
  • Dialog, Popover, Dropdown, 메뉴 및 모달 패널
  • Studio 컨셉 탐색기 및 확인 플로팅 레이어
  • Builder 캔버스, 디바이스 프레임 및 생성된 사이트 미리보기 평면
  • 드래그 미리보기, 확대/축소 피드백 및 임시 호버 도구
  • 공유 버튼 Token에 그림자가 정의된 기본 작업 버튼
  • 현재 테마가 제어하는 마케팅 페이지 및 생성된 사이트 시각적 요소

이러한 예외는 광범위한 선택자나 공유 Token을 통해 일반 콘텐츠 카드에 영향을 미쳐서는 안 됩니다.

검토 체크리스트

  • 독립적인 단색 콘텐츠 카드와 입력 필드는 공유 1단계 가벼운 그림자 역할만 사용합니다.
  • 독립적인 기본 작업, 독립적인 캡슐 및 세그먼트 컨트롤 외피는 공유 매우 가벼운 컨트롤 그림자만 사용합니다.
  • 페이지 그룹, 목록 행, 중첩된 카드, 투명 그룹, 반복 Tab/Pill, 도구 모음 및 복합 컨트롤 내부 항목은 평평하게 유지됩니다.
  • 도구 모음의 검색, 필터, 정렬, 보기 및 인라인 기본 작업은 평면으로 유지됩니다; 일반 입력 필드의 가벼운 그림자는 도구 모음으로 유출되지 않습니다. 키보드 포커스 링은 예외입니다.
  • Segmented가 이미 그림자가 있는 카드, 대화 상자 또는 도구 모음 내부에 있을 때, 외피와 선택된 항목 모두 평면으로 유지됩니다; 마우스 클릭 시 키보드 포커스 링이 표시되지 않습니다.
  • 실제 플로팅 레이어를 제외하고, 동일한 조상 체인에서 여러 일반 그림자를 겹치지 않습니다.
  • hover는 콘텐츠 카드를 수직으로 이동시키지 않습니다.
  • 중첩된 콘텐츠 카드가 제거되었거나, 외부가 명시적으로 셸로 정의되었습니다.
  • 실제 셸만 --workspace-shell-shadow을 사용합니다.
  • 실제 플로팅 레이어와 임시 상호작용 레이어만 강한 그림자를 사용합니다.
  • 배경 블러 뒤에 보이는 콘텐츠가 존재하며, 읽을 수 있는 대체 배경이 있습니다.
  • focus-visible은 포커스 링을 사용합니다.
  • 라이트 및 다크 테마 모두 충분한 대비를 유지합니다.
  • 모서리 반경이 있는 표면은 hover, focus, 드래그 또는 플로팅 레이어 피드백을 잘라내지 않습니다.
  • 데스크톱 및 모바일 너비에서 새로운 가로 오버플로우가 발생하지 않습니다.
  • npm run ui:check-card-surfaces --workspace @qokit-ai/web 검사를 통과했습니다.

페이지 내 목차