현재 사용법 (2026-09-10, 6fbaee7f): 공통 화면·디자인 시스템 · 기능 마스터. 아래는 작성 당시의 변경 설명이며 현재 전체 동작·재측정 결과를 뜻하지 않습니다.

아이콘 굵기·의미 규격 정리

화면 곳곳의 아이콘이 서로 다른 굵기로 보이던 것을 하나로 맞추고, 빨간 오류 상자 안에 안내 기호(ⓘ)가 뜨던 자리를 오류 기호(!)로 바로잡습니다. 도형이 깨져 있던 아이콘 네 개도 함께 수리합니다.

이 변경들이 한 PR로 묶인 이유는 발견 경로가 같기 때문입니다. 등록된 아이콘을 한자리에서 볼 수 있는 화면이 레포에 없었고, 그래서 어긋난 것들이 발견되지 않은 채 쌓여 있었습니다. 이번에 아이콘 갤러리 페이지를 만들자 전부 한 번에 드러났습니다.

배경

아이콘은 packages/components/src/icons.ts 한 파일에 이름과 SVG 문자열의 쌍으로 등록돼 있습니다. 이하 이 파일을 레지스트리라고 씁니다. 화면에서는 Alpine 전역 매직 $icon('이름')으로 꺼내 쓰고, 크기와 색은 감싸는 <span class="ds-ico w-4 h-4">가 갖습니다. 글리프 자체는 currentColor만 쓰므로 색을 스스로 정하지 않습니다.

아이콘을 그릴 때는 두 값을 적습니다. **viewBox**는 그림을 그리는 좌표계의 크기이고, **stroke-width**는 그 좌표계 안에서의 획 두께입니다. 화면에 표시되는 실제 굵기는 이 둘의 비율이 정합니다.

화면 굵기 = stroke-width ÷ viewBox × 표시 크기

여기가 함정이었습니다. 레지스트리에는 stroke-width 숫자만 보이는데, 같은 숫자여도 viewBox가 다르면 화면에서 다른 굵기로 보입니다. 그리고 아이콘은 대부분 w-4, 즉 16px로 표시합니다.

기존 규격은 「24 viewBox · stroke-width 1.5」였습니다. 이 값은 24px 표시를 전제한 것이어서, 실사용 크기인 16px에서는 1.0px의 가는 획으로 렌더되고 있었습니다.

굵기가 정해지는 경로

변경 전

변경 후

개념별 변경

아이콘 갤러리를 신설했습니다

docs/ko/design-system/resources/icons.md가 「준비 중」 스텁이어서, 등록된 아이콘을 훑어볼 방법은 packages/static/icons/*.svg 폴더를 파일 탐색기로 여는 것뿐이었습니다. DemoIconGallery.vue를 만들어 레지스트리를 빌드 시점에 그대로 불러와 그리드로 렌더합니다. 목록을 손으로 옮겨 적지 않으므로 아이콘을 등록하면 이 페이지도 자동으로 따라옵니다. 이름 검색과 12~24px 미리보기 크기 토글을 제공합니다.

이 PR의 나머지 항목은 전부 이 페이지를 보다가 찾은 것입니다.

굵기 규격을 16px 표시 기준으로 다시 정했습니다

획 기반 아이콘 124개의 화면 굵기를 실측하니 다섯 가지로 갈려 있었습니다. 16px 기준으로 1.00px이 88개, 1.12px이 3개, 1.20px이 7개, 1.33px이 24개, 1.50px이 1개였습니다.

원인은 하나였습니다. Heroicons v1 outline을 그대로 붙여넣은 것입니다. 그쪽 기본값이 stroke-width="2"인데 기존 규격은 1.5였습니다. ic-refresh는 path까지 원본과 바이트 단위로 동일했습니다.

새 규격은 「16px 표시에서 1.33px」 = 24 viewBox · stroke-width 2입니다. Heroicons와 Lucide가 쓰는 값과 같고, 레지스트리에서 이미 24개가 이 값이었습니다. viewBox가 24가 아니면 viewBox ÷ 12로 환산합니다.

적용은 stroke-width 숫자만 바꿨습니다. d 좌표를 건드리지 않으므로 도형이 깨질 위험이 없습니다. 123개가 단일 값으로 수렴했고, 굵은 링이 목적인 ic-spinner만 예외로 남겼습니다.

「채운 면」으로 그린 아이콘은 이 정규화를 피해 갔습니다

15개 아이콘은 획을 stroke가 아니라 가느다란 면을 채워서 그려져 있었습니다. stroke-width 속성이 아예 없으므로 위 정규화가 닿지 않습니다. 실측하니 organization 1.20px, workspace·team·signature 1.25px, money·setting 1.30px로 표준의 0.72~0.78배였습니다. 화면에서 이들만 얇아 보이던 이유입니다.

숫자를 고쳐서는 해결되지 않으므로 money·organization·workspace·team·signature를 stroke 기반으로 다시 그렸습니다. setting은 gear와 도형이 중복이었고 gear 쪽이 이미 표준 굵기였으므로, setting 이름을 유지한 채 도형을 gear 것으로 바꾸고 ic-gear를 삭제했습니다.

ic-chevron-down은 반대 방향이었습니다. 이것만 채운 면이라 나머지 세 방향보다 두꺼웠습니다. stroke 기반으로 바꿔 네 방향을 맞췄습니다.

같은 뜻이 두 이름으로 갈려 있던 것을 합쳤습니다

원 안의 i가 ic-info와 ic-info-circle-fill 두 이름으로, 원 안의 !가 ic-exclamation-circle과 그 fill로 있었습니다. ic-info를 ic-info-circle로 합쳐 호출 64곳을 옮겼습니다.

이름 규칙도 문서에 못박았습니다. ic-{의미}-{형태}-{채움} 순서이고 채움 자리는 fill일 때만 씁니다.

알림 아이콘을 심각도 3종으로 나눴습니다

위 통합 과정에서 ic-exclamation-circle을 ic-info-circle로 일괄 치환했는데, 그중 오류·경고 자리까지 함께 바뀌었습니다. 로그인 실패, 회원가입 오류, 연차 정책 불일치 같은 자리에서 빨간 상자 안에 안내 기호가 뜨는 상태가 됐습니다.

형태가 심각도를 나누도록 정리했습니다.

뜻	아이콘	모양	자리
오류	ic-exclamation-circle	원 + !	.ds-notice--danger
경고	ic-warning	삼각형 + !	.ds-notice--warning
안내	ic-info-circle	원 + i	.ds-notice--info·툴팁

되살린 ic-exclamation-circle은 ic-info-circle과 같은 원(r=9)·같은 굵기로 그리고 막대와 점만 상하 반전했습니다. 두 원이 한 가족으로 읽힙니다.

치환은 이름이 아니라 문맥으로 판정했습니다. 각 호출 지점의 앞 10줄에서 .ds-notice 변형을 찾아 danger면 느낌표, warning이면 삼각형으로 바꿨습니다. 그 덕에 근태 표 헤더의 툴팁 도움말 4곳은 순수 안내이므로 ic-info-circle-fill로 정확히 남았습니다. 결과 31곳을 고쳤고, 이 중 2곳은 develop 시점부터 이미 어긋나 있던 것입니다.

도형이 깨져 있던 아이콘을 수리했습니다

• ic-badge-check — path 끝의 호 4개가 통째로 빠져 도형이 닫히지 않았습니다. 시작점까지 대각선으로 이어져 씰의 한쪽이 잘려 보였습니다. 2026-08-10 최초 등록 때부터 그랬습니다.
• ic-lightbulb — 유리부 호의 현 길이가 11.54인데 반지름이 6이었습니다. 지름(12)에 근접한 값이라 원 둘레의 59%를 그리는 호가 되어 좌상단이 함몰됐습니다. 반지름 5.6의 정상 호로 다시 그렸습니다.
• ic-dots-grid — 이름과 다른 그림이었습니다. 실제로는 키보드였습니다(M11 14h2가 스페이스바). 이름대로 3×3 점 격자로 다시 그리고, 점 크기를 ic-dots-horizontal과 같은 구성으로 맞췄습니다.
• ic-party — 폭죽 파티클 좌표를 정리했습니다.

fill 변형을 늘렸습니다

하단 탭과 LNB의 활성 상태는 fill 변형을 씁니다. ic-bell·ic-camera·ic-cap·ic-employee·ic-folder·ic-star·ic-tag·ic-question-circle·ic-map-pin의 fill을 추가해 line↔fill 쌍이 18에서 25쌍이 됐습니다.

일괄 자동 생성은 시도했으나 채택하지 않았습니다. 획을 면으로 바꾸는 것을 fill-rule="evenodd"로 자동화해 17개를 돌렸더니 5개만 사용 가능했습니다. ic-clipboard-check는 조각만 남고, ic-approval은 검은 사각형이 되며, ic-search는 손잡이가 사라진 원이 됐습니다. 내부 디테일이 별도 <path>인 아이콘은 하나로 합치는 순간 형태가 무너집니다. 그래서 확대 렌더로 하나씩 확인해 통과한 것만 넣었습니다.

자동 생성분에는 크기 보정이 필요합니다. 획의 중심선을 쓰므로 좌우로 획 절반씩 잃어 일관되게 0.89~0.91배로 작게 나옵니다. 추가한 것 전부 viewBox를 계산해 1.00배로 맞췄습니다.

문서 데모가 아이콘을 손으로 베껴 쓰던 것을 바꿨습니다

디자인 시스템 문서의 데모 컴포넌트 7개가 아이콘 SVG를 레지스트리에서 복사해 들고 있었습니다. 사본이므로 등록본이 바뀌어도 문서만 옛 그림으로 남았고, 실제로 org가 2×2 격자, 총무의 ic-clipboard가 빈 사각형, 「수정」 버튼의 획 굵기가 2로 벌어져 있었습니다.

전부 getIcon('ic-…') 참조로 바꿔 이름만 남겼습니다. 브랜드 심볼과 표 정렬 화살표 두 가지는 예외로 사본을 유지합니다. 전자는 그라디언트 id가 문서 전역이라 한 페이지에 둘이 들어가면 충돌하고, 후자는 :d 런타임 바인딩이라 레지스트리 대상이 아닙니다.

검증 방법

check-icons.mjs가 핵심 게이트입니다. getIcon()은 없는 이름에 빈 문자열을 돌려주므로 오타 하나면 아이콘이 에러도 로그도 없이 사라집니다. 이름을 바꾸거나 지운 뒤에는 이 검사로 잔여 호출이 0인지 확인해야 합니다.

파생본(packages/static/icons/*.svg)은 pnpm icons:build로 갱신하고 pnpm icons:check가 레지스트리와의 일치를 확인합니다.