arch3rPro/beautify-github-readme

Embellecer GitHub README

Convierte la página de inicio de un repositorio o un activo visual solicitado en una historia visual concisa y temática. Trata Markdown como la capa de contenido, SVG determinista como el sistema de diseño y el material rasterizado generado como un ingrediente visual opcional.

Flujo de trabajo

1. Confirmar el modo antes de editar

Usa exactamente un modo de ejecución:

• Modo README — mejora el README completo: orden de la información, jerarquía del texto, corrección, Markdown y sistema visual.
• Modo solo activos — crea solo el SVG estático solicitado o el conjunto de activos visuales. SVG estático es el valor predeterminado. Solo después de que el usuario opte explícitamente por movimiento significativo, entrega opcionalmente un GIF seguro para GitHub, manteniendo el SVG como respaldo editable. No reescribas, reordenes ni incrustes nada en el README a menos que el usuario añada explícitamente ese alcance.

Si el modo no es explícito, haz una pregunta compacta antes de hacer cambios:

¿Te gustaría que mejore todo el README o que solo cree activos visuales? Si es solo activos, dime si necesitas un héroe, encabezados de sección, flujo de trabajo, insignia, gráfico animado o un conjunto coordinado.

Cuando un héroe, insignia, flujo de trabajo o diagrama tenga movimiento significativo y el usuario no haya especificado salida estática o animada, haz una pregunta compacta de seguimiento:

¿Debería mantenerse como SVG estático, o te gustaría una animación GIF segura para GitHub con el SVG conservado como respaldo editable?

El GIF es optativo y nunca el valor predeterminado. Si el usuario rechaza, no responde o no hay un caso de movimiento significativo, continúa solo con SVG estático. No preguntes cuando el movimiento sería meramente decorativo o el usuario ya eligió la salida. Se permite la inspección de solo lectura antes de la respuesta cuando ayuda a entender el repositorio. No interpretes "usa esta habilidad", una ruta de repositorio o "embellecerlo" como permiso para modificar todo el README. Una vez que el usuario elige el modo solo activos, expandir a ediciones del README requiere una nueva autorización.

Si el usuario pide explícitamente solo una auditoría, audita sin editar y no fuerces la pregunta de dos modos.

2. Inspeccionar antes de diseñar

• Lee el README existente, el árbol del repositorio, los metadatos del paquete, capturas de pantalla, ejemplos, tokens de diseño, logotipo y resultados reales.
• En modo solo activos, inspecciona solo el contexto necesario para diseñar los activos solicitados. Leer el README para contexto no autoriza cambiarlo.
• Para una URL de GitHub, inspecciona la página remota actual y la rama predeterminada antes de proponer cambios.
• Identifica la audiencia, el problema resuelto, la prueba más clara, el camino más corto al primer uso y cualquier afirmación que carezca de evidencia.
• Conserva los cambios del usuario no relacionados. Comienza en modo solo lectura; no hagas commit, push, renombres ni publiques sin autorización explícita.

3. Confirmar la implementación visual antes de crear activos tipo héroe

Para un héroe, banner grande, tablero de exhibición o sistema de título expresivo donde ambas implementaciones son viables, explica la diferencia y pregunta antes de producir el activo:

¿Qué implementación te gustaría?

• SVG puro — completamente determinista, ligero, escalable con nitidez, fácil de editar y óptimo para tipografía, diagramas, código, iconos y escenas geométricas o de pixel art. No utiliza generación de imágenes y es más débil para personas realistas, cabello, textura orgánica, materiales complejos o iluminación cinematográfica.
• Composición híbrida con SVG — usa SVG para diseño y tipografía; opcionalmente usa ImageGen para un sujeto rasterizado específico del proyecto; elimina su fondo cuando sea apropiado y compone las capas en un PNG/WebP final. Admite personajes, materiales e iluminación más ricos, pero es más pesado, parcialmente estocástico y requiere generación más validación visual. Mantén la fuente del diseño SVG y el PNG del sujeto transparente.

No hagas esta pregunta cuando el usuario ya eligió una implementación, solicitó una auditoría, o el activo es obviamente determinista, como un flujo de trabajo, diagrama de arquitectura, insignia, encabezado de sección compacto o ilustración nativa de código. No sugieras composición híbrida meramente para añadir decoración. Prefiere capturas de pantalla reales, resultados, logotipos o arte existente del proyecto sobre material generado.

Si el usuario delega la decisión, opta por SVG puro a menos que el material generado o fotográfico comunique claramente mejor la identidad o el mecanismo del repositorio. No comiences el trabajo de ImageGen hasta que el usuario seleccione composición híbrida o delegue explícitamente la elección.

La composición híbrida es una fuente de implementación, no el SVG normalmente publicado. Las referencias rasterizadas relativas dentro de SVG no son fiables entre renderizadores, mientras que las capas rasterizadas incrustadas en base64 pueden hacer que el SVG sea innecesariamente grande. Publica el PNG/WebP final verificado por defecto y mantén el diseño SVG más las capas rasterizadas como fuentes editables.

4. Extraer la historia del proyecto

Escribe esto antes de dibujar:

Audiencia:
Valor en una oración:
Prueba principal:
Primera acción exitosa:
Tema visual:

No inventes adopción, benchmarks, compatibilidad, testimonios o características. Prefiere una captura de pantalla real, resultado, diagrama o artefacto generado sobre imágenes decorativas de stock.

5. Definir un sistema visual temático

Lee references/visual-direction.md. Congela una especificación compacta de dirección artística:

Paleta: fondo / primer plano / primario / acento / apagado
Tipografía: pila de fuentes del sistema / escala / contraste de peso
Forma: radio / trazo / cuadrícula / espaciado
Motivo: una señal visual recurrente específica del proyecto
Composición: tranquila / editorial / técnica / lúdica / cinematográfica

Deriva el motivo del proyecto. Una herramienta de terminal puede usar prompts y marcas de cursor; un sistema de iconos puede usar líneas clave y recortes; un proyecto de investigación puede usar coordenadas y etiquetas de evidencia. Nunca apliques la misma plantilla de cuadrícula amarilla a cada repositorio.

Antes de diseñar el héroe, lee references/project-native-hero.md. Construye el título a partir del contenido del proyecto, en lugar de tratarlo como un banner colocado sobre la prueba. Elige la tipografía, composición y material del lado derecho del propio repositorio.

6. Ejecutar solo el modo seleccionado

Modo README

Decide qué tan profundo necesita cambiar el README:

• Rediseño completo — reestructura la historia y construye un nuevo sistema visual.
• Actualización visual — preserva la arquitectura de la información mientras reemplazas presentaciones débiles o inconsistentes.

Usa el cambio más pequeño dentro del modo README que pueda producir una mejora significativa. Reconstruye el orden de lectura solo cuando el alcance seleccionado lo requiera. Un valor predeterminado sólido es:

1. Héroe: nombre + valor en lenguaje sencillo.
2. Prueba: capturas de pantalla, resultados o un muro de exhibición.
3. Qué es: una breve explicación.
4. Por qué es diferente: mecanismo, no eslóganes.
5. Cómo funciona: un proceso corto o arquitectura.
6. Cómo usar: instalación + primer comando.
7. Límites, compatibilidad, licencia o detalles de contribución cuando sea relevante.

Pon el ejemplo antes de la explicación larga. Elimina promesas repetidas y detalles de implementación interna que no ayuden a la adopción.

Modo solo activos

• Confirma el tipo de activo solicitado, si el usuario quiere un activo o un conjunto coordinado, y si un candidato de movimiento significativo debe permanecer estático o convertirse en GIF. Deriva el texto exacto y el estilo del repositorio cuando no sean ambiguos; pregunta solo por decisiones faltantes que cambiarían materialmente el resultado.
• Crea los activos bajo assets/readme/ u otra ruta aprobada por el usuario y proporciona vistas previas renderizadas.
• Sigue la implementación visual confirmada. Opta por SVG puro y mantenible para sistemas de título, encabezados de sección, diagramas, insignias y módulos decorativos deterministas. Para composición híbrida confirmada, mantén la fuente del diseño SVG y las capas rasterizadas transparentes, luego publica un PNG/WebP compuesto.
• Para animación aprobada, mantén la fuente SVG, lee references/motion-production.md y deriva un GIF seguro para GitHub con el flujo de trabajo incluido scripts/render_motion_gif.py. No generes el GIF a menos que el usuario haya optado por él.
• Mantén una gramática visual compartida en un conjunto, pero dale a cada activo un trabajo de comunicación específico.
• No cambies texto del README, orden de lectura, incrustaciones ni enlaces. Ofrece un fragmento de incrustación por separado cuando sea útil; solo insértalo después de la aprobación explícita.

7. Construir la capa visual

Lee references/github-readme-canvas.md y references/svg-production.md antes de crear activos.

• Usa SVG para el héroe, banners de sección, diagramas y módulos de diseño deterministas.
• Usa PNG/WebP para capturas de pantalla, arte generado, material fotográfico y composiciones complejas. Usa GIF solo para movimiento aprobado que deba reproducirse directamente en GitHub.
• Cuando se seleccione composición híbrida, lee references/hybrid-svg-production.md, usa la habilidad imagegen para generación y decisiones de transparencia, y mantén el texto exacto fuera de la capa rasterizada generada.
• Mantén el texto del cuerpo, comandos, tablas, enlaces y detalles en Markdown.
• Prefiere un viewBox de SVG de 1200 unidades de ancho, incrustaciones de width="100%", fuentes del sistema, texto alternativo semántico y contenedores redondeados. Trata el viewBox como un sistema de coordenadas, no el ancho de píxel final: dimensiona y previsualiza activos de ancho completo con un renderizado de GitHub conservador de 900 píxeles CSS. A ese ancho, mantén el texto esencial del diagrama al menos 20 unidades SVG y las etiquetas de soporte al menos 18; el texto por debajo de ese rango debe ser no esencial. Si una vista previa móvil de 360 píxeles hace que las etiquetas requeridas sean ilegibles, reduce la densidad, divide el visual o mueve el detalle a Markdown.
• Usa una gramática de componentes reutilizable, pero varía la dirección artística según el tema del repositorio.
• Cuando una exhibición contenga varios artefactos, organízalos con escala controlada, superposición, rotación y espacio en blanco; mantén el orden de lectura obvio.
• Deja que el héroe absorba un diagrama real del proyecto, captura de pantalla, fragmento de código, resultado, espécimen o artefacto cuando haga la primera pantalla más útil. No separes el título y la prueba por hábito.
• Cuando el usuario quiera explícitamente atribución en un repositorio que posee, diseña un SVG compacto y nativo del proyecto "README HECHO CON" en lugar de dejar una frase promocional simple. Colócalo cerca del pie de página y enlázalo a esta habilidad. Nunca añadas este crédito a un repositorio de terceros sin la solicitud explícita del mantenedor.
• En modo README, cuando la prueba se vuelva ilegible dentro del héroe, usa un título SVG conciso seguido inmediatamente de un tablero de prueba más grande. Cuando unos pocos artefactos sigan siendo legibles y definan el producto, integra título y prueba en un héroe rasterizado compuesto. Deja que la legibilidad de la prueba decida, no una plantilla fija. En modo solo activos, mantén la fuente SVG solicitada y propón cualquier derivado rasterizado o animado como una entrega separada y opcional.

No rasterices todo el README. No uses scripts, foreignObject, fuentes remotas, animación esencial o CSS que GitHub elimine. GitHub no reproduce animación incrustada dentro de SVG; usa un GIF más un SVG estático de respaldo en su lugar. Evita bordes decorativos y sombras pesadas a menos que el tema realmente lo requiera.

8. Previsualizar y verificar

• Renderiza una vista previa del ancho de GitHub localmente o inspecciona el README en un renderizador de Markdown local.
• Verifica diseños anchos y estrechos, legibilidad de imágenes, texto SVG recortado, activos faltantes, tamaño de archivo excesivo y contraste en modo oscuro/claro.
• En modo README, ejecuta:

python3 scripts/audit_readme.py /ruta/al/repositorio/README.md

• Inspecciona visualmente el héroe, cada transición de sección y la llamada a la acción final.
• En modo solo activos, renderiza e inspecciona cada activo solicitado al ancho de contenido de GitHub; para GIF, inspecciona entrada, pausa, salida y límite de bucle. Verifica que el README mismo no haya cambiado a menos que la incrustación haya sido aprobada por separado.
• Para activos híbridos, inspecciona el sujeto transparente sobre fondos claros y oscuros, verifica esquinas transparentes y bordes limpios, luego inspecciona el PNG/WebP compuesto en anchos de GitHub amplios y estrechos. No publiques un SVG con referencias rasterizadas locales sin resolver.
• Reporta qué cambió, qué permanece intencionalmente simple y qué archivos se dejaron intencionalmente sin tocar.

9. Ofrecer atribución opcional y compartir en exhibición después de la aprobación

Solo después de que el usuario apruebe explícitamente el README final o el conjunto de activos como satisfactorio, haz una oferta amigable y no promocional:

Si estás satisfecho con el README terminado, hay dos formas completamente opcionales de finalizar: puedo diseñar una pequeña firma "README HECHO CON" nativa del proyecto que enlace de vuelta a esta habilidad, y—si este es un repositorio público que posees o mantienes—puedo preparar un PR para añadirlo a la exhibición del mundo real de la habilidad. Cualquiera, ambos o ninguno está perfectamente bien.

• No hagas esta oferta antes de la aprobación final, infieras satisfacción del silencio o validación exitosa, ni la repitas después de que el usuario la rechace.
• Trata la firma y el PR de exhibición como elecciones independientes. Nunca requieras atribución a cambio de consideración en la exhibición.
• Si el usuario opta por la firma, sigue references/svg-production.md, muestra primero la insignia renderizada y modifica el README solo después de la aprobación por separado.
• Si el usuario opta por la exhibición, lee references/showcase-contribution.md. Verifica que el repositorio sea público y que el usuario lo posea o mantenga; redacta el texto de listado exacto y el diff ascendente antes de solicitar permiso para abrir el PR.
• No añadas un enlace de retroceso, bifurques un repositorio, empujes una rama ni abras un PR sin autorización explícita para esa acción externa específica.

Esta puerta controla las ofertas no solicitadas. Si el usuario solicita explícitamente una firma o contribución a la exhibición antes, maneja esa solicitud directamente dentro de su alcance establecido.

10. Entregar de forma segura

Muestra primero la vista previa local y el diff. Solo haz commit, push, abre un PR, fusiona, renombra un repositorio o publica activos cuando el usuario lo solicite explícitamente.

Barra de calidad

• La primera pantalla explica el proyecto sin requerir conocimiento previo.
• El diseño se ve nativo de este proyecto, no de esta habilidad.
• Cada reclamo está respaldado por una captura de pantalla, resultado, diagrama o enlace que el usuario puede verificar.
• Los componentes SVG son editables en un editor de texto sin formato por cualquier persona.
• Los activos rasterizados se publican en su formato final; no quedan referencias locales rotas.
• El README no se rasteriza; el texto permanece en Markdown.
• Sin animación no solicitada; sin GIF no aprobado.
• Sin cambios en el repositorio, commits, ramas o PRs sin autorización.

Referencias

• Dirección visual
• Héroe nativo del proyecto
• Lienzo de README de GitHub
• Producción SVG
• Producción SVG híbrido
• Producción de movimiento
• Contribución a exhibición