service-icon

name	service-icon
description	LinKHU에 새 서비스 아이콘을 만들 때 사용. 기존 아이콘의 실측된 도안 규칙(70x70, 선 두께, 색, 여백)에 맞춰 SVG로 그린 뒤 라이트·다크 두 벌 PNG로 내보내고 검증한다. "아이콘 만들어줘", "서비스 추가하고 아이콘 그려줘", "아이콘 스타일 맞춰줘" 같은 요청에 사용.

서비스 아이콘 만들기

새 서비스를 src/data.js에 추가할 때 아이콘도 함께 만든다. 아이콘은 라이트·다크 두 벌이 필요하다.

기존 자산과 어긋나면 격자 안에서 혼자 튄다. 아래 도안 규칙은 2026-08-27 대량 추가 직전의 기존 117개를 실측해 뽑은 값이므로 추정으로 바꾸지 말고 그대로 따른다.

실측된 도안 규칙

항목	값	비고
캔버스	70×70 px	실측 당시 117개 전부 동일. 예외 없음
배경	투명	두 벌 모두
여백	0~4 px	중앙값 1 px. 도안이 캔버스를 거의 채운다
내용 면적	캔버스의 22~50%	중앙값 34%
선 두께	3 px 내외	70 px 래스터 기준 중앙값 3, 사분위 2~3
붉은색 비중	내용의 8~43%	중앙값 23%. 강조로 쓰고 전면에 깔지 않는다

선 두께 3 px은 70 px 캔버스의 약 4.3%다. 팝업의 40 px에서는 약 1.7 px, 설정의 24 px에서는 약 1 px로 보인다. 기존 단과대·학과 아이콘이 이 굵기를 사용하므로 새 아이콘도 이를 기준으로 삼는다. 2 px보다 얇은 보조선은 24 px에서 사라질 수 있으므로 핵심 실루엣에 쓰지 않는다.

색

SVG에 적는 값은 라이트 벌 기준 하나뿐이다. 다크 벌은 생성기가 만든다.

팔레트는 세 가지뿐이다 — 브랜드 레드, 검정, 투명. 값의 원본은 spec/3-2-DESIGN-UI-RULES.md §3-2-4다.

용도	SVG에 적는 값	다크 벌
선화·본체	검정	생성기가 무채색으로 대체
강조	브랜드 레드	생성기가 붉은색으로 대체
그 밖	투명	투명

두 열의 실제 hex는 모두 스펙 §3-2-4에 있다.

• 값을 여기에 적지 않는다. 스펙이 원본이고 값이 바뀐 이력이 있다. 두 곳에 적으면 갈라진다(이슈 #106이 그 사례다).
• 회색을 쓰지 않는다 (MUST). 회색은 팔레트에 없다.
• 회색·검정으로 넓은 면을 채우지 말고 선화로 그린다 (MUST). 예전 아이콘들은 면을 낮은 불투명도의 무채색으로 채웠는데, 흰 배경에서 회색으로 합성되어 카테고리마다 톤이 어긋났다. 전량 정합했고 경과는 스펙 §3-3-17에 있다. 작은 빨간 강조 면은 허용하지만 전체 실루엣을 빨강으로 채우지 않는다.
• 경계 안티에일리어싱은 검정의 알파로만 표현한다. 이 픽셀이 흰 배경에서 회색으로 보이는 것은 정상이며, 회색 금지는 면에 대한 규칙이다.
• 다크 두 값도 스펙 §3-2-4가 원본이다. SVG에 다크 색을 적지 말고 npm run generate:dark-icons에 맡긴다.
• 다크 두 색은 다크 카드 위에서 비텍스트 기준 3:1을 넘는다. 실측 대비는 스펙 §3-2-4에 있다.

빨강을 왜 두 값으로 나누는가 — 진한 라이트용 빨강은 다크 배경에서 2점대로 묻히고, 밝은 다크용 빨강은 라이트 배경에서 대비가 얕다. 한 값으로 양쪽을 만족시키려면 중간 톤이 되어 라이트가 원래 대비를 크게 잃는다. 실패 경과는 spec/3-3-DESIGN-DECISIONS.md §3-3-16에 있다.

⚠️ 저장된 PNG의 픽셀값은 SVG에 적은 값과 다르다

생성기가 흰 배경을 걷어내며 알파를 역산하므로, 저장된 라이트 PNG에는 언프리멀티플라이된 값이 들어간다.

현재 값을 예로 들면 이렇다(값 자체는 스펙이 원본이다).

SVG에 #a40f16  →  저장된 PNG는 #9e0007 알파 240  →  흰 카드 위에서 다시 #a40f16

PNG를 grep해서 브랜드 레드가 있는지 확인하려 하지 마라. 0개로 나온다. 확인하려면 흰 배경과 합성한 값을 계산한다.

만드는 순서

1. SVG로 그린다

<svg xmlns="http://www.w3.org/2000/svg" width="70" height="70" viewBox="0 0 70 70">
  <g fill="none" stroke="<스펙 §3-2-4의 검정>" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
    <!-- 도안 -->
  </g>
  <path d="..." fill="<스펙 §3-2-4의 브랜드 레드>"/>
</svg>

원본은 design/icons/<카테고리>/<id>.svg에 남긴다. 색 규칙이 바뀌면 다시 내보내면 된다.

src/ 안에 두지 않는다. scripts/package-extension.js는 src/ 아래 모든 파일을 확장 패키지에 넣으므로, SVG가 그 안에 있으면 확장에 함께 배포된다.

2. 70×70 PNG로 내보낸다

의존성을 추가하지 않고 macOS 기본 도구만 쓴다.

qlmanage -s 는 SVG를 확대하지 않는다. SVG를 고유 크기(width/height)로 그린 뒤 캔버스만 키우므로, -s 70으로 뽑으면 작은 그림이 큰 여백 안에 놓인다. width/height를 키운 사본을 만들어야 한다.

ID=aikhu; CAT=common
SVG=design/icons/$CAT/$ID.svg

# width/height만 280으로 키운 임시 사본 — viewBox는 0 0 70 70 그대로 둔다
sed 's/width="70" height="70"/width="280" height="280"/' "$SVG" > /tmp/$ID-280.svg

qlmanage -t -s 280 -o /tmp /tmp/$ID-280.svg
sips -z 70 70 "/tmp/$ID-280.svg.png" --out "src/images/$CAT/$ID.png"

280으로 뽑아 70으로 줄이는 이유는 경계 안티에일리어싱을 얻기 위해서다. 70에서 바로 뽑으면 선이 거칠다.

내보낸 결과는 흰 배경 불투명 PNG다. 다음 단계에서 생성기가 걷어낸다.

헤드리스 Chrome(--screenshot)으로도 되지만 이 저장소에서 검증하지 않았다. 위 절차를 먼저 쓴다.

3. 두 벌을 만든다

npm run generate:dark-icons

• 라이트 원본의 흰 배경을 걷어내고
• src/images/dark/<카테고리>/<id>.png에 다크 벌을 생성한다

다크 아이콘을 손으로 그리거나 고치지 않는다. 다음 실행에 덮인다.

<카테고리>는 common / colleges / departments 중 하나다. 이 폴더 이름은 파일을 나눠 담는 관례일 뿐 데이터의 category 값과 대응하지 않는다 (스펙 §4-2). 단과대는 colleges, 학과는 departments, 나머지 주제 카테고리는 전부 common에 둔다.

4. 데이터에 등록한다

src/data.js의 MASTER_SITE_LIST에 추가한다. imgSrc는 라이트 경로만 적는다 — 다크 경로는 코드가 규칙으로 파생한다.

{ id: "aikhu", name: "AiKHU", url: "https://dx.khu.ac.kr/aimentoring.html",
  imgSrc: "images/common/aikhu.png", category: "교육·역량" }

규칙은 spec/4-DATA.md를 따른다.

5. 검증한다

npm run generate:landing-data   # 랜딩 사본과 검색 데이터 동기
npm run build                   # 테스트 + 데이터·두 벌 짝·랜딩 검증 + 패키징

위의 도안 규칙을 눈대중으로 맞추지 말고 실측한다. 표의 외곽·잉크·붉은 비중은 재보지 않으면 맞는지 알 수 없다. 눈으로는 멀쩡해 보이던 도안이 세로 46 px로 나온 적이 있다(이슈 #186).

python3 - <<'EOF'
from PIL import Image
def stat(p):
    im = Image.open(p).convert("RGBA"); w, h = im.size; px = im.load()
    xs = []; ys = []; ink = 0; red = 0
    for y in range(h):
        for x in range(w):
            r, g, b, a = px[x, y]
            if a > 20:
                xs.append(x); ys.append(y); ink += 1
                if r > 110 and g < 90 and b < 90: red += 1
    return max(xs)-min(xs)+1, max(ys)-min(ys)+1, ink*100.0/(w*h), red*100.0/ink

print("목표   외곽 58~66   잉크 22~35%   붉은 15~25%")
for name in ["<id>"]:                      # 잰 아이콘 id로 바꾼다
    bw, bh, ink, red = stat(f"src/images/common/{name}.png")
    print(f"{name}  {bw}x{bh}  {ink:.1f}%  {red:.1f}%")
EOF

⚠️ 3단계(generate:dark-icons)를 돌린 뒤에 재라. 2단계에서 나온 PNG는 흰 배경이 불투명하다. 그대로 재면 잉크가 100%, 외곽이 70×70으로 나와 아무것도 알 수 없다.

그리고 눈으로 확인한다. 계산만으로는 안 보이는 문제가 있다.

• chrome://extensions에서 src/를 로드해 팝업(40 px)과 설정(24 px)에서 본다.
• 테마를 바꿔 두 벌 모두 확인한다. 다크에서 안 보이는 아이콘이 가장 흔한 실패다.
• 24 px에서 형태가 뭉개지지 않는지 본다. 세부가 많으면 단순화한다.

도안 원칙

• 주 상징 하나 + 보조 단서 1~2개. 기존 단과대·학과 아이콘은 학문·공간·도구 같은 단서를 작은 삽화처럼 조합한다. 주 상징은 3 px로 먼저 읽히게 하고 보조 단서는 2 px 내외로 둔다. 글자나 서비스와 무관한 장식은 넣지 않는다.
• 캔버스를 충분히 채운다. 기존 단과대·학과 94개의 내용 경계 중앙값은 65×63 px, 잉크 점유율은 28.7%다. 새 도안은 외곽이 대체로 5866 px 안에 들고 잉크 점유율 2235%를 목표로 한다. 작은 기호 하나를 중앙에 놓아 넓게 비우지 않는다.
• 강조는 한두 곳에. 붉은색을 도안 전체에 쓰지 않는다. 기존 단과대·학과의 붉은 픽셀 비중 중앙값은 내용의 22.8%다. 대체로 15~25% 안에서 선이나 작은 면으로 쓴다.
• 같은 계열 서비스는 같은 상징 계열로. 단과대는 건물·학문 상징, 교내 주제별 서비스는 기능 상징을 쓴다.
• 대학 로고·휘장을 쓰지 않는다. LinKHU는 경희대학교 공식 산출물이 아니다 (스펙 §3-2-1).
• 서비스가 다르면 아이콘도 다르게 만든다. 여러 서비스가 한 아이콘을 공유하면 팝업 격자에서 구분이 안 된다.
• 같은 계열 두 개를 한 번에 만들 때는 주 상징 자체를 가른다 (MUST). 계열을 맞추려다 같은 실루엣에 안쪽 기호만 바꾸면 40 px에서 두 칸이 같아 보인다. 계열감은 선 두께와 밀도가 이미 만들어 주므로 실루엣까지 같을 필요가 없다. 경희사이버대 포털·LMS를 처음에 같은 노트북으로 그렸다가 다시 그린 경과가 이슈 #186에 있다.

예시

서비스	주 상징 (3 px)	보조 단서 (2 px)	강조	실측 (외곽 / 잉크 / 붉은)
AiKHU	말풍선	좌우 노드와 연결선	붉은 4각 스파클	—
AI Hub	중심 노드	위성 노드 3개 연결	붉은 중심	—
경희사이버대 포털	아치형 관문	안쪽 아치, 좌우 가로선	붉은 열쇠구멍	59×56 / 24.3% / 17.3%
경희사이버대 LMS	화면과 받침	와이파이 호 2개, 다리	붉은 재생 버튼	59×52 / 22.4% / 16.3%

선 굵기만 따르지 말고 삽화 밀도와 캔버스 점유 기준을 5단계에서 실제로 재서 확인한다.

하지 말 것

• filter: invert()로 다크를 만들지 않는다. 명도를 뒤집으면 진한 빨강이 핑크가 되고, 필터는 요소 전체에 걸려 선화만 골라 처리할 수 없다.
• 아이콘 뒤에 밝은 타일을 깔지 않는다. 다크 화면에서 흰 상자가 격자마다 박혀 눈부시다.
• 한 벌로 두 테마를 겸하지 않는다. 양쪽 하한에 끼어 중간 톤만 남고 라이트가 대비를 잃는다.

세 방식 모두 시도했다가 폐기했다. 경과와 실측은 스펙 §3-3-16에 있다.