Abhijit-Jha/icon-skill

Icon Forge

Dibuja iconos personalizados que parezcan de un conjunto profesional y publícalos sin dependencias de ejecución. Has terminado cuando cada icono pasa la validación (lint), has visto la previsualización en 16/20/24px y se lee con claridad y consistencia en modo claro y oscuro, y los componentes generados están integrados con uso accesible.

<skill> a continuación se refiere a la carpeta que contiene este archivo (por ejemplo, .claude/skills/icon-forge, .cursor/skills/icon-forge, .agents/skills/icon-forge). Los scripts necesitan Node ≥18 y no necesitan dependencias del proyecto.

Cuándo usar / cuándo no

• Usar: una barra lateral, barra de navegación, panel, página de configuración, estado vacío o barra de herramientas necesita iconos; el usuario pide un icono personalizado o faltante; el usuario quiere reemplazar emojis/iconos de marcador de posición o un paquete de iconos pesado por un pequeño conjunto propio.
• No usar: logotipos y marcas (marcas registradas; necesitan un diseñador), favicons/iconos de aplicación, ilustraciones o arte puntual, fotos/ráster, Lottie animado. Si el usuario pide explícitamente instalar una librería (por ejemplo, "solo usa Lucide"), haz lo que pide; esta habilidad existe para el camino personalizado.

Reglas estrictas (y por qué)

1. Dibuja cada icono tú mismo; no añadas dependencias de librerías de iconos. El usuario eligió iconos propios por el tamaño del paquete y un aspecto único. No pegues datos de ruta de Lucide, Heroicons, Material, etc. (licencia y originalidad). Usa references/glyph-cookbook.md (dibujos originales) como geometría inicial.
2. Si el proyecto ya usa una librería de iconos, haz coincidir su cuadrícula, trazo, extremos y radio (ver scripts/detect.mjs y reglas de diseño §10). Los nuevos iconos deben colocarse junto a los existentes sin verse extraños.
3. Un conjunto, un estilo. Misma cuadrícula, ancho de trazo, extremos/uniones, escala de radio, relleno y nivel de detalle para cada icono. La consistencia importa más que cualquier icono individual ingenioso.
4. Los atributos de presentación solo deben estar en el <svg> raíz, el color es currentColor, y los orígenes no contienen ids, estilos, clases, transformaciones ni <g>. De lo contrario, la tematización, el modo oscuro, la propiedad strokeWidth y la inserción en línea se rompen.
5. Nunca digas que un icono es bueno sin renderizarlo y ver el PNG. La geometría que parece correcta en código suele fallar a 16px: manchas, espacios cerrados, formas descentradas, peso desigual.
6. Ejecuta los scripts; no los reimplementes. La validación (lint), optimización, previsualización y generación de código son deterministas. Nunca edites a mano los archivos generados; cambia icons/src/ y reconstruye.
7. No modifiques las dependencias del usuario. Las herramientas de previsualización se instalan en ~/.cache/icon-forge (--install); SVGO se ejecuta mediante npx si no está presente. Pregunta antes de añadir cualquier paquete al proyecto.
8. Accesible por defecto. Los iconos tienen aria-hidden a menos que estén etiquetados; los controles solo con icono reciben aria-label; objetivos interactivos ≥44px; iconos significativos ≥3:1 de contraste.

Flujo de trabajo

1. Detectar pila y estilo existente

node <skill>/scripts/detect.mjs .

Anota el framework, TypeScript, Tailwind, cualquier librería de iconos (y su preset de estilo), iconos SVG locales y el directorio de salida sugerido. Si existe un conjunto previo, abre 2–3 de sus SVGs y copia sus números raíz. De lo contrario, usa los valores por defecto: cuadrícula 24, trazo 2, extremos/uniones redondos.

2. Planificar la lista: significado → metáfora → nombre de archivo

Escribe una tabla corta antes de dibujar: etiqueta | metáfora (qué se dibuja) | nombre de archivo | inicio en el cookbook. Ejemplo: Proyectos | tablero kanban | kanban.svg | kanban. Elige metáforas convencionales (reglas de diseño §7) y una metáfora por significado. Nombra los archivos según el objeto, en kebab-case. Pregunta al usuario solo si una etiqueta es ambigua y la elección cambia el significado en la interfaz; de lo contrario, decide y menciona la elección.

3. Dibujar en la cuadrícula 24

Crea icons/src/<nombre>.svg con la raíz canónica (reglas de código SVG). Para cada icono:

• Parte de la línea clave correspondiente: círculo r10, cuadrado 18 (x/y 3), retrato 16×20, paisaje 20×16. Las líneas clave son centros de trazo.
• Mantén el borde exterior del trazo a ≥1 unidad del borde del lienzo. Usa radio 2 en esquinas grandes y 1–1.5 en pequeñas; mantén espacios de ≥2 unidades de espacio limpio.
• Haz que las partes se unan exactamente o mantengan un espacio claro. Usa coordenadas enteras para trazos de 2px. Usa la menor cantidad de elementos posible (≤6 es típico).
• Parte de la entrada más cercana en references/glyph-cookbook.md, luego adáptala. Copia la geometría de <skill>/assets/cookbook/<nombre>.svg cuando un glifo encaje tal cual.
• Calcula la geometría repetida (dientes, rayos, puntas de estrella) con unas pocas líneas de JS en lugar de adivinar. Dibuja todo el conjunto primero, luego refina. La consistencia se juzga lado a lado.

4. Validar (lint)

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

Corrige cada ✖. Trata ⚠ gap, density, scale y bounds como problemas de diseño a corregir, no ruido. Anota cada ℹ gap y verifícalo en el paso 6; los trazos paralelos apretados (barras, líneas) se manchan a 16px a menos que estén separados 4 unidades. Vuelve a ejecutar hasta que muestre PASS sin advertencias que no puedas justificar. Banderas: --grid, --padding, --mode fill, --strict, --json.

5. Optimizar

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

Esto redondea números, ejecuta SVGO (instalación local o npx svgo@4; recurre al canonicalizador incorporado sin conexión), reordena atributos raíz e imprime bytes por icono más el total comprimido. Valida también la salida: node <skill>/scripts/lint.mjs icons/svg.

6. Previsualizar y MIRAR, luego iterar

node <skill>/scripts/preview.mjs icons/svg --out icons/preview.png \
  --sidebar "dashboard:Panel,kanban:Proyectos" --active dashboard   # añade --install la primera vez si no hay motor PNG

Ve los PNG con tu herramienta de visualización de imágenes, en este orden:

1. icons/[email protected]: la tira del conjunto y las maquetas de la barra lateral. Es lo suficientemente pequeño para verlo con todo detalle.
2. icons/[email protected]: cada icono en cada tamaño, más la vista de inspección. Es alto, así que recórtalo si tu visor reduce la escala.
3. icons/preview.png: píxeles reales 1×.

Juntos muestran:

• una tira de 24/16px en modo claro y oscuro;
• una maqueta de barra lateral con un elemento activo y un carril colapsado;
• filas por icono a 16/20/24/48;
• una vista de inspección 4× con cuadrícula, líneas clave azules y el límite rojo de relleno de 1px.

Responde las preguntas de autoevaluación en las reglas de diseño §12. Correcciones típicas:

Ves	Corrige
Un icono se ve más claro/pequeño en la tira	agranda hasta su línea clave, o añade un marco/eje (los glifos abiertos se ven ligeros)
Uno se ve más pesado/ocupado	elimina detalles; ≤3 barras, ≤6 dientes, ≤2 líneas de texto
Una mancha donde las partes se unen a 16px	une exactamente o abre el espacio a ≥2 unidades
La forma se apoya en un lado en la vista de inspección	vuelve a centrar, o mueve 0.5–1 unidad para equilibrio óptico
Metáfora poco clara en el carril colapsado	elige una metáfora más literal (paso 2)

Repite los pasos 3–6 hasta que una segunda mirada no encuentre nada que corregir. Normalmente 1–3 rondas.

7. Generar la salida del framework

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

--framework react|vue|svelte|html|all; --lang ts|js; --package @app/icons escribe un sideEffects:false package.json. La salida es un módulo por icono (tree-shakable), un componente base compartido (size, color, strokeWidth, absoluteStrokeWidth, title, className), exportaciones con nombre index y icons.json. HTML genera sprite.svg + usage.html. Detalles: references/output-formats.md.

Luego verifica tipos o construye el proyecto si tiene un script (npx tsc --noEmit, npm run build) y corrige cualquier error.

8. Integrar con uso accesible

Usa el patrón de references/accessibility-and-usage.md:

• <nav aria-label>; aria-current="page" más color y fondo para el elemento activo;
• icono size-5 shrink-0 y decorativo;
• un aria-label en botones solo de icono; cerrar sesión como <button>;
• filas ≥44px; colores apagados que aún alcancen 3:1.

Formato de salida

Termina con un informe breve al usuario:

1. Iconos: tabla etiqueta → componente → metáfora y las rutas de carpeta (icons/src, icons/svg, directorio generado).
2. Comprobaciones: resultado de validación (errores/advertencias), totales de optimización (avg B/icon, gzip total), y las rutas de previsualización que inspeccionaste, además de qué cambiaste después de mirar.
3. Fragmento de uso para su framework, con atributos de accesibilidad.
4. Notas: decisiones de estilo (cuadrícula/trazo/preset coincidente), iconos RTL a reflejar, y cualquier cosa que no pudiste verificar.

Ejemplo

Usuario: "Necesito iconos de barra lateral para Panel, Proyectos, Equipo, Configuración en mi app Next.js + Tailwind." → detectar: React (Next) + TS + Tailwind, sin librería de iconos → planificar: panel/azulejos, kanban, usuarios, config/engranaje → dibujar desde el cookbook y adaptar → validar PASS → optimizar: 4 iconos, promedio ~340 B, ~0.4 KB comprimido → previsualizar: Proyectos se veía ligero, así que añadir barras; re-verificar → construir --framework react en src/components/icons → <DashboardIcon className="size-5 shrink-0" /> en la navegación con aria-current.

Referencias

Abre cuando necesites…	Lee
elegir tamaños, líneas clave, radios, espacios, metáforas o solucionar un problema de previsualización	references/design-rules.md
escribir o depurar código SVG, o entender un error de validación	references/svg-code-rules.md
partir de geometría probada para un icono de interfaz común (56 glifos dibujados)	references/glyph-cookbook.md + assets/cookbook/*.svg
generar o adaptar a mano la salida React/Vue/Svelte/Angular/HTML, o reducir el tamaño del paquete	references/output-formats.md
escribir el fragmento de uso: patrones de navegación/barra lateral, estado activo, etiquetas, contraste, RTL	references/accessibility-and-usage.md
cambiar la forma de los componentes generados (props, nombres de clase, valores predeterminados de accesibilidad)	templates/<framework>/, que build.mjs lee; edita allí, nunca en la salida
probar cambios en esta habilidad	evals/evals.json

Lista de verificación (todo debe ser verdadero antes de informar como terminado)

• No se añadió ninguna librería de iconos; cada icono dibujado para esta tarea o adaptado del cookbook.
• El estilo coincide con los iconos existentes del proyecto (o el preset por defecto) en todo el conjunto.
• lint.mjs PASS en icons/src e icons/svg; las advertencias restantes justificadas en el informe.
• Viste el PNG de previsualización después de tu último cambio; las filas de 16px en claro/oscuro son limpias; ningún icono es más pesado, más claro o más grande que sus hermanos.
• Componentes generados por build.mjs; la verificación de tipos/construcción del proyecto pasa (cuando esté disponible).
• Uso: iconos decorativos ocultos, controles solo de icono etiquetados, estado activo no solo por color, objetivos ≥44px, contraste ≥3:1.
• El informe incluye tamaños (promedio bytes/icono, total comprimido) y ruta de previsualización.