Chuyển tới nội dung chính
ZZalo Platforms
Design System

Zalo Platforms Design System

Nguồn sự thật cho color tokens, typography, spacing, components và patterns. Dùng để build và maintain toàn bộ portal — hỗ trợ light / dark mode.

Design TokensShadcn Components

Colors

Tất cả color tokens — mỗi swatch tự động đổi màu theo light / dark mode. Hex ☀ = light, ☾ = dark.

Surface

Page

portal-page

☀ #ffffff

☾ #22272e

Surface

portal-surface

☀ #ffffff

☾ #2d333b

Surface Muted

portal-surface-muted

☀ #f9fafb

☾ #373e47

Surface Subtle Strong

portal-surface-subtle-strong

☀ #eef2f6

☾ #444c56

Surface Soft

portal-surface-soft

☀ #e5f0ff

☾ rgba(90,156,255,.16)

Surface Hover

portal-surface-hover

☀ #f9fafb

☾ #373e47

Surface Stone

portal-surface-stone

☀ #ebede8

☾ #373e47

Surface Stone Hover

portal-surface-stone-hover

☀ #e0e2dd

☾ #444c56

Border

Border

portal-border

☀ #e5e7eb

☾ #444c56

Border Soft

portal-border-soft

☀ #e5e7eb

☾ #373e47

Border Strong

portal-border-strong

☀ #d1d5db

☾ #545d68

Border Light

portal-border-light

☀ #f3f4f6

☾ #373e47

Text & Heading

Text

portal-text

☀ #071831

☾ #adbac7

Text Strong

portal-text-strong

☀ #111827

☾ #cdd9e5

Text Medium

portal-text-medium

☀ #374151

☾ #adbac7

Text Muted

portal-text-muted

☀ #4b5563

☾ #909dab

Text Secondary

portal-text-secondary

☀ #6b7280

☾ #768390

Text Subtle

portal-text-subtle

☀ #9ca3af

☾ #636e7b

Text Placeholder

portal-text-placeholder

☀ #9ca3af

☾ #768390

Heading

portal-heading

☀ #071831

☾ #cdd9e5

Heading Soft

portal-heading-soft

☀ #001d48

☾ #dbe6f2

Brand

Brand

portal-brand

☀ #0068ff

☾ #0068ff

Brand Hover

portal-brand-hover

☀ #0058d8

☾ #2b82ff

Brand Strong

portal-brand-strong

☀ #001d48

☾ #8bb8ff

Brand Surface

portal-brand-surface

☀ #002d70

☾ #002d70

Brand Surface Light

portal-brand-surface-light

☀ #ebf3ff

☾ rgba(90,156,255,.18)

Brand Surface Lighter

portal-brand-surface-lighter

☀ #0068ff14

☾ rgba(90,156,255,.12)

Brand Border Soft

portal-brand-border-soft

☀ #bccceb

☾ #335f9f

ZBS Brand

portal-zbs-brand

☀ #004838

☾ #004838

ZBS Brand Hover

portal-zbs-brand-hover

☀ #00765c

☾ #00765c

ZT Brand

portal-zt-brand

☀ #073127

☾ #073127

ZT Accent

portal-zt-accent

☀ #e2fb6c

☾ #e2fb6c

Feature Colors

Feature Blue Surface

☀ #dbeafe

☾ rgba(90,156,255,.16)

Feature Blue Icon

☀ #2563eb

☾ #8bb8ff

Feature Green Surface

☀ #dcfce7

☾ rgba(126,226,195,.14)

Feature Green Icon

☀ #16a34a

☾ #7ee2c3

Feature Purple Surface

☀ #f3e8ff

☾ rgba(210,168,255,.14)

Feature Purple Icon

☀ #9333ea

☾ #d2a8ff

Feature Amber Surface

☀ #fef9c3

☾ rgba(242,204,96,.15)

Feature Amber Icon

☀ #d97706

☾ #f2cc60

Feature Red Surface

☀ #fee2e2

☾ rgba(244,112,103,.14)

Feature Red Icon

☀ #ef4444

☾ #f47067

Feature Indigo Surface

☀ #e0e7ff

☾ rgba(139,184,255,.14)

Feature Indigo Icon

☀ #4f46e5

☾ #a8c7ff

Feature Teal Surface

☀ #ccfbf1

☾ rgba(126,226,195,.16)

Semantic (Warning, Success, Code)

Warning

portal-warning

☀ #9a6700

☾ #f2cc60

Warning Surface

portal-warning-surface

☀ #fff9db

☾ rgba(242,204,96,.14)

Warning Border

portal-warning-border

☀ #fde68a

☾ rgba(242,204,96,.42)

Success

portal-success

☀ #16915f

☾ #7ee2c3

Success Surface Light

portal-success-surface-light

☀ #eafaf2

☾ rgba(126,226,195,.14)

Success Accent

portal-success-accent

☀ #d6ff66

☾ #d6ff66

Code Surface

portal-code-surface

☀ #262626

☾ #1c2128

Code Text

portal-code-text

☀ #e5e7eb

☾ #cdd9e5

Sidebar

Sidebar BG

portal-sidebar-bg

☀ #ffffff

☾ #22272e

Section Label

portal-sidebar-section-label

☀ #9ca3af

☾ #768390

Item Text

portal-sidebar-item-text

☀ #4b5563

☾ #adbac7

Item Icon

portal-sidebar-item-icon

☀ #6b7280

☾ #909dab

Item Hover BG

portal-sidebar-item-hover-bg

☀ #f3f4f6

☾ #373e47

Item Active BG

portal-sidebar-item-active-bg

☀ #eef4ff

☾ rgba(90,156,255,.16)

Item Active Text

portal-sidebar-item-active-text

☀ #0068ff

☾ #8bb8ff

Typography

Type scale và font tokens. Tất cả text dùng portal-color-text variables → tự động đổi màu.

Display3.75rem / 1.05 lh / bold
Zalo
H12rem / 1.1 lh / bold
Introduction
H21.25rem / 1.1 lh / bold
Architecture Overview
H31rem / 1.3 lh / semibold
Quick Start
H41rem / 1.4 lh / semibold
Prerequisites
Body LG1.125rem / 1.75 lh / normal
Build lightweight apps inside Zalo, reaching 70M+ users.
Body1rem / 1.75 lh / normal
Access Zalo features with seamless integration.
Body SM0.875rem / 1.6 lh / normal
Last updated: Jan 15, 2024 · 12.5k views
Caption0.75rem / 1.4 lh / medium
GETTING STARTED
Font Families

Sans-serif

--ifm-font-family-base

Roboto

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z · 0 1 2 3 4 5 6 7 8 9

"Roboto", "Segoe UI", "Helvetica Neue", "Arial", ui-sans-serif, system-ui, sans-serif

Monospace

--ifm-font-family-monospace

Fira Code

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z · 0 1 2 3 4 5 6 7 8 9

constfunction=>asyncawaitzmp.showToast()0x1A2B3C

"Fira Code", "SFMono-Regular", "SF Mono", ui-monospace, monospace

Font Weights
Aa Bb CcRegular · 400
Aa Bb CcMedium · 500
Aa Bb CcSemibold · 600
Aa Bb CcBold · 700

Spacing

4px base scale — dùng class `p-portal-N` hoặc `gap-portal-N`.

portal-1--portal-space-14px
portal-2--portal-space-28px
portal-3--portal-space-312px
portal-4--portal-space-416px
portal-5--portal-space-520px
portal-6--portal-space-624px
portal-7--portal-space-728px
portal-8--portal-space-832px
portal-9--portal-space-940px
portal-10--portal-space-1048px
portal-11--portal-space-1164px
portal-12--portal-space-1280px

Border Radius

Radius scale theo context của surface.

portal-sm

8px · --portal-radius-sm

portal-md

12px · --portal-radius-md

portal-lg

16px · --portal-radius-lg

portal-chip

10px · --portal-radius-chip

portal-input

12px · --portal-radius-input

portal-card

16px · --portal-radius-card

portal-panel

28px · --portal-radius-panel

portal-pill

9999px · --portal-radius-pill

Shadows

Box shadow tokens — tự điều chỉnh opacity theo dark mode.

portal-card
portal-card-hover
portal-panel
portal-hero
portal-button
portal-button-brand
portal-header
portal-footer

Buttons

PortalButton — variants, sizes, with icons, disabled.

Variants (size: md)

primary
brand
secondary
outline
ghost
successAccent

Sizes (variant: primary)

md
sm
xs

With Icons

Disabled

Badges

PortalBadge — tất cả variants và leading dot.

Variants

Herohero
Defaultdefault
Subtlesubtle
Successsuccess
Outlineoutline

With Leading Dot

DefaultSuccessSubtle

Icon Box

IconBox — tones và sizes.

Tones (size: md)

brand
brandSoft
brandStrong
success
muted
dark

Sizes (tone: brand)

sm
md
lg
xl

Icons

Custom SVG glyphs (portal-icons.tsx) + Tabler Icons. Hover để xem tên.

Design icons — custom SVG glyphs

overview
miniAppPlatform
zaloBusinessSolution
zaloBot
openApis
zTransfer
sdksAndLibraries
tutorials
faq
zbotBtnStart
aiSparkleSm
aiSparkleLg
facebookSolid
youtubeSolid
githubSolid
usersSolid
arrowRightSolid
activitySolid
alertTriangleSolid
appWindowSolid
badgeCheckSolid
blocksSolid
boltSolid
cableSolid
chevronRightSolid
databaseSolid
gaugeSolid
lightbulbSolid
listSolid
packageOpenSolid
paletteSolid
playCircleSolid
rocketSolid
shieldCheckSolid
shieldSolid
zapSolid

Utility icons — Tabler Icons

activity
alertTriangle
analytics
appWindow
arrowRight
arrowUp
badgeCheck
banknote
blocks
bolt
cable
check
chevronRight
code
copy
creditCard
database
facebook
github
landmark
list
megaphone
menu
message
monitor
moon
newspaper
packageOpen
playCircle
rocket
search
shieldCheck
sparkles
sun
users
utensilsCrossed
wallet
x
youtube
zap

Sidebar icons — Phosphor Icons (weight: fill)

CaretRight
ArrowSquareOut
ArrowBendDownRight
ArrowCounterClockwise
NavigationArrow
Path
DeviceMobile
Monitor
HardDrive
Keyboard
Vibrate
Scan
QrCode
Camera
VideoCamera
Folder
FileText
Database
Image
Gear
Wrench
Sliders
PencilLine
Terminal
Code
IdentificationCard
Fingerprint
Phone
Handshake
Certificate
LockKey
ShieldCheck
ChatsCircle
Megaphone
Bell
Package
Cube
PuzzlePiece
SquaresFour
Rows
List
Palette
CheckCircle
CheckSquare
Eye
Star
Lightning
CurrencyDollar
MapPin
WifiHigh
BookOpen
Rocket
ClockCounterClockwise

Patterns

Recurring UI patterns dùng trong docs và landing pages.

Callouts

Key Benefits
Instant access - no installation required
Seamless integration with Zalo features
Access to 70M+ Zalo users in Vietnam
Built-in authentication and payment
Important Note
Some APIs require explicit user permissions.
Always handle permission requests gracefully.
You're all set!
Your Official Account has been verified.
API credentials are ready to use.

Code Block (design system internal)

app.js
Page({
  data: { message: "Welcome to Mini App" },
  handleTap() {
    zmp.showToast({ message: "Button clicked" });
  },
});

QuickCodeBlock

Dark code block tái sử dụng — filename label + copy button. Import từ @/components/ui/quick-code-block

Terminal
npm install -g zmp-cli
app-config.json
{
  "app": {
    "appId": "YOUR_APP_ID",
    "appName": "My Mini App"
  }
}
auth.js
const token = await axios.post(
  "https://oauth.zaloapp.com/v4/access_token",
  { app_id: APP_ID, secret_key: SECRET_KEY, grant_type: "authorization_code" }
);

Product Card

Mini App Platform

Build lightweight apps that run inside Zalo.

View Docs

Surface Card Variants

portal-surface-card

Surface variant

--subtle

Surface variant

--brand

Surface variant

Markdown Typography (.markdown)

H1 — 2.25rem / bold

H2 — 1.5rem / bold

H3 — 1.25rem / semibold

H4 — 0.875rem / semibold

Body paragraph — 1rem / regular. Mini Apps are built using standard web technologies with Zalo's platform capabilities layered on top.

  • List item — 0.875rem / regular
  • Inline code — 0.875rem / mono

Animations

Motion tokens — định nghĩa duration, easing và keyframe cho từng loại animation trong portal. Click Replay để xem trực tiếp.

portal-fade450msease-in-out

Content Block

Dùng khi chuyển trang trong ECOSYSTEM sidebar. Content mới xuất hiện từ opacity 0 lên 1, tạo cảm giác chuyển trang mượt mà.

Duration

450ms

Easing

ease-in-out

Fill

backwards

Keyframes

opacity: 0 → 1

Usage
/* LandingLayout: <main data-ecosystem-page> */
el.animate(
  [{ opacity: "0" }, { opacity: "1" }],
  { duration: 350, easing: "ease-in-out", fill: "backwards" }
);

Nguyên tắc

  • • Dùng Web Animations API (el.animate()) để trigger động — không dùng CSS class toggle.
  • • Cancel animation đang chạy trước khi replay: el.getAnimations().forEach(a => a.cancel())
  • • fill: "backwards" giữ frame đầu tiên (opacity 0) trong giai đoạn delay, tránh flash.
  • • Respect prefers-reduced-motion cho accessibility khi cần.

Social Patterns

Các pattern UI đặc thù cho trang Social — Glass Card trên nền tối và Plugin Demo Card.

Glass Card (dark surface)

Dùng trên nền tối gradient. Backdrop blur + white/10 bg + white/20 border. Thấy trong section "Bạn Có Thể Xây Dựng Gì" ở trang Social.

Đăng Nhập Xã Hội

Xác thực một lần nhấp với tài khoản Zalo

Chia Sẻ Nội Dung

Chia sẻ trực tiếp lên bảng tin Zalo

Truy Cập Hồ Sơ

Lấy dữ liệu hồ sơ với quyền truy cập

<div class="rounded-[12px] border border-white/20 bg-white/10 p-4 backdrop-blur-sm">
  {/* content */}
</div>

Plugin Demo Card

Card 3 vùng: Header (icon + title + description + CTA button) → Demo area (light bg) → Code block (dark bg #111827). Dùng trong "Plugin Xã Hội".

Tên Plugin

Mô tả ngắn về chức năng của plugin này.

Demo Widget Preview
<div class="zalo-plugin"
     data-option="value">
</div>

SDK Card

Card đơn giản cho SDK — icon lớn (56×56) + title + description + version + link dọc theo layout. Dùng trong "Tích Hợp SDK".

JavaScript SDK

Mô tả ngắn về SDK này và các nền tảng được hỗ trợ.

v3.2.1Xem Tài Liệu

Android SDK

Mô tả ngắn về SDK này và các nền tảng được hỗ trợ.

v2.5.0Xem Tài Liệu

iOS SDK

Mô tả ngắn về SDK này và các nền tảng được hỗ trợ.

v2.4.3Xem Tài Liệu