Abhijit-Jha/icon-skill

Icon Forge

전문가 수준의 일관된 아이콘 세트처럼 보이는 사용자 정의 아이콘을 그리고, 런타임 의존성 없이 제공합니다. 모든 아이콘이 린트를 통과하고, 16/20/24px 미리보기를 직접 보고 밝은/어두운 배경에서 명확하고 일관되게 읽히며, 생성된 컴포넌트가 접근성 있는 방식으로 연결되면 작업이 완료됩니다.

<skill>은 이 파일이 위치한 폴더(예: .claude/skills/icon-forge, .cursor/skills/icon-forge, .agents/skills/icon-forge)를 의미합니다. 스크립트는 Node ≥18이 필요하며 프로젝트 의존성은 없습니다.

사용 시기 / 사용하지 말아야 할 때

• 사용: 사이드바, 네비게이션 바, 대시보드, 설정 페이지, 빈 상태(empty state), 툴바에 아이콘이 필요할 때; 사용자가 사용자 정의 아이콘이나 누락된 아이콘을 요청할 때; 사용자가 이모지/플레이스홀더 아이콘이나 무거운 아이콘 패키지를 작은 자체 세트로 교체하려 할 때.
• 사용하지 말 것: 로고 및 브랜드 마크(상표; 디자이너 필요), 파비콘/앱 아이콘, 일러스트레이션 또는 스팟 아트, 사진/래스터, 애니메이션 Lottie. 사용자가 라이브러리 설치를 명시적으로 요청하면(예: "그냥 Lucide 써"), 그 요청을 따릅니다. 이 스킬은 사용자 정의 경로를 위한 것입니다.

엄격한 규칙(그 이유)

1. 모든 아이콘을 직접 그리고, 아이콘 라이브러리 의존성을 추가하지 마십시오. 사용자는 번들 크기와 독특한 디자인을 위해 자체 아이콘을 선택했습니다. Lucide, Heroicons, Material 등의 경로 데이터를 붙여넣지 마십시오(라이선스 및 독창성 문제). 기하학 시작점으로 references/glyph-cookbook.md(원본 그림)를 사용하세요.
2. 프로젝트에서 이미 아이콘 라이브러리를 사용한다면, 그리드, 선 두께, 캡 및 반경을 일치시키십시오(scripts/detect.mjs 및 디자인 규칙 §10 참조). 새 아이콘은 기존 아이콘 옆에 어색하지 않게 배치되어야 합니다.
3. 하나의 세트, 하나의 스타일. 모든 아이콘에 대해 동일한 그리드, 선 두께, 캡/조인, 반경 스케일, 패딩, 세부 수준을 유지하십시오. 일관성은 어떤 하나의 교묘한 아이콘보다 중요합니다.
4. 프레젠테이션 속성은 루트 <svg>에만 위치하고, 색상은 currentColor이며, 소스에는 id, 스타일, 클래스, 변환, <g>가 포함되지 않습니다. 그렇지 않으면 테마, 다크 모드, strokeWidth 프로퍼티, 인라인 처리가 깨집니다.
5. 렌더링하고 PNG를 보지 않고 아이콘이 좋다고 말하지 마십시오. 코드상으로 올바르게 보이는 기하학은 16px에서 종종 실패합니다: 덩어리, 닫힌 틈, 중심이 맞지 않는 모양, 일치하지 않는 두께.
6. 스크립트를 실행하고, 직접 구현하지 마십시오. 린트, 최적화, 미리보기, 코드 생성은 결정론적입니다. 생성된 파일을 직접 편집하지 말고 icons/src/를 변경하고 다시 빌드하십시오.
7. 사용자의 의존성을 수정하지 마십시오. 미리보기 도구는 ~/.cache/icon-forge에 설치되고(--install), SVGO는 없으면 npx로 실행됩니다. 프로젝트에 패키지를 추가하기 전에 먼저 물어보십시오.
8. 기본적으로 접근성을 제공합니다. 아이콘은 레이블이 없으면 aria-hidden 처리되고, 아이콘 전용 컨트롤에는 aria-label이 있으며, 대화형 타겟은 ≥44px이고, 의미 있는 아이콘은 ≥3:1 대비를 가집니다.

작업 흐름

1. 스택 및 기존 스타일 감지

node <skill>/scripts/detect.mjs .

프레임워크, TypeScript, Tailwind, 아이콘 라이브러리(및 해당 스타일 프리셋), 로컬 SVG 아이콘, 제안된 출력 디렉토리를 확인하십시오. 기존 세트가 있다면 해당 SVG 중 2~3개를 열고 루트의 숫자를 복사하십시오. 그렇지 않으면 기본값(24 그리드, 선 두께 2, 라운드 캡/조인)을 사용하십시오.

2. 목록 계획: 의미 → 은유 → 파일 이름

드로잉 전에 간단한 표를 작성하십시오: 레이블 | 은유(그릴 대상) | 파일 이름 | 쿡북 시작점. 예시: Projects | 칸반 보드 | kanban.svg | kanban. 주류 은유(디자인 규칙 §7)를 선택하고 의미당 하나의 은유를 사용하십시오. 파일 이름은 대상 객체를 케밥-케이스로 지정하십시오. 레이블이 모호하고 선택이 UI 의미를 바꾸는 경우에만 사용자에게 질문하고, 그렇지 않으면 결정하고 선택을 명시하십시오.

3. 24 그리드 위에 그리기

icons/src/<name>.svg를 표준 루트(svg-code-rules.md)로 생성하십시오. 각 아이콘에 대해:

• 일치하는 키라인에서 시작하십시오: 원(r10), 사각형(18, x/y 3), 세로형(16×20), 가로형(20×16). 키라인은 선의 중심선입니다.
• 선의 바깥쪽 가장자리가 캔버스 가장자리로부터 ≥1 유닛 떨어지도록 유지하십시오. 큰 모서리에는 반경 2를, 작은 모서리에는 1~1.5를 사용하고, 간격은 ≥2 유닛의 여백을 유지하십시오.
• 부품은 정확히 연결하거나 명확한 간격을 유지하십시오. 2px 선에는 정수 좌표를 사용하십시오. 가능한 한 적은 요소를 사용하십시오(일반적으로 ≤6).
• 가장 가까운 references/glyph-cookbook.md 항목에서 시작하여 적응시키십시오. 글리프가 그대로 맞으면 <skill>/assets/cookbook/<name>.svg에서 기하학을 복사하십시오.
• 반복되는 기하학(톱니, 광선, 별모양 점)은 추측 대신 몇 줄의 JS로 계산하십시오. 전체 세트를 먼저 그린 다음, 다듬으십시오. 일관성은 나란히 비교하여 판단합니다.

4. 린트

node <skill>/scripts/lint.mjs icons/src

모든 ✖를 수정하십시오. ⚠ gap, density, scale, bounds는 잡음이 아니라 수정해야 할 디자인 문제로 취급하십시오. 각 ℹ gap을 기록하고 6단계에서 확인하십시오. 16px에서 뻣뻣한 평행 선(막대, 선)은 4유닛 이상 떨어져 있지 않으면 번집니다. 정당화할 수 없는 경고 없이 PASS가 표시될 때까지 다시 실행하십시오. 플래그: --grid, --padding, --mode fill, --strict, --json.

5. 최적화

node <skill>/scripts/optimize.mjs icons/src icons/svg

이 명령은 숫자를 반올림하고, SVGO를 실행하며(로컬 설치 또는 npx svgo@4, 오프라인에서는 내장 canonicalizer로 대체), 루트 속성을 재정렬하고, 아이콘당 바이트와 총 gzip 크기를 출력합니다. 출력도 린트하십시오: node <skill>/scripts/lint.mjs icons/svg.

6. 미리보기 및 확인, 그리고 반복

node <skill>/scripts/preview.mjs icons/svg --out icons/preview.png \
  --sidebar "dashboard:Dashboard,kanban:Projects" --active dashboard   # PNG 엔진이 없으면 처음에는 --install 추가

이미지 뷰어로 PNG를 다음 순서로 확인하십시오:

1. icons/[email protected]: 세트 스트립과 사이드바 모형. 충분히 작아서 전체 세부 사항을 볼 수 있습니다.
2. icons/[email protected]: 각 크기의 모든 아이콘과 검사 뷰. 이미지가 길므로 뷰어가 축소하면 잘라서 보십시오.
3. icons/preview.png: 진짜 1× 픽셀.

함께 보여주는 것:

• 24/16px 스트립(밝은/어두운 배경);
• 활성 항목과 접힌 레일이 있는 사이드바 모형;
• 16/20/24/48 크기의 아이콘별 행;
• 그리드, 파란색 키라인, 빨간색 1px 패딩 제한이 있는 4× 검사 뷰.

디자인 규칙 §12의 자기 검토 질문에 답하십시오. 일반적인 수정 사항:

발견 상황	수정 방법
스트립에서 아이콘 하나가 더 가볍거나 작게 보임	키라인까지 확장하거나 프레임/축 추가(열린 글리프는 가볍게 읽힘)
하나가 더 무겁거나 복잡해 보임	세부 사항 제거; ≤3개 막대, ≤6개 톱니, ≤2개 텍스트 줄
16px에서 부품이 만나는 부분이 번짐	정확히 연결하거나 간격을 ≥2 유닛으로 늘림
검사 뷰에서 모양이 한쪽으로 치우침	다시 중앙 정렬하거나 광학적 균형을 위해 0.5–1 유닛 이동
접힌 레일에서 은유가 불명확함	더 직관적인 은유 선택(2단계)

36단계를 두 번째 확인에서 수정할 사항이 없을 때까지 반복하십시오. 보통 13회 반복합니다.

7. 프레임워크 출력 생성

node <skill>/scripts/build.mjs icons/svg --out src/components/icons --framework react --lang ts \
  --labels "kanban:Projects,dashboard:Dashboard"

--framework react|vue|svelte|html|all; --lang ts|js; --package @app/icons는 sideEffects:false package.json을 씁니다. 출력은 아이콘당 하나의 트리 셰이커블 모듈, 공유 기본 컴포넌트(size, color, strokeWidth, absoluteStrokeWidth, title, className), index 명명된 내보내기, icons.json입니다. HTML은 sprite.svg + usage.html을 제공합니다. 자세한 내용: references/output-formats.md.

그런 다음 프로젝트에 스크립트가 있으면 타입 체크 또는 빌드(npx tsc --noEmit, npm run build)하여 오류를 수정하십시오.

8. 접근성 있는 방식으로 연결

references/accessibility-and-usage.md의 패턴을 사용하십시오:

• <nav aria-label>; 활성 항목에는 aria-current="page"와 색상 및 배경;
• 아이콘은 size-5 shrink-0이며 장식용;
• 아이콘 전용 버튼에는 aria-label; 로그아웃은 <button>;
• ≥44px 행; 3:1 대비를 유지하는 무채색.

출력 형식

사용자에게 짧은 보고서로 마무리하십시오:

1. 아이콘: 표 레이블 → 컴포넌트 → 은유 및 폴더 경로(icons/src, icons/svg, 생성된 디렉토리).
2. 검사: 린트 결과(오류/경고), 최적화 합계(평균 B/아이콘, gzip 총합), 그리고 검사한 미리보기 경로와 확인 후 변경한 사항.
3. 사용법 스니펫: 해당 프레임워크에 맞게, a11y 속성 포함.
4. 참고 사항: 스타일 결정(일치시킨 그리드/선 두께/프리셋), RTL 아이콘 미러링 필요 여부, 확인할 수 없는 사항.

예시

사용자: "Next.js + Tailwind 앱에 Dashboard, Projects, Team, Settings용 사이드바 아이콘이 필요해." → detect: React (Next) + TS + Tailwind, 아이콘 라이브러리 없음 → plan: dashboard/tiles, kanban, users, settings/gear → cookbook에서 그리고 적응 → lint PASS → optimize: 4개 아이콘, 평균 ~340 B, ~0.4 KB gzip → preview: Projects가 가볍게 보여서 막대 추가; 재확인 → build --framework react into src/components/icons → <DashboardIcon className="size-5 shrink-0" />을 nav에 aria-current와 함께 배치.

참고 자료

다음이 필요할 때…	읽을 문서
크기, 키라인, 반경, 간격, 은유 선택 또는 미리보기 문제 수정	references/design-rules.md
SVG 마크업 작성 또는 디버깅, 린트 오류 이해	references/svg-code-rules.md
일반적인 UI 아이콘(56개 그려진 글리프)의 검증된 기하학에서 시작	references/glyph-cookbook.md + assets/cookbook/*.svg
React/Vue/Svelte/Angular/HTML 출력 생성 또는 수동 적용, 번들 크기 감소	references/output-formats.md
사용법 스니펫 작성: nav/사이드바 패턴, 활성 상태, 레이블, 대비, RTL	references/accessibility-and-usage.md
생성된 컴포넌트의 형태 변경(프로퍼티, 클래스 이름, a11y 기본값)	templates/<framework>/, build.mjs가 읽는 파일; 출력이 아닌 여기서 편집
이 스킬의 변경 사항 테스트	evals/evals.json

확인 체크리스트(완료 보고 전에 모두 참이어야 함)

• 추가된 아이콘 라이브러리 없음; 모든 아이콘은 이 작업을 위해 그리거나 cookbook에서 적응시킴.
• 스타일이 프로젝트의 기존 아이콘(또는 기본 프리셋)과 전체 세트에 걸쳐 일치함.
• lint.mjs가 icons/src와 icons/svg에서 PASS; 남은 경고는 보고서에서 정당화됨.
• 마지막 변경 후 미리보기 PNG를 확인함; 16px 밝은/어두운 행이 깔끔함; 어떤 아이콘도 형제보다 무겁거나 가볍거나 크지 않음.
• build.mjs로 컴포넌트 생성됨; 프로젝트 타입 체크/빌드 통과(가능한 경우).
• 사용법: 장식용 아이콘은 숨김, 아이콘 전용 컨트롤은 레이블 있음, 활성 상태가 색상만으로 표시되지 않음, 타겟 ≥44px, 대비 ≥3:1.
• 보고서에 크기(평균 바이트/아이콘, gzip 총합) 및 미리보기 경로 포함.