Toss Payments (토스페이먼츠)

흰 문서 옆에 붙은 짙은 남색 코드 패널과 그 아래 실제로 움직이는 결제위젯 미리보기 — 읽고, 복사하고, 바로 돌려 보는 결제 연동 문서

한국개발 도구핀테크차가운modern-minimal고딕comfortablesoftflat라이트한글 지원출시 2020개정 2025

갤러리에서 열기 — 적용 예시 · 가이드 다운로드

Brand DNA

브랜드 DNA

브랜드명: 토스페이먼츠 (Toss Payments) — 이 문서가 다루는 제품은 개발자센터(docs.tosspayments.com · developers.tosspayments.com), 그 안의 샌드박스, 그리고 상점 주문서에 들어가는 결제위젯(현 「주문서형」) 이다. 토스 앱(송금·자산 화면)은 별도 문서 toss.md 에 있다.
한 줄 정체성: 비바리퍼블리카(토스)가 2020년 8월 LG유플러스 PG 부문을 인수해 출범시킨 전자결제대행사(PG). 홈페이지 문구는 「쉽고 빠른 PG 연동」, 「고객이 원했던 온라인 결제의 모든 것. 연동부터 운영까지 고민 끝!」.
공식 디자인 철학 (확인된 문구 기준):
- 개발자센터 첫 화면 — 「AI로 물 흐르듯 완성되는 코드」, 「처음이어도 괜찮아요. 결제연동 전문 개발자 수준의 AI가 대신 코딩해 드릴게요.」
- 같은 페이지 — 「개발자의 시간을 아껴드려요」: 코드 한 줄로 연동되는 결제 · 노코드 결제수단 운영 · 코드 수정 없이 디자인 커스텀. 「언어별 코드 예제를 복사, 붙여넣기만 하면 연동 끝!」
- 샌드박스 도입기(2023-11-29, DX 팀) — 「개발자의 결제 연동 과정을 개선하는 첫 번째 시도로 테스트 연동을 간소화할 샌드박스를 만들었어요」. 문서보다 먼저 돌려 보는 경험을 택했다.
- SDK v2 — 모든 결제 서비스를 하나의 SDK 로 통합, 파라미터 타입·동작 범위를 통일.
토스 공통 요소와의 관계: 색·버튼·입력창·포커스 링은 토스 공통 디자인 시스템 TDS 를 그대로 쓴다(마크업 속성 data-tds-desktop-button-*, 토큰 --color-base-blue-600:#3182f6 등 실측). 글꼴도 토스 공통 Toss Product Sans. 토스페이먼츠만의 것은 짙은 남색 코드 패널, 파일 탭 알약, 단계 번호가 붙은 연동 가이드, 문서용 테스트 키 표시, 결제위젯 미리보기, 어두운 샌드박스 작업대 다.
시그니처 요소 1개: 흰 문서 오른쪽에 붙은 남색(#122440) 코드 패널 — 위에는 checkout.html · success.html · fail.html · server.js 파일 탭(선택된 것만 연회색 알약), 아래에는 같은 코드로 렌더링된 결제위젯 Preview 가 붙어 「읽기 → 복사 → 실행」이 한 화면에서 끝난다.

Tone & Mood

톤 & 무드

핵심 키워드 3개: 친절, 명료, 실행
무드 설명: 문장은 토스 특유의 「~해요」체로 짧고 부드럽다(「연동은 네 단계로 진행돼요」). 화면은 흰 바탕·회색 글자·파랑 하나로 절제되어 있고, 시선이 머무는 곳은 오른쪽의 짙은 남색 코드 패널뿐이다. FAQ 는 본문 사이에 접이식으로 끼워 「결제 UI가 렌더링되지 않아요」 같은 실패 상황을 먼저 짚어 준다.
비주얼 스타일: 모던 미니멀 — 평면 면, 1px 구분선, 옅은 회색 알약 선택 상태
밀도(Density): Comfortable — 문서 본문 17px·줄간격 1.6 안팎, 좌측 내비 항목 높이 35px 정도로 여유 있게. 코드 패널만 촘촘하다
모서리 성향: Soft (4~8px) — 버튼·입력·인라인 코드 6px, 내비 선택 항목 8px. 코드 패널·API 요약 카드만 16px(추정), 파일 탭·Preview 토글은 알약(100px)
평면성: Flat — 그림자 대신 면 색 차이(#FFFFFF / #F2F4F6 / #122440)로 영역을 나눈다. 포커스는 TDS 이중 링(inset 1.5px + 바깥 2px)

Color System

컬러 시스템 (CSS 변수)

실측 출처: 개발자센터 문서 페이지 인라인 CSS(emotion, TDS Desktop 컴포넌트)와 www.tosspayments.com 의 TDS 토큰 CSS(--color-base-*, --color-semantic-*), 헤드리스 크롬 스크린샷 픽셀 샘플. 코드 패널 색은 스크린샷 실측.

:root {
  /* Primary — TDS blue (www.tosspayments.com --color-base-blue-*) */
  --color-primary-50:  #F2F8FF;  /* blue-50 — 선택 행·포커스 링 안쪽 */
  --color-primary-100: #EBF4FF;  /* blue-100 */
  --color-primary-200: #DCECFE;  /* blue-200 */
  --color-primary-300: #BFDBFD;  /* blue-300 */
  --color-primary-400: #93C0FC;  /* blue-400 */
  --color-primary-500: #3182F6;  /* 기준색 — 문서 링크·인라인 링크 코드·주요 버튼·결제하기 (docs 최다 사용 유채색, TDS blue-600) */
  --color-primary-600: #2272EB;  /* blue-700 — hover */
  --color-primary-700: #1B64DA;  /* 링크 hover (docs 실측) */
  --color-primary-800: #1B59C5;  /* blue-800 */
  --color-primary-900: #1C4989;  /* blue-900 */

  /* Secondary — 토스페이먼츠 로고 파랑 */
  --color-secondary-500: #0064FF; /* logo-payments-blue.svg 채움. 로고 전용, UI 에는 쓰지 않는다 */

  /* 토스페이먼츠 고유 — 코드 패널 (스크린샷 실측) */
  --code-bg:       #122440;  /* 문서 우측 코드 패널 */
  --code-divider:  #23354E;  /* 파일 탭 줄·Preview 경계 */
  --code-tab-idle: #6C7989;  /* 선택 안 된 파일 탭 */
  --code-text:     #EEFFFF;  /* 기본 글자 */
  --code-tag:      #F07178;  /* 태그 이름 */
  --code-attr:     #C792EA;  /* 속성 */
  --code-string:   #FFB74D;  /* 문자열 */
  --code-punct:    #89DDFF;  /* < > = 기호 */
  --code-comment:  #546E7A;  /* 주석 (기울임) */
  --code-fn:       #4593FC;  /* 함수 호출 */
  /* 샌드박스 작업대 (스크린샷 실측) */
  --sandbox-bg:    #0A0F10;
  --sandbox-panel: #161B1C;
  --sandbox-line:  #222728;  /* 현재 줄 강조 */

  /* Neutral — 문서 본문에 쓰이는 TDS grey (docs 인라인 CSS 실측값) */
  --color-neutral-0:    #FFFFFF;
  --color-neutral-50:   #F9FAFB;  /* 테스트 키 상자 (추정 용법) */
  --color-neutral-100:  #F2F4F6;  /* 파일 탭 선택 알약·구분선·옅은 면 */
  --color-neutral-200:  #E5E8EB;  /* 입력 테두리·검색창 */
  --color-neutral-300:  #D1D6DB;
  --color-neutral-400:  #B0B8C1;  /* placeholder */
  --color-neutral-500:  #8B95A1;  /* 캡션·breadcrumb */
  --color-neutral-600:  #6B7684;
  --color-neutral-700:  #4E5968;  /* 본문 보조·내비 글자 */
  --color-neutral-800:  #333D4B;  /* 문서 제목·본문 강조 */
  --color-neutral-900:  #191F28;  /* 결제위젯 제목 */
  --color-neutral-1000: #000000;

  /* Semantic — TDS (www 토큰) */
  --color-success-bg: #F0FAF5;   /* green-50 */
  --color-success-fg: #009467;   /* green-700 */
  --color-warning-bg: #FEF3D4;   /* 「테스트 환경이에요」 배너 (샌드박스 실측) */
  --color-warning-fg: #C95C00;   /* yellow-700 */
  --color-error-bg:   #FFEEEE;   /* docs 위험 버튼 링 */
  --color-error-fg:   #F04452;   /* docs 위험 색 */
  --color-info-bg:    #F2F8FF;
  --color-info-fg:    #1B64DA;

  /* Surface */
  --bg-base:     #FFFFFF;             /* 문서 */
  --bg-subtle:   #F2F4F6;             /* 좌측 내비 구분선·API 요약 카드 */
  --bg-elevated: #FFFFFF;             /* 결제위젯 카드 */
  --bg-overlay:  rgba(0,0,0,0.2);     /* --color-semantic-background-dim */

  /* Text */
  --text-primary:    #333D4B;
  --text-secondary:  #4E5968;
  --text-tertiary:   #8B95A1;
  --text-on-primary: #FFFFFF;
  --text-disabled:   #B0B8C1;

  /* Border */
  --border-default: #E5E8EB;
  --border-subtle:  #F2F4F6;
  --border-strong:  #333D4B;          /* 결제위젯에서 선택된 결제수단 테두리 (샌드박스 실측) */
  --border-focus:   #3182F6;          /* TDS 포커스 링 안쪽 */

  /* 인라인 코드 */
  --inline-code-bg: rgba(2,32,71,0.05); /* docs 실측 */
}

### ③.1 사용 컨텍스트 주석

파랑 두 개: 로고는 #0064FF(토스 브랜드 블루), 화면의 버튼·링크는 TDS #3182F6. 토스 앱 문서(toss.md)는 #0064FF 를 대표색으로 적었지만, 개발자센터에서 실제로 칠해지는 파랑은 #3182F6 이라 이 문서는 그 값을 대표색으로 쓴다.
코드 하이라이트는 Material Theme 계열 팔레트(태그 #F07178·속성 #C792EA·기호 #89DDFF·주석 #546E7A)를 남색 바탕에 얹은 것이다. 문자열만 주황(#FFB74D)이다.
다크 모드: 문서 페이지에는 테마 토글이 없다. www.tosspayments.com 은 <html data-tds-color-scheme="light"> 로 라이트를 고정하고, TDS CSS 에 들어 있는 prefers-color-scheme: dark 토큰(#17171C 바탕)은 이 속성 때문에 적용되지 않는다. 샌드박스·개발자센터 첫 화면이 어두운 것은 페이지 고유의 장면 연출이지 사용자가 고르는 다크 테마가 아니다. 그래서 theme_modes 는 light 하나.

Typography

타이포그래피

폰트 페어링:
- 한글: Toss Product Sans (토스 전용 서체, 비공개 — static.toss.im/tps/main-swap.css 로 배포). 폴백은 -apple-system, BlinkMacSystemFont, 'Bazier Square', 'Noto Sans KR', 'Segoe UI', Apple SD Gothic Neo (실측 font-family 그대로)
- 영문: Toss Product Sans (동일)
- 코드: Menlo, Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace (실측)
- 이모지: Tossface (토스 이모지 서체, tossface.css)
위계 (docs 실측 px + 줄간격·자간은 추정):
- Display (개발자센터 첫 화면 「AI로 물 흐르듯 완성되는 코드」): 48px / 700 / 1.3 / -0.02em (추정)
- H1 (문서 제목 「주문서형 결제 연동하기」): 40px / 700 / 1.35 / -0.02em (추정)
- H2 (「결제」 같은 절 제목): 32px / 700 / 1.4 / -0.01em
- H3 (「Payment 객체」): 24px / 700 / 1.45 / 0
- Body Large (문서 본문): 17px / 400 / 1.6 / 0 (--pc-font-size-17)
- Body (내비·표): 15px / 400 / 1.6 / 0
- Body Small (버튼·탭): 14px / 500 / 1.5 / 0
- Caption (breadcrumb·배지): 12px / 500 / 1.4 / 0
- Code (코드 패널): 13px / 400 / 1.6 (추정), 인라인 코드는 본문의 85%

Spacing

스페이싱

Base unit: 4px (컴포넌트 높이 토큰 --pc-component-height-16/20/24/32/40/48/56 이 4의 배수)
토큰: ``css --space-xs: 4px; --space-sm: 8px; --space-md: 16px; --space-lg: 24px; --space-xl: 32px; --space-2xl: 48px; --space-3xl: 64px; ``
Container: 3단 — 좌측 내비 228px(고정, 1px 구분선) · 문서 본문 최대 약 525px · 우측 코드 패널 약 525px(가이드) 또는 목차 250px(API 레퍼런스). 헤더 높이 60px, 좌우 패딩 40px (스크린샷 실측, 추정)

Border Radius

--radius-none: 0;
--radius-sm: 4px;     /* 인라인 코드, 결제위젯 결제수단 버튼 (추정) */
--radius-md: 6px;     /* 버튼·입력·검색창 — docs 최다 사용값 */
--radius-lg: 8px;     /* 좌측 내비 선택 항목, 드롭다운 */
--radius-xl: 16px;    /* 코드 패널·API 요약 카드 (추정) */
--radius-full: 9999px;/* 파일 탭 알약·Preview 토글·「AI로 시작하기」 버튼 (실측 100px) */

Shadow / Elevation

--shadow-none: none;                                              /* 문서·카드 기본 — 면 색으로 구분 */
--shadow-sm: 0 1px 2px rgba(0,23,51,0.02);                        /* 내비 항목 hover (docs 실측 rgba 조합, 추정) */
--shadow-md: 0 2px 8px rgba(0,27,55,0.1);                         /* 드롭다운·언어 선택 메뉴 (추정) */
--shadow-lg: 0 8px 24px rgba(2,32,71,0.12);                       /* 샌드박스 단계 안내 말풍선 (추정) */
--shadow-xl: 0 16px 40px rgba(0,12,30,0.24);                      /* 모달 (추정) */
--focus-ring: inset 0 0 0 1.5px #3182F6, 0 0 0 2px #E8F3FF;       /* TDS 포커스 링 — 실측 */

Iconography

스타일: Filled 위주 + 일부 Outline — 파일 탭 앞 작은 문서 아이콘, 체크박스, 「AI에게 질문」 로봇 아이콘은 채움. 검색·꺾쇠는 선
Stroke 굵기: 약 1.8~2px (추정)
모서리 처리: Round
추천 라이브러리: 공식은 토스 자체 아이콘(static.toss.im/icons) + Tossface. 대체재로는 Lucide(선)·Phosphor Fill(채움)

Component Guide

컴포넌트 가이드 (상태별 CSS)

Button (TDS Desktop Button 실측 링 규칙)

.tp-btn { height: 40px; padding: 0 16px; border-radius: var(--radius-md); font: 600 15px/1 'Toss Product Sans', sans-serif; border: 0; transition: background .15s ease, box-shadow .15s ease; }
.tp-btn--primary { background: var(--color-primary-500); color: #fff; }
.tp-btn--primary:hover { background: var(--color-primary-600); }
.tp-btn--primary:active { background: var(--color-primary-700); }
.tp-btn--primary:focus-visible { box-shadow: inset 0 0 0 1.5px #E8F3FF, 0 0 0 2px #3182F6; }
.tp-btn--primary:disabled { background: var(--color-primary-200); cursor: not-allowed; }
.tp-btn--primary[aria-busy="true"] { color: transparent; background-image: radial-gradient(circle, #fff 1.5px, transparent 2px); background-size: 8px 8px; background-position: center; background-repeat: repeat-x; }
.tp-btn--secondary { background: var(--color-neutral-100); color: var(--text-primary); }      /* 「AI에게 질문」·「Markdown으로 복사」 */
.tp-btn--secondary:hover { background: var(--color-neutral-200); }
.tp-btn--ghost { background: transparent; color: var(--text-secondary); }
.tp-btn--ghost:hover { background: rgba(2,32,71,0.05); }
.tp-btn--danger { background: var(--color-error-fg); color: #fff; }
.tp-btn--danger:focus-visible { box-shadow: inset 0 0 0 1.5px #FFEEEE, 0 0 0 2px #F04452; }

Input (검색창 「검색 Ctrl + K」)

.tp-input { height: 32px; padding: 0 12px; border: 1px solid var(--border-default); border-radius: var(--radius-md); font-size: 14px; color: var(--text-primary); background: #fff; }
.tp-input::placeholder { color: var(--text-disabled); }
.tp-input:focus { outline: 0; box-shadow: inset 0 0 0 1.5px #3182F6, 0 0 0 2px rgba(26,122,249,.14); border-color: transparent; }
.tp-input[aria-invalid="true"] { box-shadow: inset 0 0 0 1.5px #F04452, 0 0 0 2px rgba(237,40,49,.13); }
.tp-input:disabled { background: var(--color-neutral-50); color: var(--text-disabled); }

Card

.tp-card { background: var(--bg-subtle); border-radius: var(--radius-xl); padding: 20px; }           /* API 레퍼런스 「API 키·보안」 요약 카드 */
.tp-card--code { background: var(--code-bg); border-radius: var(--radius-xl); color: var(--code-text); } /* 강조형 = 코드 패널 */
.tp-card--outlined { background: #fff; border: 1px solid var(--border-default); border-radius: var(--radius-lg); }
.tp-callout-warning { background: #fff; border: 1.5px solid #FFD158; border-radius: var(--radius-lg); }  /* 「API 버전 정책」 안내 상자 (추정 색) */

Badge / Tag

.tp-badge { display: inline-flex; align-items: center; height: 20px; padding: 0 6px; border-radius: var(--radius-sm); font: 600 11px/1 sans-serif; }
.tp-badge--solid { background: var(--color-primary-500); color: #fff; }     /* 결제위젯 「3% 즉시 할인」 */
.tp-badge--subtle { background: #D6E3F7; color: #3073DD; }                  /* 내비 「표준」 (실측) */
.tp-badge--outline { border: 1px solid var(--border-default); color: var(--text-secondary); }
.tp-file-tab { height: 26px; padding: 0 10px; border-radius: 9999px; font-size: 12px; color: var(--code-tab-idle); }
.tp-file-tab[aria-selected="true"] { background: var(--color-neutral-100); color: var(--text-primary); font-weight: 600; }

Navigation (좌측 문서 내비)

.tp-sidenav { width: 228px; border-right: 1px solid var(--color-neutral-100); padding: 16px 10px; }
.tp-sidenav__item { display: flex; align-items: center; height: 35px; padding: 0 12px; border-radius: var(--radius-lg); font-size: 14px; color: var(--text-secondary); }
.tp-sidenav__item:hover { background: rgba(2,32,71,0.05); }
.tp-sidenav__item[aria-current="page"] { background: #F5F6F7; color: var(--text-primary); font-weight: 600; }
.tp-sidenav__group { margin-top: 20px; font-size: 13px; color: var(--text-tertiary); }
.tp-gnb__tab[aria-current="page"] { color: var(--color-primary-500); font-weight: 600; } /* 상단 「가이드」 활성 */

Motion

--duration-fast: 150ms;   /* TDS 버튼 transition-duration .15s (실측) */
--duration-base: 200ms;   /* 배경·색·box-shadow .2s (www 실측) */
--duration-slow: 300ms;   /* 내비 펼침 (추정) */
--ease-out: cubic-bezier(0.25, 0.1, 0.25, 1); /* ease (실측) */
--ease-in-out: cubic-bezier(0.42, 0, 0.58, 1);

Anti-patterns

1. 로고 파랑(#0064FF)을 버튼·링크에 쓰지 않는다 — UI 파랑은 TDS #3182F6 하나. 2. 코드 패널을 흰 바탕·회색 테두리로 만들지 않는다 — 문서와 코드는 흰 면 / 남색 면으로 확실히 갈라야 한다. 3. 실제처럼 보이는 API 키를 예시에 노출하지 않는다 — 문서용 테스트 키·test_ 접두사로 테스트 환경임을 드러낸다. 4. 딱딱한 명령조(「~하십시오」)를 쓰지 않는다 — 「~해요」체로 짧게, 실패 상황은 FAQ 로 먼저 짚는다. 5. 카드마다 그림자를 겹치지 않는다 — 평면 면 색과 1px 구분선으로만 위계를 만든다.

Brand DNA

브랜드 DNA

Tone & Mood

톤 & 무드

Color System

컬러 시스템 (CSS 변수)

Typography

타이포그래피

Spacing

스페이싱

Border Radius

Border Radius

Shadow / Elevation

Shadow / Elevation

Iconography

Iconography

Component Guide

컴포넌트 가이드 (상태별 CSS)

Motion

Motion

Anti-patterns

Anti-patterns

Sources

출처