Style Guide
This guide defines Birdpaper UI’s style tokens—typography, size, radius, shadow, spacing, motion, and more—so components stay visually consistent. Every token is exposed as a CSS variable and works with theme customization and dark mode.
Typography
Font Family
font-family: Inter, -apple-system, BlinkMacSystemFont, PingFang SC,
Hiragino Sans GB, Noto Sans, Microsoft YaHei,
Helvetica Neue, Helvetica, Arial, sans-serif;Prefer the system font stack for the best rendering and load performance on each platform. Latin text prefers Inter; Chinese falls back to native platform fonts (PingFang SC / Noto Sans / Microsoft YaHei).
Font Size
The type scale has four levels, from helper text to page titles.
| Helper text | 12px | 1.4 | Notes, timestamps, tags |
| Body / form | 14px | 1.6 | Paragraphs, forms, table content |
| Subtitle | 16px | 1.5 | Card titles, section headings |
| Title | 20px | 1.4 | Page titles, modal titles |
Tip: Keep body text at 14px. Avoid mixing too many size levels on the same page.
Font Weight
| Regular | 400 | Body and descriptive text |
| Medium | 500 | Headings and emphasis |
| Semibold | 600 | Page titles and critical information |
Tip: Regular (400) is the default. Use Medium (500) for subtitles and emphasis, and Semibold (600) only for page-level titles and critical information—avoid overusing it.
Size
Components use a four-level size system that controls height, font size, horizontal padding, and radius. Form controls such as Button, Input, and Select all follow this scale.
| Mini | --bp-size-height-mini | 22px | 12px | 10px | 3px |
| Small | --bp-size-height-small | 28px | 13px | 14px | 4px |
| Default | --bp-size-height-default | 32px | 14px | 20px | 6px |
| Large | --bp-size-height-large | 36px | 14px | 26px | 8px |
Guideline: Use one size within a form region. Mini works well for compact table action columns; Large suits standalone primary actions.
Radius
Radius tokens track the size system so components of different sizes keep a consistent visual rhythm.
| Small | 3px | Mini-sized components |
| Default | 6px | Default-sized components |
| Large | 8px | Large components, cards, overlays |
| Full | 40px | Pill buttons, capsule tags |
Guideline: Use 8px for cards and overlays; use 40px for pill-shaped elements such as capsule tags. Don’t mix many radius values on the same page.
Shadow
A layered shadow scale expresses spatial elevation.
| Light | 0 2px 8px rgba(0, 0, 0, 0.06) | Card hover state |
| Default | 0 4px 12px rgba(0, 0, 0, 0.1) | Popovers, tooltips |
| Deep | 0 4px 16px rgba(0, 0, 0, 0.15) | Floating layers, dropdowns |
Guideline: Use light shadows for hover, default for popovers, and deep for floating layers. Shadow depth should track z-index—higher layers get deeper shadows.
Spacing
Spacing follows a 4px grid so gaps stay predictable and reusable.
| Tight | 4px | Gap between icon and text |
| Small | 8px | Inside form fields |
| Medium | 12px | List item spacing |
| Default | 16px | Section spacing |
| Large | 24px | Page region spacing |
Guideline: Prefer preset spacing tokens over ad-hoc values. Tight (4px) is only for adjacent elements such as icon and text; use Large (24px) between page regions.
Border
Shared border rules keep inputs, dividers, and state feedback visually consistent.
| Inputs, dividers | 1px solid var(--bp-gray-2) |
| Focus | 1px solid var(--bp-primary-6) |
| Error | 1px solid var(--bp-danger-6) |
| Disabled | 1px solid var(--bp-gray-3) |
Guideline: Use semantic CSS variables for border color so dark mode adapts automatically. Focus borders match the brand color; use the danger border only when form validation fails.
Layering (z-index)
Manage stacking with CSS variables instead of hard-coded values to avoid z-index conflicts.
| --z-index-base | 2000 | Trigger, Tooltip |
| --z-index-modal | 2000 | Modal dialogs |
| --z-index-drawer | 2001 | Drawer panels |
| --z-index-message | 2003 | Message toasts |
Guideline: If your app needs a custom layer, offset from
--z-index-base(for examplecalc(var(--z-index-base) + 10)) instead of using magic numbers.
Motion
Shared durations and easing curves keep interaction feedback feeling consistent.
| Color / opacity | 0.2s | ease |
| Open / close | 0.25s | ease-in-out |
| Layout change | 0.3s | ease |
| Loading spin | 1.2s | linear (infinite) |
Guideline: Use ease-in-out for open/close motions and ease for fade-outs. Keep transitions at or under 0.3s so the UI stays responsive.