roast-my-design-system

roast-my-design-system

Tu IA puede escribir la UI. Esto asegura que escriba tu UI.

Una herramienta CLI gratuita (y habilidad de Claude Code) que analiza el design system de tu repositorio con datos reales, y luego genera las reglas que mantienen a tu agente de IA dentro del sistema.

Nuevo en 5.1: el análisis del roast ahora viaja dentro del informe. Al ejecutarse como habilidad de Claude Code, el informe gana una sección "Qué significan los números" — la lectura de Claude de tu escaneo, en el mismo archivo compartible que la puntuación, para que el análisis llegue a quien sea que se reenvíe el informe. Etiquetado como escrito por IA, nunca mezclado con la medición.

Nuevo en 5.0: se ejecuta como un servidor MCP local. Un comando, y tu agente consulta el design system antes de escribir UI, y luego hace que el trabajo sea revisado después: cuál Button es canónico, qué token contiene ese color, revisa mis cambios. Local, determinista, nada sale de tu máquina. Ver Respuestas en vivo vía MCP.

Ejecútalo en tu código y obtén, en aproximadamente un segundo:

• Una puntuación de salud que puedes defender en una reunión. 0-100, determinista, comparada con las normas del Ideal Design System, 34 repositorios públicos escaneados y 10 design systems de renombre (Primer, Polaris, Carbon, shadcn/ui…).
• Puntuaciones por paquete para monorepos. Un número combinado oculta qué paquete es el problema: packages/ui puntúa 80 mientras que apps/web puntúa 40, y ahora puedes verlo.
• Los recibos detrás de ello. Cada color y su gemelo casi idéntico, cada valor de espaciado, tipografía, componente duplicado o nunca importado, estilo en línea y !important, con rutas de archivo reales, en un único informe HTML autocontenido que puedes abrir, compartir por Slack o enviar por correo.
• Las primeras correcciones clasificadas por retorno. Una lista "Por dónde empezar" derivada de tus propios números: conserva el informe como auditoría, o entrégalo a Claude como lista de tareas para la corrección.
• Reglas que detienen el desorden de volver. Un design-system-rules.md generado con componentes canónicos, tu archivo de tokens y duplicados conocidos a evitar, para que tu agente de IA siga tu sistema en lugar de adivinarlo. --apply los inyecta en cada archivo de agente que tengas: Claude, Cursor, GitHub Copilot y Windsurf. Cada escaneo también verifica las reglas que ya tienes en busca de referencias obsoletas: rutas que ya no existen, componentes nombrados canónicos que ya nada importa.

Por qué existe esto

Tu agente de IA (Claude, Cursor, Copilot) construye UI imitando lo que ya está en tu repositorio. Si tu repositorio tiene 112 colores y cuatro implementaciones de Button, tu agente adivina cuál es canónico, y se equivoca la mitad de las veces. Por eso la UI generada por IA se ve casi-pero-no-del-todo correcta. El primer paso para arreglarlo es ver el desorden medido.

Cada comando

Un solo escaneo alimenta todo; las banderas deciden qué se guarda en disco. Combínalas libremente.

Comando	Lo que obtienes
npx roast-my-design-system	El escaneo y design-system-roast.html, abiertos en tu navegador
npx roast-my-design-system <path>	Escanea un repositorio distinto al directorio actual
... --apply	Las reglas de agente generadas inyectadas directamente en cada archivo de agente que tengas: CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/, .windsurfrules y .github/copilot-instructions.md, dentro de un bloque marcado. Re-ejecutar reemplaza solo ese bloque, nunca tu propio texto. Windsurf y Copilot obtienen una variante compacta ajustada a sus límites
... --rules	Las mismas reglas escritas en design-system-rules.md en su lugar, para pegar manualmente
... --card	roast-card.svg: una tarjeta compartible de 1200x630 con la puntuación y los peores hallazgos. SVG puro, se incrusta en un README
... --sarif	design-system-roast.sarif para el escaneo de código de GitHub: súbelo en CI y los hallazgos aparecen en la pestaña Security, anotados en los archivos
... --mcp	El escaneo como servidor MCP local: cinco herramientas que tu agente llama mientras escribe UI, desde "¿ya existe un Button?" hasta "revisa mis cambios". Ver Respuestas en vivo vía MCP
... --check	Los archivos modificados del árbol de trabajo verificados contra el design system, en la terminal. Sale con código 1 si hay hallazgos, para que encaje en scripts
... --by "Dwayne Hicks"	Un crédito de solicitante en el encabezado del informe, junto a la fecha del escaneo
... --notes <file.md>	Un análisis escrito por agente incrustado en el informe como "Qué significan los números": etiquetado como escrito por IA, mantenido aparte de los números medidos. La habilidad de Claude Code lo escribe y lo pasa automáticamente; la bandera está aquí para que cualquier agente pueda
... --section "Title" <file.md>	Un capítulo escrito por agente añadido después de las notas, mismo estilo, misma etiqueta de escrito-por-IA, con subtítulos permitidos. Repetible, para que el análisis que supera las notas siga viviendo dentro del informe en lugar de una página hecha a mano
... --exclude lab/	Deja una carpeta fuera del escaneo (repite la bandera o sepáralas con comas). O lista las carpetas en un archivo .roastignore en la raíz del repositorio. De cualquier manera, el informe lo dice en el encabezado; ver Delimitando el escaneo
... --json	El resumen del escaneo como JSON en stdout, para scripts y pipelines
... --theme light / --out <file> / --no-open	Informe claro, ruta de informe personalizada, no abrir el navegador
/roast-my-design-system (en Claude Code)	La experiencia completa: el roast en el chat y incrustado en el informe como "Qué significan los números", la oferta de reglas y el bucle de corrección con Claude sobre tus propios números

Un escaneo escribe reglas para cada agente: Claude, Cursor, GitHub Copilot y Windsurf. Cada escaneo también verifica las reglas de agente que ya tienes y marca referencias obsoletas, sin necesidad de bandera.

Casos de uso de ejemplo

• Auditoría previa a la refactorización. Ejecuta /roast-my-design-system antes de una limpieza del design system para obtener la línea base medida: cada color, valor de espaciado, componente duplicado y estilo en línea, con rutas de archivo reales.
• Diagnóstico de salida de IA casi correcta. Cuando Claude sigue generando UI que se ve ligeramente desajustada, el informe muestra qué componentes duplicados y valores sueltos está imitando, y dónde viven los canónicos.
• Argumentando sin reunión. Deja caer el informe HTML autocontenido en Slack: una puntuación de salud y tres puntos de referencia (normas ideales, la mediana de 34 repositorios, 10 sistemas de renombre) argumentan por el design system por ti.
• El bucle de corrección. Devuelve el informe a Claude como lista de tareas y trabaja a través de la sección Por dónde empezar, archivo por archivo.

El informe completo para vercel/ai-chatbot, de arriba a abajo — incluyendo "Qué significan los números", la lectura de Claude del escaneo, incrustada justo debajo del veredicto:

El mismo informe en modo claro (un archivo, conmutador integrado):

Qué hace confiables los números

• Escáner determinista, no muestreo de IA. Un script Node sin dependencias lee cada archivo (aproximadamente un segundo en un repositorio normal, unos pocos en un monorepo grande) y devuelve los mismos números en cada ejecución. Claude narra; nunca cuenta.
• Solo lectura. Nada en tu repositorio se modifica. Las únicas salidas son un JSON temporal y el informe HTML.
• Sin red, sin telemetría. Todo se ejecuta localmente. Nada sobre tu código sale de tu máquina.
• Exclusiones honestas. Archivos de prueba, historias de Storybook, sitios de documentación, aplicaciones de ejemplo, arte SVG y plantillas de correo electrónico (que deben tener estilos en línea) están excluidos, para que no puedas desacreditar los números por un tecnicismo. Tus propias exclusiones (.roastignore, --exclude) se imprimen en el encabezado del informe con recuentos de archivos, para que un escaneo delimitado nunca pueda hacerse pasar por todo el repositorio.
• Conteo consciente de la intención (v3). Los estilos en línea calculados en tiempo de ejecución, las API de componentes compuestos y los componentes envoltorio no son crímenes y no se cuentan como tales. Los repositorios liderados por tokens se juzgan por sus valores codificados sueltos, no por su arquitectura de tokens. Los valores arbitrarios repetidos se leen como decisiones sin nombre, no como deriva.
• Un punto de referencia real. El estándar "Avg Design System" proviene de escanear 34 repositorios públicos de React (cal.com, excalidraw, supabase, grafana, twenty, dub, langfuse…). Mediana: 130 colores, 17 grises, 20 componentes duplicados, 49 bloques de estilo en línea, 70 valores arbitrarios de Tailwind.
• Un segundo punto de referencia: sistemas de renombre. Escaneos curados y delimitados de 10 design systems conocidos (shadcn/ui, Primer, Polaris, Carbon, Material UI, Chakra, Ant Design, GOV.UK, Spectrum, Cloudscape) muestran cómo se ve la disciplina a escala.

Delimitando el escaneo

Algunos repositorios albergan más de un mundo visual a propósito: el producto más un sitio de marketing, un patio de juegos, un lote de experimentos. Mezclarlos produce una puntuación que no describe a ninguno. Delimita el escaneo al design system que realmente estás juzgando:

npx roast-my-design-system --exclude lab/ --exclude playground/

O hazlo permanente con un archivo .roastignore en la raíz del repositorio, una carpeta relativa al repositorio por línea:

# separate visual worlds, not the product's design system
lab/
playground/

Ambas rutas se fusionan, y ambas son ruidosas a propósito. El JSON de cosecha registra cada patrón activo y cuántos archivos eliminó, y el informe imprime una línea en el encabezado ("2 carpetas excluidas por .roastignore (lab/, playground/) · 946 archivos mantenidos fuera de este escaneo"). Puedes estrechar la pregunta, pero el informe siempre dice qué pregunta se hizo, para que una puntuación delimitada no pueda ser manipulada silenciosamente. No hay negación ni sintaxis de glob: prefijos de carpeta simples, nada ingenioso.

Respuestas en vivo vía MCP

El informe y el archivo de reglas describen el repositorio tal como estaba en el momento del escaneo. --mcp mantiene el mismo motor funcionando mientras tu agente trabaja, para que las preguntas se respondan desde el código tal como está ahora, y los errores se detecten antes de que aterricen:

Herramienta	La pregunta que responde
roast_get_context	¿Qué debería saber antes de tocar la UI aquí? Enrutado por la carpeta que se está editando
roast_find_component	¿Ya existe un componente para esto, y cuál es canónico? Con un ejemplo de uso real. Cuando dos candidatos empatan, lo dice y nombra a ambos
roast_find_token	Tengo #111111 / 13px en mano. ¿Qué debería haber usado?
roast_validate	Estoy a punto de guardar esto. ¿Rompe el sistema?
roast_review	Revisa mis archivos modificados. Lee el diff de git por sí mismo, así que no se pega código de vuelta

El bucle: contexto antes de construir, encontrar mientras se construye, validar antes de guardar, revisar antes de terminar.

Añádelo a Claude Code:

claude mcp add roast -- npx roast-my-design-system --mcp

Cualquier cliente MCP puede registrar el mismo comando stdio (probado con Claude Code; Cursor y Windsurf hablan el mismo protocolo). Misma promesa que el escaneo: local, solo lectura, un escaneo al inicio, sin puerto, sin cuenta, nada sobre tu código sale de tu máquina. Y una respuesta limpia lee "no se encontraron violaciones medidas" con la lista de verificaciones adjunta, porque un escáner solo puede certificar lo que puede contar.

En CI

El escáner ya habla SARIF, así que conectarlo al escaneo de código de GitHub son seis líneas. Los hallazgos aparecen en la pestaña Security, anotados en los propios archivos:

- uses: actions/checkout@v4
- run: npx roast-my-design-system . --sarif --no-open
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: design-system-roast.sarif

Instalación

Sin instalación, sin necesidad de Claude — solo pruébalo:

npx roast-my-design-system

Ejecútalo dentro de cualquier repositorio. Mismo escáner, mismo informe, directo desde npm. La habilidad de Claude Code a continuación añade la conversación encima: el roast en el chat, luego una lista de tareas con la que realmente puedes trabajar con Claude.

Claude Code (recomendado):

/plugin marketplace add pencilrebel/roast-my-design-system
/plugin install roast-my-design-system@roast-my-design-system

Si esos comandos dan error, es probable que tu Claude Code sea más antiguo que la función de marketplace de plugins: actualiza Claude Code e inténtalo de nuevo, o simplemente usa la ruta manual a continuación (funciona en todas partes e instala la misma skill).

Manual (Claude Code, cualquier versión):

git clone https://github.com/pencilrebel/roast-my-design-system.git
cp -r roast-my-design-system/skills/roast-my-design-system ~/.claude/skills/

(Usa .claude/skills/ dentro de un repositorio para compartirlo con tu equipo).

OpenAI Codex CLI (mismo SKILL.md, misma carpeta):

git clone https://github.com/pencilrebel/roast-my-design-system.git
cp -r roast-my-design-system/skills/roast-my-design-system ~/.codex/skills/

Invócalo con $roast-my-design-system (o deja que Codex lo empareje automáticamente). Usa .codex/skills/ dentro de un repositorio para compartirlo con tu equipo.

npx skills: npx skills add pencilrebel/roast-my-design-system funciona para agentes que leen ~/.agents/skills/. Claude Code actualmente lee ~/.claude/skills/, así que prefiere una de las rutas anteriores.

Requiere Node 18+.

Uso

Abre Claude Code en el repositorio que quieres que critique y escribe:

/roast-my-design-system

Recibes la crítica en el chat más design-system-roast.html en la raíz de tu repositorio: una página autocontenida (ábrela, compártela por Slack, envíala por correo, sin solicitudes externas) con:

• una puntuación de salud calculada a partir de cómo se comparan tus números con el ideal
• "Qué significan los números": la lectura de Claude de tu escaneo — qué hallazgos importan realmente, qué buenos números son accidentes, qué arreglar primero — incrustada en el mismo archivo que reenviarás, etiquetada como escrita por Claude y mantenida separada de los números medidos. La puntuación sola puede halagar; esta sección es lo que mantiene honesto un 85/100 compartido
• mosaicos de estadísticas que te comparan con los tres puntos de referencia: Ideal, el promedio de 34 repositorios y los sistemas reputados
• un alternador de tema claro/oscuro en un solo archivo
• la barra de paleta ponderada por uso, la rampa de grises, los recibos de espaciado fuera de escala, los recibos de componentes duplicados con rutas de archivo clicables y el registro de los peores infractores
• un cierre de Por dónde empezar: hasta tres movimientos derivados de los números de tu propio repositorio, cada uno con un recibo de ruta de archivo
• un regalo 🎁 debajo: soportaste la crítica, así que design-system-rules.md está envuelto dentro del propio informe. Desenvuélvelo, luego copia o descarga las reglas de agente generadas a partir de tu escaneo.

Después de la crítica, la skill también ofrece escribir design-system-rules.md en el disco y fusionarlo en tu CLAUDE.md, .cursor/rules o AGENTS.md.

Ejemplos en vivo

Tres críticas reales de repositorios públicos, alojados tal cual (el mismo HTML autocontenido que genera la skill):

• excalidraw/excalidraw
• dubinc/dub
• vercel/ai-chatbot

Qué mide

Métrica	Sistema de diseño ideal	Mediana de 34 repositorios escaneados	Mediana de 10 sistemas reputados
Colores distintos	~24	130	24
Tonos de gris	hasta 13	17	5
Valores de espaciado fuera de escala	~12	34	6
Tipografías	2–3	3	1
Radios de borde	hasta 10	13	2
Componentes duplicados	0	20	12
Bloques de estilo en línea	0	49	12
Valores arbitrarios de Tailwind	~20	70	0
Pares de colores casi idénticos	0	13	1
Declaraciones !important	0	7	3
Componentes nunca importados	0	0	0

Sí, el repositorio mediano ya es un desastre. Ese es el punto.

Tu IA puede escribir la interfaz. Esto asegura que escriba tu interfaz.

Licencia

MIT. El código es tuyo para bifurcar, modificar y redistribuir; el aviso de copyright viaja con él.

Si construyes un informe, resumen o auditoría propio a partir de las puntuaciones, conteos o comparaciones de referencia de esta herramienta, mantén una línea en él: Construido con roast-my-design-system por Greg Kozakiewicz. Los datos del escaneo piden lo mismo a los agentes de IA que los consumen.

roast-my-design-system™ y la marca GK son marcas comerciales de Greg Kozakiewicz. Bifurcar es bienvenido, republicar bajo este nombre no lo es: consulta marca y atribución.

Construido y diseñado por Greg Kozakiewicz.