​

커스텀 아이콘 적용 스킬

​

적용 원칙

• 로컬 images/ 추가 금지 규칙의 예외는 로고·아이콘 등 정적 자산입니다. 스크린샷은 계속 외부 URL을 사용합니다.
• 브랜드 컬러를 고정하지 않습니다. 사용자가 명시하지 않으면 기존 사이드바 비활성 아이콘 톤에 맞춥니다.
• 커스텀 SVG는 Mintlify 사이드바에서 <img>로 렌더링되므로 currentColor 자동 상속을 기대하지 않습니다.
• active 상태 색상은 SVG 내부가 아니라 전역 style.css에서 #sidebar-content li[data-active] selector로 보정합니다.
• style.css는 저장소 루트에 두면 Mintlify가 자동 로드합니다. docs.json에 css 키를 추가하지 않습니다.
• 같은 SVG를 본문 <Card icon="/images/icons/{slug}.svg">로도 쓸 수 있습니다(ko/introduction.mdx, ko/default-agent-setup.mdx, ko/agents-and-bots.mdx 사례). 다만 위 CSS 보정은 사이드바 전용이라 본문 카드에는 적용되지 않습니다.
• 공식 아이콘은 공식 사이트·공식 GitHub·Simple Icons 등 1차 또는 준공식 출처를 확인합니다. 출처가 불명확하면 적용 전에 확인합니다.

​

작업 절차

1. 대상 페이지 확인
   • 대상 MDX의 frontmatter icon 값을 확인합니다.
   • 같은 그룹의 다른 페이지 아이콘 톤을 확인합니다.
   • 예: ko/linear.mdx, ko/mcp.mdx.
2. SVG 자산 추가
   • 경로는 images/icons/{slug}.svg를 사용합니다.
   • 기본 SVG 색상 구조:

<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <title>Icon Name</title>
  <style>
    path { fill: #A0A0A0; }
    @media (prefers-color-scheme: dark) {
      path { fill: #707070; }
    }
  </style>
  <path d="..." />
</svg>

• SVG가 path가 아닌 circle, rect, line, polyline 등을 쓰면 style selector를 해당 요소에 맞게 조정합니다.
• stroke 기반 아이콘은 stroke 색상도 함께 처리하거나 fill 기반 SVG로 정리합니다.

3. 페이지 frontmatter 변경

---
title: '...'
description: '...'
icon: '/images/icons/{slug}.svg'
---

4. active 상태 CSS 보정
   • style.css가 없으면 저장소 루트에 만듭니다.
   • 기존 selector가 있으면 중복 블록을 만들지 말고 selector 목록에 추가합니다.

#sidebar-content li[data-active] img[src$="/images/icons/{slug}.svg"] {
  filter: brightness(0);
}

html.dark #sidebar-content li[data-active] img[src$="/images/icons/{slug}.svg"] {
  filter: brightness(0) invert(1);
}

• 여러 커스텀 아이콘이 있으면 다음처럼 합칩니다. (현재 style.css의 실제 내용입니다 — 아이콘을 추가할 때 이 selector 목록에 한 줄씩 더합니다.)

#sidebar-content li[data-active] img[src$="/images/icons/linear.svg"],
#sidebar-content li[data-active] img[src$="/images/icons/mcp.svg"],
#sidebar-content li[data-active] img[src$="/images/icons/openclaw-hermes.svg"] {
  filter: brightness(0);
}

html.dark #sidebar-content li[data-active] img[src$="/images/icons/linear.svg"],
html.dark #sidebar-content li[data-active] img[src$="/images/icons/mcp.svg"],
html.dark #sidebar-content li[data-active] img[src$="/images/icons/openclaw-hermes.svg"] {
  filter: brightness(0) invert(1);
}

​

검증 절차

1. 로컬 프리뷰 확인
   • 이미 mintlify dev가 떠 있으면 해당 URL을 사용합니다.
   • 없으면 저장소 루트에서 npx mintlify dev를 실행합니다.
2. Playwright 또는 브라우저 검사로 DOM 확인
   • active 페이지에서 대상 아이콘이 <img src="/images/icons/{slug}.svg">로 렌더링되는지 확인합니다.
   • active 상태에서 계산된 filter가 라이트 모드 brightness(0)인지 확인합니다.
   • html.dark 클래스를 임시 적용했을 때 brightness(0) invert(1)인지 확인합니다.
   • 다른 페이지에서 대상 아이콘이 inactive일 때 filter: none인지 확인합니다.
3. 부산물 정리
   • Playwright가 만든 .playwright-mcp/ 스냅샷은 작업 산출물이 아니면 삭제합니다.
   • 사용자나 기존 도구가 만든 무관한 변경은 되돌리지 않습니다.

​

완료 보고