DOL Design System - Radius

Scope: Radius tokens → rule dùng thật, để designer/AI chọn radius theo kích thước element. For philosophy: see DIRECTION.md §8 Radius philosophy. For code (Tailwind classes): see ../ui-style-guide/CORE.md §5 Radius.

1. Purpose

Tài liệu này chuyển radius tokens thành rule dùng thật - chọn radius theo element size thay vì chỉ nhớ tên token.

Triết lý soft-large + anti-patterns → DIRECTION.md.

2. Hard rules

• Ưu tiên token semantic: control/*, surface/*, overlay/*, pill-shape
• Không pick trực tiếp Base Radius nếu không đang chỉnh scale hệ thống
• Control dùng family control/*
• Card / content container dùng family surface/*
• Modal / dropdown / popover / sheet dùng family overlay/*

3. Control radius by element height

Default mapping khuyến nghị:

Element height	Recommended radius	Token	Notes
20-24	4-8px	control/sm hoặc control/md	Tiny control chỉ bo nhẹ
28-32	8-10px	control/md hoặc control/md-sub	Compact control
36	12px	control/lg	Medium control
40	14px	control/lg-sub	Standard button / field compact
48	16px	control/xl	Primary button default
56	20px	control/2xl	Large button
64	24px	control/3xl	Hero button / large prominent control
80+	32px+	control/4xl hoặc control/5xl	Large content-like control block

Design intent:

• height 40 → radius 14
• height 48 → radius 16
• element càng lớn thì radius cũng tăng lên theo 20, 24, 32, 40

4. Default control mapping

Control type	Recommended token
Standard input / standard button	control/lg-sub hoặc control/xl tùy height
Primary button 48px	control/xl
Large CTA 56px	control/2xl
Hero CTA 64px	control/3xl
Checkbox / tiny utility	control/sm
Dense compact button	control/md hoặc control/md-sub

Rule of thumb:

• Nếu control là core action và có chiều cao 48px, mặc định dùng control/xl
• Nếu cùng một component family có nhiều sizes, radius phải tăng cùng height, không giữ nguyên một radius cho mọi size

5. Surface and overlay mapping

Surface

Surface type	Recommended token	Notes
Standard card	surface/md	Default an toàn
Feature card / elevated card	surface/lg hoặc surface/xl	Khi block lớn hơn và muốn cảm giác mềm hơn
Large section block	surface/2xl	Dùng cho container lớn
Showcase / hero surface	surface/3xl	Chỉ dùng khi block thực sự lớn

Overlay

Overlay type	Recommended token	Notes
Tooltip / small popup	overlay/sm
Dropdown / popover	overlay/md
Modal default	overlay/lg
Large modal / bottom sheet prominent	overlay/xl hoặc overlay/2xl

6. Pill usage

Dùng pill-shape cho:

• chip
• capsule tag
• status pill
• segmented item dạng capsule thật sự

Không dùng pill-shape cho:

• card
• modal
• input thường
• mọi button chỉ vì muốn “bo nhiều”

7. AI defaults

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

1. Button/Input 40px: control/lg-sub
2. Button/Input 48px: control/xl
3. Button/Input 56px: control/2xl
4. Card mặc định: surface/md
5. Modal mặc định: overlay/lg

8. Do and Dont

Do:

• Giữ radius tăng theo height.
• Dùng soft-large radius như visual default.
• Chọn family đúng theo loại element: control, surface, overlay.

Dont:

• Không dùng một radius cố định cho mọi button size.
• Không fallback về corner nhỏ kiểu 6-8px cho button 48px nếu không có constraint mật độ thật.
• Không dùng pill cho mọi thứ.

Navigation

• Hub: README.md
• Direction & philosophy: DIRECTION.md
• Related topic files: spacing.md
• Code reference: ../ui-style-guide/CORE.md §5 Radius (controls, surfaces, overlays với Tailwind classes)
• Cross-repo: Playground - docs/PLAYGROUND_UI_REUSE_GUIDE.md (component reuse patterns)