DOL Design System - Shadow & Style Layers

Scope: Shadow tier mapping, variable/effect/paint style precedence + paint style inventory. For philosophy: see DIRECTION.md §3 Style layer precedence + §9 Shadow philosophy. For code (Tailwind classes): see ../ui-style-guide/CORE.md §7 Shadow & Depth.

1. Purpose

Tài liệu này cung cấp technical reference cho:

• Variable-first rule chi tiết (khi nào dùng variable, alias)
• Effect style (shadow tiers, colored shadow, focus ring, legacy ban)
• Paint style (inventory canonical, khi nào được dùng)
• Prompting rule cho AI builders

Triết lý precedence (Variable > Effect > Paint) và shadow direction → DIRECTION.md.

2. Variable-first rule

2.1 Luôn dùng variable cho:

• text hierarchy
• semantic surface/fill
• border và divider
• spacing, inset, page padding, section gap
• control height
• radius

2.2 Trong external AI builders

Nếu tool không hiểu full token graph:

• ưu tiên các alias --ds-* trong DOL_General_AI_Theme_Adapter.css
• chỉ dùng các role generic như --background, --primary, --radius-* khi tool bắt buộc cần app-theme convention

3. Effect style usage

3.1 Default elevation

Default shadow family cho UI thường là:

• shadow-neutral/to-bot/1
• shadow-neutral/to-bot/2
• shadow-neutral/to-bot/3
• shadow-neutral/to-bot/4
• shadow-neutral/to-bot/5

Mapping thực dụng:

Level	Style mặc định	Khi dùng
1	shadow-neutral/to-bot/1	card rất nhẹ, input group, surface tách lớp nhẹ
2	shadow-neutral/to-bot/2	dropdown nhỏ, popover nhẹ, sticky element nhẹ
3	shadow-neutral/to-bot/3	raised card chuẩn, panel được nhấn
4	shadow-neutral/to-bot/4	modal/sheet nổi rõ hơn bình thường
5	shadow-neutral/to-bot/5	hero floating, coachmark, premium emphasis

Code-facing Tailwind mapping:

Tailwind	Effect style
shadow-sm / shadow	shadow-neutral/to-bot/1
shadow-md	shadow-neutral/to-bot/2
shadow-lg	shadow-neutral/to-bot/3
shadow-xl	shadow-neutral/to-bot/4
shadow-2xl	shadow-neutral/to-bot/5

Tailwind mapping dùng literal shadow values để giữ shadow-brand-600/10, shadow-info-600/10, v.v. hoạt động. Không map trực tiếp shadow-* qua var(--shadow-neutral-*) trong Tailwind config.

3.2 Directional shadows

• to-top, to-left, to-right chỉ dùng khi có lý do về hướng bề mặt hoặc animation.
• Nếu không có lý do rõ, dùng to-bot.

3.3 Colored shadows

Colored shadow families như:

• shadow-brand
• shadow-info
• shadow-success
• shadow-warning
• shadow-danger
• shadow-special
• shadow-AI
• shadow-paper

chỉ nên dùng khi:

• cần accent có chủ đích theo brand/category
• surface đó thật sự mang tính campaign, special state, hoặc themed section

Không dùng colored shadows làm default elevation cho layout bình thường.

3.4 Focus ring

• Dùng Interactive/FocusRing cho treatment focus khi cần style đã canon.
• Không thay focus ring bằng colored shadow level 3/4/5.

3.5 Legacy ban

• Không dùng Shadow black (old) cho thiết kế mới.
• Chỉ giữ để backward compatibility hoặc đọc file cũ.

4. Paint style usage

4.1 Paint style được phép dùng khi:

• là decorative background đã canon hoá
• là reusable media/image slot
• là branded gradient có naming rõ
• component spec hoặc screen spec gọi đúng style name

Các family hiện tại gồm:

• Overlay
• Img lib
• ComponentBgColor
• AI
• Gradient Practice
• Ranking
• DOL PRO
• Social

4.2 Paint style không dùng cho:

• body text color
• heading text color
• semantic border
• input/background cơ bản
• state color cơ bản như success/warning/error/info

4.3 Rule an toàn

• Nếu AI chỉ cần “background nhẹ”, “surface phụ”, “panel nhấn”, hãy dùng semantic variables chứ không chọn gradient.
• Chỉ gọi paint style khi muốn đúng một branded treatment đã tồn tại, ví dụ DOL PRO/pro-gradient-linear-1 hoặc Ranking/Top 1.

5. Prompting rule cho AI

Khi prompt AI builder:

• mô tả semantic token trước: text, surface, border, radius, spacing
• mô tả effect style sau nếu cần độ nổi
• chỉ nhắc paint style nếu cần đúng branded/decorative treatment

Ví dụ tốt:

• “Use text-color/neutral-primary, roomy spacing, shadow-neutral/to-bot/2, radius soft-large.”
• “Use DOL PRO gradient treatment only for the premium hero card, keep the rest semantic-first.”

Ví dụ không tốt:

• “Use any nice gradient for cards.”
• “Use shadow to separate everything.”

6. Checklist trước handoff

• UI này đã dùng semantic variable làm mặc định chưa?
• Shadow đang là shadow-neutral hay đang lạm dụng colored shadow?
• Paint style có phải là decorative asset thật sự cần thiết không?
• Có đang dùng legacy Shadow black (old) không?
• Nếu export sang AI builder, adapter có đủ alias cho phần core chưa?

Navigation

• Hub: README.md
• Direction & philosophy: DIRECTION.md
• Related topic files: color.md
• Code reference: ../ui-style-guide/CORE.md §7 Shadow & Depth (Tailwind scale remapped to DOL neutral tone)