Card và phân tầng bề mặt
Quy tắc sử dụng card nội dung, Shell không gian làm việc, lớp phủ, bóng đổ và làm mờ nền.
Card nội dung giữ dạng phẳng; lớp vỏ ngoài thể hiện nhóm không gian làm việc.
Card nội dung tiêu chuẩn không sử dụng bóng bên ngoài.
Lựa chọn và trạng thái được truyền tải qua màu sắc và phân cấp thông tin.
Quy chuẩn chất liệu và phân tầng Card
Tài liệu này công khai giải thích khi nào giao diện Qokit sử dụng bóng đổ, độ trong suốt, gradient và làm mờ nền. Áp dụng cho nền tảng mở rộng, Builder, CMS, Dashboard, Studio và Admin. Các trang marketing và trang web được tạo ra có thể biểu cảm hơn, nhưng hiệu quả phải thuộc về chủ đề hiện tại và đảm bảo nội dung dễ đọc.
Nguyên tắc cốt lõi
Hiệu ứng hình ảnh dùng để thể hiện cấu trúc, không dùng để trang trí từng khối:
- Nội dung được phân biệt qua sự khác biệt màu nền.
- Container thể hiện sự thuộc về qua độ trong suốt hoặc gradient tiết chế.
- Lớp phủ thể hiện phân tầng qua bóng đổ.
- Tương tác thể hiện trạng thái qua màu sắc và vòng focus.
Card màu đặc độc lập và ô nhập liệu sử dụng bóng đổ cấp một nhẹ dùng chung; danh sách, bề mặt lồng nhau và nhóm trong suốt giữ phẳng; chỉ lớp phủ thực sự mới sử dụng bóng đổ rõ rệt.
Trình tự xác định
Trước khi thêm hiệu ứng chất liệu, hãy xác định vai trò của bề mặt:
- Có phải card màu đặc độc lập hoặc ô nhập liệu không? Sử dụng bề mặt cấp một dùng chung hoặc bóng đổ trường dữ liệu.
- Có phải hàng danh sách, card lồng nhau, tùy chọn lặp lại hoặc nhóm trong suốt không? Giữ phẳng.
- Có phải tổ chức nhiều card nội dung bên trong thành một không gian làm việc không? Sử dụng Shell.
- Có phủ lên nội dung trang hoặc xuất hiện phía trên mặt phẳng hiện tại không? Sử dụng bóng đổ lớp phủ.
- Có đang ở trạng thái kéo thả, thu phóng hoặc tạm thời lơ lửng không? Sử dụng bóng đổ tạm thời.
- Chỉ để thể hiện hover, được chọn hoặc focus? Sử dụng vai trò hover dùng chung, màu nền tương tác và vòng focus.
Trừ khi vai trò bề mặt thực sự cần thiết, không xếp chồng bóng đổ, độ trong suốt, gradient và làm mờ cùng lúc.
Ma trận tình huống
| Vai trò bề mặt | Bóng đổ | Trong suốt hoặc gradient | Làm mờ nền |
|---|---|---|---|
| Card nội dung màu đặc độc lập, card chỉ số | Bóng đổ nhẹ cấp một dùng chung | Cho phép chênh lệch màu nền nhẹ | Không |
| Hàng danh sách, card lồng nhau, nhóm trong suốt, tùy chọn lặp lại | Không | Cho phép chênh lệch màu nền nhẹ | Không |
| Shell nhóm trong trang | Không | Khuyến nghị | Thường không cần |
| Sidebar hoặc Shell không gian làm việc cố định | Nhẹ | Khuyến nghị | Cho phép khi có nội dung hiển thị phía sau |
| Dialog, Popover, Dropdown, menu ngữ cảnh | Bóng đổ lớp phủ rõ ràng | Nền phải đủ đặc để đảm bảo dễ đọc | Cho phép |
| Xem trước kéo thả, trạng thái thu phóng, xem trước lơ lửng | Tạm thời mạnh hơn | Tùy chọn | Thường không cần |
| Hover | Giữ hoặc tăng nhẹ bóng đổ cấp một | Có thể thay đổi nền | Không thay đổi |
| Trạng thái được chọn hoặc kích hoạt | Không | Nền màu nhấn hoặc gradient tiết chế | Không thay đổi |
| Ô nhập liệu, ô tìm kiếm | Bóng đổ trường dữ liệu cực nhẹ | Sử dụng màu bề mặt điều khiển | Thường không cần |
| Thao tác chính độc lập, viên nang độc lập, vỏ điều khiển phân đoạn | Bóng đổ điều khiển cực nhẹ | Sử dụng màu bề mặt điều khiển | Thường không cần |
| Thanh công cụ và điều khiển lớp trong suốt | Không | Sử dụng màu bề mặt điều khiển hoặc trong suốt | Thường không cần |
| Card hình ảnh trang marketing hoặc trang web được tạo | Do chủ đề quyết định | Cho phép | Sử dụng tiết chế |
Ánh xạ thành phần
<Card>mặc định sử dụnglayer="content": bóng đổ nhẹ cấp một dùng chung, không viền, bo tròn20pxmặc định; các biến thể muted, lồng nhau, danh sách và trong suốt giữ phẳng.<Card layer="shell">: trong trang chỉ chịu trách nhiệm nhóm, sử dụng bề mặt trong suốt hoặc gradient nhẹ và giữ phẳng; Shell không gian làm việc cố định được cung cấp phân tầng riêng bởi chế độ sở hữu.<Card shape="pill">: dùng cho card đơn hàng gọn, bo tròn hình viên nang elip.SidebarNavigation: Shell không gian làm việc độc lập, giữ lại gradient rõ ràng, độ trong suốt, làm mờ và bóng đổ nhẹ.PromptPanelcủa Studio khi làm container không gian làm việc: sử dụng--workspace-shell-shadow.DialogPanel, menu thả xuống, Popover, menu ngữ cảnh và trình duyệt khái niệm: sử dụng bóng đổ lớp phủ.- Canvas Builder, xem trước thiết bị, xem trước trang web được tạo, xem trước kéo thả và trạng thái thu phóng: vì đại diện cho mặt phẳng xem trước độc lập hoặc lớp tương tác tạm thời, có thể giữ bóng đổ chuyên dụng.
Không tạo card nội dung lơ lửng chồng lớp. Nếu thực sự cần nhóm bên ngoài, nó phải là Shell phẳng. Ngoài lớp phủ thực sự, cùng một chuỗi tổ tiên DOM chỉ xuất hiện tối đa một bóng đổ nội dung hoặc điều khiển thông thường.
Sử dụng biến thiết kế (Token)
Ưu tiên sử dụng Token dùng chung, không hard-code hiệu ứng:
- Bóng đổ card nội dung:
--card-shadow: var(--qk-shadow-surface) - Bóng đổ hover card nội dung:
--card-shadow-hover: var(--qk-shadow-surface-hover) - Bóng đổ trường dữ liệu:
--input-shadow: var(--qk-shadow-field) - Bóng đổ trường dữ liệu kích hoạt:
--input-state-shadow: var(--qk-shadow-field-active) - Bóng đổ điều khiển:
--qk-shadow-control/--qk-shadow-control-hover - Bóng đổ điều khiển thao tác chính:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - Làm mờ card nội dung:
--card-backdrop-filter: none - Bề mặt Shell:
--card-shell-surface - Làm mờ Shell:
--card-shell-backdrop-filter - Bóng đổ Shell không gian làm việc:
--workspace-shell-shadow - Bề mặt Dialog:
--dialog-surface, cung cấp gradient chủ đề tiết chế - Làm mờ Dialog:
--dialog-backdrop-filter - Bóng đổ lớp phủ Dialog:
--dialog-shadow - Bo tròn Dialog: tái sử dụng
--card-radius - Focus bàn phím:
--focus-ring - Bóng đổ lớp phủ: sử dụng Token lớp phủ Dialog, Dropdown, Menu hoặc cấp trang hiện có
Card nội dung thông thường và panel không gian làm việc không được sử dụng Token --shadow chung mạnh hơn.
Bóng đổ toàn cục áp dụng thang đo yên tĩnh "dịch chuyển ngắn, độ trong suốt thấp, tăng dần theo cấp đặt". Card, trường dữ liệu và điều khiển thông thường không được làm sâu hoặc phóng to bóng đổ dùng chung trong định tuyến; Popover và Dialog thể hiện sự tách khỏi trang qua dịch chuyển lớn hơn và phạm vi mờ, thay vì xếp chồng sương mù xám tối.
Quy tắc tương tác
Hover
- Card nội dung không được nâng lên cấp cao hơn
--qk-shadow-surface-hover. - Không nâng card nội dung qua
translateY. - Sử dụng thay đổi nền nhẹ hoặc phản hồi điều khiển rõ ràng.
- Không thay đổi hình dạng, tránh bo tròn không nhất quán hoặc bóng đổ bị cắt.
Được chọn và kích hoạt
- Sử dụng bề mặt màu nhấn, trạng thái biểu tượng, trạng thái ngữ nghĩa hoặc gradient tiết chế.
- Không chỉ thể hiện trạng thái qua bóng đổ.
Focus bàn phím
- Sử dụng quy tắc focus-visible dùng chung hoặc
--focus-ring. - Bóng đổ card chung không thể thay thế gợi ý focus.
- Phải rõ ràng dễ thấy trong cả chủ đề sáng và tối.
Kéo thả và thu phóng
- Chỉ cho phép sử dụng bóng đổ mạnh hơn khi lớp đang di chuyển hoặc thay đổi kích thước.
- Phải loại bỏ bóng đổ tạm thời sau khi tương tác kết thúc.
- Container tràn không được cắt hiệu ứng phản hồi của lớp di chuyển.
Trong suốt và làm mờ nền
Độ trong suốt dùng để thể hiện mối quan hệ thuộc về giữa bề mặt bên ngoài và không gian làm việc. Làm mờ nền chỉ có ý nghĩa khi thực sự có nội dung, màu sắc hoặc hình ảnh hiển thị phía sau bề mặt.
- Không sử dụng làm mờ trên nền màu đặc, nó chỉ tăng chi phí render, không thể hiện phân tầng.
- Dù đi qua nền nào phía sau, văn bản, biểu tượng và điều khiển phải dễ đọc rõ ràng.
- Khi trình duyệt không hỗ trợ làm mờ nền, phải có nền dự phòng không trong suốt hoặc dễ đọc.
- Cường độ mờ trong giao diện không gian làm việc dày đặc phải tiết chế.
- Phải xác minh cả chủ đề sáng và tối.
Ngoại lệ cho phép giữ bóng đổ
- Shell sidebar không gian làm việc
- Dialog, Popover, Dropdown, menu và panel modal
- Trình duyệt khái niệm và lớp phủ xác nhận của Studio
- Canvas Builder, khung thiết bị và mặt phẳng xem trước trang web được tạo
- Xem trước kéo thả, phản hồi thu phóng và công cụ lơ lửng tạm thời
- Nút thao tác chính có bóng đổ được định nghĩa trong Token nút dùng chung
- Yếu tố hình ảnh trang marketing và trang web được tạo được kiểm soát bởi chủ đề hiện tại
Những ngoại lệ này không được ảnh hưởng đến card nội dung thông thường qua bộ chọn rộng hoặc Token dùng chung.
Danh sách kiểm tra
- Card nội dung màu đặc độc lập và ô nhập liệu chỉ sử dụng vai trò bóng đổ nhẹ cấp một dùng chung.
- Thao tác chính độc lập, viên nang độc lập và vỏ điều khiển phân đoạn chỉ sử dụng bóng đổ điều khiển cực nhẹ dùng chung.
- Nhóm trong trang, hàng danh sách, card lồng nhau, nhóm trong suốt, Tab/Pill lặp lại, thanh công cụ và mục bên trong điều khiển phức hợp giữ phẳng.
- Tìm kiếm, lọc, sắp xếp, xem và thao tác chính nội tuyến trong thanh công cụ giữ phẳng; bóng đổ nhẹ của ô nhập liệu thông thường không được rò rỉ vào thanh công cụ, ngoại trừ vòng focus bàn phím.
- Khi Segmented nằm trong card, hộp thoại hoặc thanh công cụ đã có bóng đổ, vỏ và mục được chọn đều giữ phẳng; nhấp chuột không hiển thị vòng focus bàn phím.
- Ngoài lớp phủ thực sự, không xếp chồng nhiều bóng đổ thông thường trong cùng một chuỗi tổ tiên.
- Hover không làm card nội dung di chuyển theo chiều dọc.
- Đã loại bỏ card nội dung lồng nhau, hoặc xác định rõ bên ngoài là Shell.
- Chỉ Shell thực sự sử dụng
--workspace-shell-shadow. - Chỉ lớp phủ thực sự và lớp tương tác tạm thời sử dụng bóng đổ mạnh hơn.
- Có nội dung hiển thị phía sau làm mờ nền và có nền dự phòng dễ đọc.
- focus-visible sử dụng vòng focus.
- Cả chủ đề sáng và tối đều duy trì độ tương phản đủ.
- Bề mặt bo tròn không cắt phản hồi hover, focus, kéo thả hoặc lớp phủ.
- Chiều rộng desktop và mobile không xuất hiện tràn ngang mới.
- Kiểm tra
npm run ui:check-card-surfaces --workspace @qokit-ai/webđã qua.