Home Assistant 브랜드 자산(아이콘/로고)를 공식/표준 방식 등록 절차

빠른 개요

• 저장소: home-assistant/brands (공식 브랜드 자산 저장소)
• 위치 규칙
  • 코어 통합: core_integrations/<domain>/
  • 커스텀 통합: custom_integrations/<domain>/
• 제공 파일(최대 8개)
  • 기본: icon.png, icon@2x.png, logo.png, logo@2x.png
  • 다크 테마: dark_icon.png, dark_icon@2x.png, dark_logo.png, dark_logo@2x.png
• URL 패턴 예
  https://brands.home-assistant.io/<domain>/icon.png
https://brands.home-assistant.io/<domain>/logo@2x.png … 등

이미지 규격·정책 체크리스트

1. 형식: PNG (투명 배경 권장), 무손실 최적화(예: optipng)
2. 아이콘(icon): 정사각형 1:1
   • 일반: 256×256
   • hDPI: 512×512 → 파일명 icon@2x.png
3. 로고(logo): 가로형 권장(브랜드 비율 유지)
   • 짧은 변 기준 일반: 128~256px
   • hDPI: 256~512px → 파일명 logo@2x.png
4. 다크 테마: dark_* 파일을 제공하면 다크 테마에서 우선 사용
5. 여백(패딩): 불필요한 투명 여백은 최소화(트리밍 권장)
6. 파일명: 정확히 위 규칙 준수(대소문자 포함)
7. 브랜드/상표: 사용 권한(라이선스/가이드) 확인 필수
8. 도메인 일치: 폴더명 <domain>은 manifest.json의 domain과 동일해야 함

폴백 규칙

logo.png가 없으면 icon.png가 로고로 폴백될 수 있음

• @2x가 없으면 일반 파일을 사용(고해상도에서 흐릿할 수 있음)

300x250

사전 준비 (도메인/리소스 확인)

• 통합의 manifest.json 예

  {
    "domain": "my_company",
    "name": "My Company",
    "version": "1.0.0",
    "documentation": "…",
    "requirements": [],
    "codeowners": ["@you"]
  }

• domain 값 = 브랜드 경로 폴더명 → custom_integrations/my_company/

로컬 제작 환경 준비(권장 도구)

# Ubuntu/Debian 기준
sudo apt-get update
sudo apt-get install -y git imagemagick optipng jq

# SVG → PNG로 변환이 필요하면(아이콘 소스가 SVG인 경우)
sudo apt-get install -y librsvg2-bin   # rsvg-convert 명령어 제공
# 또는 inkscape 사용 가능

저장소 포크 → 클론 → 브랜치 생성

# GitHub에서 home-assistant/brands 저장소를 '포크' 한 뒤 로컬에 클론
git clone https://github.com/<your-user>/brands
cd brands

# 작업 브랜치 생성
git checkout -b feat/add-my_company-brand

디렉터리 구성 & 파일 배치

1) 커스텀 통합(일반적으로 여기에 해당)

mkdir -p custom_integrations/my_company
# 준비한 원본 이미지 복사
cp ~/imgs/icon_256.png  custom_integrations/my_company/icon.png
cp ~/imgs/icon_512.png  custom_integrations/my_company/icon@2x.png
cp ~/imgs/logo_256w.png custom_integrations/my_company/logo.png
cp ~/imgs/logo_512w.png custom_integrations/my_company/logo@2x.png

# (선택) 다크 테마 최적화 버전
cp ~/imgs/dark_icon_256.png   custom_integrations/my_company/dark_icon.png
cp ~/imgs/dark_icon_512.png   custom_integrations/my_company/dark_icon@2x.png
cp ~/imgs/dark_logo_256w.png  custom_integrations/my_company/dark_logo.png
cp ~/imgs/dark_logo_512w.png  custom_integrations/my_company/dark_logo@2x.png

2) 코어 통합(코어에 병합된 통합인 경우)

mkdir -p core_integrations/my_core_domain
cp ~/imgs/icon_256.png  core_integrations/my_core_domain/icon.png
…

주의: 커스텀 경로에는 심볼릭 링크 사용 금지를 권장합니다(배포 시 실제 파일이 필요).

이미지 자동 보정/검증 스크립트(예시)

아래는 여백 제거, 크기 보정, 무손실 최적화, 치수 검증까지 한 번에 수행하는 예시입니다.

#!/usr/bin/env bash
set -euo pipefail

DOMAIN="my_company"
DIR="custom_integrations/${DOMAIN}"

# 1) 여백 제거 + 메타데이터 제거 + 인터레이스 적용
for f in icon.png icon@2x.png logo.png logo@2x.png dark_icon.png dark_icon@2x.png dark_logo.png dark_logo@2x.png; do
  [ -f "${DIR}/${f}" ] || continue
  magick "${DIR}/${f}" -trim +repage -strip -interlace PNG "${DIR}/${f}"
done

# 2) 크기 보정
# 아이콘: 256 / 512
[ -f "${DIR}/icon.png" ]     && magick "${DIR}/icon.png"     -resize 256x256\! "${DIR}/icon.png"
[ -f "${DIR}/icon@2x.png" ]  && magick "${DIR}/icon@2x.png"  -resize 512x512\! "${DIR}/icon@2x.png"

# 로고: 짧은 변 256 / 512 (비율 유지)
# 가로형 로고 가정: 짧은 변 기준으로 최소 크기 보정 (너무 작으면 키움)
resize_min () {
  local file="$1" short="$2"
  # 긴/짧은 변 판단 없이 "짧은 변 기준"으로만 최소 크기 보정
  magick "${file}" -resize "${short}x${short}>" "${file}"
}
[ -f "${DIR}/logo.png" ]     && resize_min "${DIR}/logo.png" 256
[ -f "${DIR}/logo@2x.png" ]  && resize_min "${DIR}/logo@2x.png" 512
[ -f "${DIR}/dark_logo.png" ]     && resize_min "${DIR}/dark_logo.png" 256
[ -f "${DIR}/dark_logo@2x.png" ]  && resize_min "${DIR}/dark_logo@2x.png" 512

# 3) @2x 없을 때 생성(권장: 직접 만든 고해상도 원본 사용)
if [ -f "${DIR}/icon.png" ] && [ ! -f "${DIR}/icon@2x.png" ]; then
  magick "${DIR}/icon.png" -resize 512x512\! "${DIR}/icon@2x.png"
fi
if [ -f "${DIR}/logo.png" ] && [ ! -f "${DIR}/logo@2x.png" ]; then
  magick "${DIR}/logo.png" -resize 512x512\> "${DIR}/logo@2x.png"
fi

# 4) 무손실 최적화
optipng -quiet -o7 "${DIR}"/*.png || true

# 5) 치수 검증 출력
echo "== Final sizes =="
identify -format "%f %wx%h\n" "${DIR}"/*.png

SVG → PNG 변환 예시

# SVG 아이콘을 PNG로(투명 배경), MDI 등 벡터 소스에 유용
rsvg-convert --width=256 --height=256 -o "${DIR}/icon.png" ~/svg/my_icon.svg
rsvg-convert --width=512 --height=512 -o "${DIR}/icon@2x.png" ~/svg/my_icon.svg

커밋·푸시·PR 생성

git add custom_integrations/my_company
git commit -m "Add brand assets for custom integration: my_company"
git push -u origin HEAD
# GitHub에서 Pull Request 생성 (base: upstream brands, compare: 본인 브랜치)

PR 설명 템플릿(예시)

• Integration domain: my_company
• Type: Custom integration
• Added files: icon.png, icon@2x.png, logo.png, logo@2x.png, dark_* 4종
• Image source: (공식 제공 로고/가이드 확인 완료)
• Notes
  • 아이콘/로고 크기 및 PNG 최적화 완료
  • 투명 배경, 여백 최소화
  • 상표/라이선스 준수 확인

리뷰 시 파일명/크기/형식을 중점 확인합니다. 필요 시 수정 커밋으로 반영하세요.

머지 후 반영·검증

• 캐시로 인해 반영이 즉시 보이지 않을 수 있습니다. (브라우저/네트워크 캐시)
• 표준 URL 패턴으로 접근해 이미지가 제공되는지 확인
  • /[domain]/icon.png
  • /[domain]/icon@2x.png
  • /[domain]/logo.png
  • /[domain]/logo@2x.png
  • /[domain]/dark_icon.png
  • /[domain]/dark_logo.png …
• Home Assistant Integrations 화면을 새로고침(앱/브라우저 캐시 영향 시 강력 새로고침)
• 내부 프록시/캐시 사용 시 무효화 정책에 따라 갱신 확인

자주 발생하는 문제(해결 가이드)

1. 도메인 불일치: 폴더명과 manifest.json의 domain이 다르면 미노출
2. 파일명 오타: icon@2x.png 철자/대소문자 오류 → hDPI 미적용
3. 해상도 미확보: 아이콘 256/512, 로고 짧은 변 256/512 규칙 미준수
4. 불필요한 여백 과다: 작은 사이즈에서 흐릿/작게 보임 → 트리밍
5. JPG 업로드: PNG만 허용(투명/아이콘 가독성 이슈)
6. 다크 테마 미구현: dark_* 미제공 시 밝은 로고가 어둠 속에 묻힘
7. 브랜드 가이드 위반: 컬러/세이프존/비율 임의 변경 → 반려 가능
8. 커스텀 통합에 HA 로고 사용: 오인 소지 → 금지
9. PR 설명 부실: 출처·권한·변경 요약 미기재 → 리뷰 지연
10. 캐시 오판: “안 바뀐다” → 캐시 클리어/시간 경과 후 재확인

거버넌스 체크리스트

• 상표/라이선스 준수: 공식 가이드/라이선스 확인, 사내 법무 승인 절차
• 무결성 관리: PR 리뷰·승인 플로우 필수, 변경 이력 기록
• 권한 최소화: 저장소 쓰기 권한 최소, 2FA/GPG 서명 커밋 권장
• 콘텐츠 검증: 악성/스테가노 등 의심 파일 차단(내부 백신/EDR 스캔)
• 릴리즈 커뮤니케이션: 반영 지연(캐시) 안내, 롤백 시나리오(원복 PR/재배포)

도메인만 넣으면 8종 이미지(필수/선택)를 정리해주는 원클릭 스크립트(예시)

#!/usr/bin/env bash
# usage: ./prepare_brand.sh <domain> <src_icon_svg_or_png> <src_logo_png> [--dark-icon <png>] [--dark-logo <png>]
set -euo pipefail

DOMAIN="${1:?domain required}"
SRC_ICON="${2:?icon svg/png required}"
SRC_LOGO="${3:?logo png required}"
DARK_ICON="${4-}"
DARK_LOGO="${5-}"

ROOT="custom_integrations/${DOMAIN}"
mkdir -p "${ROOT}"

need() { command -v "$1" >/dev/null 2>&1 || { echo "need $1"; exit 1; }; }
need magick; need optipng

to_png_256_512 () {
  local src="$1" base="$2"
  if [[ "${src}" == *.svg ]]; then
    need rsvg-convert
    rsvg-convert --width=256 --height=256 -o "${ROOT}/${base}.png"    "${src}"
    rsvg-convert --width=512 --height=512 -o "${ROOT}/${base}@2x.png" "${src}"
  else
    magick "${src}" -resize 256x256\! "${ROOT}/${base}.png"
    magick "${src}" -resize 512x512\! "${ROOT}/${base}@2x.png"
  fi
  magick "${ROOT}/${base}.png"    -trim +repage -strip -interlace PNG "${ROOT}/${base}.png"
  magick "${ROOT}/${base}@2x.png" -trim +repage -strip -interlace PNG "${ROOT}/${base}@2x.png"
}

# 1) icon
to_png_256_512 "${SRC_ICON}" "icon"

# 2) logo (가로형 가정: 짧은 변 기준)
cp "${SRC_LOGO}" "${ROOT}/logo.png"
magick "${ROOT}/logo.png" -trim +repage -strip -interlace PNG -resize '256x256>' "${ROOT}/logo.png"
magick "${ROOT}/logo.png" -resize '512x512>' "${ROOT}/logo@2x.png"

# 3) dark variants (선택)
if [[ -n "${DARK_ICON}" && -f "${DARK_ICON}" ]]; then
  cp "${DARK_ICON}" "${ROOT}/dark_icon.png"
  magick "${ROOT}/dark_icon.png" -trim +repage -strip -interlace PNG -resize 256x256\! "${ROOT}/dark_icon.png"
  magick "${ROOT}/dark_icon.png" -resize 512x512\! "${ROOT}/dark_icon@2x.png"
fi
if [[ -n "${DARK_LOGO}" && -f "${DARK_LOGO}" ]]; then
  cp "${DARK_LOGO}" "${ROOT}/dark_logo.png"
  magick "${ROOT}/dark_logo.png" -trim +repage -strip -interlace PNG -resize '256x256>' "${ROOT}/dark_logo.png"
  magick "${ROOT}/dark_logo.png" -resize '512x512>' "${ROOT}/dark_logo@2x.png"
fi

# 4) 최적화 & 결과
optipng -quiet -o7 "${ROOT}"/*.png || true
echo "== ${ROOT} 완료 =="
identify -format "%f %wx%h\n" "${ROOT}"/*.png

사용 예시

./prepare_brand.sh my_company ./src/my_icon.svg ./src/my_logo.png \
  ./src/dark_my_icon.png ./src/dark_my_logo.png

커밋 → PR → 반영 확인(예시 흐름)

1. git add custom_integrations/my_company && git commit -m "Add my_company brand"
2. git push 후 PR 생성
3. 리뷰 피드백 반영(파일명/크기/여백/색상 대비 등)
4. 머지 후 캐시 고려하여 표준 경로(…/<domain>/icon.png 등)로 확인
5. Home Assistant Integrations 화면 새로고침/앱 재실행으로 최종 검증

핵심만 다시 정리

• 도메인 폴더명 = manifest.json의 domain
• PNG + 아이콘 256/512, 로고 짧은 변 256/512
• 다크 테마는 dark_*로 별도 제공
• 여백 최소화, 투명 배경, 무손실 최적화
• 포크 → 브랜치 → 파일 추가 → PR → 머지
• 캐시로 인한 지연을 감안하여 확인