Arco Design System — UI Implementation Guide

Arco Design is ByteDance's design system. Always apply these tokens and patterns when styling web interfaces to Arco spec.

---

Design Tokens (CSS Variables)

Paste into :root of every page:

:root {
  /* Background */
  --color-bg-1: #ffffff;
  --color-bg-2: #f7f8fa;
  --color-bg-3: #f2f3f5;

  /* Text */
  --color-text-1: rgb(29, 33, 41);      /* primary */
  --color-text-2: rgb(78, 89, 105);     /* secondary */
  --color-text-3: rgb(134, 144, 156);   /* placeholder / hint */
  --color-text-4: rgb(201, 205, 212);   /* disabled */

  /* Border */
  --color-border-1: rgb(242, 243, 245);
  --color-border-2: rgb(229, 230, 235); /* default border */
  --color-border-3: rgb(201, 205, 212); /* stronger border */

  /* Fill */
  --color-fill-1: rgb(247, 248, 250);
  --color-fill-2: rgb(242, 243, 245);
  --color-fill-3: rgb(229, 230, 235);

  /* Primary — Arco Blue */
  --primary-1: rgb(232, 237, 255);      /* light bg */
  --primary-6: rgb(22, 93, 255);        /* main */
  --primary-7: rgb(14, 76, 230);        /* hover */

  /* Functional */
  --success-1: rgb(232, 248, 232);
  --success-6: rgb(0, 180, 42);
  --warning-1: rgb(255, 247, 232);
  --warning-6: rgb(255, 125, 0);
  --danger-1:  rgb(255, 236, 232);
  --danger-6:  rgb(245, 63, 63);

  /* Border Radius */
  --border-radius-small:  2px;
  --border-radius-medium: 4px;
  --border-radius-large:  8px;

  /* Shadow */
  --shadow-1: 0 1px 4px rgba(0, 0, 0, .08);
  --shadow-2: 0 4px 10px rgba(0, 0, 0, .10);
  --shadow-3: 0 8px 20px rgba(0, 0, 0, .12);
}

---

Typography

• Font family: "PingFang SC", "Noto Sans SC", "Microsoft YaHei", sans-serif
• Base size: 14px, line-height 1.5715
• Page title (h1): 22–28px, weight 700
• Section title (h2): 16–18px, weight 600
• Label: 13px, weight 500, color var(--color-text-2)
• Body: 14px, weight 400, color var(--color-text-1)
• Caption / hint: 12px, color var(--color-text-3)

---

Layout

• Max width: 1400px, centered, margin: 0 auto
• Page background: var(--color-bg-2) (light gray) or #fff
• Section gap: 16px
• Card padding: 20px 24px
• Grid gap: 16px

---

Components

Card

.card {
  background: var(--color-bg-1);
  border: 1px solid var(--color-border-2);
  border-radius: var(--border-radius-large);
  box-shadow: var(--shadow-1);
  padding: 20px 24px;
}

• Section h2 inside card: add border-bottom: 1px solid var(--color-border-2); padding-bottom: 12px; margin-bottom: 16px

Button

button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  height: 32px;
  padding: 0 15px;
  border-radius: var(--border-radius-medium); /* 4px */
  font-size: 14px;
  font-family: inherit;
  cursor: pointer;
  transition: background .1s, border-color .1s;
}
/* Primary */
.btn-primary { background: var(--primary-6); border: 1px solid var(--primary-6); color: #fff; }
.btn-primary:hover { background: var(--primary-7); border-color: var(--primary-7); }
/* Outline / Default */
.btn-default { background: #fff; border: 1px solid var(--color-border-2); color: var(--color-text-2); }
.btn-default:hover { border-color: var(--primary-6); color: var(--primary-6); }
/* Danger */
.btn-danger { background: #fff; border: 1px solid var(--color-border-2); color: var(--danger-6); }
.btn-danger:hover { border-color: var(--danger-6); background: var(--danger-1); }

• No gradients, no large shadows on buttons
• Pill shape = border-radius: 999px; standard = 4px

Form Controls (Input / Select / Textarea)

input, select, textarea {
  border: 1px solid var(--color-border-2);
  border-radius: var(--border-radius-medium);
  padding: 7px 11px;
  font-size: 14px;
  color: var(--color-text-1);
  background: #fff;
  outline: none;
  transition: border-color .1s, box-shadow .1s;
}
input:hover, select:hover, textarea:hover { border-color: var(--color-border-3); }
input:focus, select:focus, textarea:focus {
  border-color: var(--primary-6);
  box-shadow: 0 0 0 2px rgba(22, 93, 255, .2);
}
/* Error state */
.error input, .error select { border-color: var(--danger-6); background: var(--danger-1); }
/* Custom select arrow */
select:not([multiple]) {
  appearance: none;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath fill='%2386909C' d='M6 8L1 3h10z'/%3E%3C/svg%3E");
  background-repeat: no-repeat;
  background-position: right 10px center;
  padding-right: 28px;
}

• Label: 13px, weight 500, var(--color-text-2), sits above input with 6px gap
• Required marker: label::after { content: " *"; color: var(--danger-6); }

Tag / Badge

.tag {
  display: inline-block;
  padding: 1px 8px;
  border-radius: var(--border-radius-small); /* 2px */
  border: 1px solid transparent;
  font-size: 12px;
  line-height: 1.5;
  white-space: nowrap;
}
.tag-blue    { color: var(--primary-6); border-color: var(--primary-6); background: var(--primary-1); }
.tag-green   { color: var(--success-6); border-color: var(--success-6); background: var(--success-1); }
.tag-orange  { color: var(--warning-6); border-color: var(--warning-6); background: var(--warning-1); }
.tag-red     { color: var(--danger-6);  border-color: var(--danger-6);  background: var(--danger-1);  }

Table

table { width: 100%; border-collapse: collapse; font-size: 13px; }
th, td { text-align: left; padding: 9px 12px; border-bottom: 1px solid var(--color-border-2); vertical-align: middle; }
th { font-size: 12px; font-weight: 500; color: var(--color-text-3); background: var(--color-fill-1); }
tr:last-child td { border-bottom: none; }

Chip / Toggle Button (multi-select)

.chip {
  border: 1px solid var(--color-border-2);
  border-radius: var(--border-radius-medium);
  padding: 0 12px;
  line-height: 28px;
  background: #fff;
  color: var(--color-text-2);
  font-size: 13px;
  cursor: pointer;
  transition: border-color .1s, color .1s, background .1s;
}
.chip:hover  { border-color: var(--primary-6); color: var(--primary-6); }
.chip.active { border-color: var(--primary-6); background: var(--primary-1); color: var(--primary-6); }

---

Key Rules

1. No decorative gradients on backgrounds — use flat fills
2. No large colored shadows — only subtle rgba(0,0,0,.08–.12) shadows
3. Border radius: cards/containers 8px; buttons/inputs 4px; tags 2px; pills 999px
4. Primary color is Arco Blue rgb(22, 93, 255) — not teal, not indigo
5. Text hierarchy: use the 4 text color variables, never arbitrary hex
6. Spacing unit: multiples of 4px (4, 8, 12, 16, 20, 24, 32)
7. Font size scale: 12 / 13 / 14 / 16 / 18 / 22 / 28px
8. Interactive states: hover changes border/color; focus adds box-shadow: 0 0 0 2px rgba(22,93,255,.2)