DOL Design System - Spacing

Scope: Roomy spacing defaults, grouping rules, and hierarchy guidance. For philosophy: see DIRECTION.md §7 Spacing philosophy. For code (Tailwind classes): see ../ui-style-guide/CORE.md §4 Spacing.

1. Purpose

Tài liệu này định nghĩa cách dùng spacing theo hướng rộng rãi nhưng có tổ chức, để hierarchy rõ hơn và giảm việc “nhồi UI”.

Mục tiêu:

• dùng khoảng trắng để phân tầng nội dung
• nhóm element liên quan theo proximity và similarity
• map quyết định spacing về semantic tokens thay vì px rời rạc

Triết lý generous spacing + atomic grouping + anti-patterns → DIRECTION.md.

2. Hard rules

• Dùng semantic layout token trước: spacing/*, inset/*, section/gap/*, page/padding/*, container/*
• Không hardcode px nếu token semantic đã có
• Ưu tiên tăng khoảng cách giữa nhóm khác nhau hơn là thêm line/divider. Ví dụ: CTA area trong card nên dùng padding-top đủ lớn thay vì border-top
• Một component family nên có spacing rhythm nhất quán giữa các instance cùng size

3. Spacing levels by hierarchy

Level A - Inside one atom or tight molecule

Dùng cho:

• icon + label
• label + value ngắn
• inline badge stack

Token khuyên dùng:

• spacing/space-2 đến spacing/space-3
• inset/inset-2 đến inset/inset-3

Level B - Related elements in one molecule

Dùng cho:

• label + input
• title + subtitle ngắn
• button group / action group

Token khuyên dùng:

• spacing/space-3 đến spacing/space-5
• inset/inset-3 đến inset/inset-4

Level C - Groups inside one organism or card

Dùng cho:

• header block + content block
• form section trong card
• content stack trong modal/card

Token khuyên dùng:

• spacing/space-5 đến spacing/space-8
• inset/inset-4 đến inset/inset-8

Level D - Between distinct sections

Dùng cho:

• block này sang block khác trên page
• hero -> benefits
• summary -> detail section

Token khuyên dùng:

• section/gap/gap-xs trở lên
• default page section nên bắt đầu từ gap-sm hoặc gap-md, không nên bắt đầu quá sít

4. Recommended defaults by use case

Use case	Recommended token range	Notes
Icon + text trong button	spacing/space-2 đến spacing/space-3	Không quá chật
Label + helper + field stack	spacing/space-2 đến spacing/space-4	Giữ gần vì cùng một field
Related actions trong toolbar / card footer	spacing/space-3 đến spacing/space-5	Một group rõ ràng
Nội dung stack trong card	spacing/space-4 đến spacing/space-6	Default roomy
Card padding mặc định	inset/inset-4 đến inset/inset-6	16-24px
Large card / modal padding	inset/inset-6 đến inset/inset-8	24-32px
Giữa card groups khác nhau	spacing/space-6 đến spacing/space-10	Tách rõ group
Giữa page sections	section/gap/gap-sm đến section/gap/gap-lg	Default cho page flow
Page padding mặc định	page/padding/standard	compact chỉ dùng khi thật sự dense

5. Page padding and section policy

Page padding

• Default page padding: page/padding/standard
• page/padding/compact chỉ dùng cho dense productivity surface hoặc mobile chật
• page/padding/large-case dùng cho landing, editorial, hoặc layout cần nhiều không khí

Section gaps

• Section gap không nên “sát” như spacing nội bộ card
• Mặc định page section nên dùng từ section/gap/gap-sm trở lên
• Hero, banner, hoặc block chuyển chương nên bắt đầu từ gap-md hoặc lớn hơn

6. Atomic design grouping rule

Áp dụng nhanh:

1. Atoms trong cùng một molecule: spacing nhỏ
2. Molecules trong cùng một organism: spacing trung bình
3. Organisms khác vai trò: spacing lớn
4. Section khác nhau trên page: section gap

Nếu hai item có cùng vai trò và cần được “đọc là một cụm”, hãy giảm spacing giữa chúng trước. Nếu hai block khác vai trò hoặc khác nhiệm vụ, hãy tăng spacing trước khi nghĩ tới divider.

7. AI defaults

Nếu AI thiếu context chi tiết, hãy dùng:

1. Button / inline icon gap: spacing/space-2
2. Card content stack: spacing/space-4
3. Standard card padding: inset/inset-4
4. Comfortable card/modal padding lớn hơn: inset/inset-6
5. Page padding: page/padding/standard
6. Major section gap: section/gap/gap-sm hoặc section/gap/gap-md

8. Wireframe spacing defaults

Wireframe dùng để thể hiện layout structure, nhưng vẫn phải tuân thủ hierarchy spacing:

Wireframe context	Minimum gap	Rationale
Giữa sections (WireSection ↔ WireSection)	space-y-10 (40px)	Level D - distinct sections
Bên trong WireSection (title ↔ content ↔ children)	space-y-4 (16px)	Level C - groups inside organism
Grid items (cards cùng hàng)	gap-4 (16px)	Level B - related elements
Grid rows (hàng cards khác nhau)	space-y-4 (16px)	Level B-C - related groups
Heading ↔ grid content bên dưới	mt-6 (24px)	Level C - heading to content block

Rule: wireframe spacing không được nhỏ hơn space-3 (12px) cho bất kỳ relationship nào. Nếu 2 blocks cùng xuất hiện mà không có label/divider phân cách, gap tối thiểu là space-4 (16px).

9. Do and Dont

Do:

• Dùng spacing để làm rõ hierarchy.
• Nhóm element cùng chức năng đủ gần để nhìn ra một cụm.
• Chọn token lớn hơn một chút khi phân vân giữa 2 option gần nhau, nếu layout chưa thật sự chật.
• Trong wireframe, tuân thủ spacing hierarchy tương tự UI - wireframe chật sẽ dẫn đến UI chật.

Dont:

• Không để mọi khoảng cách đều giống nhau.
• Không dùng spacing nhỏ cho cả page chỉ vì muốn “gọn”.
• Không thay divider cho hierarchy spacing khi vấn đề thực chất là group chưa rõ.
• Không dùng space-y-3 hoặc gap-3 làm default cho mọi context trong wireframe - phải map đúng hierarchy level.

Navigation

• Hub: README.md
• Direction & philosophy: DIRECTION.md
• Related topic files: radius.md
• Code reference: ../ui-style-guide/CORE.md §4 Spacing (hierarchy levels, common defaults table với Tailwind classes)