타이포그래피

Figma Foundation · 02. Typography · 값은 coui_core 가 정본입니다. 정본 파일은 Figma 라이브러리.

이 페이지는 텍스트 역할을 고르고, 지금 테마의 스케일을 확인하는 곳입니다. 22개 역할은 coui_core 의 CoreTypography 가 정하고, Flutter / Web 이 같은 Text chain 으로 읽습니다.

픽셀 크기나 weight 를 직접 주지 마세요. 역할이 크기·무게·트래킹을 함께 가져갑니다. 토큰 축 전체는 디자인 토큰 을 보세요.

Display / Headline / Title 이 각각 Large · Medium · Small 로 9개, Body 가 Large · Medium · Small · Xs 4단계, Label 이 XL2 · XL · Large · Medium · Small · Xs 6단계, Code 가 Xs · Sm · Md 3단계입니다. Label 이 여섯인 이유는 컨트롤 라벨이 Body 보다 넓은 크기 범위를 덮어야 하기 때문이고, 그래서 Label 은 Body 보다 한 단계 무겁습니다(500 대 400) — 크기가 아니라 무게로 "읽는 글"과 "누르는 것의 이름"을 가릅니다. Code 는 고정폭 서체(Geist Mono) 400 이고, 세 크기가 21px 한 줄 격자에 앉습니다.

언제 쓰나#

역할을 고르세요

• 화면 제목 → headline* / title*
• 본문·설명 → body*
• 버튼·칩·탭·필드 라벨 → label*
• 코드·줄 번호·경로·로그 → code*
• 색은 chain 으로 붙입니다 — Text('저장').labelMedium.onPrimary

쓰지 마세요

• fontSize: 16 / fontWeight: FontWeight.w600 를 위젯에 박기 — 테마 스케일이 비껴갑니다
• Body 로 버튼 글자를 쓰기 — 무게가 달라 "누르는 것"으로 안 읽힙니다

긴 카피·문서 본문은 Text 컴포넌트와 chain API 를 같이 보세요.

coui_core 맵#

아래 표의 샘플은 CSS 변수를 읽으므로 테마와 창 폭을 따라 움직입니다 — 창이 좁으면 display · headline 샘플이 화면 폭의 단계만큼 작아집니다. 오른쪽 수치(크기 / line-height / weight / letter-spacing)는 CoUI 기본 스케일(CoreTypography.coui)에서 읽은 Desktop 값이라 테마도 창 폭도 따라 움직이지 않습니다. code 역할의 line-height 는 배수가 아니라 px 로 적힙니다.

사용법#

// Flutter — chain API
Text('Heading').headlineLarge
Text('Body').bodyMedium.onSurface

// Web — 동일 chain
Text('Heading').headlineLarge

chain 으로 쓸 수 있는 메서드 전체 목록(typography · weight · 색상 · modifier)과 적용 순서는 Text 컴포넌트 문서에 있습니다. 이 페이지는 어느 역할을 고를지와 chain 이냐 Style 슬롯이냐만 답합니다.

headline 과 title — 크기와 쓰임으로 갈린다#

Desktop 에서 크기는 한 번도 겹치지 않는 연속 사다리입니다(headline 32/28/24 → title 20/18/16). 여기서 "겹쳐 보인다"는 인상은 값이 아니라 Large/Medium/Small 이라는 이름 반복에서 옵니다. Mobile 에서는 headline 이 24/20/16 으로 내려가 title 20/18/16 과 크기가 겹칩니다(화면 폭에 따른 단계) — 그 폭에서 둘을 가르는 것은 굵기(700 ↔ 600)와 쓰임입니다.

역할 묶음마다 굵기 하나, 행간 하나입니다. 자간은 역할이 아니라 크기가 정합니다 — 20px 이상은 −2%, 그 아래는 −1%, 고정폭은 0 입니다.

headline 과 title 은 행간이 같고, title 은 굵기가 한 단계 낮습니다(600). 둘을 가르는 것은 크기와 쓰임입니다. body 만 행간이 1.5 인 이유는 여러 줄로 이어 읽는 글이기 때문입니다 — 한 줄로 끝나는 제목과 라벨은 1.4 를 같이 씁니다.

고르는 기준 한 문장 — 그 텍스트가 페이지를 나누는 표지판이면 headline, 바로 아래 본문에 붙어 그 본문을 설명하면 title.

이 킷 자신의 답이 TextBlock 의 헤딩 매핑에 있습니다 — h1→displaySmall, h2→headlineLarge, h3→headlineSmall, h4→titleLarge, h5→titleMedium, h6→titleSmall. 문서 상위 구획은 headline, 문단 바로 위 소제목은 title.

body 와 label — 같은 크기라도 역할이 다르다#

bodyMedium 과 labelLarge 는 모두 14지만, body 는 400·행간 1.5 이고 label 은 500·행간 1.4 입니다. 같은 크기에서 굵기와 행간으로 "읽는 글"과 "누르는 것의 이름"을 구별합니다.

body 는 15/14/13/12(bodyLarge … bodyXs), label 은 16/15/14/13/12/11 (labelXl2 … labelXs) 입니다. label 은 1px 간격 사다리입니다.

label 은 큰 컨트롤부터 키캡·숫자 배지 같은 작은 이름표까지 덮고, body 는 문장 가독성을 위해 12(bodyXs)에서 멈춥니다.

문장으로 읽히는 것은 body, 대상에 붙어 이름표 역할을 하는 것은 label. 11이 필요하면 그건 정의상 label 입니다 — body 에는 그 단이 없습니다.

같은 크기에서 역할을 바꾸는 것도 굵기·행간을 바꾸므로 실제 화면이 달라집니다.

컨트롤 라벨은 역할의 500 입니다. Button · Chip · Badge(낱말) · RadioGroup 카드 제목은 굵기를 덮지 않고 크기별 label 역할의 500 을 그대로 그립니다 — 한 줄에 놓인 버튼과 칩이 같은 굵기로 읽히고, 캔버스에서는 그 역할의 텍스트 스타일이 라벨에 붙습니다. 칩은 선택을 채움으로 구분하므로 굵기가 어떤 상태에서도 같고, 누를 때 칩 폭이 움직이지 않습니다.

예외는 굵기가 따로 할 말이 있는 자리입니다. Badge 의 숫자(count)는 600 입니다 — 작은 크기의 숫자 한두 자는 낱말보다 가볍게 읽히기 때문입니다. 진한 Tag 의 라벨은 600 이고(흰 글자의 대비 조건), ChipInput 배지는 입력 하나 안에 여러 개가 쌓이는 값 표시라 자기 400 을 명시합니다.

code — 고정폭과 21px 줄#

codeXs · codeSm · codeMd (11 · 12 · 13) 는 고정폭 서체 Geist Mono 400 이고, 셋 다 줄 높이가 21px 로 고정입니다.

• 줄 높이가 배수가 아니라 길이인 이유 — 편집기에서 12px 줄 번호와 13px 코드가 같은 줄 격자에 앉아야 합니다. 배수 하나로는 11 · 12 · 13 을 한 높이에 맞출 수 없고, 가까운 배수는 화면 한 장을 내려가며 몇 px 씩 어긋납니다.
• 자간 0 — 고정폭은 글자 폭이 곧 격자입니다.
• 쓰는 곳 — codeSm 은 줄 번호·로그·경로·파일 트리, codeMd 는 편집기 본문, codeXs 는 좁은 패널의 값입니다.
• 한글 — Geist Mono 에는 한글이 없어, 코드 안의 한글은 두 플랫폼 모두 Pretendard 로 그려집니다.
• 서체 공급 — Flutter 는 coui_flutter 가 번들한 GeistMono 가 그리므로 앱이 넣을 것이 없습니다. Web 은 앱이 Geist Mono 를 불러와야 합니다 (설치).

display 는 큰 단일 값과 문서 제목에#

display 는 큰 단일 값이나 장문 문서 제목에, headline 은 화면 구획이나 강조된 값에 씁니다. 본문과 컨트롤의 이름은 body 와 label 이 맡습니다.

display 는 읽히는 대상이 큰 숫자·단어 하나인 화면에 맞습니다. 또 다른 용도는 장문 문서의 문서 제목입니다 (TextBlock 이 h1 을 displaySmall 로 매핑합니다).

앱 화면 제목에 display 를 쓰면 대개 과합니다 — 그 자리는 headline 이고, 컴포넌트들도 대체로 그렇게 합니다. 기본 display 와 headline 은 모두 bold(700)라 둘의 차이는 크기뿐입니다 — display 를 고를 이유는 그 크기가 필요한지 하나입니다.

displayLarge · displayMedium · headlineMedium 은 chain API 에 존재하고 쓸 수 있습니다. 필요 이상으로 큰 역할을 고르는 근거로 삼지는 마세요.

화면 폭에 따른 단계#

display · headline 여섯 역할은 화면 폭에 따라 작아집니다. 제목은 자기가 머리에 놓인 화면의 폭에 맞아야 하기 때문입니다. title · body · label · code 는 이어 읽는 글과 컨트롤의 글자라 어느 폭에서나 같은 크기입니다.

• display 는 단계마다 8px, headline 은 4px 씩 내려갑니다.
• 굵기 · 행간 · 서체는 그대로입니다. 자간은 위의 규칙대로 크기가 정하므로, Mobile 의 headlineSmall(16) 만 −1% 이고 나머지는 −2% 입니다.
• 경계 768 · 1024 는 레이아웃 브레이크포인트(CoreBreakpoint)와 같습니다. 가로로 눕힌 휴대폰은 폭이 768 이상이면 Tablet 입니다.
• Figma 라이브러리의 Semantic/ Typography Mobile · Tablet · Desktop 모드가 같은 표입니다 — 토큰 익스포트가 이 표에서 값을 읽습니다. 캔버스 프레임은 디자이너가 고른 모드로 그려지고 화면 폭을 모릅니다.

기본은 자동입니다#

CoUIApp · CoUIWeb 을 쓰는 앱은 아무것도 하지 않아도 이 단계를 따릅니다. CoUIApp 없이 CoUILayer 로 CoUI 를 얹은 Flutter 앱도 같습니다 — 단계를 고르는 것은 CoUILayer 입니다. Flutter 는 앱 뷰의 폭으로 단계를 고르고, Web 은 스타일시트의 미디어 규칙으로 고르므로 서버가 렌더한 첫 화면부터 그 폭의 크기로 그려집니다.

컴포넌트는 단계를 따로 읽지 않습니다. 테마의 역할(Flutter)과 역할 CSS 변수(Web)가 바뀌므로, 역할로 그리는 글자가 함께 바뀝니다 — Text chain(Text('…').headlineLarge), TextBlock 의 h1–h3, PageHeader 제목, Countdown, Stat 의 값, AppBar 의 prominent 제목이 그렇습니다.

크기는 표의 값으로 바꾸는 것이 아니라 역할마다 같은 비율로 줄입니다. 그래서 제목 크기를 직접 저작한 앱의 스케일도 CoUI 표와 같은 비율로 줄고, 사용자가 키운 글자 배율도 그대로 남습니다.

단계를 고정할 때#

앱 전체를 한 단계로 고정하려면 앱 루트에 적습니다. null(기본)이면 화면 폭을 따릅니다.

// Flutter — 모든 폭에서 Desktop 크기
CoUIApp(
  theme: theme,
  typographyTier: CoreBreakpointTier.desktop,
  home: const HomePage(),
)

// Web
CoUIWeb(
  theme: theme,
  typographyTier: CoreBreakpointTier.desktop,
  child: const App(),
)

CoUILayer 를 직접 쓰는 앱은 CoUILayer(typographyTier:) 에 같은 값을 줍니다. Web 은 호스트 페이지가 <html data-coui-typography-tier="desktop"> 을 달아도 같습니다. CoUIWeb 에 값을 주지 않으면 호스트가 단 속성을 그대로 둡니다.

고정을 바꾸려면 다른 값으로 다시 빌드합니다. null 로 다시 빌드하면 두 플랫폼 모두 다시 화면 폭을 따릅니다 — Web 은 자기가 단 속성을 지우지 않고 단계 이름이 아닌 값으로 바꾸며, 스타일시트는 단계를 이름하지 않는 문서를 화면 폭으로 판정합니다.

화면의 한 부분만 고정하려면 그 부분을 감쌉니다. 두 플랫폼 코드가 같습니다.

// 이 안의 제목은 폭과 무관하게 Desktop 크기
TypographyTierScope(tier: CoreBreakpointTier.desktop, child: hero)

• 이 안에서 연 패널(팝오버 · 메뉴 · 툴팁 · 대화상자)도 이 범위를 따릅니다. 패널은 오버레이로 바깥에 그려지지만, 두 플랫폼 모두 패널을 연 자리의 범위를 패널에도 적용합니다.
• 서랍(openDrawer, 서랍을 여는 Swiper 포함)은 연 자리가 아니라 서랍이 올라가는 자리의 단계를 따릅니다. 기본은 앱 루트라 범위 안에서 열어도 앱의 단계입니다. Flutter 에서 useRootNavigator: false 로 범위 안의 내비게이터에 올리거나, Web 에서 범위 안에 둔 OverlayHost 에 올리면 그 범위의 단계를 따릅니다.
• Flutter 에서 범위는 둘러싼 글자 크기로 지금 단계를 알아냅니다. 부분 트리에서 서체나 굵기만 바꾼 스케일은 그 서체 · 굵기를 둔 채 크기만 옮기고, 크기까지 따로 정한 Theme 아래에서는 그 스케일을 Desktop 으로 보므로 Desktop 범위는 그 스케일을 그대로 둡니다. AdaptiveScaler 아래에서는 그 배율이 범위 안에도 그대로 남습니다.
• 다른 화면 안에 끼운 뷰는 뷰의 폭이 곧 화면 폭이라, 좁은 패널이면 Mobile 로 그려집니다 — Flutter 뷰도, iframe 에 넣은 Web 페이지도 같습니다. 화면이 아닌 뷰(임베드 · 미리보기)는 호스트가 단계를 고정하세요 — 이 사이트의 미리보기가 두 플랫폼 모두 Desktop 으로 고정합니다.
• Web 페이지를 인쇄하면 고정하지 않은 페이지도 Desktop 크기로 찍힙니다. 종이에 맞춘 폭은 대개 768 보다 좁아 미디어 규칙만으로는 Mobile 이 되지만, 인쇄된 제목은 화면의 머리에 놓인 제목이 아닙니다.

상자를 채우는 글자는 Desktop 에 머뭅니다#

Avatar 이니셜과 TimePicker 의 시 · 분 · 초 숫자는 화면 폭과 무관한 크기의 상자를 채우도록 고른 글자입니다. 글자만 줄면 상자가 비어 보이므로, 두 플랫폼 모두 자기 상자를 TypographyTierScope(tier: CoreBreakpointTier.desktop) 로 감싸 Desktop 크기를 유지합니다. 같은 성격의 상자를 직접 만들 때도 그렇게 감싸세요.

따라오지 않는 것#

• 크기를 직접 적은 글자 — fontSize: 덧씌움, 토큰 없는 스타일, .s24 같은 크기 chain.
• CoUIApp · CoUILayer 를 쓰지 않는 Flutter 앱, CoUI 스타일시트(ThemeConfig.cssVariables)를 싣지 않은 Web 페이지.
• 레이아웃 — 반응형 레이아웃 컴포넌트는 폭으로 자기 브레이크포인트를 따로 판정하므로, 글자 단계를 고정해도 레이아웃은 폭을 따릅니다.
• 실행 중 커스텀 테마(setCustomTheme) — 색과 반경만 바꿉니다. 글자 스케일은 스타일시트를 만드는 자리(ThemeConfig.typography)에서 정합니다.

한 컴포넌트는 1~2단, 많아야 3단#

하나의 인스턴스에는 제목·본문처럼 적은 수의 역할을 먼저 고르세요.

3개 이상 중 상당수는 사이즈 테이블(defaultsBySize)이라 한 인스턴스가 그걸 다 그리지 않습니다. 실제로 동시에 여러 단을 그리는 것은 Stat(값·라벨·변화량)과 TimePicker 처럼 각 텍스트의 기능이 서로 다른 경우입니다. 3단은 선택 가이드이지 컴포넌트 API 가 강제하는 상한이 아닙니다.

화면 단위 상한은 이 킷이 답하지 않습니다. 화면은 컴포넌트의 합이므로, 각 컴포넌트가 1~2단을 지키면 화면은 자연히 정돈됩니다. 화면이 직접 정하는 것은 보통 제목 한 단 + 본문 한 단입니다.

위계는 인접 단으로 만든다#

제목·본문의 크기 차이는 인접 단부터 검토하세요. defaultsBySize 가 있는 컴포넌트는 그 테이블이 제목·값·라벨 역할을 함께 정하므로 일부 값만 덮기 전에 기본 위계를 확인합니다.

나란히 놓으면 위계가 안 생기는 짝#

22개 역할이 모두 다른 크기를 갖는 것은 아닙니다. 같은 크기도 역할의 굵기·행간·서체가 다를 수 있습니다. 아래 짝은 모든 화면 폭에서 같은 크기입니다.

좁은 화면에서는 headline 이 내려가 짝이 더 생깁니다.

같은 크기 안의 역할 변경은 크기 위계를 만들지 않습니다. 굵기·행간 차이가 목적에 맞는지 보고, 크기 차이도 필요하면 다른 단을 선택하세요.

chain 이냐 Style 슬롯이냐 — 슬롯 타입이 정한다#

취향이 아닙니다. 그 자리가 무엇을 받는지만 보면 됩니다.

왜 갈리나: 합성 슬롯은 임의 위젯을 받으므로 chain 을 든 Text 를 그냥 넣으면 됩니다. chrome 슬롯은 그 컴포넌트의 모든 시각 값이 지나는 단일 입구라 타입이 CoreXxxStyle 하나로 고정돼 있어 위젯을 넣을 수 없습니다.

결정 한 문장 — 이 인스턴스 하나의 텍스트를 바꾸려면 chain, 그 컴포넌트가 그리는 텍스트의 기본값을 바꾸려면 chrome 슬롯(프로젝트 전체면 Theme).

둘이 같은 텍스트를 가리킬 때#

Card 처럼 header(합성 슬롯)와 headerTextStyle(chrome)이 같은 텍스트를 가리키면 두 경로만 쓰세요:

// 슬롯 기본값을 그대로 → 맨 Text
Card(header: Text('제목'))

// 다른 역할을 쓰려면 → 역할을 명시한 chain
Card(header: Text('제목').titleLarge)

굵기나 색만 얹는 부분 chain(Text('제목').semiBold)은 이 자리에서 피하세요. 색을 바꿔야 하면 chrome 슬롯으로 보내는 것이 안전합니다.

.lineLimit · .ellipsis 같은 레이아웃 modifier 는 안전합니다 — 주변 스타일을 그대로 두고 줄 수만 제한합니다.

제목에 다른 서체를 쓸 때#

기본 스케일은 code 세 역할만 고정폭(Geist Mono)으로, 나머지는 모두 본문 서체(Pretendard)로 그립니다. 제품이 제목에 자기 서체를 쓰려면 스케일의 역할에 서체를 적습니다 — 컴포넌트마다 적지 않습니다.

// display · headline 여섯 역할이 이 서체로 그려집니다
final typography = CoreTypography.coui.withFamily('Hahmlet');

// Flutter
ThemeData.fromCore(myCoreTheme.copyWith(typography: typography));

// Web — <style> 에 넣는 스타일시트가 이 스케일에서 만들어집니다
ThemeConfig.from(CouiColorPresets.source, typography: typography).cssVariables;

• 서체 파일은 앱이 공급합니다(Pretendard 와 같습니다).
• 그 서체에 없는 글자는 본문 서체로 그려집니다 — 라틴 표시용 서체로 한글 제목을 써도 한글은 Pretendard 로 나옵니다.
• title · body · label 은 본문 서체에 둡니다. 이어지는 글과 컨트롤 라벨의 서체가 바뀌면 글의 종류가 바뀐 것으로 읽힙니다. 다른 역할이 필요하면 withFamily('…', roles: [...]) 로 고릅니다.
• code 역할은 고르지 마세요. 고정폭이 아닌 서체를 적으면 줄 번호와 코드가 맞춰 앉던 글자 격자가 사라집니다.
• Figma 라이브러리는 CoUI 기본 스케일만 싣습니다 — 제품의 제목 서체는 라이브러리 텍스트 스타일에 없습니다.

크기를 바꿀 때#

행간과 자간은 비율이라 크기를 바꾸면 비례해 따라옵니다. 보정하려고 line-height 나 letter-spacing 을 손으로 다시 지정하지 마세요 — 특히 label 에 height: 1 / leading-none 은 두 플랫폼의 시각이 갈립니다.

code 역할의 21px 줄은 길이라서, 크기를 덮어써도 줄은 그대로입니다 — 줄 격자는 글자 크기와 상관없이 유지돼야 하기 때문입니다. 사용자가 키운 글자 배율은 줄도 함께 키웁니다. 줄을 배수(lineHeight)로 다시 적으면 고정 줄은 사라지고 그 배수가 이깁니다 — 역할 뒤에 적은 배수가 이깁니다.

체인에서 역할은 앞에 적은 크기 · 굵기 · 행간 · 서체를 지웁니다. 역할이 그 넷을 한 묶음으로 진술하기 때문입니다 — .s20.codeSm 은 12px, .h140.codeMd 는 21px 줄, .sans.codeSm 은 고정폭으로 그려집니다(두 플랫폼 같음). 자간과 기울임은 역할을 지나도 남습니다. 그래서 역할을 바꾸려면 역할을 먼저 고르고, 덮을 값을 그 뒤에 적습니다.

이전 스케일로 잠시 되돌리기#

이 스케일은 크기·행간·자간이 이전 판과 다릅니다(본문 18/16/14 → 15/14/13, 라벨 행간 1.2 → 1.4, headline 600 → 700, 자간 다섯 단 → 두 단). 앱을 옮기는 동안 이전 크기가 필요하면 이전 역할 표 CoreTypography.couiV1 을 테마에 넣습니다. 두 마이너 동안만 남는 @Deprecated 값입니다.

// Flutter
ThemeData.fromCore(myCoreTheme.copyWith(typography: CoreTypography.couiV1));

// Web
ThemeConfig.from(CouiColorPresets.source, typography: CoreTypography.couiV1);

• 되돌리는 것은 역할 표뿐입니다. 컴포넌트가 읽는 역할은 되돌아가지 않아서, 다른 역할을 읽게 된 컴포넌트는 그 역할의 이전 값을 읽습니다.
• 이전 표에 없던 역할은 가장 가까운 이전 역할의 값입니다 — bodyXs 는 이전 bodySmall, labelXs 는 이전 labelSmall, code 역할은 이전 bodySmall 의 크기·행간을 고정폭으로 그린 값입니다.

전체 스케일#