카드와 표면 계층
콘텐츠 카드, 워크스페이스 셸, 플로팅 레이어, 그림자 및 배경 블러 사용 규칙.
콘텐츠 카드는 평평하게 유지되며, 외부 쉘은 워크스페이스 그룹화를 전달합니다.
표준 콘텐츠 카드는 외부 그림자를 사용하지 않습니다.
선택 및 상태는 색상과 정보 계층을 통해 전달됩니다.
카드 재질 및 계층 규격
이 문서는 Qokit 작업 인터페이스가 어떤 상황에서 그림자, 투명도, 그라데이션 및 배경 블러를 사용하는지 공개적으로 설명합니다. 플랫폼 확장, Builder, CMS, Dashboard, Studio 및 Admin에 적용됩니다. 마케팅 페이지와 생성된 사이트는 더 표현력이 풍부할 수 있지만, 효과는 현재 테마에 귀속되어야 하며 콘텐츠 가독성을 보장해야 합니다.
핵심 원칙
시각 효과는 구조를 표현하는 데 사용되며, 모든 블록을 장식하는 데 사용되지 않습니다:
- 콘텐츠는 배경 색상 차이로 구분됩니다.
- 컨테이너는 투명도 또는 절제된 그라데이션으로 소속감을 표현합니다.
- 플로팅 레이어는 그림자로 계층을 표현합니다.
- 상호작용은 색상과 포커스 링으로 상태를 표현합니다.
독립적인 단색 카드와 입력 필드는 공유 1단계 가벼운 그림자를 사용하며, 목록, 중첩된 표면 및 투명 그룹은 평평하게 유지되고, 실제 플로팅 레이어만 뚜렷한 그림자를 사용합니다.
판단 순서
재질 효과를 추가하기 전에 표면의 역할을 먼저 판단합니다:
- 독립적인 단색 카드 또는 입력 필드인가? 공유 1단계 표면 또는 필드 그림자를 사용합니다.
- 목록 행, 중첩된 카드, 반복 옵션 또는 투명 그룹인가? 평평하게 유지합니다.
- 여러 내부 콘텐츠 카드를 하나의 워크스페이스로 구성하는가? 셸을 사용합니다.
- 페이지 콘텐츠를 덮거나 현재 평면 위에 나타나는가? 플로팅 레이어 그림자를 사용합니다.
- 드래그, 확대/축소 또는 임시 호버 상태인가? 임시 그림자를 사용합니다.
- 단순히 hover, 선택 또는 focus를 표현하기 위한 것인가? 공유 hover 역할, 상호작용 배경색 및 포커스 링을 사용합니다.
표면 역할이 정말로 필요하지 않는 한, 그림자, 투명도, 그라데이션 및 블러를 동시에 겹치지 마십시오.
시나리오 매트릭스
| 표면 역할 | 그림자 | 투명도 또는 그라데이션 | 배경 블러 |
|---|---|---|---|
| 독립적인 단색 콘텐츠 카드, 지표 카드 | 공유 1단계 가벼운 그림자 | 약간의 배경 색상 차이 허용 | 없음 |
| 목록 행, 중첩된 카드, 투명 그룹, 반복 옵션 | 없음 | 약간의 배경 색상 차이 허용 | 없음 |
| 페이지 내 그룹 셸 | 없음 | 권장 | 일반적으로 필요하지 않음 |
| 사이드바 또는 상주 워크스페이스 셸 | 경량 | 권장 | 뒤에 보이는 콘텐츠가 있을 때 허용 |
| Dialog, Popover, Dropdown, 컨텍스트 메뉴 | 명확한 플로팅 레이어 그림자 | 배경은 가독성을 보장할 만큼 충분히 단색이어야 함 | 허용 |
| 드래그 미리보기, 확대/축소 상태, 호버 미리보기 | 임시로 강하게 | 선택 사항 | 일반적으로 필요하지 않음 |
| Hover | 1단계 그림자 유지 또는 약간 강화 | 배경 변경 가능 | 변화 없음 |
| 선택 또는 활성화 상태 | 없음 | 강조 색상 배경 또는 절제된 그라데이션 | 변화 없음 |
| 입력 필드, 검색 필드 | 매우 가벼운 필드 그림자 | 컨트롤 표면 색상 사용 | 일반적으로 필요하지 않음 |
| 독립적인 기본 작업, 독립적인 캡슐, 세그먼트 컨트롤 외피 | 매우 가벼운 컨트롤 그림자 | 컨트롤 표면 색상 사용 | 일반적으로 필요 않음 |
| 도구 모음 및 투명 내부 컨트롤 | 없음 | 컨트롤 표면 색상 또는 투명 사용 | 일반적으로 필요하지 않음 |
| 마케팅 페이지 또는 생성된 사이트 시각적 카드 | 테마에 의해 결정 | 허용 | 절제하여 사용 |
컴포넌트 매핑
<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검사를 통과했습니다.