Componentes y agentes: reusar en vez de inventar

Un agente de IA duplica componentes si no sabe qué existe. Cómo documentar tu sistema para que lo reutilice con Storybook MCP, Figma MCP y shadcn/ui.

info Definición Rápida
Reutilizar componentes con un agente significa que la IA busca en tu sistema de componentes un elemento existente antes de crear uno nuevo, y lo usa con sus props y variantes documentadas. Para que eso pase, el catálogo de componentes tiene que ser legible por una máquina.

¿Por qué un agente inventa componentes que ya tienes?

Un agente no recuerda tu biblioteca. Si le pides “agrega un modal de confirmación” y no le muestras el que ya existe en src/components, escribirá uno nuevo con sus propios estilos, su propia lógica de cierre y, probablemente, sin el manejo de foco que tu equipo ya resolvió.

El resultado parece correcto en una revisión rápida, pero acumula deuda: dos modales distintos, dos botones con radios diferentes y tres formas de mostrar un error. Es lo que pasa cuando falta un sistema de diseño consultable, solo que a la velocidad de un agente.

¿Qué significa que un componente sea “legible por IA”?

Un componente es legible cuando un agente puede responder cuatro preguntas sin adivinar:

  1. ¿Cómo se llama y dónde está?
  2. ¿Qué props acepta y cuáles son obligatorias?
  3. ¿Qué variantes y estados tiene?
  4. ¿Cuándo usarlo y cuándo no?

La cuarta pregunta es la que más se olvida. Un componente sin reglas de uso se usa mal aunque el agente conozca su API. Es el mismo principio de un buen sistema de diseño para personas: documentar la intención, no solo la forma. Para ir más a fondo, mira un design system que la IA pueda leer.

¿Cómo lo resuelven las herramientas?

Tres herramientas oficiales muestran el mismo patrón: el agente consulta un catálogo antes de escribir.

  • Storybook MCP. Es un addon (npx storybook add @storybook/addon-mcp) que expone un servidor MCP con tres grupos de herramientas. El de documentación (docs-list, docs-show, docs-show-story) devuelve el índice de componentes, sus props y sus historias. El de desarrollo ayuda a escribir y previsualizar historias (por ejemplo, stories-preview), y el de pruebas tiene test-run. La documentación depende de un manifiesto de componentes que viene desactivado y se activa con features: { componentsManifest: true }. Solo funciona con React, Angular con Vite y Vue 3 con Vite (este último necesita además experimentalDocgenServer). En otros frameworks, las herramientas de desarrollo y pruebas siguen disponibles, pero no las de documentación. Todo está en vista previa y la API puede cambiar.
  • Figma MCP. search_design_system busca componentes, variables y estilos en las bibliotecas conectadas, y se pueden enviar varias búsquedas en una sola llamada. get_code_connect_map devuelve, para cada instancia de tu selección, el componente de tu código con el que está mapeada. Ese mapeo existe solo si alguien configuró Code Connect, el puente entre componentes de Figma y de código, disponible con asiento Dev o Full en los planes Professional, Organization y Enterprise. Para el flujo completo, lee De Figma a código con MCP.
  • shadcn/ui MCP. Si tu sistema se distribuye como registro (el modelo de shadcn/ui), el servidor MCP de shadcn lista y busca componentes, bloques y plantillas de los registros configurados en components.json y los instala con peticiones como “agrega un formulario de login”. Acepta registros de terceros y privados, por ejemplo la biblioteca interna de una empresa, con cabeceras de autenticación. Se inicia con shadcn@latest mcp init.

La diferencia práctica: Storybook responde “cómo se usa este componente”, Figma “cuál es el componente del código para este diseño” y el registro de shadcn “qué hay disponible para instalar”.

¿Cómo documentar un componente para un agente?

Escribe la documentación como si fuera para un junior que llega el lunes. Incluye:

  • Un párrafo de uso: “Úsalo para confirmar una acción destructiva. No lo uses para navegar.”
  • La tabla de props, con tipos y valores por defecto.
  • Un ejemplo mínimo que compile.
  • Los casos donde no debe usarse: “No lo pongas dentro de otro modal.”

Esta documentación también entra en el contexto del agente, así que tiene un costo: cada línea que escribes ocupa espacio. Prioriza las reglas de uso sobre las descripciones obvias. Y deja en las instrucciones permanentes del repositorio, como un archivo CLAUDE.md o AGENTS.md (más aquí), una regla corta: “Antes de crear un componente, busca en el catálogo; si no usas uno existente, explica por qué”.

¿Cuándo NO conviene forzar la reutilización?

  • Cuando el componente existente no sirve para el caso y adaptarlo lo rompería. Un componente con veinte props condicionales es más difícil de mantener que uno nuevo y simple.
  • Cuando el sistema está en plena reescritura. Pedirle al agente que reutilice componentes que vas a eliminar produce trabajo que se tira.
  • Cuando no hay catálogo. Sin documentación, el agente solo puede adivinar, y reutilizar una adivinanza es peor que escribir código nuevo.

Ejemplo

Ejemplo ilustrativo: un equipo tiene un componente ConfirmDialog con las props title, onConfirm y variant="destructive". Lo documenta en Storybook con una frase de uso y un ejemplo. Después pide a un agente con Storybook MCP: “Agrega confirmación antes de borrar un proyecto.” El agente consulta docs-list, encuentra ConfirmDialog, lee sus props y lo usa con variant="destructive". Sin la documentación, habría escrito un modal propio.

Lo que tienes que revisar: que el agente no haya creado un componente nuevo en src/components con un nombre parecido. Una búsqueda por nombre en el repositorio lo detecta en segundos.

Errores comunes

  • Documentar solo las props y no el uso. El agente sabe llamar al componente pero no sabe cuándo.
  • Dejar componentes duplicados en el repositorio sin marcar cuál es el oficial. El agente elegirá el que vea primero.
  • Dar por hecho que Storybook MCP funciona igual en cualquier framework. Revisa el soporte antes de contar con él.
  • Olvidar activar el manifiesto de componentes: sin él, las herramientas de documentación no están disponibles.
  • Permitir que el agente cree un componente nuevo sin pedir justificación. Pídele que explique por qué no reutilizó uno existente.
  • No revisar la accesibilidad del resultado. Reutilizar un componente no garantiza que el caso nuevo sea accesible.

Fuentes

Preguntas frecuentes

¿Por qué un agente de IA crea componentes duplicados?
Porque no sabe que ya existen o no tiene forma de consultarlos. Sin un catálogo legible, el agente tiende a generar un botón o un modal nuevo cada vez que lo necesita.
¿Qué puede hacer Storybook MCP para evitarlo?
Su conjunto de herramientas de documentación permite que el agente liste los componentes, lea sus props y ejemplos, y los reutilice. Está en vista previa. Según Storybook, esa parte solo funciona con React, Angular con Vite y Vue 3 con Vite, y requiere activar el manifiesto de componentes.
¿Cómo ayuda Figma MCP a reutilizar componentes?
Con la herramienta search_design_system el agente busca componentes, variables y estilos de las bibliotecas conectadas. Con get_code_connect_map ve qué componente del código corresponde a cada instancia de Figma, si el equipo configuró Code Connect.
¿Qué documentación necesita un agente para usar bien un componente?
Las props que acepta, sus variantes, cuándo usarlo y cuándo no, y un ejemplo mínimo. Esa información es la que el agente lee antes de escribir código.