Communitygithub.com

bompus/hr-better-typography

웹 UI의 타이포그래피 규칙: 타입 스케일, 줄 간격, 줄바꿈, 말줄임, 표준 숫자, 폰트 로딩 및 모바일 입력 텍스트 크기. 웹 UI CSS에서 텍스트가 렌더링되는 방식이나 검토 시 사용합니다.

hr-better-typography란 무엇인가요?

이 스킬은 웹 UI 타이포그래피의 선언적이고 체계적인 관리를 위한 포괄적인 규칙과 모범 사례를 제공합니다. 주로 Claude Code, Cursor 등 AI 코딩 어시스턴트와 함께 사용되며, 텍스트가 렌더링, 줄바꿈, 잘리는 방식을 제어하여 일관된 타입 시스템을 구축합니다. 타입 스케일, 줄 간격, 문자 간격, 단락 너비 제한, tabular numbers, 폰트 로딩, 모바일 입력 크기 등 다양한 측면을 다루며, 각 규칙은 구체적인 CSS 선언과 함께 설명됩니다. 또한 서체 합성 방지, 지능형 구두점 사용, 밑줄 스타일링, 텍스트 선택성 유지 등 고급 주제도 포함합니다. 검토 및 보고 체계를 제공하여 문제를 HIGH/MEDIUM/LOW 심각도로 분류하고, 브라우저 유무에 따른 검증 방법을 제시합니다. 부적절한 폰트 합성, 잘못된 제목 계층, 고아 단어, 균형 잡히지 않은 제목 등 일반적인 실수와 그 해결책을 표로 정리하여 실용적인 참고 자료를 제공합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bompus/house-rules/tree/HEAD/skills/hr-better-typography

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

타이포그래피

타이포그래피는 대부분 절제입니다: 합리적인 스케일, 편안한 간격, 충분한 대비. 레이블, 테이블 셀, 마케팅 헤드라인, 기사 단락은 모두 동일한 규칙을 공유하지 않습니다.

검토 시에는 코드를 훑어보지 말고 렌더링된 페이지를 읽으십시오. 잘못된 줄바꿈, 고아 단어, 말줄임은 실제 콘텐츠 길이에서만 드러납니다.

모든 수정은 프로젝트의 스타일링 시스템으로 작성하고, 익숙해 보이는 동등한 값 대신 아래의 정확한 값을 사용하십시오. 치트 시트는 각 선언을 Tailwind 동등 값에 매핑합니다.

단어 자체는 hr-better-writing에 속합니다. 의미론적 제목 구조는 hr-better-accessibility에 속합니다. 공간적 RTL 레이아웃과 논리적 속성은 hr-better-layout에 속합니다. 대비 측정은 hr-better-colors에 속합니다. 이 스킬은 텍스트가 혼합 방향 콘텐츠에서 어떻게 렌더링되고, 줄바꿈되며, 동작하는지를 관장합니다.

올바른 포맷 제공

웹에서는 Brotli 압축과 광범위한 지원을 위해 .woff2를 사용하십시오. .woff는 매우 오래된 브라우저를 위한 폴백입니다. .ttf와 .otf는 웹 압축이 없는 데스크톱 포맷입니다. 파일이 로드되는 방식은 프로젝트의 관심사입니다.

속성과 원시 태그

CSS 속성이 존재하면 사용하십시오. font-weight: 650 대신 font-variation-settings: \"wght\" 650. font-optical-sizing: auto 대신 \"opsz\". font-variant-numeric: tabular-nums 대신 font-feature-settings: \"tnum\" 1.

속성은 가변 폰트가 아닌 폴백이 렌더링될 때도 작동합니다. 원시 태그는 고유한 속성이 없는 사용자 정의 축(\"GRAD\" 80)과 틈새 기능(\"ss01\" 1)을 위해 남겨두십시오. 축과 기능 태그는 variable-fonts-and-opentype.md에 나열되어 있습니다.

의도된 굵기와 스타일 로드

브라우저는 활성 패밀리가 제공하지 않는 굵기나 스타일을 합성하여 실제 서체를 왜곡합니다. 디자인에서 사용하는 서체를 로드하십시오.

font-synthesis: none은 합성을 끄지만, 강조를 없애므로 보고하지 않습니다. 필요한 모든 굵은 글씨, 기울임꼴, 작은 대문자, 위첨자, 아래첨자 형태가 폴백 스택 전체에서 구별되는지 확인한 후에만 설정하십시오.

적은 폰트, 크기, 굵기

세 가지 이상의 폰트는 거의 사용하지 마십시오. 굵기와 크기가 계층을 정의합니다. 과도하게 사용하면 가독성이 빠르게 떨어집니다. 유사성이 아닌 대비를 위해 짝을 지으십시오: 산세리프 본문 위에 세리프 헤드라인은 의도적으로 읽히지만, 거의 동일한 두 산세리프는 실수로 읽힙니다.

18px 미만에서는 굵기 400 이상을 유지하십시오. 300 미만의 굵기는 28px 이상에서만 디스플레이 용도입니다. 텍스트 크기에서는 사라집니다. 페어링 가이드는 choosing-fonts.md에 있습니다.

의미론적 이름이 있는 타입 스케일 사용

소수의 크기 집합을 정의하고 가능한 한 벗어나지 마십시오. 시스템이 없는 하드코딩된 크기는 규모가 커지면 무너집니다. 스케일 외부의 임의 크기에서 실패하는 린트 규칙이나 가드 테스트로 스케일을 강제하십시오.

사용 규칙이 명확할 때 text-sm과 같은 단독 기본 이름은 괜찮습니다. 팀에서는 용도별로 크기 이름을 지정하십시오(text-body-sm). 그러면 규칙이 다른 사람에 의해 유지됩니다. 스케일 구성은 spacing-and-sizing.md에 있습니다.

제목 크기는 수준에 따라 내려감

제목 수준을 타입 스케일의 내림차순 단계에 매핑하여 시각적으로 하위 제목이 상위 제목보다 우세하지 않도록 하십시오. 인접한 수준은 굵기나 간격으로 구별되는 한 스케일의 작은 쪽 끝에서 크기를 공유할 수 있습니다. 의미론적 요소는 hr-better-accessibility의 것입니다. 이 스킬은 시각적 처리만 설정합니다.

역할별 줄 간격

제목은 더 좁게, 약 1.1. 본문은 1.5에서 1.6. 단위 없는 값을 선호하십시오. 그러면 줄 간격이 글꼴 크기에 따라 조정됩니다. 고정 24px는 그렇지 않습니다.

좁은 줄 간격은 짧은 텍스트용입니다. 세 줄 이상으로 줄바꿈되는 모든 텍스트는 높이가 제한된 행에서도 최소 1.4가 필요합니다.

크기별 문자 간격

큰 제목은 종종 약간 음수 문자 간격이 더 좋아 보입니다. 작은 대문자 레이블은 약간 양수 문자 간격이 필요합니다. 그렇지 않으면 글자가 비좁아 보입니다. 읽기 크기의 본문은 둘 다 필요하지 않습니다.

행 길이 제한

긴 행은 눈이 다음 행을 찾기 어렵게 만듭니다. 긴 형식의 텍스트는 한 줄에 약 60-75자로 제한하십시오. 어떤 단위든 작동합니다. 제한이 존재하고 줄 길이가 범위 내에 있으면 됩니다. 단위 선택 및 픽셀 동등 값을 참조하십시오.

의도적으로 줄바꿈

네 가지 선언, 네 가지 작업:

  • text-wrap: balance는 텍스트를 여러 줄에 균등하게 분배합니다. 제목에 사용하십시오.
  • text-wrap: pretty는 마지막 줄에 짧은 단어 하나가 남는 것을 방지합니다. 설명에 사용하십시오.
  • overflow-wrap: break-word는 긴 단어, 링크 또는 ID가 컨테이너를 벗어날 수 있는 곳에 사용하십시오.
  • white-space: nowrap은 줄바꿈이 어색해 보이는 레이블과 배지에 사용하십시오.

긴 형식의 텍스트에서는 balance와 pretty를 건너뛰십시오.

변경되는 값에 표준 숫자 사용

기본적으로 숫자는 너비가 다르므로 타이머, 카운터, 가격이 업데이트될 때 레이아웃이 이동합니다. 변경되는 모든 값에 font-variant-numeric: tabular-nums를 적용하십시오.

콘텐츠 손실 없이 말줄임

한 줄의 경우 text-overflow: ellipsis와 함께 overflow: hidden 및 white-space: nowrap을 사용하십시오. 여러 줄의 경우 line-clamp를 사용하십시오. 말줄임은 콘텐츠를 숨깁니다. 누락된 텍스트가 중요할 때는 툴팁이나 확장 보기에서 전체 값을 접근 가능하게 유지하십시오.

필드별로 선택하십시오. 사용자가 항목을 식별하는 데 전체가 필요한 이름과 제목은 줄바꿈하십시오. 파일 이름, 경로, 도메인을 공유하는 이메일과 같이 항목이 끝에서 다른 경우 중간에서 말줄임하십시오. 끝 말줄임은 항목을 동일하게 보이게 만들기 때문입니다. 사용자가 비교하는 숫자, 금액, 날짜는 절대 말줄임하지 마십시오. 자세한 내용은 wrapping-and-punctuation.md에 있습니다.

텍스트는 자연스럽게 작성하고 CSS로 스타일링

텍스트는 자연스러운 대소문자로 저장하고 text-transform으로 표현을 제어하십시오. 그러면 리디자인이 콘텐츠 재작성을 의미하지 않습니다.

렌더링된 텍스트에서 스마트 구두점 사용:

  • 본문에서는 둥근 따옴표, 코드에서는 직선 따옴표.
  • 범위에는 en 대시: 2010–2020.
  • 세 개의 마침표가 아닌 단일 줄임표 문자.
  •  는 16 px를 줄바꿈에서 함께 유지합니다.
  • ­는 긴 단어가 어디에서 줄바꿈될 수 있는지 지정합니다.

폰트의 밑줄

기본 밑줄은 브라우저가 결정하는 곳에 위치합니다. text-underline-position: from-font 및 text-decoration-thickness: from-font로 폰트 자체 메트릭에서 위치와 두께를 가져옵니다. text-decoration-thickness, text-underline-offset 및 text-decoration-skip-ink로 수동 조정합니다.

text-decoration-style은 선을 점선, 파선 또는 물결선으로 그립니다. 점선 밑줄은 단어에 약어나 정의된 용어와 같은 추가 정보가 있음을 나타내는 일반적인 힌트입니다.

실제 밑줄에서 색상만이 안정적으로 애니메이션되는 부분입니다. 따라서 애니메이션되는 것이 색상뿐이 아니라면 text-decoration을 사용하는 대신 밑줄을 별도의 요소로 만드십시오.

모바일에서 16px 입력

iOS Safari는 입력 텍스트가 16px보다 작을 때 전체 페이지를 확대/축소합니다. 두 가지 수정 방법이 크기를 16px로 유지하고 다르게 보이므로 디자인이 원하는 것을 물어보십시오:

  • 모바일에서 입력 크기를 키웁니다(text-base sm:text-sm). 작은 화면에서 모양이 변경됩니다.
  • font-size: 16px를 유지하고 transform: scale()로 의도된 크기를 렌더링하고 너비와 line-height를 보정합니다. 모든 뷰포트에서 동일하지만 유지 관리할 코드가 더 많습니다.

두 방법 모두 details-and-accessibility.md에 있습니다.

크기 및 대비 최소값

긴 형식의 본문 텍스트는 브라우저 기본값인 16px에서 시작하십시오. 이유를 말할 수 있을 때만 벗어나십시오: 서체가 작게 실행되거나, 행 길이가 좁거나, 제품이 밀집된 전문 도구인 경우.

UI 텍스트는 더 작아질 수 있습니다. 14px는 입력과 메뉴의 유용한 시작점이고, 13px는 캡션에, 드물게 12px 미만입니다. 입력은 여전히 모바일에서 16px가 필요합니다.

텍스트가 낮은 대비로 보일 때 hr-better-colors를 사용하여 렌더링된 쌍을 측정하고 hr-better-accessibility를 사용하여 요구 사항을 분류하십시오. 요청하지 않는 한 색상을 그대로 두십시오.

루트의 폰트 스무딩

macOS에서는 텍스트가 의도보다 굵게 렌더링됩니다. 루트 레이아웃에 한 번 -webkit-font-smoothing: antialiased 및 -moz-osx-font-smoothing: grayscale을 적용하고, 컴포넌트별로는 절대 적용하지 마십시오. Tailwind의 antialiased가 둘 다 다룹니다.

언어 및 양방향 동작

lang을 설정하여 브라우저와 보조 기술이 올바른 발음, 따옴표 및 하이픈 넣기를 선택하도록 하십시오. 방향이 변경되는 문서 또는 콘텐츠 경계에서 dir을 설정하십시오. 숫자 순서를 유지하고 <bdi>를 사용하여 혼합 방향 값을 분리하십시오. 공간적 미러링 및 논리적 CSS 속성은 hr-better-layout에 속합니다.

유용한 텍스트 선택 가능 유지

기본적으로 텍스트를 선택 가능하게 유지하십시오. ::selection은 브랜드를 읽기 경험에 가져올 수 있으며, 선택된 조합이 읽을 수 있는 한 사용할 수 있습니다.

user-select: none은 우발적인 선택이 방해가 되는 드래그 또는 제스처 기반 표면에 속합니다. 인터페이스 전체에 걸쳐 또는 버튼 레이블이 강조 표시될 수 있기 때문에 절대 사용하지 마십시오.

완료 전 확인

실수수정
합성된 서체가 디자인과 다름실제 서체 로드; 확인된 합성 모드만 비활성화
하위 제목이 시각적으로 상위 제목을 우세해당 섹션의 계층 구조를 내림차순 스케일 단계에 매핑
기본 크기로 선택된 제목 요소의미론을 먼저 선택한 후 CSS에서 크기 설정
단락 마지막 줄의 고아 단어text-wrap: pretty
두 줄 제목의 불균형text-wrap: balance
인터페이스의 정렬된 텍스트text-align: start; 특정 편집 레이아웃을 위해 정렬 예약
밑줄이 내림자 통과text-decoration-skip-ink: auto, from-font 메트릭
혼합 방향 값이 잘못된 순서로 렌더링lang/dir 수정; <bdi>로 값 분리
애플리케이션 크롬에서 선택 비활성화복원; 드래그 또는 제스처와 충돌하는 곳에서만 억제
추가 정보 힌트에 시각적 신호 없음text-decoration-style: dotted를 통한 점선 밑줄
14px UI 텍스트에 얇은/가벼운 굵기18px 미만에서는 굵기 400+; 얇은 굵기는 디스플레이 전용
세 줄 카드 설명에 leading-none3줄 이상으로 줄바꿈되는 텍스트는 최소 1.4

보고

심각도. HIGH는 텍스트를 읽을 수 없게 만들거나 복구 방법 없이 콘텐츠를 자릅니다. MEDIUM은 타입 시스템이나 제목 계층을 깨뜨립니다. LOW는 고립된 가다듬기입니다.

검증. 브라우저 없이: 각 제목 수준에 대한 계산된 크기와 굵기, 내림차순 확인; 선언된 줄 간격과 행 길이; 실제 문자열 길이에 대한 말줄임 규칙. 브라우저 사용: 실제 콘텐츠 길이에서 줄바꿈, 고아 단어, 말줄임을 포착하기 위해 뷰포트 크기 조정. 실행할 수 없었던 모든 검사를 Not verified로 보고하십시오.

형식. 각각 위반하는 원칙 아래에 결과를 그룹화하고, 심각도별로 정렬하며, 나타나는 모든 위치를 나열하는 각 근본 원인당 한 행:

심각도위치변경 전변경 후이유

위치는 path/to/file:line입니다. 이유는 원칙과 사용자 영향을 명명합니다.

HIGH가 남아 있으면 Block을 보고하고, 그렇지 않으면 Approve를 보고하고 나머지는 할 일로 테이블에 남겨둡니다. 검사하지 않은 범위를 Approve하지 마십시오. 보고할 사항이 없으면 "실행 가능한 타이포그래피 발견 사항 없음"을 명시하고 검증을 보고하십시오.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

관련 스킬